Tools

Tools are reusable processing units within integrations that encapsulate input transformation, conditional routing, output mapping, and data enrichment logic behind an input/output contract. They can be referenced from flows, APIs, AI agents, MCP servers, and other tools to promote modularity and reuse.

Tool schema

List tools

get

/v1/tools

Returns all tools in the account. Filter by _integrationId to scope results to a single integration.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

_integrationIdstringOptional

Filter tools by integration identifier

Example: 5f8d43a1b9e5a80011a35f2c

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Successfully retrieved list of tools

application/json

204

No tools exist in the account

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/tools

GET /v1/tools HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "69d462d5b9c28ea0b7f82522",
    "name": "Get Shopify Order",
    "description": "Fetches a Shopify order by order ID and returns the full order object.",
    "_integrationId": "68ed772471086fb1a76686de",
    "input": {
      "name": "Order ID Input",
      "description": "Provide the Shopify order ID to look up.",
      "schema": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string"
          }
        },
        "required": [
          "orderId"
        ]
      }
    },
    "routers": [
      {
        "id": "router_main",
        "name": "Fetch Order",
        "branches": [
          {
            "name": "Fetch Order from Shopify",
            "pageProcessors": [
              {
                "type": "export",
                "_exportId": "69d462c2a3f9fae38d72b07b",
                "responseMapping": {
                  "fields": [
                    {
                      "extract": "data",
                      "generate": "data"
                    }
                  ]
                }
              }
            ],
            "nextRouterId": "outputRouter"
          }
        ]
      }
    ],
    "createdAt": "2026-04-07T01:50:13.477Z",
    "lastModified": "2026-04-07T01:59:30.900Z"
  }
]

Create a tool

post

/v1/tools

Creates a new tool within an integration. name and _integrationId are required. Routers use first_matching_branch strategy only, and each branch's nextRouterId must point to another router's id or "outputRouter" to exit the tool.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request schema for creating or updating a tool. Tools are reusable processing units that encapsulate input transformation, conditional routing, and output mapping logic within an integration.

namestring · min: 1 · max: 100Required

Human-readable name for the tool.

Displayed in the UI and used to identify the tool's purpose.

Example: Enrich Customer Data

descriptionstring · max: 5120Optional

Optional detailed description of what the tool does.

Use this to document the tool's purpose, expected inputs/outputs, and any special considerations.

Example: Validates and enriches incoming customer records by looking up account status and applying business rules.

_integrationIdstring · objectIdRequired

Reference to the integration this tool belongs to.

Every tool must be associated with an integration. The integration determines the scope and access controls for the tool.

Example: 5f8d43a1b9e5a80011a35f2c

draftbooleanOptional

When true, this tool is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

Responses

201

Tool created successfully

application/json

Tool object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the tool.

Displayed in the UI and used to identify the tool's purpose.

Example: Enrich Customer Data

descriptionstring · max: 5120Optional

Optional detailed description of what the tool does.

Use this to document the tool's purpose, expected inputs/outputs, and any special considerations.

Example: Validates and enriches incoming customer records by looking up account status and applying business rules.

_integrationIdstring · objectIdRequired

Reference to the integration this tool belongs to.

Every tool must be associated with an integration. The integration determines the scope and access controls for the tool.

Example: 5f8d43a1b9e5a80011a35f2c

draftbooleanOptional

When true, this tool is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this tool was created by cloning or installing a template.

Example: 69afbdb19c78a72fc05b1b8b

draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft tool auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Validation failed. Notably, nesting tools inside tools beyond 5 levels is rejected with tool_nesting_depth_exceeded ("Tool cannot be added. It exceeds the maximum nesting depth of 5 levels.").

application/json

post/v1/tools

POST /v1/tools HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "name": "Get Shopify Order",
  "_integrationId": "68ed772471086fb1a76686de"
}

{
  "_id": "69d462d5b9c28ea0b7f82522",
  "_integrationId": "68ed772471086fb1a76686de",
  "name": "Get Shopify Order",
  "createdAt": "2026-04-07T01:50:13.477Z",
  "lastModified": "2026-04-07T01:50:13.477Z"
}

Get a tool

get

/v1/tools/{_id}

Returns the complete configuration of a specific tool.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool

Example: 5f8d43a1b9e5a80011a35f2c

Responses

200

Tool retrieved successfully

application/json

Tool object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the tool.

Displayed in the UI and used to identify the tool's purpose.

Example: Enrich Customer Data

descriptionstring · max: 5120Optional

Optional detailed description of what the tool does.

Use this to document the tool's purpose, expected inputs/outputs, and any special considerations.

Example: Validates and enriches incoming customer records by looking up account status and applying business rules.

_integrationIdstring · objectIdRequired

Reference to the integration this tool belongs to.

Every tool must be associated with an integration. The integration determines the scope and access controls for the tool.

Example: 5f8d43a1b9e5a80011a35f2c

draftbooleanOptional

When true, this tool is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this tool was created by cloning or installing a template.

Example: 69afbdb19c78a72fc05b1b8b

draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft tool auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}

GET /v1/tools/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "69d462d5b9c28ea0b7f82522",
  "name": "Get Shopify Order",
  "description": "Fetches a Shopify order by order ID and returns the full order object.",
  "_integrationId": "68ed772471086fb1a76686de",
  "input": {
    "name": "Order ID Input",
    "description": "Provide the Shopify order ID to look up.",
    "schema": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "orderId"
      ]
    }
  },
  "routers": [
    {
      "id": "router_main",
      "name": "Fetch Order",
      "branches": [
        {
          "name": "Fetch Order from Shopify",
          "pageProcessors": [
            {
              "type": "export",
              "_exportId": "69d462c2a3f9fae38d72b07b",
              "responseMapping": {
                "fields": [
                  {
                    "extract": "data",
                    "generate": "data"
                  }
                ]
              }
            }
          ],
          "nextRouterId": "outputRouter"
        }
      ]
    }
  ],
  "createdAt": "2026-04-07T01:50:13.477Z",
  "lastModified": "2026-04-07T01:59:30.900Z"
}

Update a tool

put

/v1/tools/{_id}

Replaces the tool configuration — GET the tool first, modify the fields you need, then PUT the full object back. Omitting description, routers, or aiDescription removes them. input and output are the exception: omitting either object keeps its stored fields (only its mockInput is cleared), while sending it replaces the object wholesale, so include every sub-field you want to keep. name and _integrationId are required on every PUT.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool

Example: 5f8d43a1b9e5a80011a35f2c

Body

Request schema for creating or updating a tool. Tools are reusable processing units that encapsulate input transformation, conditional routing, and output mapping logic within an integration.

namestring · min: 1 · max: 100Required

Human-readable name for the tool.

Displayed in the UI and used to identify the tool's purpose.

Example: Enrich Customer Data

descriptionstring · max: 5120Optional

Optional detailed description of what the tool does.

Use this to document the tool's purpose, expected inputs/outputs, and any special considerations.

Example: Validates and enriches incoming customer records by looking up account status and applying business rules.

_integrationIdstring · objectIdRequired

Reference to the integration this tool belongs to.

Every tool must be associated with an integration. The integration determines the scope and access controls for the tool.

Example: 5f8d43a1b9e5a80011a35f2c

draftbooleanOptional

When true, this tool is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

Responses

200

Tool updated successfully

application/json

Tool object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the tool.

Displayed in the UI and used to identify the tool's purpose.

Example: Enrich Customer Data

descriptionstring · max: 5120Optional

Optional detailed description of what the tool does.

Use this to document the tool's purpose, expected inputs/outputs, and any special considerations.

