usertasksDocs
Sign in

Integrations

References

Saved, typed operations on an integration — inputs, request templates and output mappings — callable from workflows, agents, reports and MCP.

A reference is one operation: method, path template, query parameters, headers, body template, typed inputs and outputs. Callers supply inputs; the reference builds the request, calls the integration with its stored credentials and maps the response to named outputs.

A reference
{
  "name": "Get vendor",
  "method": "GET",
  "path_template": "/vendors/{{vendor_id}}",
  "inputs": [{ "name": "vendor_id", "type": "string", "required": true }],
  "outputs": [
    { "name": "vendor_name", "path": "name", "type": "string" },
    { "name": "risk", "path": "risk.rating", "type": "string" }
  ]
}

Using references

  • Workflows — the Call API / Reference node maps variables to inputs and outputs to variables; a Live Reference binds one so expressions always read fresh data.
  • AI agents — grant a reference as a tool; the agent sees its name, description and input schema.
  • Reports — references with outputs can be report sources.
  • MCP and API — references_execute / POST /api/v1/references/{id}/execute (usertasks references execute <id> --set inputs:='{"vendor_id":"V-311"}').

Testing

Run a reference from its page with sample inputs and see the request (secrets redacted), status, timing and mapped outputs. Calls made by tests are logged like any other.

Response model

Each reference has a response model: the shape of its response (nested objects, lists with their item fields, types, descriptions and example values). Workflows browse it in the data picker, so designers click response › data[] › email instead of writing JSON paths.

  • OpenAPI/Swagger import fills it from the 2xx response schema ($refs resolved); database references from the table columns; connectors from their declared outputs.
  • Test in the reference builder captures it from the real response when the reference has no model yet (or only an inferred one); Capture from test response merges another sample. The builder shows the model as a tree, and + on a field adds a named output with the right path.
  • References created before models existed derive one from their outputs' paths until their next test.

It is stored at request_config.response_schema and returned as response_schema by GET /api/v1/references/{id} and MCP references_get. Set it with response_schema on create/update (null clears it), or capture it from a call: POST /api/v1/references/{id}/execute with "capture_schema": true (MCP integrations_execute_reference, usertasks references execute <id> --set capture_schema:=true).

A response model
{ "source": "sample", "root": { "type": "object", "fields": [
  { "name": "data", "type": "array", "items": { "type": "object", "fields": [
    { "name": "email", "type": "string", "example": "ada@example.com" }
  ] } }
] } }

Object fields are a list of { name, … } (not a JSON Schema properties map), and examples are never kept for credential-shaped field names.

Bulk operations

usertasks references bulk-delete --set ids:='["…","…"]' removes many references at once; connectors can regenerate their ready-made references with usertasks connectors regenerate-references <id>.