Get Started

Follow this guide to run the full assistant API lifecycle.

0. Prerequisites

You need an API key and a target environment URL.

Create an API key in API Keys, then export env vars:

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

1. Purchase a Slot

Create a prebuy slot and receive a checkout URL.

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

Copy data.deploymentId into DEPLOYMENT_ID, then open data.checkoutUrl and complete payment.

2. Activate the Slot

Configure assistant settings and trigger deployment.

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 API Assistant",
    "modelProvider": "anthropic",
    "modelId": "claude-sonnet-4-5-20250929",
    "telegramBotToken": "<TELEGRAM_BOT_TOKEN>",
    "modelApiKey": "<MODEL_API_KEY>",
    "callbackUrl": "https://example.com/deploy-callback"
  }'

3. Check Status

Poll status until deployment becomes active or failed.

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

4. Manage Lifecycle

Stop, redeploy, patch config, and delete.

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

# Redeploy
curl -X POST "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/redeploy" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Patch config (allowed in purchased/stopped/failed)
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 Name"}'

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

Troubleshooting

Common issues when testing locally.

401 Unauthorized: API key missing or invalid.

409 Invalid state: endpoint called in wrong lifecycle state (for example activate before purchase).

callbackUrl rejected: must be public https and not localhost/private IP.

No Polar locally: simulate purchase by setting deployment status to purchased in DB before calling activate.