Example: Validates and enriches incoming customer records by looking up account status and applying business rules.

_integrationIdstring · objectIdRequired

Reference to the integration this tool belongs to.

Every tool must be associated with an integration. The integration determines the scope and access controls for the tool.

Example: 5f8d43a1b9e5a80011a35f2c

draftbooleanOptional

When true, this tool is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this tool was created by cloning or installing a template.

Example: 69afbdb19c78a72fc05b1b8b

draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft tool auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Validation failed. Notably, nesting tools inside tools beyond 5 levels is rejected with tool_nesting_depth_exceeded ("Tool cannot be added. It exceeds the maximum nesting depth of 5 levels.").

application/json

put/v1/tools/{_id}

PUT /v1/tools/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "name": "Get Shopify Order (v2)",
  "description": "Fetches a Shopify order by order ID and returns key fields.",
  "_integrationId": "68ed772471086fb1a76686de",
  "input": {
    "name": "Order ID Input",
    "schema": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "orderId"
      ]
    }
  },
  "routers": [
    {
      "id": "router_main",
      "name": "Fetch Order",
      "routeRecordsTo": "first_matching_branch",
      "routeRecordsUsing": "input_filters",
      "branches": [
        {
          "name": "Fetch from Shopify",
          "pageProcessors": [
            {
              "type": "export",
              "_exportId": "69d462c2a3f9fae38d72b07b",
              "responseMapping": {
                "fields": [
                  {
                    "extract": "data",
                    "generate": "data"
                  }
                ]
              }
            }
          ],
          "nextRouterId": "outputRouter"
        }
      ]
    }
  ]
}

{
  "_id": "69d462d5b9c28ea0b7f82522",
  "name": "Get Shopify Order (v2)",
  "description": "Fetches a Shopify order by order ID and returns key fields.",
  "_integrationId": "68ed772471086fb1a76686de",
  "input": {
    "name": "Order ID Input",
    "schema": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "orderId"
      ]
    }
  },
  "routers": [
    {
      "id": "router_main",
      "name": "Fetch Order",
      "routeRecordsTo": "first_matching_branch",
      "routeRecordsUsing": "input_filters",
      "branches": [
        {
          "name": "Fetch from Shopify",
          "pageProcessors": [
            {
              "type": "export",
              "_exportId": "69d462c2a3f9fae38d72b07b",
              "responseMapping": {
                "fields": [
                  {
                    "extract": "data",
                    "generate": "data"
                  }
                ]
              }
            }
          ],
          "nextRouterId": "outputRouter"
        }
      ]
    }
  ],
  "createdAt": "2026-04-07T01:50:13.477Z",
  "lastModified": "2026-04-07T02:15:42.118Z"
}

Delete a tool

delete

/v1/tools/{_id}

Deletes a tool. Soft-deleted and retained in the recycle bin for 30 days. Fails with 422 if other resources (MCP servers, access tokens) still reference this tool — call GET /v1/tools/{_id}/dependencies first to check.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool

Example: 5f8d43a1b9e5a80011a35f2c

Responses

204

Tool deleted successfully

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

The resource has dependents that must be deleted first. Each entry in the errors array names one blocking resource.

application/json

delete/v1/tools/{_id}

DELETE /v1/tools/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch a tool

patch

/v1/tools/{_id}

Partially updates a tool using a JSON Patch document (RFC 6902). The add, remove, replace, and move operations are supported (copy and test are rejected), and only on the following whitelisted paths:

Path	Description
/name	Tool display name
/description	Tool description
/aiDescription	AI-generated description object
/input/debugUntil	Debug-capture expiry for the Tool Input stage (ISO-8601, at most 3600 seconds from now)
/output/debugUntil	Debug-capture expiry for the Tool Output stage (ISO-8601, at most 3600 seconds from now)

All other paths are rejected with 422 (not a whitelisted property). A debugUntil more than 3600 seconds ahead is rejected with 422 update_not_allowed and nothing is saved; remove on an absent debugUntil succeeds (204). Changing a debugUntil needs the Tool update permission on the Tool's integration, like every other path.

PATCH is the intended way to update these fields without accidentally resetting other tool configuration via PUT.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool

Example: 69d462d5b9c28ea0b7f82522

Bodyobject · JsonPatchOperation[]

A JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.

opstring · enumRequired

The operation to perform.

Possible values:

pathstringRequired

JSON Pointer (RFC 6901) to the field to patch. Only whitelisted paths are accepted — unlisted paths return 422 with "<path> is not a whitelisted property".

valueanyOptional

The new value to set. Required for replace and add, omit for remove.

Responses

204

Tool patched successfully.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

patch/v1/tools/{_id}

PATCH /v1/tools/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Updated Tool Name"
  }
]

No content

List connections a tool depends on

get

/v1/tools/{_id}/connections

Returns the full Connection resources the tool references — both directly (via _connectionId fields on its steps) and transitively through descendant resources (inner tools, lookups, imports, exports).

Useful for discovering what systems a tool talks to before cloning, moving, or evaluating the blast radius of a connection change. For the full dependency tree (imports, exports, nested tools), use GET /v1/tools/{_id}/descendants instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Tool id.

Example: 69d462d5b9c28ea0b7f82522

Responses

200

Array of full Connection objects referenced by the tool and its descendants. Empty array when no connections are referenced.

application/json

Connection object as returned by the API.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

namestring · max: 100Required

Display name for the connection.

Example: Salesforce Production

typestring · enumRequired

The type of connection determining which authentication and connectivity options are available

Possible values:

externalIdstringOptional

External identifier for the connection, often used for integration with third-party systems

Example: erp-conn-001

assistantstringOptional

Application name in lowercase for HTTP connections to systems with integrator.io adaptors. Used to identify the target application being connected to. Examples - Shopify: "shopify", eBay: "ebay". Only applicable for HTTP connection types.

Example: shopify

_agentIdstring · objectIdOptional

Reference to a Celigo on-premise Agent. Required for connection types that need local network or filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB). The agent establishes a secure tunnel between the on-premise environment and integrator.io.

Example: 5f8d43a1b9e5a80011a35f2c

_borrowConcurrencyFromConnectionIdstring · objectIdOptional

Reference to another connection to share concurrency limits with. When set, this connection's traffic counts against the referenced connection's limit instead of its own, and its own concurrency and auto-recovery settings have no effect. One level only: the referenced connection may not itself borrow, and a connection that others borrow from cannot start borrowing.

Example: 615dfa0742763671275b70ab

debugDatestring · date-timeOptional

Date until which debug logging is enabled for this connection

Example: 2026-01-15T09:30:00.000Z

settingsFormobjectOptional

Dynamic form configuration for connection-specific settings

settingsobjectOptional

Connection-specific settings and configurations

offlinebooleanRead-onlyOptional

When true, the connection has been taken offline and is skipped during flow execution.

_sourceIdstring · objectIdRead-onlyOptional

Source connection this was cloned from.

Example: 5f29dbc69e8a0f0e29a491b7

connectionRolestring · enumRead-onlyOptional

Distinguishes account-owned connections from the per-end-user credential copies MCP servers collect. Absent on connections last saved before the field existed, which behave as standard. Sending mcpChild on POST or PUT /v1/connections fails with 422 mcp_child_generic_route_not_allowed, and /connectionRole is not a patchable path; child connections are written only by the MCP end-user setup page, never through /v1.

Example: standardPossible values:

endUserProvidedFieldsstring[]Optional

