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. This is a full replacement — GET the tool first, modify the fields you need, then PUT the full object back. Omitting a field removes it. 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: 592

{
  "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",
      "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",
      "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

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 concurrency is counted against the referenced connection's limit instead of maintaining its own.

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

_userIdstring · objectIdRead-onlyOptional

User who owns this connection.

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, the connection automatically backs off and retries when it encounters rate-limit errors from the target system.

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: */*

[]

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

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

Tool invocation error. May include invocationId when logging is active.

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: 52

{
  "input": {
    "customerId": "CUST-12345"
  },
  "overrides": {}
}

{
  "output": {
    "customerId": "CUST-12345"
  },
  "errors": [],
  "invocationId": "65b3a7f12c1e4a0009d5e3f1"
}

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 outbound requests the step issued, retained for troubleshooting. Use the key of an entry with GET /v1/tools/{_id}/{_stepId}/requests/{key} to fetch the full detail of a single captured request.

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

_stepIdstring · objectIdRequired

Export or import step id whose captured debug requests you want. Must be a step ObjectId — reserved path segments such as invocations, invoke, and test are not valid step ids.

Example: 67ee026136f4d1eeb529ad63

Responses

200

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

application/json

Debug request list envelope.

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}/{_stepId}/requests

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

{
  "requests": []
}

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the tool.

Example: 69d462d5b9c28ea0b7f82522

_stepIdstring · objectIdRequired

Export or import step id the captured request belongs to. Must be a step ObjectId — reserved path segments such as invocations, invoke, and test are not valid step ids.

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.

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

404

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

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": "6a2e23bbcf5b64ca6b93b774",
  "method": "POST",
  "url": "https://httpbin.org/post",
  "statusCode": 200
}