Skip to main content
POST
/
v1
/
integrations
/
{integrationId}
/
tools
/
{toolId}
/
execute
Execute Tool
curl --request POST \
  --url https://api.sigmamind.ai/v1/integrations/{integrationId}/tools/{toolId}/execute \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "placeholders": {
    "customerId": "7654321"
  },
  "authId": "auth_P3kNz7Yv1Qm9"
}
'
{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. To get your key, go to Dashboard → API Keys and create or copy your Production API key.

Path Parameters

​
integrationId
string
required

Unique identifier of the integration to which the tool belongs.

​
toolId
string
required

Unique identifier of the tool to execute.

Body

application/json

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"}.

Example:
{ "customerId": "7654321" }
​
authId
string

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

Maximum string length: 64
Example:

"auth_P3kNz7Yv1Qm9"

Response

OK

Result of executing a tool against its configured third-party API.

​
toolId
string

Unique identifier of the tool that was executed.

Example:

"tool_X9pLm2Wq8Rt3"

​
integrationId
string

Unique identifier of the integration this tool belongs to.

Example:

"intg_AuUKK371Spr5"

​
url
string

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

Example:

"https://my-store.myshopify.com/admin/api/2024-01/customers/7654321.json"

​
method
string

The HTTP method used for the request.

Example:

"GET"

​
statusCode
integer<int32>

HTTP status code returned by the third-party API.

Example:

200

​
success
boolean

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

Example:

true

​
responseBody
object

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.

Example:
{
  "customer_name": "Michael",
  "account_id": "ACC-001"
}
​
responseHeaders
object

Response headers returned by the third-party API.

Example:
{
  "Content-Type": "application/json; charset=utf-8"
}
​
errorMessage
string

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

Example:

"404 Not Found: {\"errors\": \"Customer not found\"}"

​
durationMs
integer<int64>

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

Example:

342

​
executedAt
string<date-time>

Timestamp when the execution was triggered.

Example:

"2024-04-20T10:00:00.000Z"