Dot-paths of this connection's fields (for example http.encrypted.apiKey or rdbms.user) that each MCP end user must supply on their own mcpChild copy instead of inheriting the parent's value. Only returned on a standard connection that has paths set; never returned on a child. Writable through POST, PUT, and PATCH; by the platform contract, a write that changes the list invalidates the children end users already hold against this parent.

Example: ["http.encrypted.apiKey","http.unencrypted.accountId"]

_parentConnectionIdstring · objectIdRead-onlyOptional

Parent connection this child copies its non-credential configuration from. Present only when connectionRole is mcpChild; set by the end-user setup page and ignored when sent on a standard connection.

Example: 615dfa0742763671275b70ab

_mcpOwnerIdstring · objectIdRead-onlyOptional

Account owner whose parent connection and MCP servers this child belongs to. Present only when connectionRole is mcpChild; on a child, _userId is the end user and this field is the account.

Example: 5d2e1f0a9b8c7d6e5f4a3b2c

_parentSyncedAtstring · date-timeRead-onlyOptional

Timestamp when the child's non-credential fields were last synced from the parent connection. Present only when connectionRole is mcpChild.

Example: 2026-09-15T18:42:10.331Z

_userIdstring · objectIdRead-onlyOptional

End user who owns this mcpChild connection's credentials. Present only when connectionRole is mcpChild; a standard connection belongs to the account and omits this field.

Example: 5d2e1f0a9b8c7d6e5f4a3b2c

debugUntilstring · date-timeRead-onlyOptional

Debug logging is active until this timestamp. Absent or in the past means debug is off.

Example: 2026-01-15T09:30:00.000Z

encryptedstringRead-onlyOptional

Masked placeholder for encrypted credential fields. Always returns "******".

isHTTPbooleanRead-onlyOptional

When true, the connection uses the HTTP adaptor internally, even when type is wrapper.

autoRecoverRateLimitErrorsbooleanOptional

When true, rate-limit errors from the target system trigger automatic recovery: concurrency drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes, after which the flag switches itself off), and concurrency climbs back toward targetConcurrencyLevel. While true, targetConcurrencyLevel is the throughput lever: a concurrencyLevel sent in a PUT is ignored, and one sent in a PATCH is stored but the recovery machinery moves it back toward the target.

Default: true

enableMicroBatchForOneToManybooleanOptional

When true, enables micro-batching for one-to-many data flows through this connection.

Default: true

enableCsvObjectParsingbooleanOptional

When true, enables CSV-to-object parsing for data received through this connection.

Default: true

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}/connections

GET /v1/tools/{_id}/connections HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[]

Replace a connection across a tool

put

/v1/tools/{_id}/replaceConnection

Repoints every export and import step in the tool's routers that uses _connectionId to _newConnectionId, saving each step resource in place. Use it instead of per-resource PUTs when rotating credentials or promoting a tool between environments; GET /v1/tools/{_id}/connections shows which connections the tool references before and after.

Each affected step is re-validated against the replacement connection before anything is saved, so a connection of an incompatible type (an FTP connection for an HTTP lookup, for example) fails the whole request with 422 and leaves every step unchanged. A request whose _connectionId matches no step still succeeds with 204. Unlike the API sibling, no count is returned.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Tool id.

Example: 6ab1fddcb9e454749404c2c0

Body

Request body to swap one connection for another on every export and import step in the tool's routers. Both ids must be well-formed; the replacement connection must exist in the account and satisfy each affected step's adaptor validation.

_connectionIdstring · objectIdRequired

Connection currently referenced by the tool's steps. Steps that reference a different connection are left untouched.

Example: 6ab1fdda79bf70c118730f42

_newConnectionIdstring · objectIdRequired

Connection to reference instead. Must be usable by every matching step — an HTTP lookup cannot be repointed to an FTP connection, for example.

Example: 6ab1fddbb9e454749404c291

Responses

204

Matching steps now reference the new connection (also returned when no step matched). No response body.

No content

400

A required id is missing or malformed.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

The tool or the replacement connection does not exist in the account.

application/json

422

A matching step cannot use the replacement connection. The error is the affected step's adaptor validation failure; no step is changed.

application/json

put/v1/tools/{_id}/replaceConnection

PUT /v1/tools/{_id}/replaceConnection HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "_connectionId": "6ab1fdda79bf70c118730f42",
  "_newConnectionId": "6ab1fddbb9e454749404c291"
}

No content

List resources a tool depends on, grouped by type

get

/v1/tools/{_id}/descendants

Returns the full dependency tree of a tool as three arrays: the imports, exports, and nested tools it references directly or transitively. Each entry is the complete resource document, so the caller doesn't need to fan out individual GETs.

Pair with GET /v1/tools/{_id}/connections to enumerate the full resource and connection footprint in two calls.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Tool id.

Example: 69d462d5b9c28ea0b7f82522

Responses

200

Full descendant resource docs grouped by type. Each array may be empty when the tool doesn't reference that resource kind.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}/descendants

GET /v1/tools/{_id}/descendants HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "imports": [],
  "exports": [],
  "tools": []
}

Clone a tool

post

/v1/tools/{_id}/clone

Creates a copy of a tool in the target integration and returns a manifest of the resources the clone created. The clone records its lineage in _sourceId, which places it in the source tool's clone family.

The target integration is never inferred from the source tool — pass the source tool's own integration id to clone in place.

Use GET /v1/tools/{_id}/clone/preview first to see what the clone would create.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The id of the tool to clone.

Example: 6a869d2d3ae8ccee42a45c01

Body

_integrationIdstring · objectIdRequired

Integration the cloned tool is created in.

Example: 6a429af50547257e3301246c

namestringOptional

Name for the cloned tool. Defaults to Clone - <source tool name> when omitted.

Example: Customer enrichment tool (copy)

Responses

201

The clone was created. Returns a manifest of the resources the clone created.

application/json

Manifest of resources created by the clone.

modelstringOptional

Model name of the created resource (e.g. Tool).

Example: Tool

_idstring · objectIdOptional

Unique id of the created resource.

Example: 6a869d2f3ae8ccee42a45c44

400

The body omits _integrationId (required_field_missing).

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

post/v1/tools/{_id}/clone

POST /v1/tools/{_id}/clone HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 86

{
  "_integrationId": "6a429af50547257e3301246c",
  "name": "Customer enrichment tool (copy)"
}

[
  {
    "model": "Tool",
    "_id": "6a869d2f3ae8ccee42a45c44"
  }
]

Preview cloning a tool

get

/v1/tools/{_id}/clone/preview

Returns a preview of the resources that would be created by cloning this tool. No resources are created.

Call this before POST /v1/tools/{_id}/clone to inspect what the clone would create.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Tool id to preview cloning.

Example: 6a869d2d3ae8ccee42a45c01

Responses

200

Clone preview retrieved successfully.

application/json

Preview of the resources that would be created by a clone operation. Each object in the objects array represents a resource that will be cloned, including the target resource and all transitive dependencies (connections, scripts, exports, imports, etc.).

stackRequiredbooleanOptional

Whether the clone requires a stack (connector-level) environment to proceed.

_stackIdstring · nullableOptional

The stack id associated with the resource, or null if no stack is involved.

Example: 5f8d43a1b9e5a80011a35f2c

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}/clone/preview

GET /v1/tools/{_id}/clone/preview HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "objects": [
    {
      "model": "Tool",
      "doc": {
        "name": "Customer enrichment tool",
        "_integrationId": "6a429af50547257e3301246c"
      }
    }
  ],
  "stackRequired": false,
  "_stackId": null
}

List dependencies of a tool

get

/v1/tools/{_id}/dependencies

