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

userIdstringOptional

Filter runs by user ID

Example: user_12345

statusstring · enumOptional

Filter runs by a single status value

Example: RUNNINGPossible values:

customerIntegrationIdsstring[]Optional

Filter runs by customer integration IDs. Use repeated query params, for example: ?customerIntegrationIds=salesforce_abcd1234&customerIntegrationIds=hubspot_efgh5678

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

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

Responses

200

Runs retrieved successfully

application/json

runIdstring · uuidRequired

Unique identifier for the run

repeatKeystring · stringRequired

Key passed or generated during creation to repeat the run later

repeatRunIdstring · uuidOptional

The UUID of the run that was repeated

statusstring · enumRequired

Current status of the run

Example: RUNNINGPossible values:

executionPlanIdstring · uuidRequired

The UUID of the execution plan that was used for the run

Example: 550e8400-e29b-41d4-a716-446655440000

eventsobject[]Required

Array of events in the run

resultobjectOptional

Result of the run execution

intentstringRequired

The intent or goal for the run

Example: Create a summary of the latest sales data

contextstringRequired

Additional context that was provided during run creation

Example: Focus on Q4 2023 data with regional breakdown

createdAtstring · date-timeRequired

Timestamp when the run was created

updatedAtstring · date-timeRequired

Timestamp when the run was last updated

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",
    "executionPlanId": "550e8400-e29b-41d4-a716-446655440000",
    "events": [
      {}
    ],
    "result": {},
    "intent": "Create a summary of the latest sales data",
    "context": "Focus on Q4 2023 data with regional breakdown",
    "createdAt": "2026-03-25T23:48:52.830Z",
    "updatedAt": "2026-03-25T23:48:52.830Z"
  }
]

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

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": "550e8400-e29b-41d4-a716-446655440000",
  "plan": {
    "planType": "json",
    "plan": {
      "title": "Monthly Revenue Report 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

runIdstring · uuidRequired

Unique identifier for the run

repeatKeystring · stringRequired

Key passed or generated during creation to repeat the run later

repeatRunIdstring · uuidOptional

The UUID of the run that was repeated

statusstring · enumRequired

Current status of the run

Example: RUNNINGPossible values:

executionPlanIdstring · uuidRequired

The UUID of the execution plan that was used for the run

Example: 550e8400-e29b-41d4-a716-446655440000

eventsobject[]Required

Array of events in the run

resultobjectOptional

Result of the run execution

intentstringRequired

The intent or goal for the run

Example: Create a summary of the latest sales data

contextstringRequired

Additional context that was provided during run creation

Example: Focus on Q4 2023 data with regional breakdown

createdAtstring · date-timeRequired

Timestamp when the run was created

updatedAtstring · date-timeRequired

Timestamp when the run was last updated

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",
  "executionPlanId": "550e8400-e29b-41d4-a716-446655440000",
  "events": [
    {}
  ],
  "result": {},
  "intent": "Create a summary of the latest sales data",
  "context": "Focus on Q4 2023 data with regional breakdown",
  "createdAt": "2026-03-25T23:48:52.830Z",
  "updatedAt": "2026-03-25T23:48:52.830Z"
}

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

stringOptional

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