Run

List Runs

get

Retrieves a paginated list of runs for the authenticated user

Authorizations

x-api-key

x-api-keystringRequired

Query parameters

includeEventsbooleanOptionalDefault: false

pagenumber · min: 1 · max: 1000OptionalDefault: 1

pageSizenumber · min: 1 · max: 100OptionalDefault: 10

Responses

200

Runs retrieved successfully

application/json

401

Unauthorized - invalid API key

500

Internal server error

get

/v1/runs

HTTPcURLJavaScriptPython

GET /v1/runs HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Accept: */*

[
  {
    "runId": "123e4567-e89b-12d3-a456-426614174000",
    "repeatKey": "text",
    "repeatRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "RUNNING",
    "stepsFinished": [
      {}
    ],
    "result": {},
    "intent": "Create a summary of the latest sales data",
    "context": "Focus on Q4 2023 data with regional breakdown",
    "createdAt": "2025-12-23T17:22:13.041Z",
    "updatedAt": "2025-12-23T17:22:13.041Z"
  }
]

Create a new Run

post

Creates a new run with the specified intent and selected integrations

Authorizations

x-api-key

x-api-keystringRequired

Body

application/json

intentstringRequired

The intent or goal for the run

Example: Create a summary of the latest sales data

selectedCustomerIntegrationIdsstring[]Required

Array of selected customer integration IDs to use for the run, or use ["*"] to include all active integrations

Example: ["integration-1","integration-2"]

contextstringRequired

Additional context for the run execution

Example: Focus on Q4 2023 data with regional breakdown

userIdstringRequired

The ID of the user who is initiating the run

Example: user-123

approvalStrategystring · enumOptional

Approval strategy for the run

Example: NONEPossible values:

repeatKeystring · stringOptional

The key of the run to repeat

outputSchemaobject · json-schemaOptional

JSON Schema draft 7 schema for the run output format

passThroughobject[]Optional

Pass through data for the run, e.g. credentials for the integrations used in the run

Example: [{"customerIntegrationId":"integration-1","headers":{"Authorization":"Bearer 1234567890"}}]

Responses

201

Run successfully created

application/json

400

Invalid request body or parameters

401

Unauthorized - invalid API key

post

/v1/runs

HTTPcURLJavaScriptPython

POST /v1/runs HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 368

{
  "intent": "Create a summary of the latest sales data",
  "selectedCustomerIntegrationIds": [
    "integration-1",
    "integration-2"
  ],
  "context": "Focus on Q4 2023 data with regional breakdown",
  "userId": "user-123",
  "approvalStrategy": "NONE",
  "repeatKey": "text",
  "outputSchema": {},
  "passThrough": [
    {
      "customerIntegrationId": "integration-1",
      "headers": {
        "Authorization": "Bearer 1234567890"
      }
    }
  ]
}

{
  "runId": "123e4567-e89b-12d3-a456-426614174000",
  "repeatKey": "text",
  "status": "QUEUED",
  "stepsFinished": [
    {}
  ],
  "plan": {
    "planType": "json",
    "plan": {}
  },
  "repeatRunId": "123e4567-e89b-12d3-a456-426614174000"
}

Approve or deny a run or its individual steps

get

Approve or deny a run or its individual steps

Authorizations

x-api-key

x-api-keystringRequired

Query parameters

tokenstringRequired

Responses

201

Approval handled

application/json

400

Invalid request body or parameters

401

Unauthorized - invalid API key

get

/v1/runs/approval

HTTPcURLJavaScriptPython

GET /v1/runs/approval?token=text HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Accept: */*

No content

Get Run details

get

Retrieves detailed information about a specific run

Authorizations

x-api-key

x-api-keystringRequired

Path parameters

runIdstring · uuidRequired

Unique identifier of the run to retrieve

Responses

200

Run details retrieved successfully

application/json

401

Unauthorized - invalid API key

404

Run not found

get

/v1/runs/{runId}

HTTPcURLJavaScriptPython

GET /v1/runs/{runId} HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Accept: */*

{
  "runId": "123e4567-e89b-12d3-a456-426614174000",
  "repeatKey": "text",
  "repeatRunId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "RUNNING",
  "stepsFinished": [
    {}
  ],
  "result": {},
  "intent": "Create a summary of the latest sales data",
  "context": "Focus on Q4 2023 data with regional breakdown",
  "createdAt": "2025-12-23T17:22:13.041Z",
  "updatedAt": "2025-12-23T17:22:13.041Z"
}

Abort a Run

delete

Aborts a running or queued run by its ID

Authorizations

x-api-key

x-api-keystringRequired

Path parameters

runIdstring · uuidRequired

Unique identifier of the run to abort

Responses

200

Run successfully aborted

No content

401

Unauthorized - invalid API key

404

Run not found

delete

/v1/runs/{runId}

HTTPcURLJavaScriptPython

DELETE /v1/runs/{runId} HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Accept: */*

No content

Server-Sent Events stream for a Run

get

Establishes a Server-Sent Events connection to stream real-time updates for a run

Authorizations

x-api-key

x-api-keystringRequired

Path parameters

runIdstring · uuidRequired

Unique identifier of the run to stream events for

Responses

200

SSE stream established successfully

text/event-stream

Responsestring

Server-sent events stream with run updates

401

Unauthorized - invalid API key

404

Run not found

500

Internal server error or stream error

get

/v1/runs/{runId}/sse

HTTPcURLJavaScriptPython

GET /v1/runs/{runId}/sse HTTP/1.1
Host: api.toolregistry.ai
x-api-key: YOUR_API_KEY
Accept: */*

text