Returns the set of resources that depend on the specified resource. The response is an object whose keys are dependent-resource types (e.g. flows, imports) and whose values are arrays of dependency entries.

Returns {} for both zero-dependency and nonexistent IDs.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Resource ID.

Example: 69d462d5b9c28ea0b7f82522

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/tools/{_id}/dependencies

GET /v1/tools/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}

Get a downloadable template for a tool

get

/v1/tools/{_id}/template

Packages the tool as an installable template and returns a signed S3 URL where the template .zip can be downloaded. The URL is pre-signed and short-lived (approximately 15 minutes), so fetch the file promptly; call the endpoint again for a fresh URL.

The .zip contains the tool definition plus every resource it references — nested tools, exports, imports, connections, and scripts — grouped into one folder per resource type, with an integration.json manifest at the root. Requires the create:tool:template permission.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Tool id.

Example: 69d462d5b9c28ea0b7f82522

Responses

200

Signed download URL for the tool template zip.

application/json

signedURLstring · uriOptional

Pre-signed, short-lived S3 URL to download the template .zip.

Example: https://integrator-templates.s3.us-east-1.amazonaws.com/69d462d5b9c28ea0b7f82522.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a

keystringOptional

S3 object key for the generated template .zip, named <toolId>.zip.

Example: 69d462d5b9c28ea0b7f82522.zip

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}/template

GET /v1/tools/{_id}/template HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-templates.s3.us-east-1.amazonaws.com/69d462d5b9c28ea0b7f82522.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a",
  "key": "69d462d5b9c28ea0b7f82522.zip"
}

Invoke a Tool synchronously

post

/v1/tools/{_id}/invoke

Executes a Tool synchronously and returns the mapped output (or errors).

Optional x-log-mode enables enterprise invocation logging. When logging is active for the run, the response includes invocationId — use that value as {executionId} with GET /v1/tools/{_id}/invocations/{executionId}. Sandbox Tools return 403 when logging is attempted.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

Header parameters

x-log-modestring · enumOptional

Enables enterprise Tool logging for this invoke. Omit to skip logging. Every direct API call is a standalone invoke: only debug enables logging — the other valid values are accepted but silently ignored (the invoke runs without logging; no error is returned). Values outside the enum return 400. The basic and detailed levels (standard is an alias for basic) apply only to Agent, MCP, and Guardrail invocations, where Celigo services forward the invoker's effective log level; external callers cannot select them.

Example: debugPossible values:

x-integration-idstring · objectIdOptional

Invoker integration id for Agent or Guardrail invokes. Ignored for MCP and standalone invokes.

x-by-user-idstring · objectIdOptional

End-user id that triggered an Agent or Guardrail invoke. Ignored for MCP and standalone invokes.

x-invoker-idstring · objectIdOptional

Direct caller resource id for Agent or Guardrail invokes. Ignored for MCP and standalone invokes.

Body

Tool invoke body. Both input and overrides are required — a missing body or a missing key returns 400. Pass {} for either when there is nothing to send.

Other propertiesanyOptional

Responses

200

Tool executed successfully.

application/json

invocationIdstring · objectIdOptional

Present when enterprise Tool logging is active for the run.

Other propertiesanyOptional

400

Malformed request — a body missing input or overrides, an x-log-mode value outside the enum, or a Tool whose branches have no steps yet.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

The Tool ran but a step failed. Includes invocationId when logging is active, so the failed run can be opened in the run history.

application/json

post/v1/tools/{_id}/invoke

POST /v1/tools/{_id}/invoke HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "input": {
    "orderId": "SO-1043"
  },
  "overrides": {
    "connections": [
      {
        "_abstractId": "6ab1f5657b3d01a9084253a5",
        "_id": "6ab1f5657b3d01a9084253a5"
      }
    ]
  }
}

{
  "output": {
    "orderId": "SO-1043",
    "title": "Sample Slide Show"
  },
  "errors": [],
  "invocationId": "6ab1f5a17cd5cdd66da1cd40"
}

List Tool invocation run history

get

/v1/tools/{_id}/invocations

Returns the run history for a Tool — one entry per invocation that ran with enterprise logging enabled (x-log-mode on POST /v1/tools/{_id}/invoke, or the log level forwarded by the calling Agent, MCP server, or Guardrail). Invocations that ran without logging never appear here.

Newest first by default. When time_gte, time_lte, next, and prev are all omitted, only the last 5 minutes are returned — pass an explicit window for a broader history. Use an entry's executionId with GET /v1/tools/{_id}/invocations/{executionId} to drill into its steps.

Sandbox Tools return 403. Custom roles only see invocations whose _invokerIntegrationId is in their accessible integrations.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

Query parameters

pageSizeinteger · min: 1 · max: 100Optional

Number of entries per page. Larger values are clamped to 100.

Default: 50Example: 50

sortOrderstring · enumOptional

Sort direction by invocation time.

Default: descPossible values:

nextstring · date-timeOptional

Cursor timestamp for the next page. Copy it from _pagination.nextPageUrl together with cursorExecutionId; mutually exclusive with prev.

prevstring · date-timeOptional

Cursor timestamp for the previous page. Copy it from _pagination.prevPageUrl together with cursorExecutionId; mutually exclusive with next.

cursorExecutionIdstring · objectIdOptional

Tie-breaker execution id, required when paging with next/prev.

time_gtestring · date-timeOptional

Include invocations at or after this timestamp.

time_ltestring · date-timeOptional

Include invocations at or before this timestamp.

traceKeyPrefixstring · min: 1 · max: 500Optional

Filter on traceKey (the value the Tool's input.traceKeyTemplate produced). A prefix longer than 2 characters matches with starts-with; 1–2 characters match exactly.

Example: order-SO-10

invokerTypestringOptional

Filter by invoker type — a single value or a comma-separated list of ToolInvocationSummary.invokerType values.

Example: agent,mcp

_invokerIdstring · objectIdOptional

Filter by the direct caller resource id (the Agent, MCP server, or Guardrail import).

_invokerIntegrationIdstring · objectIdOptional

Narrow results to one invoker integration. Custom roles may only pass an integration they can access; otherwise the list is empty.

statusstringOptional

Filter by invocation status — a single value or a comma-separated list of ToolInvocationSummary.status values. Any other token returns 400 invalid_status.

Example: success,error

Responses

200

Paginated run history. invocations[] is empty when nothing matches.

application/json

Paginated Tool invocation run history.

400

Invalid query parameter, for example a status token outside the enum.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Unknown or inaccessible Tool _id.

application/json

get/v1/tools/{_id}/invocations

GET /v1/tools/{_id}/invocations HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "invocations": [
    {
      "executionId": "6ab1f5a17cd5cdd66da1cd40",
      "_toolId": "65a98d1ef2b40000098c3a4d",
      "_invokerIntegrationId": "6587bb20d12345000a1f9a3c",
      "_triggeredByUserId": "65a98d1ef2b40000098c3a01",
      "invokerType": "standalone",
      "_invokerId": "",
      "status": "success",
      "traceKey": "order-SO-1043",
      "remoteIP": "203.0.113.10",
      "time": "2026-09-22T03:27:29.411000Z",
      "timeTaken": 1025,
      "logMode": "debug"
    },
    {
      "executionId": "6ab1f5877cd5cdd66da1cc8b",
      "_toolId": "65a98d1ef2b40000098c3a4d",
      "_invokerIntegrationId": "6587bb20d12345000a1f9a3c",
      "_triggeredByUserId": "65a98d1ef2b40000098c3a01",
      "invokerType": "standalone",
      "_invokerId": "",
      "status": "error",
      "traceKey": "order-SO-1043",
      "remoteIP": "203.0.113.10",
      "time": "2026-09-22T03:27:03.060000Z",
      "timeTaken": 316,
      "logMode": "debug"
    }
  ],
  "_pagination": {
    "nextPageUrl": null,
    "prevPageUrl": null
  }
}

