---
title: "Execute Tool"
method: POST
path: "/v1/integrations/{integrationId}/tools/{toolId}/execute"
tags: ["Integration Tools"]
---

# Execute Tool

`POST /v1/integrations/{integrationId}/tools/{toolId}/execute`

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.

## Path parameters

- `integrationId` string, required
- `toolId` string, required

## Request body

- ExecuteToolRequest — Request body to execute a tool against its configured third-party API. Supply values for every {{variable}} placeholder declared in the tool's endpoint, queryParams, and bodyParams. The tool's stored auth credentials are resolved automatically — you do not need to pass credentials here.
  - `placeholders` object — 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"}.
  - `authId` string — The authId of the credential set to use for this execution.

## Response `200`

OK

- ExecuteToolResponse — Result of executing a tool against its configured third-party API.
  - `toolId` string — Unique identifier of the tool that was executed.
  - `integrationId` string — Unique identifier of the integration this tool belongs to.
  - `url` string — The fully resolved URL that was called, with all {{variable}} placeholders substituted.
  - `method` string — The HTTP method used for the request.
  - `statusCode` integer — HTTP status code returned by the third-party API.
  - `success` boolean — Whether the third-party API returned a 2xx success response.
  - `responseBody` JsonNode — 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.
  - `responseHeaders` object — Response headers returned by the third-party API.
  - `errorMessage` string — Error message when success is false — contains the raw error body or exception message.
  - `durationMs` integer — How long the third-party API took to respond, in milliseconds.
  - `executedAt` string, date-time — Timestamp when the execution was triggered.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/sigmamind/apis/sigmamind-apis.md) · [All operations](https://skmtc.net/sigmamind/apis/sigmamind-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sigmamind/sigmamind-apis/versions/d00f52b5123f/schema)