Skip to main content
All chatbot management endpoints require session authentication. Requests are scoped to your organization — you can only access chatbots that belong to your org.

​
GET /api/v1/chatbots

List all chatbots in your organization. Auth: Session Response 200 OK: 
[
  {
    "id": "uuid",
    "name": "Support Bot",
    "api_key_prefix": "ob_live_a1b2c3...",
    "settings": { "onboarded": true },
    "created_at": "2024-01-15T10:00:00Z"
  }
]
The api_key_prefix field contains the first several characters of the API key for identification purposes. The full key is never returned from this endpoint.

​
POST /api/v1/chatbots

Create a new chatbot. Returns the full API key in the response. Auth: Session Request body: 
{ "name": "My Chatbot" }
Response 200 OK: 
{
  "ok": true,
  "chatbot": {
    "id": "uuid",
    "name": "My Chatbot",
    "api_key_prefix": "ob_live_a1b2c3...",
    "settings": {},
    "created_at": "2024-01-15T10:00:00Z"
  },
  "apiKey": "ob_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
Your API key is shown only once when you create or rotate it. Copy it immediately and store it securely. The full key cannot be recovered after you leave the page.

​
GET /api/v1/chatbots/:id

Get a single chatbot by ID. Auth: Session Response 200 OK: 
{
  "id": "uuid",
  "name": "Support Bot",
  "api_key_prefix": "ob_live_a1b2c3...",
  "settings": { "onboarded": true },
  "created_at": "2024-01-15T10:00:00Z"
}
The response has the same shape as a single item from the list endpoint.

​
PATCH /api/v1/chatbots/:id

Update a chatbot’s name or settings. Both fields are optional. When you include settings, the values are deep-merged with the existing settings object rather than replacing it. Auth: Session Request body: 
{
  "name": "New Name",
  "settings": { "userAnalysisEnabled": false }
}
Response 200 OK: 
{
  "id": "uuid",
  "name": "New Name",
  "api_key_prefix": "ob_live_a1b2c3...",
  "settings": { "onboarded": true, "userAnalysisEnabled": false },
  "created_at": "2024-01-15T10:00:00Z"
}

​
DELETE /api/v1/chatbots/:id

Permanently delete a chatbot and all its associated data, including conversations, messages, and analysis results. Auth: Session Response 200 OK: 
{ "ok": true }
Deleting a chatbot is permanent and cannot be undone. All conversations, messages, and analysis results associated with the chatbot are removed.

​
POST /api/v1/chatbots/:id/rotate-key

Generate a new API key for the chatbot. The old key is immediately invalidated — any requests using the previous key will return 401 Unauthorized. Auth: Session Response 200 OK: 
{
  "ok": true,
  "chatbot": {
    "id": "uuid",
    "name": "Support Bot",
    "api_key_prefix": "ob_live_d7e8f9...",
    "settings": { "onboarded": true },
    "created_at": "2024-01-15T10:00:00Z"
  },
  "apiKey": "ob_live_d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
}
Your API key is shown only once when you create or rotate it. Copy it immediately and store it securely. The full key cannot be recovered after you leave the page.
Update the key in all your integrations immediately after rotation to avoid downtime.