Delete Tool invocation logs in a date range

delete

/v1/tools/{_id}/invocations

Queues asynchronous deletion of the stored invocation logs for the Tool within [time_gte, time_lte]. Returns 202 Accepted immediately; the entries disappear from GET /v1/tools/{_id}/invocations once the background cleanup runs. Requires log-deletion access. Sandbox Tools return 403.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

Query parameters

time_gtestring · date-timeRequired

Start of the deletion window. Omitting it returns 400 invalid_query_params.

time_ltestring · date-timeRequired

End of the deletion window. Must not be in the future.

Responses

202

Deletion request accepted for asynchronous processing. No body.

No content

400

Missing or invalid window parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/tools/{_id}/invocations

DELETE /v1/tools/{_id}/invocations?time_gte=2026-01-01T00%3A00%3A00.000Z&time_lte=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get trace metadata for a Tool invocation

get

/v1/tools/{_id}/invocations/{executionId}

Returns the invocation header plus one step record per stage the run passed through: the Tool's input bubble (<toolId>_input), each export or import step, and the output bubble (<toolId>_output). A run that failed before any step executed returns an empty steps array. Use a step's _expOrImpId, groupId, and recordId with the log-data endpoint to read the payload it processed.

When the invocation is missing or not visible under the caller's integration ACL, the endpoint returns 204 No Content. 404 applies only to an unknown or inaccessible Tool _id. A malformed executionId returns 422. Sandbox Tools return 403.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

executionIdstring · objectIdRequired

The execution id (24-character lowercase hex ObjectId) from the run-history list or from invocationId on the invoke response.

Example: 6ab1f5a17cd5cdd66da1cd40

Responses

200

Trace metadata for the invocation.

application/json

Invocation header plus every step record for the run. A subset of the list summary — _invokerIntegrationId, _triggeredByUserId, and remoteIP are only on the list endpoint.

executionIdstring · objectIdRequired

Identifier of this invocation. Same value returned as invocationId from POST /v1/tools/{_id}/invoke when logging is enabled.

Example: 6ab1f5a17cd5cdd66da1cd40

_toolIdstring · objectIdRequired

Tool that was invoked.

Example: 65a98d1ef2b40000098c3a4d

statusstring · enumRequired

Outcome of the invocation.

Example: successPossible values:

timestring · date-timeRequired

Timestamp when the invocation started.

Example: 2026-09-22T03:27:29.411000Z

timeTakenintegerRequired

Total processing time in milliseconds.

Example: 1025

traceKeystringRequired

Value the Tool's input.traceKeyTemplate produced for this invocation. Empty string when the Tool has no template.

Example: order-SO-1043

invokerTypestring · enumRequired

Kind of caller that invoked the Tool.

Example: standalonePossible values:

_invokerIdstringRequired

Import id of the Agent, MCP, or Guardrail caller. Empty string for a standalone invoke.

Example: 65a98d1ef2b40000098c3b5e

logModestring · enumRequired

Logging level that was active for this invocation.

Example: debugPossible values:

204

Invocation not found or not visible under the caller's integration ACL.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Malformed executionId.

application/json

get/v1/tools/{_id}/invocations/{executionId}

GET /v1/tools/{_id}/invocations/{executionId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "executionId": "6ab1f5a17cd5cdd66da1cd40",
  "_toolId": "65a98d1ef2b40000098c3a4d",
  "status": "success",
  "time": "2026-09-22T03:27:29.411000Z",
  "timeTaken": 1025,
  "traceKey": "order-SO-1043",
  "invokerType": "standalone",
  "_invokerId": "",
  "logMode": "debug",
  "steps": [
    {
      "_expOrImpId": "65a98d1ef2b40000098c3a4d_input",
      "status": "success",
      "timeTaken": 77,
      "groupId": "YYFuqOqC",
      "recordId": "iDKd5iTA",
      "time": "2026-09-22T03:27:29.872000Z"
    },
    {
      "_expOrImpId": "6ab1f572de9162306b4d7be5",
      "status": "success",
      "timeTaken": 179,
      "groupId": "EkuA4OGu",
      "recordId": "iDKd5iTA",
      "time": "2026-09-22T03:27:30.146000Z"
    },
    {
      "_expOrImpId": "65a98d1ef2b40000098c3a4d_output",
      "status": "success",
      "timeTaken": 80,
      "groupId": "oHc2QJWQ",
      "recordId": "iDKd5iTA",
      "time": "2026-09-22T03:27:30.314000Z"
    }
  ]
}

List child records under a Tool trace step

get

/v1/tools/{_id}/invocations/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children

Returns the child records a step produced from one parent record — the rows a lookup step returned, or the records a one-to-many expansion generated. parentRecordId is the recordId of the step entry on the trace-metadata response. Results are cursor-paginated (next/prev); the input and output bubbles have no children.

When the invocation is missing or not visible under the caller's integration ACL, the endpoint returns 204 No Content. 404 applies only to an unknown or inaccessible Tool _id. A malformed executionId returns 422. Sandbox Tools return 403.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

executionIdstring · objectIdRequired

The execution id (24-character lowercase hex ObjectId).

Example: 6ab1f5a17cd5cdd66da1cd40

_expOrImpIdstringRequired

Step identifier from the trace-metadata response: an export or import id, or the Tool's input/output bubble id (<toolId>_input / <toolId>_output).

Example: 6ab1f572de9162306b4d7be5

parentRecordIdstringRequired

The parent record id whose children are returned.

Example: iDKd5iTA

Query parameters

statusstringOptional

Filter children by processing outcome (single value or comma-separated list).

Example: success,error

pageSizeinteger · min: 1 · max: 100Optional

Number of entries per page. Larger values are clamped to 100.

Default: 50Example: 50

sortOrderstring · enumOptional

Sort direction by step time.

Default: descPossible values:

nextstring · date-timeOptional

Cursor timestamp for the next page (from nextPageUrl).

prevstring · date-timeOptional

Cursor timestamp for the previous page (from prevPageUrl).

cursorRecordIdstringOptional

Tie-breaker record id, required when paging with next/prev.

Responses

200

Paginated child step records. children[] is empty when the parent produced none.

application/json

Paginated child records under a parent record in a Tool invocation trace.

nextPageUrlstring · nullableRequired

URL to fetch the next page; null when there is no next page.

prevPageUrlstring · nullableRequired

URL to fetch the previous page; null when there is no previous page.

204

Invocation not found or not visible under the caller's integration ACL.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/tools/{_id}/invocations/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children

GET /v1/tools/{_id}/invocations/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "children": [
    {
      "_expOrImpId": "6ab1f572de9162306b4d7be5",
      "status": "success",
      "timeTaken": 85,
      "groupId": "EkuA4OGu",
      "recordId": "IVaZT9kv",
      "parentRecordId": "iDKd5iTA",
      "time": "2026-09-22T03:27:30.146000Z"
    }
  ],
  "nextPageUrl": null,
  "prevPageUrl": null
}

Query decoded log data for a Tool trace step

post

/v1/tools/{_id}/invocations/{executionId}/logs/data/query

