getclaw

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"required

Select whether the deployment uses your own model key or managed credits.

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
  }
}