Sign in

v1

latestOpenAPI 3.0.12026-07-226992320.0 KB
Integration Tools

Execute Tool

Executes a tool against its configured third-party API using the supplied placeholder values. Auth credentials are resolved automatically; specify authId to select specific credentials when multiple exist. Returns the raw response from the external API including status code, headers, and body.

post/v1/integrations/{integrationId}/tools/{toolId}/execute

Path parameters

integrationIdstring required

Unique identifier of the integration to which the tool belongs.

toolIdstring required

Unique identifier of the tool to execute.

Request body

placeholdersobject

A map of placeholder names to values used to resolve {{placeholder}} tokens in the tool's endpoint URL, query parameters, and request body at runtime. Each placeholder used in the request must have a corresponding entry in this map. Example: for endpoint '/customers/{{customerId}}.json', provide {"customerId": "7654321"}.

authIdstring

The authId of the credential set to use for this execution.

Example request

{
  "placeholders": {
    "customerId": "7654321"
  },
  "authId": "auth_P3kNz7Yv1Qm9"
}

Response

OK

toolIdstring

Unique identifier of the tool that was executed.

integrationIdstring

Unique identifier of the integration this tool belongs to.

urlstring

The fully resolved URL that was called, with all {{variable}} placeholders substituted.

methodstring

The HTTP method used for the request.

statusCodeinteger

HTTP status code returned by the third-party API.

successboolean

Whether the third-party API returned a 2xx success response.

responseBodyJsonNode

Dynamic key-value pairs that were passed to the agent at call start for personalisation. Keys correspond to variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). Null or empty if no dynamic variables were provided when the call was created.

responseHeadersobject

Response headers returned by the third-party API.

errorMessagestring

Error message when success is false — contains the raw error body or exception message.

durationMsinteger

How long the third-party API took to respond, in milliseconds.

executedAtstring date-time

Timestamp when the execution was triggered.

Example response

{
  "toolId": "tool_X9pLm2Wq8Rt3",
  "integrationId": "intg_AuUKK371Spr5",
  "url": "https://my-store.myshopify.com/admin/api/2024-01/customers/7654321.json",
  "method": "GET",
  "statusCode": 200,
  "success": true,
  "responseBody": {
    "customer_name": "Michael",
    "account_id": "ACC-001"
  },
  "responseHeaders": {
    "Content-Type": "application/json; charset=utf-8"
  },
  "errorMessage": "404 Not Found: {\"errors\": \"Customer not found\"}",
  "durationMs": 342,
  "executedAt": "2024-04-20T10:00:00.000Z"
}