Assistants

API Reference

Detailed reference for every v1 assistants endpoint. All success responses use{ data: ... }and errors use{ error: { code, message, details? } }.

Raw OpenAPI spec:/api/openapi

Setup

Export these values before running request examples.

export BASE_URL="https://getclaw.sh"
export API_KEY="<YOUR_API_KEY>"
export DEPLOYMENT_ID="<DEPLOYMENT_ID>"

Purchase assistant slot

Creates a prebuy deployment slot and returns a Polar checkout URL.

POST/api/v1/assistants/purchase

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Request Body

apiMode"byok" | "managed" | "unlimited"required

Select whether the deployment uses your own model key (byok), included monthly credits (managed), or the higher unlimited allowance.

Notes

This endpoint only creates the slot and checkout link. Deployment activation is a separate call.
Complete checkout before calling activate.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

400INVALID_REQUEST

Invalid request body

Body is missing required keys or includes unknown keys.

500PAYMENT_NOT_CONFIGURED

Payment system not configured

Product IDs are missing from server environment configuration.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X POST "$BASE_URL/api/v1/assistants/purchase" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiMode": "byok"
  }'

Response

201

Checkout session created.

{
  "data": {
    "deploymentId": "dep_1234567890abcdef",
    "checkoutUrl": "https://polar.sh/checkout/session_abc123"
  }
}

Activate assistant

Configures a purchased prebuy slot and starts deployment.

POST/api/v1/assistants/{deploymentId}/activate

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Request Body

namestringrequired

Assistant name.

Constraints: 1-100 characters

modelProviderstring

Required for BYOK mode. Managed mode enforces openrouter internally.

modelIdstringrequired

Model identifier.

telegramBotTokenstringrequired

Telegram bot token for channel delivery.

modelApiKeystring

Required for BYOK mode; ignored for managed mode.

callbackUrlstring (URL)

Public callback endpoint to receive deployment status updates.

Constraints: Must be https; Max length 2048; Hostname cannot be localhost/private/link-local/loopback

Notes

Activation transitions the deployment status to `deploying`.
This endpoint is only valid after successful checkout payment.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

400INVALID_REQUEST

Invalid request body

Body fails schema validation.

400INVALID_INPUT

Activation payload is inconsistent with deployment mode

Example: missing BYOK modelApiKey/modelProvider or unknown model.

409INVALID_STATE

Deployment must be in purchased prebuy state to activate

Slot is not currently `purchased` with `isPrebuy=true`.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X POST "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/activate" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "telegramBotToken": "<TELEGRAM_BOT_TOKEN>",
    "modelApiKey": "<MODEL_API_KEY>",
    "callbackUrl": "https://example.com/deploy-callback"
  }'

Response

200

Activation accepted; deployment begins.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "userId": "usr_1234567890abcdef",
    "organizationId": null,
    "name": "My API Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "channelType": "telegram",
    "apiMode": "byok",
    "workerName": "openclaw-ab12cd34",
    "workerUrl": null,
    "status": "deploying",
    "statusMessage": null,
    "paymentStatus": "paid",
    "polarSubscriptionId": "sub_1234",
    "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
    "canceledAt": null,
    "isPrebuy": false,
    "userCallbackUrl": "https://example.com/deploy-callback",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T12:00:00.000Z"
  }
}

Get assistant status

Returns lightweight deployment state for polling.

GET/api/v1/assistants/{deploymentId}/status

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Notes

Use this endpoint for polling until status becomes `active` or `failed`.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X GET "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/status" \
  -H "X-API-Key: $API_KEY"

Response

200

Current deployment status returned.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "status": "active",
    "statusMessage": null,
    "workerUrl": "https://openclaw-ab12cd34.workers.dev"
  }
}

List assistants

Returns all assistants owned by the authenticated user.

GET/api/v1/assistants

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Notes

Response envelope is always `{ data: ... }` on success.
Stale pending-payment deployments older than one hour are excluded.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X GET "$BASE_URL/api/v1/assistants" \
  -H "X-API-Key: $API_KEY"

Response

200

Assistants list returned.

{
  "data": [
    {
      "id": "dep_1234567890abcdef",
      "userId": "usr_1234567890abcdef",
      "organizationId": null,
      "name": "My API Assistant",
      "modelProvider": "anthropic",
      "modelId": "claude-sonnet-4-5-20250929",
      "channelType": "telegram",
      "apiMode": "byok",
      "workerName": "openclaw-ab12cd34",
      "workerUrl": null,
      "status": "deploying",
      "statusMessage": null,
      "paymentStatus": "paid",
      "polarSubscriptionId": "sub_1234",
      "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
      "canceledAt": null,
      "isPrebuy": false,
      "userCallbackUrl": "https://example.com/deploy-callback",
      "createdAt": "2026-02-13T12:00:00.000Z",
      "updatedAt": "2026-02-13T12:00:00.000Z"
    }
  ]
}