Returns the payload a step processed during the invocation — what went in and what came out — selected by _expOrImpId, stage, groupId, and recordId from the trace-metadata response. The input and output bubbles store their payload under the schemaValidation stage; a lookup step stores the response it merged under responseMapping. A selector that matches nothing returns 200 with an empty logs array. Large payloads are not inlined — the entry carries an externalReference whose s3Key you pass to the signed-URL endpoint.

For nested Tools, set stage to tool with the nested ToolImport id to fetch the composed input/output payload.

When the invocation is missing or not visible under the caller's integration ACL, the endpoint returns 204 No Content. 404 applies only to an unknown or inaccessible Tool _id. A malformed executionId returns 422, and a body missing any of the four selector keys returns 400. Sandbox Tools return 403.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

executionIdstring · objectIdRequired

The execution id (24-character lowercase hex ObjectId).

Example: 6ab1f5a17cd5cdd66da1cd40

Body

Selector for one stored payload within a Tool invocation. Copy _expOrImpId, groupId, and recordId from a step on the trace-metadata response and name the stage whose payload you want.

_expOrImpIdstringRequired

Stage identifier from the trace: an export or import id, the Tool's input/output bubble id (<toolId>_input / <toolId>_output), or a nested ToolImport id when stage is tool.

Example: 6ab1f572de9162306b4d7be5

stagestringRequired

Processing stage whose payload to fetch. The input and output bubbles store their payload under schemaValidation; a lookup step stores the merged response under responseMapping; use tool for a nested ToolImport's composed payload.

Example: schemaValidation

groupIdstringRequired

Group identifier of the step record.

Example: YYFuqOqC

recordIdstringRequired

Identifier of the record to fetch.

Example: iDKd5iTA

Responses

200

Decoded log payload and any error metadata.

application/json

Decoded log payload for a step, plus any error metadata collected while resolving it.

204

Invocation not found or not visible under the caller's integration ACL.

400

Request body is missing one or more selector keys.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/tools/{_id}/invocations/{executionId}/logs/data/query

POST /v1/tools/{_id}/invocations/{executionId}/logs/data/query HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "_expOrImpId": "65a98d1ef2b40000098c3a4d_input",
  "stage": "schemaValidation",
  "groupId": "YYFuqOqC",
  "recordId": "iDKd5iTA"
}

{
  "logs": [
    {
      "log": {
        "timestamp": "2026-09-22T03:27:29.871Z",
        "groupId": "YYFuqOqC",
        "recordId": "iDKd5iTA",
        "stage": "schemaValidation",
        "toolStage": "input",
        "input": {
          "record": {
            "orderId": "SO-1043"
          }
        },
        "output": {
          "record": {
            "orderId": "SO-1043"
          }
        },
        "errors": []
      }
    }
  ],
  "errors": []
}

Get a signed URL for a stored Tool log payload

get

/v1/tools/{_id}/invocations/{executionId}/logs/signedURL

Returns a short-lived signed URL to download a stored log payload that the log-data endpoint returned as an external reference (externalReference[].source.s3Key). The key is resolved inside the invocation's own storage prefix, so a key from another invocation cannot be read through this route. The URL is minted without checking that the object exists — downloading a key that was never stored fails at the storage layer.

When the invocation is missing or not visible under the caller's integration ACL, the endpoint returns 204 No Content. Sandbox Tools return 403.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

executionIdstring · objectIdRequired

The execution id (24-character lowercase hex ObjectId).

Example: 6ab1f5a17cd5cdd66da1cd40

Query parameters

s3KeystringRequired

Relative key of the stored log object, copied from externalReference[].source.s3Key on the log-data response. Omitting it returns 400 missing_required_parameter.

Example: 6ab1f572de9162306b4d7be5/responseMapping/EkuA4OGu/iDKd5iTA.json

Responses

200

Signed URL for the requested object.

application/json

A short-lived signed URL for downloading a stored Tool log payload object.

signedURLstringRequired

Time-limited signed URL to download the referenced log object.

Example: https://example.com/signed-log-download?signature=...

204

Invocation not found or not visible under the caller's integration ACL.

400

Missing s3Key.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/tools/{_id}/invocations/{executionId}/logs/signedURL

GET /v1/tools/{_id}/invocations/{executionId}/logs/signedURL?s3Key=6ab1f572de9162306b4d7be5%2FresponseMapping%2FEkuA4OGu%2FiDKd5iTA.json HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-userdata.s3.us-east-1.amazonaws.com/tool-invocation-logs/65a98d1ef2b40000098c3a01/65a98d1ef2b40000098c3a4d/6ab1f5a17cd5cdd66da1cd40/6ab1f572de9162306b4d7be5/responseMapping/EkuA4OGu/iDKd5iTA.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=..."
}

List captured request logs for a Tool

get

/v1/tools/{_id}/logs

Lists the request/response envelopes the platform has stored for this Tool as a whole — the Tool-level counterpart of GET /v1/apis/{_id}/logs. Entries are file-backed with server-controlled retention; an empty requests[] means nothing is currently stored. Standalone invokes through POST /v1/tools/{_id}/invoke do not write here — use GET /v1/tools/{_id}/invocations for run history.

List entries are summaries (key, time, method, statusCode); read the payload with GET /v1/tools/{_id}/logs/{key}. Without a time window the newest entries are returned; time_lte and time_gt are epoch milliseconds and time_lte requires time_gt.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

Query parameters

time_gtinteger · int64Optional

Lower bound of the time window (exclusive), as epoch milliseconds.

Example: 1789900000000

time_lteinteger · int64Optional

Upper bound of the time window (inclusive), as epoch milliseconds. Requires time_gt; an ISO timestamp or a missing time_gt returns 422.

Example: 1790047623357

methodstring[]Optional

Only return entries with these HTTP methods. Repeat the parameter for several values.

Example: ["POST"]

statusCodestring[]Optional

Only return entries with these status codes. Repeat the parameter for several values.

Example: ["200","422"]

nextPageTokenstringOptional

Continuation token. Follow the nextPageURL of the previous page instead of constructing it.

Responses

200

Log envelope. requests[] is empty when nothing is stored for the Tool.

application/json

Envelope returned by GET /v1/tools/{_id}/logs. requests[] is empty when no captured request is currently stored for the Tool — nothing has been captured, or the retention window has elapsed.

nextPageURLstringOptional

Relative URL of the next page, carrying the narrowed time window and a continuation token. Present only while more of the storage window remains to be searched — it can appear alongside an empty requests[]. Follow it as returned; do not construct it.

Example: /v1/tools/65a98d1ef2b40000098c3a4d/logs?time_gt=1789900000000&time_lte=1790047400000

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Invalid time window — time_lte without time_gt, or a value that is not epoch milliseconds.

application/json

get/v1/tools/{_id}/logs

GET /v1/tools/{_id}/logs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "requests": []
}

Delete captured request logs for a Tool

delete

/v1/tools/{_id}/logs

Deletes stored request/response envelopes by the key values listed by GET /v1/tools/{_id}/logs, between 1 and 1000 per call. The response separates the keys that were removed from the keys that failed, with the storage failure reason. A key that no longer exists is reported as deleted.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

Body

Keys of the captured requests to delete.

keysstring[] · min: 1 · max: 1000Required

Keys from the GET /v1/tools/{_id}/logs listing. An empty or missing array returns 400.

Responses

200

Deletion outcome.

application/json

Deletion result envelope.

deletedstring[]Required

Keys that were removed.

400

Missing or empty keys, or more than 1000 keys.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/tools/{_id}/logs

DELETE /v1/tools/{_id}/logs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "keys": [
    "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST"
  ]
}

{
  "deleted": [
    "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST"
  ],
  "errors": []
}

Get one captured request log by key

get

