# Getclaw Assistants API v1 Reference (LLM Markdown)

This document mirrors `/docs/api-reference` and is optimized for machine parsing and retrieval.

## Global Conventions

- Base URL: `https://getclaw.sh` (or your self-hosted base URL)
- Auth header: `X-API-Key: <API_KEY>`
- Success envelope: `{ data: ... }`
- Error envelope: `{ error: { code, message, details? } }`
- Raw OpenAPI spec: `/api/openapi`

## Endpoint Index

- [purchase-assistant-slot](#purchase-assistant-slot) - `POST /api/v1/assistants/purchase` - Purchase assistant slot
- [activate-assistant](#activate-assistant) - `POST /api/v1/assistants/{deploymentId}/activate` - Activate assistant
- [assistant-status](#assistant-status) - `GET /api/v1/assistants/{deploymentId}/status` - Get assistant status
- [list-assistants](#list-assistants) - `GET /api/v1/assistants` - List assistants
- [get-assistant](#get-assistant) - `GET /api/v1/assistants/{deploymentId}` - Get assistant
- [update-assistant](#update-assistant) - `PATCH /api/v1/assistants/{deploymentId}` - Update assistant config
- [redeploy-assistant](#redeploy-assistant) - `POST /api/v1/assistants/{deploymentId}/redeploy` - Redeploy assistant
- [stop-assistant](#stop-assistant) - `POST /api/v1/assistants/{deploymentId}/stop` - Stop assistant
- [delete-assistant](#delete-assistant) - `DELETE /api/v1/assistants/{deploymentId}` - Delete assistant

## Endpoints

### purchase-assistant-slot

- Method: `POST`
- Path: `/api/v1/assistants/purchase`
- Title: Purchase assistant slot
- Summary: Creates a prebuy deployment slot and returns a Polar checkout URL.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
_None._

#### Request Body Fields
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `apiMode` | `"byok" | "managed" | "unlimited"` | Yes | Select whether the deployment uses your own model key (byok), included monthly credits (managed), or the higher unlimited allowance. |

#### Example Requests
##### cURL (bash)
```bash
curl -X POST "$BASE_URL/api/v1/assistants/purchase" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiMode": "byok"
  }'
```

##### TypeScript (ts)
```ts
const response = await fetch("${BASE_URL}/api/v1/assistants/purchase", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ apiMode: "byok" }),
});

const json = await response.json();
if (response.ok) {
  console.log(json.data.deploymentId, json.data.checkoutUrl);
}
```

#### Success Responses
##### 201 Checkout session created.
```json
{
  "data": {
    "deploymentId": "dep_1234567890abcdef",
    "checkoutUrl": "https://polar.sh/checkout/session_abc123"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 400 | `INVALID_REQUEST` | Invalid request body | Body is missing required keys or includes unknown keys. |
| 500 | `PAYMENT_NOT_CONFIGURED` | Payment system not configured | Product IDs are missing from server environment configuration. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

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

### activate-assistant

- Method: `POST`
- Path: `/api/v1/assistants/{deploymentId}/activate`
- Title: Activate assistant
- Summary: Configures a purchased prebuy slot and starts deployment.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Assistant name. |
|  |  |  | Constraints: 1-100 characters |
| `modelProvider` | `string` | No | Required for BYOK mode. Managed mode enforces openrouter internally. |
| `modelId` | `string` | Yes | Model identifier. |
| `telegramBotToken` | `string` | Yes | Telegram bot token for channel delivery. |
| `modelApiKey` | `string` | No | Required for BYOK mode; ignored for managed mode. |
| `callbackUrl` | `string (URL)` | No | Public callback endpoint to receive deployment status updates. |
|  |  |  | Constraints: Must be https; Max length 2048; Hostname cannot be localhost/private/link-local/loopback |

#### Example Requests
##### cURL (bash)
```bash
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"
  }'
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}/activate",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Assistant",
      modelProvider: "anthropic",
      modelId: "claude-sonnet-4-5-20250929",
      telegramBotToken: process.env.TELEGRAM_BOT_TOKEN,
      modelApiKey: process.env.MODEL_API_KEY,
      callbackUrl: "https://example.com/deploy-callback",
    }),
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Activation accepted; deployment begins.
```json
{
  "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"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 400 | `INVALID_REQUEST` | Invalid request body | Body fails schema validation. |
| 400 | `INVALID_INPUT` | Activation payload is inconsistent with deployment mode | Example: missing BYOK modelApiKey/modelProvider or unknown model. |
| 409 | `INVALID_STATE` | Deployment must be in purchased prebuy state to activate | Slot is not currently `purchased` with `isPrebuy=true`. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

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

### assistant-status

- Method: `GET`
- Path: `/api/v1/assistants/{deploymentId}/status`
- Title: Get assistant status
- Summary: Returns lightweight deployment state for polling.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
_None._

#### Example Requests
##### cURL (bash)
```bash
curl -X GET "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/status" \
  -H "X-API-Key: $API_KEY"
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}/status",
  {
    method: "GET",
    headers: { "X-API-Key": process.env.API_KEY! },
  }
);

const json = await response.json();
console.log(json.data.status);
```

#### Success Responses
##### 200 Current deployment status returned.
```json
{
  "data": {
    "id": "dep_1234567890abcdef",
    "status": "active",
    "statusMessage": null,
    "workerUrl": "https://openclaw-ab12cd34.workers.dev"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

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

### list-assistants

- Method: `GET`
- Path: `/api/v1/assistants`
- Title: List assistants
- Summary: Returns all assistants owned by the authenticated user.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
_None._

#### Request Body Fields
_None._

#### Example Requests
##### cURL (bash)
```bash
curl -X GET "$BASE_URL/api/v1/assistants" \
  -H "X-API-Key: $API_KEY"
```

##### TypeScript (ts)
```ts
const response = await fetch("${BASE_URL}/api/v1/assistants", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.API_KEY!,
  },
});

const json = await response.json();
if (!response.ok) {
  console.error(json.error);
} else {
  console.log(json.data);
}
```

#### Success Responses
##### 200 Assistants list returned.
```json
{
  "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"
    }
  ]
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

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

### get-assistant

- Method: `GET`
- Path: `/api/v1/assistants/{deploymentId}`
- Title: Get assistant
- Summary: Fetches a single assistant deployment record by ID.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
_None._

#### Example Requests
##### cURL (bash)
```bash
curl -X GET "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID" \
  -H "X-API-Key: $API_KEY"
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}",
  {
    method: "GET",
    headers: { "X-API-Key": process.env.API_KEY! },
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Assistant details returned.
```json
{
  "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"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

### update-assistant

- Method: `PATCH`
- Path: `/api/v1/assistants/{deploymentId}`
- Title: Update assistant config
- Summary: Updates mutable assistant configuration fields.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | No | Assistant display name. |
|  |  |  | Constraints: 1-100 characters |
| `modelProvider` | `string` | No | Provider ID (required for some BYOK model changes). |
| `modelId` | `string` | No | Model identifier. |
| `telegramBotToken` | `string` | No | Telegram bot token to replace the current one. |
| `modelApiKey` | `string` | No | Model provider API key (BYOK only). |

#### Example Requests
##### cURL (bash)
```bash
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"
  }'
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Updated Assistant" }),
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Assistant updated.
```json
{
  "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"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 400 | `INVALID_REQUEST` | Invalid request body | Body fails schema validation (including empty body with no update fields). |
| 400 | `INVALID_INPUT` | Model provider/model combination is invalid | Provided provider/model values are not allowed for deployment mode. |
| 409 | `INVALID_STATE` | Deployment can only be updated when status is purchased, stopped, or failed | Patch is attempted while deployment is not editable. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

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

### redeploy-assistant

- Method: `POST`
- Path: `/api/v1/assistants/{deploymentId}/redeploy`
- Title: Redeploy assistant
- Summary: Starts a fresh deployment for an active/failed/stopped assistant.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `callbackUrl` | `string (URL)` | No | Optional callback URL update for this deployment. |
|  |  |  | Constraints: Must be https; Max length 2048; Hostname cannot be localhost/private/link-local/loopback |

#### Example Requests
##### cURL (bash)
```bash
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"
  }'
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}/redeploy",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ callbackUrl: "https://example.com/deploy-callback" }),
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Redeploy accepted; status moves to deploying.
```json
{
  "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"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 400 | `INVALID_REQUEST` | Invalid request body | Body fails schema validation. |
| 409 | `INVALID_STATE` | Deployment can only be redeployed when status is active, failed, or stopped | Current status is outside allowed redeploy states. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

### stop-assistant

- Method: `POST`
- Path: `/api/v1/assistants/{deploymentId}/stop`
- Title: Stop assistant
- Summary: Stops a deployment and deletes the current worker.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
_None._

#### Example Requests
##### cURL (bash)
```bash
curl -X POST "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID/stop" \
  -H "X-API-Key: $API_KEY"
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}/stop",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.API_KEY! },
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Assistant stopped.
```json
{
  "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"
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 502 | `WORKER_DELETE_FAILED` | Failed to delete deployed worker before stopping | Worker deletion failed with a non-404 upstream response. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |

### delete-assistant

- Method: `DELETE`
- Path: `/api/v1/assistants/{deploymentId}`
- Title: Delete assistant
- Summary: Deletes an assistant deployment and attempts worker/subscription cleanup.
- Auth: Required via X-API-Key header.

#### Headers
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `string` | Yes | Your API key from the dashboard API Keys page. |

#### Path Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | `string (UUID)` | Yes | Assistant deployment ID returned from purchase or list endpoints. |

#### Request Body Fields
_None._

#### Example Requests
##### cURL (bash)
```bash
curl -X DELETE "$BASE_URL/api/v1/assistants/$DEPLOYMENT_ID" \
  -H "X-API-Key: $API_KEY"
```

##### TypeScript (ts)
```ts
const response = await fetch(
  "${BASE_URL}/api/v1/assistants/${DEPLOYMENT_ID}",
  {
    method: "DELETE",
    headers: { "X-API-Key": process.env.API_KEY! },
  }
);

const json = await response.json();
console.log(json);
```

#### Success Responses
##### 200 Assistant deleted.
```json
{
  "data": {
    "success": true
  }
}
```

#### Error Responses
| Status | Code | Message | When |
| --- | --- | --- | --- |
| 401 | `UNAUTHORIZED` | API key required or invalid API key | X-API-Key header is missing or invalid. |
| 404 | `NOT_FOUND` | Deployment not found | The deployment does not exist or does not belong to the API key owner. |
| 502 | `WORKER_DELETE_FAILED` | Failed to delete deployed worker before deleting assistant | Worker deletion failed with a non-404 upstream response. |
| 404 | `API_DISABLED` | Assistant v1 API is disabled | ASSISTANTS_API_V1_ENABLED is false. |
| 500 | `INTERNAL_ERROR` | Unexpected server error | Unhandled internal exception. |