Get assistant

Fetches a single assistant deployment record by ID.

GET/api/v1/assistants/{deploymentId}

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X GET "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID" \
  -H "X-API-Key: $API_KEY"

Response

200

Assistant details returned.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "userId": "usr_1234567890abcdef",
    "organizationId": null,
    "name": "My API Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "channelType": "telegram",
    "apiMode": "byok",
    "workerName": "openclaw-ab12cd34",
    "workerUrl": null,
    "status": "deploying",
    "statusMessage": null,
    "paymentStatus": "paid",
    "polarSubscriptionId": "sub_1234",
    "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
    "canceledAt": null,
    "isPrebuy": false,
    "userCallbackUrl": "https://example.com/deploy-callback",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T12:00:00.000Z"
  }
}

Update assistant config

Updates mutable assistant configuration fields.

PATCH/api/v1/assistants/{deploymentId}

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Request Body

namestring

Assistant display name.

Constraints: 1-100 characters

modelProviderstring

Provider ID (required for some BYOK model changes).

modelIdstring

Model identifier.

telegramBotTokenstring

Telegram bot token to replace the current one.

modelApiKeystring

Model provider API key (BYOK only).

Notes

At least one body field is required.
Managed deployments enforce modelProvider=openrouter and reject modelApiKey updates.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

400INVALID_REQUEST

Invalid request body

Body fails schema validation (including empty body with no update fields).

400INVALID_INPUT

Model provider/model combination is invalid

Provided provider/model values are not allowed for deployment mode.

409INVALID_STATE

Deployment can only be updated when status is purchased, stopped, or failed

Patch is attempted while deployment is not editable.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X PATCH "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929"
  }'

Response

200

Assistant updated.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "userId": "usr_1234567890abcdef",
    "organizationId": null,
    "name": "Updated Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "channelType": "telegram",
    "apiMode": "byok",
    "workerName": "openclaw-ab12cd34",
    "workerUrl": null,
    "status": "deploying",
    "statusMessage": null,
    "paymentStatus": "paid",
    "polarSubscriptionId": "sub_1234",
    "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
    "canceledAt": null,
    "isPrebuy": false,
    "userCallbackUrl": "https://example.com/deploy-callback",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T12:10:00.000Z"
  }
}

Redeploy assistant

Starts a fresh deployment for an active/failed/stopped assistant.

POST/api/v1/assistants/{deploymentId}/redeploy

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Request Body

callbackUrlstring (URL)

Optional callback URL update for this deployment.

Constraints: Must be https; Max length 2048; Hostname cannot be localhost/private/link-local/loopback

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

400INVALID_REQUEST

Invalid request body

Body fails schema validation.

409INVALID_STATE

Deployment can only be redeployed when status is active, failed, or stopped

Current status is outside allowed redeploy states.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X POST "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/redeploy" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://example.com/deploy-callback"
  }'

Response

200

Redeploy accepted; status moves to deploying.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "userId": "usr_1234567890abcdef",
    "organizationId": null,
    "name": "My API Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "channelType": "telegram",
    "apiMode": "byok",
    "workerName": "openclaw-ab12cd34",
    "workerUrl": null,
    "status": "deploying",
    "statusMessage": null,
    "paymentStatus": "paid",
    "polarSubscriptionId": "sub_1234",
    "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
    "canceledAt": null,
    "isPrebuy": false,
    "userCallbackUrl": "https://example.com/deploy-callback",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T12:00:00.000Z"
  }
}

Stop assistant

Stops a deployment and deletes the current worker.

POST/api/v1/assistants/{deploymentId}/stop

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

502WORKER_DELETE_FAILED

Failed to delete deployed worker before stopping

Worker deletion failed with a non-404 upstream response.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X POST "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/stop" \
  -H "X-API-Key: $API_KEY"

Response

200

Assistant stopped.

{
  "data": {
    "id": "dep_1234567890abcdef",
    "userId": "usr_1234567890abcdef",
    "organizationId": null,
    "name": "My API Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "channelType": "telegram",
    "apiMode": "byok",
    "workerName": "openclaw-ab12cd34",
    "workerUrl": null,
    "status": "stopped",
    "statusMessage": null,
    "paymentStatus": "paid",
    "polarSubscriptionId": "sub_1234",
    "currentPeriodEnd": "2026-03-13T12:00:00.000Z",
    "canceledAt": null,
    "isPrebuy": false,
    "userCallbackUrl": "https://example.com/deploy-callback",
    "createdAt": "2026-02-13T12:00:00.000Z",
    "updatedAt": "2026-02-13T12:20:00.000Z"
  }
}

Delete assistant

Deletes an assistant deployment and attempts worker/subscription cleanup.

DELETE/api/v1/assistants/{deploymentId}

Authentication

Required via X-API-Key header.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

502WORKER_DELETE_FAILED

Failed to delete deployed worker before deleting assistant

