Read conversations

Every message you send through the API is recorded in a conversation. These endpoints let you read that history: list your account’s conversations and open any of them to see all their messages. They’re read-only — nothing is modified.

Authentication

Every request is authenticated with your public API key in the X-API-Key header. You can only see conversations that belong to your own account.

List conversations

Base path: /v1/public/v1/conversations

Method	Path	Purpose
GET	/conversations	List recent conversations.

Query parameters

Parameter	Type	Default	Description
limit	integer	20	How many conversations to return. Between 1 and 100.
status	string	—	Filter by status, e.g. active or closed.

Request

GET /v1/public/v1/conversations?limit=20&status=active
X-API-Key: <your-api-key>

Response (200 OK)

[
  {
    "id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
    "user_ref": "customer@example.com",
    "status": "active",
    "message_count": 4,
    "started_at": "2026-07-29T12:30:00Z",
    "last_message_at": "2026-07-29T12:34:56Z"
  }
]

Field	Type	Description
id	UUID	Unique conversation id. Use it to read the detail.
user_ref	string	The reference you passed as user_ref, or an auto-generated one.
status	string	Conversation status, e.g. active or closed.
message_count	integer	Total messages exchanged.
started_at	datetime	When the conversation was created (ISO-8601, UTC).
last_message_at	datetime	Timestamp of the most recent message, if any.

Read a conversation

Method	Path	Purpose
GET	/conversations/{id}	Retrieve a conversation with all its messages.

Returns the same fields as the summary above plus messages, with the conversation history (up to the 200 most recent messages).

Request

GET /v1/public/v1/conversations/a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f
X-API-Key: <your-api-key>

Response (200 OK)

{
  "id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
  "user_ref": "customer@example.com",
  "status": "active",
  "message_count": 4,
  "started_at": "2026-07-29T12:30:00Z",
  "last_message_at": "2026-07-29T12:34:56Z",
  "messages": [
    { "role": "user", "content": "What are your opening hours?", "created_at": "2026-07-29T12:30:00Z" },
    { "role": "assistant", "content": "We're open Monday to Friday, 9am to 6pm.", "created_at": "2026-07-29T12:30:02Z" }
  ]
}

Each item in messages has role (user or assistant), content, and created_at.

Errors

Code	Meaning
401	The X-API-Key header is missing or the key is invalid.
403	Your plan doesn’t include public API access.
404	The conversation doesn’t exist or doesn’t belong to your account.