/v1/tools/{_id}/logs/{key}

Returns the full stored request/response envelope for one captured Tool request, looked up by a key from GET /v1/tools/{_id}/logs. The key must match exactly; a key that has expired from retention or was never stored returns 404 file_not_found.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The Tool id.

Example: 65a98d1ef2b40000098c3a4d

keystringRequired

Log key from the GET /v1/tools/{_id}/logs listing, used exactly as returned.

Example: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST

Responses

200

The stored envelope with key, id, and time added.

application/json

Full decoded request/response envelope for one captured Tool request, returned by GET /v1/tools/{_id}/logs/{key}. The stored envelope is returned as-is with the key, id, and time decoded from the log key added to it.

keystringRequired

Echoes the key path parameter.

Example: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST

idstringRequired

Storage id of this log record — the second segment of key.

Example: a10af1ade8fe477a847771c1e3716e36

timeinteger · int64Required

Epoch milliseconds when the request was handled, decoded from key.

Example: 1776917346304

Other propertiesanyOptional

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Unknown Tool, or no stored log for this key.

application/json

get/v1/tools/{_id}/logs/{key}

GET /v1/tools/{_id}/logs/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "key": "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST",
  "id": "a10af1ade8fe477a847771c1e3716e36",
  "time": 1776917346304,
  "request": {
    "method": "POST",
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"input\":{\"orderId\":\"SO-1042\"},\"overrides\":{}}"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"output\":{\"orderId\":\"SO-1042\"},\"errors\":[]}"
  }
}

Run a tool in test mode

post

/v1/tools/{_id}/test/run

Synchronously executes a tool in test mode and returns the run metadata together with the resulting flow job and its child jobs. Use this to validate a tool's routing and step configuration before referencing it from a flow, API, agent, or MCP server.

The request body is optional. When supplied, wrap the test input in an input key ({"input": {...}}) matching the tool's input contract. The run does not read the tool's saved input.mockInput — without a wrapped input the tool executes against an empty input record. The metadata object in the response maps each step id to the ordered list of stage names that ran for that step; use those ids with GET /v1/tools/{_id}/test/run/{runId}/{_stepId} to inspect stage-by-stage results. The run id for follow-up calls is the flowJob._id value.

Test runs are a separate, short-lived history from normal runs — capture any follow-up step or log details soon after the run completes.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool to test.

Example: 69d462d5b9c28ea0b7f82522

Body

Optional test input for the run. Send an empty object or omit the body entirely to run with no input.

Other propertiesanyOptional

Responses

200

The tool ran. Returns the per-step stage metadata, the flow job that executed the tool, and the child jobs for each step.

application/json

Test-run result envelope.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/tools/{_id}/test/run

POST /v1/tools/{_id}/test/run HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "metadata": {
    "69d462d5b9c28ea0b7f82522": [
      "request",
      "parse"
    ],
    "6a2e23bbcf5b64ca6b93b73d": [],
    "69d462d5b9c28ea0b7f82522_input": [
      "input"
    ],
    "main": [
      "router"
    ]
  },
  "flowJob": {
    "_id": "6a2e23bbcf5b64ca6b93b757",
    "_userId": "624cb0346309dc3a543733a2",
    "type": "flow",
    "_integrationId": "68ed772471086fb1a76686de",
    "_flowId": "69d462d5b9c28ea0b7f82522",
    "status": "completed",
    "numError": 1,
    "numSuccess": 1,
    "startedAt": "2026-06-14T03:44:59.577Z",
    "endedAt": "2026-06-14T03:44:59.947Z",
    "createdAt": "2026-06-14T03:44:59.530Z"
  },
  "childJobs": [
    {
      "_id": "6a2e23bbcf5b64ca6b93b774",
      "_userId": "624cb0346309dc3a543733a2",
      "type": "export",
      "_parentJobId": "6a2e23bbcf5b64ca6b93b757",
      "status": "completed",
      "numSuccess": 1,
      "_expOrImpId": "69d462d5b9c28ea0b7f82522"
    },
    {
      "_id": "6a2e23bbcf5b64ca6b93b784",
      "_userId": "624cb0346309dc3a543733a2",
      "type": "tool",
      "_parentJobId": "6a2e23bbcf5b64ca6b93b757",
      "_toolId": "69d462d5b9c28ea0b7f82522",
      "status": "completed",
      "numError": 1
    }
  ]
}

Get a tool test-run step result

get

/v1/tools/{_id}/test/run/{runId}/{_stepId}

Returns the stage-by-stage result of a single step from a prior tool test run. Each entry in stages[] describes one stage (e.g. request, parse, router, input) with its input, output, and any errors.

The runId is the flowJob._id returned by POST /v1/tools/{_id}/test/run. The {_stepId} is one of the step ids found in that run's metadata map. Test-run history is separate from normal run history and is short-lived — fetch step results soon after the run completes.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

runIdstringRequired

Test run id from the POST /v1/tools/{_id}/test/run response (flowJob._id). Distinct from normal flow-run Job ids.

_stepIdstringRequired

Id of the step whose stage results you want. Find step ids in the test-run metadata map.

Responses

200

Stage-by-stage result for the step. stages[] carries per-stage input, output, and errors; the top-level errors array aggregates step-level errors.

application/json

Step result envelope.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/tools/{_id}/test/run/{runId}/{_stepId}

GET /v1/tools/{_id}/test/run/{runId}/{_stepId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "stages": [
    {
      "name": "request",
      "errors": null,
      "output": null,
      "input": [
        {
          "record": {
            "page": {
              "_userId": "624cb0346309dc3a543733a2",
              "data": [
                {}
              ]
            }
          },
          "errors": [],
          "traceKey": null
        }
      ]
    },
    {
      "name": "parse",
      "errors": null,
      "output": [
        {
          "record": {},
          "errors": [],
          "traceKey": null
        }
      ],
      "input": null
    }
  ],
  "errors": []
}

Get request/response logs for a tool test-run step

get

/v1/tools/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse

Returns the outbound HTTP request/response log pairs captured during a specific step of a tool test run. Only steps that issued outbound HTTP calls (exports, imports, lookups) produce entries — routers, filters, and other in-process stages return 404 with code req_res_logs_not_found by design.

The runId is the flowJob._id returned by POST /v1/tools/{_id}/test/run; the {_stepId} is the export or import id of the step you want logs for, found in the test-run metadata map.

Response entries may carry base64-encoded JSON in request.body and response.body — decode string bodies before parsing. Test runs are short-lived ephemeral state, so capture logs soon after the run completes.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

runIdstringRequired

Test run id from the POST /v1/tools/{_id}/test/run response (flowJob._id). Distinct from normal flow-run Job ids.

_stepIdstringRequired

Export or import id of the step whose logs you want. Non-HTTP stages (routers, filters) 404 with req_res_logs_not_found.

Responses

200

Array of request/response log pairs captured during the step. request.body / response.body may be base64-encoded JSON.

application/json

One request/response pair captured by the test engine.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Either the run/step id didn't resolve, or the step produced no request/response logs (non-HTTP stage — router, filter, etc.).

application/json

get/v1/tools/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse

GET /v1/tools/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "request": {
      "method": "POST",
      "url": "https://httpbin.org/post",
      "headers": {
        "content-type": "application/json"
      },
      "body": "eyJuYW1lIjoiQWNtZSBDb3Jwb3JhdGlvbiJ9"
    },
    "response": {
      "statusCode": 200,
      "headers": {
        "content-type": "application/json"
      },
      "body": "eyJqc29uIjp7Im5hbWUiOiJBY21lIENvcnBvcmF0aW9uIn19"
    }
  }
]

