Conversations

3 endpoints

get/v1/conversations

List conversations

Returns a paginated list of the account's conversations (chat threads) (cursor v2). Stable sort: created_at DESC, id DESC.

A conversation groups a visitor's messages with an agent (AI or human) under the calling account. Threads are created and messages are sent from the front end / chat SDK — the public API is read-only.

Filters

?agent_slug — exact match on the AI agent replying in the thread.
?agent_identity_id — exact match on the thread's specific AI agent (an account can have several chatbots).
?source — exact match on the thread source (URL, funnel label, widget, etc.).

Required scopes: conversations:read

Query parameters

Name	Type	Required	Description
`agent_slug`	`string`	optional	AI agent slug — exact match on the threads this agent serves.
`agent_identity_id`	`string`	optional	Identifier of the specific AI agent — exact match on the threads it serves.
`source`	`string`	optional	Thread source — exact match (URL, funnel label, `widget`, etc.).

Responses

Status	Description
`200`	Paginated list of conversations.
`400`	The request is malformed (missing header, invalid JSON, invalid parameter).
`401`	Unknown API key or invalid format.
`403`	Authorization denied. Two causes, distinguished by `code`: `insufficient_scope` (the key lacks the required scope — `details.required_scope`) or `feature_not_available` (the public API or the targeted module isn't included in the account's plan — `details.feature` names the feature, e.g. `public_api`, `quotes`). A plan denial is final for the key: don't retry; the account must change plans.
`429`	The per-window request quota has been exceeded for this API key or endpoint.
`500`	Unexpected server error. Always include the `request_id` when contacting support.

Example request

curl -X GET 'https://api.capturia.io/v1/conversations' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

get/v1/conversations/{id}

Retrieve a conversation

Returns a conversation's metadata by its ID. To retrieve the individual messages, use GET /v1/conversations/{id}/messages.

If the conversation belongs to another account (or doesn't exist), returns 404 resource_not_found — tenant isolation hides the existence of conversations outside the calling account.

Required scopes: conversations:read

Responses

Status	Description
`200`	Conversation found.
`401`	Unknown API key or invalid format.
`403`	Authorization denied. Two causes, distinguished by `code`: `insufficient_scope` (the key lacks the required scope — `details.required_scope`) or `feature_not_available` (the public API or the targeted module isn't included in the account's plan — `details.feature` names the feature, e.g. `public_api`, `quotes`). A plan denial is final for the key: don't retry; the account must change plans.
`404`	The requested resource doesn't exist (or isn't within the tenant's scope).
`429`	The per-window request quota has been exceeded for this API key or endpoint.
`500`	Unexpected server error. Always include the `request_id` when contacting support.

Example request

curl -X GET 'https://api.capturia.io/v1/conversations/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

get/v1/conversations/{id}/messages

List a conversation's messages

Returns a paginated list of a conversation's messages in chronological reading order (created_at ASC, id ASC), with an id tiebreaker to prevent duplicates or skipped rows between two pages when several messages share the same millisecond.

This sort direction (ASC) is the reverse of the other v2 list endpoints (DESC) — a conversation reads naturally in the chronological order of the exchange.

Each message tells you who wrote it (author_kind): the visitor, the AI agent, or a sales rep on the team who replied from the Inbox (author_name then holds their first name).

If the conversation belongs to another account (or doesn't exist), returns 404 resource_not_found.

Required scopes: conversations:read

Responses

Status	Description
`200`	Paginated list of messages (chronological order).
`400`	The request is malformed (missing header, invalid JSON, invalid parameter).
`401`	Unknown API key or invalid format.
`403`	Authorization denied. Two causes, distinguished by `code`: `insufficient_scope` (the key lacks the required scope — `details.required_scope`) or `feature_not_available` (the public API or the targeted module isn't included in the account's plan — `details.feature` names the feature, e.g. `public_api`, `quotes`). A plan denial is final for the key: don't retry; the account must change plans.
`404`	The requested resource doesn't exist (or isn't within the tenant's scope).
`429`	The per-window request quota has been exceeded for this API key or endpoint.
`500`	Unexpected server error. Always include the `request_id` when contacting support.

Example request

curl -X GET 'https://api.capturia.io/v1/conversations/{id}/messages' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'