Conversations API

List, retrieve, and close conversation threads for Direct API and widget deployments.

Endpoints

Method	Path	Description
`GET`	`/api/v1/conversations`	List conversations
`POST`	`/api/v1/conversations`	Create conversation
`GET`	`/api/v1/conversations/{id}`	Get conversation
`PATCH`	`/api/v1/conversations/{id}`	Update metadata
`DELETE`	`/api/v1/conversations/{id}`	Close / archive conversation
`GET`	`/api/v1/conversations/{id}/messages`	List messages in thread

Requires API key or session auth. Widget visitors receive a conversation_id from the first message response.

List conversations

GET /api/v1/conversations?deployment_id=dep_abc123&limit=50
Authorization: Bearer ch_live_xxx

Query param	Description
`deployment_id`	Filter by deployment
`assistant_id`	Filter by assistant
`status`	`open`, `closed`
`since`	ISO 8601 — conversations updated after this time
`limit`, `cursor`	Pagination

Response:

{
  "data": [
    {
      "id": "conv_8mN4pQ1r",
      "deployment_id": "dep_abc123",
      "assistant_id": "asst_7xK9mN2p",
      "status": "open",
      "message_count": 12,
      "created_at": "2026-07-15T14:22:00Z",
      "updated_at": "2026-07-16T08:10:00Z"
    }
  ],
  "next_cursor": null
}

Create conversation

Useful for Direct API integrations that manage threads server-side:

POST /api/v1/conversations

{
  "deployment_id": "dep_abc123",
  "external_user_id": "user_9281",
  "metadata": {
    "channel": "mobile_app",
    "locale": "en-US"
  }
}

Get conversation

GET /api/v1/conversations/conv_8mN4pQ1r

Includes summary fields and metadata you attached at creation.

Close conversation

DELETE /api/v1/conversations/conv_8mN4pQ1r

Marks the thread closed. Historical messages remain available per retention policy.

Webhooks

Subscribe to conversation.created, conversation.updated, and message.created via Webhooks API instead of polling when possible.