API Reference

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

Get All Agent Runs

get

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/agent-runs' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

{
  "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": [
        {}
      ],
      "created_at": "2025-03-31T18:26:01.161Z",
      "updated_at": "2025-03-31T18:26:01.161Z",
      "bundle": "text",
      "toolhouse_id": "text",
      "vars": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "callback_url": "https://example.com"
    }
  ]
}

Successful Response

Create Agent Run

post

Authorizations

Body

chat_idstring · uuidrequired

schedule_idany ofoptional

bundlestring · default: "default"optional

toolhouse_idstring · default: "default"optional

varsany ofoptional

callback_urlany ofoptional

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/agent-runs' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "chat_id": "123e4567-e89b-12d3-a456-426614174000",
    "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
    "bundle": "text",
    "toolhouse_id": "text",
    "vars": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "callback_url": "https://example.com"
  }'

200

422

200

No body

Successful Response

Get Agent Run

get

Authorizations

Path parameters

run_idstring · uuidrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/agent-runs/{run_id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

422

200

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "chat_id": "123e4567-e89b-12d3-a456-426614174000",
    "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
    "results": [
      {}
    ],
    "status": "queued",
    "created_at": "2025-03-31T18:26:01.161Z",
    "updated_at": "2025-03-31T18:26:01.161Z",
    "bundle": "text",
    "toolhouse_id": "text",
    "vars": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "callback_url": "https://example.com",
    "last_agent_message": "text"
  }
}

Successful Response

Put Agent Run

put

Authorizations

Path parameters

run_idstring · uuidrequired

Body

messagestringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/v1/agent-runs/{run_id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "text"
  }'

200

422

200

No body

Successful Response