List the key's conversations

curl --request GET \
  --url https://api.chattler.ai/v1/agents/{agent_id}/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "external_user_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_message_preview": "<string>"
    }
  ],
  "next_cursor": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Conversations

List the key's conversations

Return the conversations that belong to the authenticated API key, most recently updated first. Every key has its own isolated namespace: a conversation is identified by the key and the external_user_id the client supplied, so the same external user reached through two different keys is two different conversations, and a key never sees dialogs from another key or channel.

Authentication

Authorization: Bearer cht_live_<key_id>.<secret> — the only accepted form. Query-string credentials are ignored, and no Browser-ID header is needed.
Both read-only and full keys may call this endpoint.

Path Parameters

agent_id: The agent the key is bound to; a key used against another agent is refused

Query Parameters

external_user_id: only conversations of this external user
date_from, date_to: ISO-8601 bounds on updated_at; date_to is exclusive. Timezone-aware values are converted to UTC, naive values are read as UTC, and date_to earlier than date_from is a validation error
limit: page size, 1-100 (default 20)
cursor: the next_cursor value from the previous page; omit for the first page

Example Request

curl -X GET "/v1/agents/{agent_id}/conversations?limit=20&date_from=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer cht_live_{key_id}.{secret}"

Response

data: array of conversations, most recently updated first, each with id, external_user_id, created_at, updated_at (ISO-8601 UTC) and last_message_preview (the latest user or assistant text, truncated to 160 characters, or null)
next_cursor: opaque string for the next page, or null on the last page

Every response, success or failure, carries an X-Request-ID header (a UUID) and the rate-limit headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Errors

All public API errors use one envelope: {"error": {"code": "...", "message": "...", "request_id": "..."}}.

invalid_api_key (401): missing, malformed, unknown, or wrong-secret key
agent_mismatch (403): the key belongs to a different agent
validation_error (422): bad limit or malformed cursor
rate_limit_exceeded (429): the key’s technical window is exhausted; Retry-After says when to retry
api_rate_limit_unavailable (503): the limiter backend is down; the request is refused rather than served unmetered, retry after Retry-After
internal_error (500): unexpected failure; quote the request_id when reporting it

GET

agents

{agent_id}

conversations

List the key's conversations

curl --request GET \
  --url https://api.chattler.ai/v1/agents/{agent_id}/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "external_user_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_message_preview": "<string>"
    }
  ],
  "next_cursor": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Agent API key: Authorization: Bearer cht_live_<key_id>.

Path Parameters

agent_id

string

required

Query Parameters

external_user_id

string | null

Maximum string length: 255

date_from

string<date-time> | null

date_to

string<date-time> | null

limit

integer

default:20

Required range: 1 <= x <= 100

cursor

string | null

Response

One page of the key's conversations plus the next cursor

data

ApiConversationItem · object[]

required

Show child attributes

next_cursor

string | null

Opaque cursor for the next page; null on the last page

API Reference

Chat

Conversations

List the key's conversations

Authentication

Path Parameters

Query Parameters

Example Request

Response

Errors

Authorizations

Path Parameters

Query Parameters

Response