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",
    "events": [
      {}
    ],
    "result": {},
    "intent": "Create a summary of the latest sales data",
    "context": "Focus on Q4 2023 data with regional breakdown",
    "createdAt": "2026-02-07T11:31:58.131Z",
    "updatedAt": "2026-02-07T11:31:58.131Z"
  }
]

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",
  "events": [
    {}
  ],
  "executionPlanId": "123e4567-e89b-12d3-a456-426614174000",
  "plan": {
    "planType": "json",
    "plan": {
      "description": "Gather information needed for a financial report",
      "steps": [
        {
          "id": "step-1",
          "description": "Fetch all invoices from the last 30 days",
          "dependsOnSteps": [
            "step-0"
          ]
        }
      ]
    }
  },
  "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

Query parameters

includeEventsstringOptional

Include run events in the response (e.g., "true" or "false")

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",
  "events": [
    {}
  ],
  "result": {},
  "intent": "Create a summary of the latest sales data",
  "context": "Focus on Q4 2023 data with regional breakdown",
  "createdAt": "2026-02-07T11:31:58.131Z",
  "updatedAt": "2026-02-07T11:31:58.131Z"
}

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

Query parameters

includeToolCallsstringOptional

Include tool call details in the stream (e.g., "true" or "false"). By default, tool calls are not included and for step events, only text (description of the step) is included.

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