Skip to main content
POST
/
tools
/
{toolId}
/
run
Run a tool
curl --request POST \
  --url https://api.superglue.ai/v1/tools/{toolId}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "inputs": {
    "query": "latest AI news",
    "maxResults": 5
  },
  "credentials": {
    "apiKey": "sk_live_abc123def456",
    "apiSecret": "secret_xyz789"
  },
  "options": {
    "async": false,
    "timeout": 123,
    "webhookUrl": "https://your-app.com/webhooks/superglue",
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
'
{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "toolId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "metadata": {
    "startedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "durationMs": 5234
  },
  "tool": {
    "id": "<string>",
    "version": "2.1.0"
  },
  "toolPayload": {},
  "data": {},
  "error": "Connection timeout after 30 seconds",
  "stepResults": [
    {
      "stepId": "<string>",
      "success": true,
      "data": {},
      "error": "<string>"
    }
  ],
  "options": {},
  "requestSource": "api",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Authorizations

​
Authorization
string
header
required

Static API key authentication using Bearer token scheme. Include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY

API keys can be generated in your superglue dashboard.

Path Parameters

​
toolId
string
required

Body

application/json
​
runId
string

Optional pre-generated run ID. If not provided, server generates one. Useful for idempotency and tracking runs before they start.

Example:

"7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b"

​
inputs
object

Tool-specific input parameters

Example:
{
  "query": "latest AI news",
  "maxResults": 5
}
​
credentials
object

Runtime credentials for systems (overrides stored system credentials if provided). WARNING: These credentials are not persisted. Use systems for stored credentials.

Example:
{
  "apiKey": "sk_live_abc123def456",
  "apiSecret": "secret_xyz789"
}
​
options
object

Response

Tool execution completed (sync)

​
runId
string
required

Unique identifier for this run (maps to 'id' in GraphQL schema)

Example:

"7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b"

​
toolId
string
required

ID of the tool that was executed

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
status
enum<string>
required

Execution status:

  • running: Execution in progress
  • success: Completed successfully
  • failed: Failed due to error
  • aborted: Cancelled by user or system
Available options:
running,
success,
failed,
aborted
Example:

"success"

​
metadata
object
required
​
tool
object

Tool metadata (not full configuration, maps to 'toolConfig' in GraphQL)

​
toolPayload
object

The inputs and options provided when running the tool (maps to 'toolPayload' in GraphQL)

​
data
object

Tool execution results (only present when status is success, maps to 'toolResult' in GraphQL)

​
error
string

Error message (only present when status is failed or aborted)

Example:

"Connection timeout after 30 seconds"

​
stepResults
object[]

Results from each execution step (only for multi-step tools)

​
options
object

Execution options that were used for this run

​
requestSource
string

Source identifier for where the run was initiated

Example:

"api"

​
traceId
string

Trace ID for this run (for debugging and log correlation)

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"