SIsigmamind
Integration Tools

Execute Tool

Changed on

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. Optionally set saveAsMock to persist the live request/response as a named mock, or useMockToolDataId to return a stored mock without calling the third-party API. Returns the response body, status code, and optional mockToolDataId.

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

Request

  • Base URL
    https://api.sigmamind.ai
  • Auth
    API key in header X-API-Key

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",
  "saveAsMock": {
    "name": "Success - Order Confirmed",
    "agentId": "agent_D5D0p7TUs66TTAEAx",
    "toolAlias": "get_order"
  }
}

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.

mockToolDataIdstring

Public identifier of the mock created when saveAsMock was supplied on the execute request.

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:00Z",
  "mockToolDataId": "mock_HaDxmGfwb8MZLlKM"
}

Changes

  • 64c0435b10ebRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status