List captured debug requests for a tool step

get

/v1/tools/{_id}/{_stepId}/requests

Lists the debug request records captured for a specific step of a tool. These are the raw request/response payloads the step processed, retained for troubleshooting while debug capture is active for the step — a future debugUntil on the step's export or import document, or input.debugUntil / output.debugUntil on the tool for the Tool Input and Tool Output stages. Capture runs in every execution context (a standalone invoke at any x-log-mode, an AI agent or MCP caller, a flow or API that calls the tool, a parent tool); test runs write nothing here. Use the key of an entry with GET /v1/tools/{_id}/{_stepId}/requests/{key} to fetch the full detail of a single captured request.

HTTP and NetSuite steps record one entry per request they send. The tool_input stage records one entry per incoming record (200 when the record passes the input schema, 422 with the validation errors when it does not); the tool_output stage records one entry per output validation. Routers, filters and scripts never record.

An account owner or administrator lists every entry. A shared user sees only entries from runs invoked under integrations they can access (standalone invokes are recorded under the tool's own integration).

When more records match than fit in one page, nextPageURL returns the relative URL for the next page.

Important: Time parameters (time_lte, time_gt) must be epoch milliseconds (integers), not ISO 8601 strings. When time_lte is provided, time_gt is also required.

Requires the manage:tool:logs permission. Returns {requests: []} when the step has captured no debug requests.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

_stepIdstringRequired

The step whose captured logs to list: the ObjectId of an export or import step defined directly in this tool's routers, or one of the two virtual stage ids tool_input (the record entering the tool, validated against the input schema) and tool_output (the post-mapped record, validated against the output schema). Steps nested inside a child tool are addressed on that child tool's id; an ObjectId that is not a direct step of this tool returns 404 invalid_ref. Any other value — including reserved path segments such as invocations, invoke, and test — returns 400 invalid_ref.

Example: 67ee026136f4d1eeb529ad63

Query parameters

time_gtinteger · int64Optional

Lower bound of the time window (exclusive), as epoch milliseconds. Required when time_lte is provided.

Example: 1776917000000

time_lteinteger · int64Optional

Upper bound of the time window (inclusive), as epoch milliseconds. Defaults to now if omitted. When provided, time_gt is also required.

Example: 1776917346304

methodstring[]Optional

Only return records with these HTTP methods. Repeat the parameter to filter on multiple values.

Example: ["POST","GET"]

statusCodestring[]Optional

Only return records with these response status codes. Repeat the parameter to filter on multiple values.

Example: ["200","422"]

stagestring[]Optional

Only return records for these processing stages. Repeat the parameter to filter on multiple values.

nextPageTokenstringOptional

Continuation token for pagination. Do not construct this manually — follow the nextPageURL returned by the previous page instead.

Responses

200

Captured debug request records for the step. Empty requests array when none were captured.

application/json

Debug request list envelope.

nextPageURLstringOptional

Relative URL of the next page. Present only when more records match than were returned.

400

_stepId is neither an ObjectId nor tool_input / tool_output. Error code: invalid_ref.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

The tool does not exist, or _stepId is an ObjectId that is not a step defined directly in this tool. Error code: invalid_ref.

application/json

422

Invalid time filter parameters. Error code: invalid_or_missing_field.

application/json

get/v1/tools/{_id}/{_stepId}/requests

GET /v1/tools/{_id}/{_stepId}/requests HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "requests": []
}

Delete captured debug requests for a tool step

delete

/v1/tools/{_id}/{_stepId}/requests

Deletes captured debug request records for a specific step of a tool, by their key values from GET /v1/tools/{_id}/{_stepId}/requests. Between 1 and 1000 keys can be deleted per call; the deletion is synchronous and scoped to this step only.

The response lists the keys that were deleted and, separately, any keys that failed to delete along with the failure reason. A key that no longer exists is reported under deleted, not errors.

Requires the manage:tool:logs:deletion permission. A shared user's delete removes only records from runs invoked under integrations they can access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

_stepIdstringRequired

The step whose captured logs to delete: the ObjectId of an export or import step defined directly in this tool's routers, or the virtual stage id tool_input or tool_output. Any other value returns 400 invalid_ref; an ObjectId that is not a direct step of this tool returns 404 invalid_ref.

Example: 67ee026136f4d1eeb529ad63

Body

Keys of the captured debug requests to delete.

keysstring[] · min: 1 · max: 1000Required

Keys of the records to delete, from the GET /v1/tools/{_id}/{_stepId}/requests listing.

Responses

200

Deletion outcome. deleted lists the removed keys; errors lists keys that could not be removed with the failure reason.

application/json

Deletion result envelope.

deletedstring[]Required

Keys of the records that were deleted.

400

The body carries no keys array (error code invalid_url), or _stepId is neither an ObjectId nor tool_input / tool_output (error code invalid_ref).

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

The tool does not exist, or _stepId is an ObjectId that is not a step defined directly in this tool. Error code: invalid_ref.

application/json

delete/v1/tools/{_id}/{_stepId}/requests

DELETE /v1/tools/{_id}/{_stepId}/requests HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "keys": [
    "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST",
    "5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST"
  ]
}

{
  "deleted": [
    "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST",
    "5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST"
  ],
  "errors": []
}

Get a captured debug request for a tool step

get

/v1/tools/{_id}/{_stepId}/requests/{key}

Returns the full detail of a single captured debug request for a tool step, identified by its key. Obtain the key from GET /v1/tools/{_id}/{_stepId}/requests.

For an HTTP or NetSuite step the record carries the adaptor HTTP request/response the step issued, with credentials masked and the bodies as strings. For the tool_input and tool_output stages (and a ToolImport step) the record is synthetic: request.body is the JSON record entering the stage, response.body is the validated JSON record (statusCode 200) or the validation errors (statusCode 422), the request carries no url, and context names the run that produced it. Synthetic bodies are stored unmasked. Every record carries the key, record id, and capture time.

Requires the manage:tool:logs permission.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

_stepIdstringRequired

The step the captured request belongs to: the ObjectId of an export or import step defined directly in this tool's routers, or the virtual stage id tool_input or tool_output. Steps nested inside a child tool are addressed on that child tool's id; an ObjectId that is not a direct step of this tool returns 404 invalid_ref. Any other value — including reserved path segments such as invocations, invoke, and test — returns 400 invalid_ref.

Example: 67ee026136f4d1eeb529ad63

keystringRequired

Key identifying the captured debug request, from the GET /v1/tools/{_id}/{_stepId}/requests listing.

Responses

200

The captured debug request detail.

application/json

A single captured debug request record, including the captured request/response payloads.

keystringOptional

Echoes the key path parameter.

idstringOptional

Internal storage id parsed from the log filename.

timeinteger · int64Optional

Epoch milliseconds when this pair was stored.

Other propertiesanyOptional

400

_stepId is neither an ObjectId nor tool_input / tool_output. Error code: invalid_ref.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

The tool or the step does not exist (invalid_ref), or no record carries this key (file_not_found).

application/json

get/v1/tools/{_id}/{_stepId}/requests/{key}

GET /v1/tools/{_id}/{_stepId}/requests/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "key": "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST-lookup-60a2c4e6f321d800129a1a3c",
  "id": "a10af1ade8fe477a847771c1e3716e36",
  "time": 1776917346304,
  "request": {
    "method": "POST",
    "url": "https://httpbin.org/post",
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"orderId\":\"SO-1042\"}"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"ok\":true}",
    "receivedAt": 1776917346302
  }
}