Worker deletion failed with a non-404 upstream response.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X DELETE "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID" \
  -H "X-API-Key: $API_KEY"

Response

200

Assistant deleted.

{
  "data": {
    "success": true
  }
}

Chat completions

OpenAI-compatible chat endpoint backed by your Hermes assistant. Supports streaming SSE and server-side conversation history.

POST/api/v1/assistants/{deploymentId}/chat/completions

Authentication

Required via X-API-Key header or Authorization: Bearer <key>. Use either — Bearer lets stock OpenAI SDKs talk to this endpoint with no header customization.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Authorizationstring

Alternative to X-API-Key. Format: `Bearer <YOUR_API_KEY>`. Use this when pointing OpenAI SDKs at the endpoint.

X-Hermes-Session-Idstring

Optional opaque conversation id. Hermes persists message history per session in container-local SQLite, so subsequent requests with the same id get full context without you replaying past turns. Omit for stateless one-shot calls.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Request Body

modelstringrequired

Use `hermes-agent` to invoke the model and tools configured on the deployment. The Hermes runtime resolves it to the underlying provider/model selected during activation.

messagesChatMessage[]required

OpenAI-style array of `{ role: 'system' | 'user' | 'assistant', content: string }`. Only the new user turn is required when X-Hermes-Session-Id is set — Hermes owns the prior history.

streamboolean

When true, response is `text/event-stream` with OpenAI `chat.completion.chunk` data events plus `event: hermes.tool.progress` frames carrying `{ tool, emoji, label }` for in-flight tool calls. Defaults to false.

max_tokensnumber

Optional cap on output tokens (provider-dependent).

temperaturenumber

Sampling temperature. Forwarded to the underlying provider as-is.

Notes

Authentication accepts either `X-API-Key: <KEY>` or `Authorization: Bearer <KEY>` — both validate against your getclaw API keys.
Conversation history: pass `X-Hermes-Session-Id` to let Hermes persist turns server-side. Without it, every call is stateless.
Streaming: response uses Server-Sent Events. In addition to OpenAI `chat.completion.chunk` data events, Hermes emits `event: hermes.tool.progress` frames with `{ tool, emoji, label }` while tools are running. Treat unknown events as opaque metadata.
The endpoint forwards the request body verbatim; any OpenAI-compatible parameter (e.g. `temperature`, `max_tokens`, `top_p`) supported by your assistant's underlying model provider works.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

400INVALID_REQUEST

Request body is required

Body is empty.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

409UNSUPPORTED_FRAMEWORK

Chat API is only available for Hermes assistants

The deployment is not a Hermes assistant.

409ASSISTANT_NOT_READY

Assistant is not active

The deployment status is not `active`, or the worker URL / gateway token has not been provisioned yet.

502BAD_GATEWAY

Assistant is unreachable

The upstream Hermes worker did not respond within 180 seconds, returned a connection error, or the proxy could not establish a stream.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -N -X POST \
  "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Say hi from Hermes." }
    ]
  }'

Response

200

When `stream: false`, OpenAI-style `chat.completion` JSON. When `stream: true`, an SSE stream of OpenAI `chat.completion.chunk` data events terminated by `data: [DONE]`. Tool progress frames may also appear with `event: hermes.tool.progress` carrying `{ tool, emoji, label }`.

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1735690000,
  "model": "hermes-agent",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi from Hermes."
      },
      "finish_reason": "stop"
    }
  ]
}

List models

OpenAI-compatible models listing for a single Hermes assistant. Returns the canonical `hermes-agent` entry.

GET/api/v1/assistants/{deploymentId}/models

Authentication

Required via X-API-Key header or Authorization: Bearer <key>.

Headers

X-API-Keystringrequired

Your API key from the dashboard API Keys page.

Path Parameters

deploymentIdstring (UUID)required

Assistant deployment ID returned from purchase or list endpoints.

Notes

Useful for OpenAI SDKs that probe `/v1/models` on init. The id `hermes-agent` is a magic alias the Hermes runtime resolves to whichever provider/model is configured on the deployment.

Error Responses

401UNAUTHORIZED

API key required or invalid API key

X-API-Key header is missing or invalid.

404NOT_FOUND

Deployment not found

The deployment does not exist or does not belong to the API key owner.

409UNSUPPORTED_FRAMEWORK

Chat API is only available for Hermes assistants

The deployment is not a Hermes assistant.

404API_DISABLED

Assistant v1 API is disabled

ASSISTANTS_API_V1_ENABLED is false.

500INTERNAL_ERROR

Unexpected server error

Unhandled internal exception.

Example Request

curl -X GET "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/models" \
  -H "X-API-Key: $API_KEY"

Response

200

List of models exposed by the assistant.

{
  "object": "list",
  "data": [
    {
      "id": "hermes-agent",
      "object": "model",
      "owned_by": "getclaw",
      "created": 1735690000
    }
  ]
}