API Reference

The Bearer Token is the TOOLHOUSE_API_KEY. You can find your API key(s) here.

Get All Agent Runs

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Agent runs successfully retrieved

application/json

500

Internal server error

get

/v1/agent-runs

HTTPcURLJavaScriptPython

GET /v1/agent-runs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "chat_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "text",
      "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "queued",
      "results": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "created_at": "2026-01-19T00:06:05.133Z",
      "updated_at": "2026-01-19T00:06:05.133Z",
      "bundle": "default",
      "toolhouse_id": "default",
      "vars": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "callback_url": "https://example.com",
      "error": "text"
    }
  ]
}

Create Agent Run

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

chat_idstring · uuidRequired

schedule_idany ofOptional

string · uuidOptional

or

nullOptional

bundlestringOptionalDefault: default

toolhouse_idstringOptionalDefault: default

varsany ofOptional

or

nullOptional

callback_urlany ofOptional

string · uri · min: 1Optional

or

nullOptional

Responses

200

Agent run successfully created

application/json

403

Chat ID is invalid or does not belong to you

422

Validation Error

application/json

500

Internal server error

post

/v1/agent-runs

HTTPcURLJavaScriptPython

POST /v1/agent-runs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226

{
  "chat_id": "123e4567-e89b-12d3-a456-426614174000",
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "bundle": "default",
  "toolhouse_id": "default",
  "vars": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "callback_url": "https://example.com"
}

No content

Get Agent Run

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

run_idstring · uuidRequired

Responses

200

Agent run successfully retrieved

application/json

403

Chat ID associated to this Agent Run is invalid

404

Agent run not found

422

Validation Error

application/json

500

Internal server error

get

/v1/agent-runs/{run_id}

HTTPcURLJavaScriptPython

GET /v1/agent-runs/{run_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "chat_id": "123e4567-e89b-12d3-a456-426614174000",
    "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
    "results": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "status": "queued",
    "created_at": "2026-01-19T00:06:05.133Z",
    "updated_at": "2026-01-19T00:06:05.133Z",
    "bundle": "default",
    "toolhouse_id": "default",
    "vars": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "callback_url": "https://example.com",
    "last_agent_message": "text"
  }
}

Put Agent Run

put

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

run_idstring · uuidRequired

Body

application/json

messagestringRequired

Responses

200

Agent run successfully updated

application/json

403

Chat ID is invalid or does not belong to you

406

You can only add messages to completed runs

422

Validation Error

application/json

500

Internal server error

put

/v1/agent-runs/{run_id}

HTTPcURLJavaScriptPython

PUT /v1/agent-runs/{run_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "message": "text"
}

No content