Chatbots | Developer API | Conversation Engine

List Chatbots

Returns a paginated list of all chatbots in the workspace.

http

GET /api/dev/v1/chatbots
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots
Authorization: Bearer <api-key>

Query Parameters

Parameters

limitintegeroptionaldefault: 29

Number of results per page. Min 1, max 37.

cursorstringoptional

Opaque pagination cursor returned from a previous response's next_cursor field.

bash

curl -X GET "http://localhost:3000/api/dev/v1/chatbots?limit=20" \
  -H "Authorization: Bearer <your-api-key>"curl -X GET "http://localhost:3000/api/dev/v1/chatbots?limit=20" \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots",
    headers={"Authorization": "Bearer <your-api-key>"},
    params={"limit": 20},
)
print(response.json())import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots",
    headers={"Authorization": "Bearer <your-api-key>"},
    params={"limit": 20},
)
print(response.json())

javascript

const params = new URLSearchParams({ limit: 20 });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots?${params}`,
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();const params = new URLSearchParams({ limit: 20 });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots?${params}`,
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();

Response - 200 OK

json

{
  "items": [
    {
      "id": "01JMXYZ...",
      "name": "Support Bot",
      "description": "Handles customer support queries",
      "is_active": true,
      "created_at": "2026-01-10T12:00:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxSk1YWVoifQ==",
  "total": 5
}{
  "items": [
    {
      "id": "01JMXYZ...",
      "name": "Support Bot",
      "description": "Handles customer support queries",
      "is_active": true,
      "created_at": "2026-01-10T12:00:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxSk1YWVoifQ==",
  "total": 5
}

Create Chatbot

Creates a new chatbot in the workspace.

http

POST /api/dev/v1/chatbots
Authorization: Bearer <api-key>
Content-Type: application/jsonPOST /api/dev/v1/chatbots
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

Body

namestringrequired

Chatbot display name. Must be unique within the workspace.

descriptionstringoptional

Optional description of the chatbot's purpose.

categorystringoptional

Optional category label (e.g. support, sales, onboarding).

bash

curl -X POST http://localhost:3000/api/dev/v1/chatbots \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "description": "Handles tier-1 customer support",
    "category": "support"
  }'curl -X POST http://localhost:3000/api/dev/v1/chatbots \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "description": "Handles tier-1 customer support",
    "category": "support"
  }'

python

import requests

response = requests.post(
    "http://localhost:3000/api/dev/v1/chatbots",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "name": "Support Bot",
        "description": "Handles tier-1 customer support",
        "category": "support",
    },
)
print(response.json())import requests

response = requests.post(
    "http://localhost:3000/api/dev/v1/chatbots",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "name": "Support Bot",
        "description": "Handles tier-1 customer support",
        "category": "support",
    },
)
print(response.json())

javascript

const response = await fetch("http://localhost:3000/api/dev/v1/chatbots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support Bot",
    description: "Handles tier-1 customer support",
    category: "support",
  }),
});
const data = await response.json();const response = await fetch("http://localhost:3000/api/dev/v1/chatbots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Support Bot",
    description: "Handles tier-1 customer support",
    category: "support",
  }),
});
const data = await response.json();

Response - 201 Created

json

{
  "id": "01JMXYZ123ABC",
  "workspace_id": "01JMWXY456DEF",
  "name": "Support Bot",
  "description": "Handles tier-1 customer support",
  "category": "support",
  "webhook_secret": "whsec_abc123...",
  "is_active": true,
  "created_at": "2026-02-01T10:30:00Z",
  "updated_at": null
}{
  "id": "01JMXYZ123ABC",
  "workspace_id": "01JMWXY456DEF",
  "name": "Support Bot",
  "description": "Handles tier-1 customer support",
  "category": "support",
  "webhook_secret": "whsec_abc123...",
  "is_active": true,
  "created_at": "2026-02-01T10:30:00Z",
  "updated_at": null
}

Get Chatbot

Retrieves a single chatbot by ID.

http

GET /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>

bash

curl -X GET http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>"curl -X GET http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

javascript

const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();

Response - 200 OK - returns a ChatbotResponse object (same shape as Create response above).

Get Chatbot With Stats

Returns the chatbot along with usage statistics.

http

GET /api/dev/v1/chatbots/{chatbot_id}/stats
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots/{chatbot_id}/stats
Authorization: Bearer <api-key>

bash

curl -X GET http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats \
  -H "Authorization: Bearer <your-api-key>"curl -X GET http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())import requests

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

javascript

const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats",
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/stats",
  {
    headers: { "Authorization": "Bearer <your-api-key>" },
  }
);
const data = await response.json();

Response - 200 OK

json

{
  "id": "01JMXYZ123ABC",
  "name": "Support Bot",
  "is_active": true,
  "stats": {
    "total_conversations": 1240,
    "total_messages": 8765,
    "active_users_7d": 342
  },
  "created_at": "2026-02-01T10:30:00Z"
}{
  "id": "01JMXYZ123ABC",
  "name": "Support Bot",
  "is_active": true,
  "stats": {
    "total_conversations": 1240,
    "total_messages": 8765,
    "active_users_7d": 342
  },
  "created_at": "2026-02-01T10:30:00Z"
}

Update Chatbot

Updates a chatbot's name, description, or category. Only include fields you want to change.

http

PATCH /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>
Content-Type: application/jsonPATCH /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

Body (all fields optional)

namestringoptional

New chatbot name.

descriptionstringoptional

New description.

categorystringoptional

New category label.

bash

curl -X PATCH http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Support Bot"}'curl -X PATCH http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Support Bot"}'

python

import requests

response = requests.patch(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"name": "Renamed Support Bot"},
)
print(response.json())import requests

response = requests.patch(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={"name": "Renamed Support Bot"},
)
print(response.json())

javascript

const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer <your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Renamed Support Bot" }),
  }
);
const data = await response.json();const response = await fetch(
  "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer <your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Renamed Support Bot" }),
  }
);
const data = await response.json();

Response - 200 OK - returns the updated ChatbotResponse.

Delete Chatbot

Permanently deletes a chatbot and all its associated flows, conversations, and integrations.

http

DELETE /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>DELETE /api/dev/v1/chatbots/{chatbot_id}
Authorization: Bearer <api-key>

bash

curl -X DELETE http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>"curl -X DELETE http://localhost:3000/api/dev/v1/chatbots/<chatbot-id> \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

response = requests.delete(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
)
# response has no body (204 No Content)import requests

response = requests.delete(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>",
    headers={"Authorization": "Bearer <your-api-key>"},
)
# response has no body (204 No Content)

javascript

await fetch("http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>", {
  method: "DELETE",
  headers: { "Authorization": "Bearer <your-api-key>" },
});
// 204 No Contentawait fetch("http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>", {
  method: "DELETE",
  headers: { "Authorization": "Bearer <your-api-key>" },
});
// 204 No Content

Response - 204 No Content

Irreversible action

Deleting a chatbot permanently removes all flows, conversations, integrations, and analytics data attached to it. This action cannot be undone.

Chatbot Object

ChatbotResponse fields

idstring

Unique chatbot ID (ULID).

workspace_idstring

ID of the owning workspace.

namestring

Chatbot display name.

descriptionstring

Optional description.

categorystring

Optional category tag.

webhook_secretstring

Secret used to verify incoming webhook signatures.

is_activeboolean

Whether the chatbot is currently active.

created_atstring

Creation timestamp (ISO 8601).

updated_atstring

Last update timestamp, or null if never updated.