# Chesly API REST reference

> Every operation of the Chesly API, with its parameters, answers and errors, from the OpenAPI document. Start a trial and make keys at https://web.chesly.app/api. Agent setup: https://agents.chesly.app/agents.md

## Overview

The base URL is `https://api.chesly.app`. Each call takes your key as `Authorization: Bearer ck_live_…`, except the ones marked as needing none. This page is built from the OpenAPI 3.1 document at [api.chesly.app/v1/openapi.json](https://api.chesly.app/v1/openapi.json), which the API's own code generates: point a client generator or an agent at it. Every operation can also answer the errors its list names, each linked to what to do; a call with a key can always meet `invalid_api_key`, `rate_limited`, `api_paused`, `upstream_unavailable` and `internal_error`.

## Your key

### GET /v1/me

The key in use: its scope, limits, plan and this month's calls.

- `200`: The key, its limits, its plan and its usage. Answers without an API plan: [Me](https://agents.chesly.app/docs/api#me).
- Errors: 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Accounts

### GET /v1/accounts

The accounts the user connected in Chesly, oldest first.

- `200`: The connected accounts and their status: [AccountList](https://agents.chesly.app/docs/api#accountlist).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Chats

### GET /v1/chats

The user's chats, a page at a time.

| Parameter | In | Type | Description |
|---|---|---|---|
| `account_id` | query | string | Optional. |
| `network` | query | string | Only this network's chats, such as whatsapp. Email is listed only with email. Optional. |
| `updated_since` | query | time (ISO 8601) | Only chats whose last message is at or after this time. Optional. |
| `unread` | query | `true` or `false` | Optional. |
| `archived` | query | `true`, `false` or `all` | Optional. |
| `q` | query | string | Optional. |
| `sort` | query | `recent` or `unread` | Optional. |
| `limit` | query | integer | Optional. |
| `cursor` | query | string | Optional. |

- `200`: A page of chats: [ChatPage](https://agents.chesly.app/docs/api#chatpage).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_cursor`](https://agents.chesly.app/docs/errors#invalid_cursor) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`account_not_found`](https://agents.chesly.app/docs/errors#account_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### GET /v1/chats/{chat_id}

One chat.

| Parameter | In | Type | Description |
|---|---|---|---|
| `chat_id` | path | string | The chat's ID (chat_…). |

- `200`: The chat: [Chat](https://agents.chesly.app/docs/api#chat).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`chat_not_found`](https://agents.chesly.app/docs/errors#chat_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### POST /v1/chats/{chat_id}/read

Mark a chat read up to its newest message.

| Parameter | In | Type | Description |
|---|---|---|---|
| `chat_id` | path | string | The chat's ID (chat_…). |
| `Idempotency-Key` | header | string | 1 to 255 characters from A-Za-z0-9._:- (or that, quoted). Repeat a request with the same key within 24 hours and get the first answer back. Optional. |

- `200`: The chat is read; whether the network got a receipt: [ReadResult](https://agents.chesly.app/docs/api#readresult).
- Errors: 400 [`idempotency_key_invalid`](https://agents.chesly.app/docs/errors#idempotency_key_invalid) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing), [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`chat_not_found`](https://agents.chesly.app/docs/errors#chat_not_found) · 409 [`idempotency_in_progress`](https://agents.chesly.app/docs/errors#idempotency_in_progress) · 413 [`payload_too_large`](https://agents.chesly.app/docs/errors#payload_too_large) · 422 [`idempotency_key_reused`](https://agents.chesly.app/docs/errors#idempotency_key_reused) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`network_unavailable`](https://agents.chesly.app/docs/errors#network_unavailable), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

## Messages

### GET /v1/chats/{chat_id}/messages

A chat's messages, newest first, a page at a time.

| Parameter | In | Type | Description |
|---|---|---|---|
| `chat_id` | path | string | The chat's ID (chat_…). |
| `before` | query | time (ISO 8601) | Only messages sent before this time. Optional. |
| `after` | query | time (ISO 8601) | Only messages sent after this time. Optional. |
| `limit` | query | integer | Optional. |
| `cursor` | query | string | Optional. |

- `200`: A page of messages: [MessagePage](https://agents.chesly.app/docs/api#messagepage).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_cursor`](https://agents.chesly.app/docs/errors#invalid_cursor) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`chat_not_found`](https://agents.chesly.app/docs/errors#chat_not_found) · 409 [`account_reconnect_required`](https://agents.chesly.app/docs/errors#account_reconnect_required) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### POST /v1/chats/{chat_id}/messages

Send a message to a chat.

| Parameter | In | Type | Description |
|---|---|---|---|
| `chat_id` | path | string | The chat's ID (chat_…). |
| `Idempotency-Key` | header | string | Sends at most once per key, however often the request is retried: 1 to 255 of A-Z, a-z, 0-9, ".", "_", ":" and "-". Kept 24 hours. A retry with the same key and body answers the first answer again, with Idempotent-Replayed: true. Optional. |

The body, `application/json`, is a [SendMessage](https://agents.chesly.app/docs/api#sendmessage).

- `201`: The message as sent. Its delivery is queued until the network takes it; GET /v1/messages/{message_id} follows it: [Message](https://agents.chesly.app/docs/api#message).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`text_too_long`](https://agents.chesly.app/docs/errors#text_too_long), [`invalid_reply_to`](https://agents.chesly.app/docs/errors#invalid_reply_to), [`unsupported_chat`](https://agents.chesly.app/docs/errors#unsupported_chat), [`idempotency_key_invalid`](https://agents.chesly.app/docs/errors#idempotency_key_invalid), [`media_too_large`](https://agents.chesly.app/docs/errors#media_too_large) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope), [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`chat_not_found`](https://agents.chesly.app/docs/errors#chat_not_found), [`media_not_found`](https://agents.chesly.app/docs/errors#media_not_found) · 409 [`message_request`](https://agents.chesly.app/docs/errors#message_request), [`idempotency_in_progress`](https://agents.chesly.app/docs/errors#idempotency_in_progress) · 410 [`media_expired`](https://agents.chesly.app/docs/errors#media_expired) · 422 [`idempotency_key_reused`](https://agents.chesly.app/docs/errors#idempotency_key_reused) · 429 [`send_limit_reached`](https://agents.chesly.app/docs/errors#send_limit_reached), [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`network_unavailable`](https://agents.chesly.app/docs/errors#network_unavailable), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### GET /v1/messages/{message_id}

One message, with its delivery status.

| Parameter | In | Type | Description |
|---|---|---|---|
| `message_id` | path | string | The message's ID (msg_…). |

- `200`: The message: [Message](https://agents.chesly.app/docs/api#message).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`message_not_found`](https://agents.chesly.app/docs/errors#message_not_found) · 409 [`account_reconnect_required`](https://agents.chesly.app/docs/errors#account_reconnect_required) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### GET /v1/messages/search

Search the text of the user's messages.

| Parameter | In | Type | Description |
|---|---|---|---|
| `q` | query | string |  |
| `chat_id` | query | string | Optional. |
| `account_id` | query | string | Optional. |
| `network` | query | string | Only this network's chats, such as whatsapp. Email is included only with email. Optional. |
| `limit` | query | integer | Optional. |

- `200`: The messages found, each with its chat's name and network: [SearchResults](https://agents.chesly.app/docs/api#searchresults).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`account_not_found`](https://agents.chesly.app/docs/errors#account_not_found), [`chat_not_found`](https://agents.chesly.app/docs/errors#chat_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`search_unavailable`](https://agents.chesly.app/docs/errors#search_unavailable), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### GET /v1/messages

Everything new across the user's chats since a time, a page at a time.

| Parameter | In | Type | Description |
|---|---|---|---|
| `since` | query | time (ISO 8601) |  |
| `network` | query | string | Only this network's chats, such as whatsapp. Email is included only with email. Optional. |
| `limit` | query | integer | Optional. |
| `cursor` | query | string | Optional. |

- `200`: A page of the walk: [MessagesSince](https://agents.chesly.app/docs/api#messagessince).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_cursor`](https://agents.chesly.app/docs/errors#invalid_cursor) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`feed_unavailable`](https://agents.chesly.app/docs/errors#feed_unavailable), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### GET /v1/catch_up

The unread chats, newest first, each with its newest messages.

| Parameter | In | Type | Description |
|---|---|---|---|
| `chats` | query | integer | Optional. |
| `per_chat` | query | integer | Optional. |
| `network` | query | string | Only this network's chats, such as whatsapp. Email is included only with email. Optional. |

- `200`: The catch-up: [CatchUp](https://agents.chesly.app/docs/api#catchup).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### POST /v1/media

Upload a file to send.

The body, `multipart/form-data`, is a [MediaUpload](https://agents.chesly.app/docs/api#mediaupload).

- `201`: The upload. Send its id as media_id within 24 hours: [UploadedMedia](https://agents.chesly.app/docs/api#uploadedmedia).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`media_too_large`](https://agents.chesly.app/docs/errors#media_too_large) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 408 [`upload_timeout`](https://agents.chesly.app/docs/errors#upload_timeout) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

### POST /v1/messages/{message_id}/transcript

Transcribe a voice message.

| Parameter | In | Type | Description |
|---|---|---|---|
| `message_id` | path | string | The voice message's ID (msg_…). |

- `200`: The transcript. Its audio counts toward your plan's transcription minutes, unless it was cached: [Transcript](https://agents.chesly.app/docs/api#transcript).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`not_a_voice_note`](https://agents.chesly.app/docs/errors#not_a_voice_note), [`media_too_large`](https://agents.chesly.app/docs/errors#media_too_large) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required), [`transcription_limit_reached`](https://agents.chesly.app/docs/errors#transcription_limit_reached) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope), [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 404 [`message_not_found`](https://agents.chesly.app/docs/errors#message_not_found), [`media_not_found`](https://agents.chesly.app/docs/errors#media_not_found) · 410 [`media_expired`](https://agents.chesly.app/docs/errors#media_expired) · 422 [`transcription_failed`](https://agents.chesly.app/docs/errors#transcription_failed) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`transcription_unavailable`](https://agents.chesly.app/docs/errors#transcription_unavailable), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

## Media

### GET /v1/media/{media_id}

A message's media, as bytes.

| Parameter | In | Type | Description |
|---|---|---|---|
| `media_id` | path | string | The media's ID (media_…), from a message's media.id. |

- `200`: The file, in its own Content-Type. Ranges and validators work: `*/*`.
- `206`: The byte range asked for (Range): `*/*`.
- `304`: Not modified (If-None-Match or If-Modified-Since).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`media_too_large`](https://agents.chesly.app/docs/errors#media_too_large) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 404 [`media_not_found`](https://agents.chesly.app/docs/errors#media_not_found) · 410 [`media_expired`](https://agents.chesly.app/docs/errors#media_expired) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`media_unavailable`](https://agents.chesly.app/docs/errors#media_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Contacts

### GET /v1/contacts

Find the people of your direct chats by name.

| Parameter | In | Type | Description |
|---|---|---|---|
| `q` | query | string | Part of the person's name, matched ignoring case and accents. |
| `limit` | query | integer | Optional. |

- `200`: The people found, each with their direct chat: [ContactList](https://agents.chesly.app/docs/api#contactlist).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`signing_key_missing`](https://agents.chesly.app/docs/errors#signing_key_missing) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused).

## Events

### GET /v1/events

Events after a cursor, oldest first.

| Parameter | In | Type | Description |
|---|---|---|---|
| `after` | query | string | The last event ID you have (evt_…): events after it. Optional. |
| `types` | query | string | Event types, comma-separated. Without: every type. Optional. |
| `chat_id` | query | string | One chat's events (chat_…). Optional. |
| `account_id` | query | string | One account's events (acct_…); an email account's email too. Optional. |
| `networks` | query | string | Networks, comma-separated. Without: every network but email, which comes only when named here or by account_id. Optional. |
| `limit` | query | integer | Optional. |

- `200`: A page of events: [EventPage](https://agents.chesly.app/docs/api#eventpage).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 410 [`events_expired`](https://agents.chesly.app/docs/errors#events_expired) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### GET /v1/events/stream

Events as they happen, as server-sent events.

| Parameter | In | Type | Description |
|---|---|---|---|
| `after` | query | string | The last event ID you have (evt_…): events after it. Optional. |
| `types` | query | string | Event types, comma-separated. Without: every type. Optional. |
| `chat_id` | query | string | One chat's events (chat_…). Optional. |
| `account_id` | query | string | One account's events (acct_…); an email account's email too. Optional. |
| `networks` | query | string | Networks, comma-separated. Without: every network but email, which comes only when named here or by account_id. Optional. |
| `Last-Event-ID` | header | string | The last event ID you had: the stream resumes after it. Optional. |

- `200`: retry: 3000, then each event as id, event and data lines (data is the ApiEvent JSON); a ping comment every 15 s. Without a cursor, the newest event's ID first, alone: `text/event-stream`.
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 410 [`events_expired`](https://agents.chesly.app/docs/errors#events_expired) · 429 [`too_many_streams`](https://agents.chesly.app/docs/errors#too_many_streams), [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Webhooks

### GET /v1/webhooks

Your webhook endpoints.

- `200`: Every endpoint, newest first: [WebhookList](https://agents.chesly.app/docs/api#webhooklist).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### POST /v1/webhooks

Add a webhook endpoint.

The body, `application/json`:

| Field | Type | Description |
|---|---|---|
| `url` | string |  |
| `event_types` | array of `message.received`, `message.sent`, `message.edited`, `message.deleted`, `message.delivery_failed`, `chat.created`, `chat.updated`, `chat.read`, `account.connected`, `account.disconnected`, `account.needs_attention`, `reaction.added` or `reaction.removed` | Optional. |
| `networks` | array of `email`, `whatsapp`, `telegram`, `discord`, `instagram`, `messenger`, `signal`, `slack`, `gmessages`, `googlechat`, `twitter`, `linkedin`, `reddit` or `imessage` | Optional. |
| `payload` | `full` or `ids` | Optional. |
| `description` | string or null | Optional. |

- `201`: The endpoint, with its signing secret: shown this once: [WebhookCreated](https://agents.chesly.app/docs/api#webhookcreated).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_webhook_url`](https://agents.chesly.app/docs/errors#invalid_webhook_url), [`webhook_limit_reached`](https://agents.chesly.app/docs/errors#webhook_limit_reached) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`plan_unavailable`](https://agents.chesly.app/docs/errors#plan_unavailable), [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### GET /v1/webhooks/{webhook_id}

A webhook endpoint.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |

- `200`: The endpoint: [Webhook](https://agents.chesly.app/docs/api#webhook).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### PATCH /v1/webhooks/{webhook_id}

Change a webhook endpoint, or turn it on or off.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |

The body, `application/json`:

| Field | Type | Description |
|---|---|---|
| `url` | string | Optional. |
| `event_types` | array of `message.received`, `message.sent`, `message.edited`, `message.deleted`, `message.delivery_failed`, `chat.created`, `chat.updated`, `chat.read`, `account.connected`, `account.disconnected`, `account.needs_attention`, `reaction.added` or `reaction.removed` | Optional. |
| `networks` | array of `email`, `whatsapp`, `telegram`, `discord`, `instagram`, `messenger`, `signal`, `slack`, `gmessages`, `googlechat`, `twitter`, `linkedin`, `reddit` or `imessage` | Optional. |
| `payload` | `full` or `ids` | Optional. |
| `description` | string or null | Optional. |
| `enabled` | boolean | Optional. |

- `200`: The endpoint as it is now: [Webhook](https://agents.chesly.app/docs/api#webhook).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_webhook_url`](https://agents.chesly.app/docs/errors#invalid_webhook_url) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`forbidden`](https://agents.chesly.app/docs/errors#forbidden), [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### DELETE /v1/webhooks/{webhook_id}

Delete a webhook endpoint and its pending deliveries.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |

- `204`: Deleted.
- Errors: 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### POST /v1/webhooks/{webhook_id}/rotate_secret

A new signing secret; the old one signs too for 24 hours.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |

- `200`: The new secret: shown this once: [WebhookSecret](https://agents.chesly.app/docs/api#webhooksecret).
- Errors: 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### POST /v1/webhooks/{webhook_id}/test

Send the endpoint a webhook.test event.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |

- `202`: Queued; its delivery shows how it went: [WebhookTest](https://agents.chesly.app/docs/api#webhooktest).
- Errors: 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### GET /v1/webhooks/{webhook_id}/deliveries

An endpoint's deliveries, newest first.

| Parameter | In | Type | Description |
|---|---|---|---|
| `webhook_id` | path | string | The webhook's ID (wh_…). |
| `status` | query | `pending`, `succeeded`, `failed` or `discarded` | Optional. |
| `limit` | query | integer | Optional. |
| `cursor` | query | string | Optional. |

- `200`: A page of deliveries: [WebhookDeliveryPage](https://agents.chesly.app/docs/api#webhookdeliverypage).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request), [`invalid_cursor`](https://agents.chesly.app/docs/errors#invalid_cursor) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 402 [`api_plan_required`](https://agents.chesly.app/docs/errors#api_plan_required) · 404 [`webhook_not_found`](https://agents.chesly.app/docs/errors#webhook_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Keys

### GET /v1/keys

List your API keys.

- `200`: Your active keys, newest first: [KeyList](https://agents.chesly.app/docs/api#keylist).
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

### DELETE /v1/keys/{key_id}

Revoke an API key, this one included.

| Parameter | In | Type | Description |
|---|---|---|---|
| `key_id` | path | string | The key's ID, from GET /v1/keys. |

- `204`: Revoked: the key's next request is refused.
- Errors: 400 [`invalid_request`](https://agents.chesly.app/docs/errors#invalid_request) · 401 [`invalid_api_key`](https://agents.chesly.app/docs/errors#invalid_api_key) · 403 [`insufficient_scope`](https://agents.chesly.app/docs/errors#insufficient_scope) · 404 [`key_not_found`](https://agents.chesly.app/docs/errors#key_not_found) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`api_paused`](https://agents.chesly.app/docs/errors#api_paused), [`upstream_unavailable`](https://agents.chesly.app/docs/errors#upstream_unavailable).

## Sign-in

### POST /v1/cli/sessions

Start a CLI sign-in: a code for the user to approve on web.chesly.app.

No key needed.

The body, `application/json`, which you can leave out, is a [CliSessionRequest](https://agents.chesly.app/docs/api#clisessionrequest).

- `200`: The sign-in, to show the user and to poll: [CliSession](https://agents.chesly.app/docs/api#clisession).
- Errors: 413 [`payload_too_large`](https://agents.chesly.app/docs/errors#payload_too_large) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error).

### POST /v1/cli/sessions/token

Poll a CLI sign-in for its key, every interval seconds.

No key needed.

The body, `application/json`, is a [CliTokenRequest](https://agents.chesly.app/docs/api#clitokenrequest).

- `200`: Approved: the new key: [CliToken](https://agents.chesly.app/docs/api#clitoken).
- `400`: Not yet, or not at all (RFC 8628 §3.5): keep polling on authorization_pending, slow down on slow_down: [CliTokenError](https://agents.chesly.app/docs/api#clitokenerror).
- Errors: 413 [`payload_too_large`](https://agents.chesly.app/docs/errors#payload_too_large) · 429 [`rate_limited`](https://agents.chesly.app/docs/errors#rate_limited) · 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error) · 503 [`plan_unavailable`](https://agents.chesly.app/docs/errors#plan_unavailable).

## The OpenAPI document

### GET /v1/openapi.json

This OpenAPI 3.1 document.

No key needed.

- `200`: The OpenAPI 3.1 document of /v1, events included as webhooks: JSON.
- Errors: 500 [`internal_error`](https://agents.chesly.app/docs/errors#internal_error).

## Schemas

The objects the operations take and answer with.

### Contact

| Field | Type | Description |
|---|---|---|
| `id` | string | The person's ID (contact_…): the same for them every time. |
| `name` | string | Their name, as their direct chat is named. |
| `network` | string |  |
| `account_id` | string or null | The account their chat is on (acct_…), when Chesly can tell. |
| `chat_id` | string | Their direct chat with the user (chat_…). |

### ContactList

| Field | Type | Description |
|---|---|---|
| `contacts` | array of [Contact](https://agents.chesly.app/docs/api#contact) | Exact names first, then the most recent chat. |

### Problem

| Field | Type | Description |
|---|---|---|
| `type` | URL | The code's entry in the error docs. |
| `title` | string |  |
| `status` | integer |  |
| `detail` | string | Optional. |
| `code` | string | Stable: branch on it. |
| `request_id` | string |  |
| `retry_after` | integer | Seconds, on a 429 or 503 that says when to retry. Optional. |
| `errors` | array of object | Each problem with the request, on a 400 invalid_request. Optional. |
| `errors[].detail` | string |  |
| `errors[].pointer` | string |  |

### ApiEvent

| Field | Type | Description |
|---|---|---|
| `id` | string | The event's ID (evt_…): dedupe by it. |
| `type` | `message.received`, `message.sent`, `message.edited`, `message.deleted`, `message.delivery_failed`, `chat.created`, `chat.updated`, `chat.read`, `account.connected`, `account.disconnected`, `account.needs_attention`, `reaction.added` or `reaction.removed` |  |
| `timestamp` | time (ISO 8601) |  |
| `data` | object | The type's data: see the webhooks of this document. |

### EventPage

| Field | Type | Description |
|---|---|---|
| `events` | array of [ApiEvent](https://agents.chesly.app/docs/api#apievent) |  |
| `next_cursor` | string or null | The last event's ID, or after when none came back. |
| `has_more` | boolean |  |

### Webhook

| Field | Type | Description |
|---|---|---|
| `id` | string | The webhook's ID (wh_…). |
| `url` | string |  |
| `description` | string or null |  |
| `event_types` | array of `message.received`, `message.sent`, `message.edited`, `message.deleted`, `message.delivery_failed`, `chat.created`, `chat.updated`, `chat.read`, `account.connected`, `account.disconnected`, `account.needs_attention`, `reaction.added` or `reaction.removed` | Empty: every type. |
| `networks` | array of string | Empty: every network but email. |
| `payload` | `full` or `ids` |  |
| `status` | `enabled` or `disabled` |  |
| `disabled_reason` | `user`, `failing`, `gone`, `key_revoked` or null | Why it is off: you turned it off (user), it failed for 3 days (failing), it answered 410 (gone), or an API key that made it, changed it or set its URL was revoked for leaking (key_revoked). |
| `failing_since` | time (ISO 8601) or null |  |
| `created_at` | time (ISO 8601) |  |
| `updated_at` | time (ISO 8601) |  |

### WebhookList

| Field | Type | Description |
|---|---|---|
| `webhooks` | array of [Webhook](https://agents.chesly.app/docs/api#webhook) |  |

### WebhookCreated

object.

### WebhookSecret

| Field | Type | Description |
|---|---|---|
| `secret` | string | The new signing secret (whsec_…): shown this once. |
| `previous_secret_expires_at` | time (ISO 8601) | Until then, deliveries carry a signature by the old secret too. One old secret is kept: rotating again before then ends the overlap of the one before. |

### WebhookTest

| Field | Type | Description |
|---|---|---|
| `delivery_id` | string |  |

### WebhookDelivery

| Field | Type | Description |
|---|---|---|
| `id` | string | The delivery's ID (dlv_…). |
| `event_id` | string or null |  |
| `event_type` | string |  |
| `status` | `pending`, `succeeded`, `failed` or `discarded` |  |
| `attempts` | integer |  |
| `next_attempt_at` | time (ISO 8601) or null |  |
| `last_attempt_at` | time (ISO 8601) or null |  |
| `last_status_code` | integer or null |  |
| `last_error` | string or null |  |
| `last_response_excerpt` | string or null | The start of your endpoint's last answer. |
| `created_at` | time (ISO 8601) |  |
| `delivered_at` | time (ISO 8601) or null |  |

### WebhookDeliveryPage

| Field | Type | Description |
|---|---|---|
| `deliveries` | array of [WebhookDelivery](https://agents.chesly.app/docs/api#webhookdelivery) |  |
| `next_cursor` | string or null |  |

### Key

| Field | Type | Description |
|---|---|---|
| `id` | string | The key's ID, for DELETE /v1/keys/{key_id}. |
| `name` | string |  |
| `scope` | `full` or `read` |  |
| `prefix` | string | The key's first 12 characters. |
| `last4` | string | The key's last 4 characters. |
| `created_via` | string | Where it was made: cli (chesly login) or web (the dashboard). |
| `created_at` | time (ISO 8601) |  |
| `last_used_at` | time (ISO 8601) or null | Recorded at most every 5 minutes. |

### KeyList

| Field | Type | Description |
|---|---|---|
| `keys` | array of [Key](https://agents.chesly.app/docs/api#key) |  |

### SendLimit

| Field | Type | Description |
|---|---|---|
| `account_id` | string or null |  |
| `network` | string |  |
| `per_hour` | integer |  |
| `per_day` | integer |  |
| `used_last_hour` | integer |  |
| `used_last_day` | integer |  |

### PlanSummary

| Field | Type | Description |
|---|---|---|
| `plan` | `personal`, `pro` or null | The plan bought; a comp reads pro; null without one. |
| `status` | `none`, `trialing`, `active`, `past_due`, `unpaid`, `canceled` or `comped` | unpaid: Stripe stopped retrying a failed payment; no access until the card is updated. |
| `trial_ends_at` | time (ISO 8601) or null |  |
| `period_start` | time (ISO 8601) or null |  |
| `period_end` | time (ISO 8601) or null |  |
| `cancel_at` | time (ISO 8601) or null | When a canceled plan ends (the end of the period paid for); null while it renews. |
| `calls_this_period` | integer | Counted, never billed. |
| `transcription_seconds_this_period` | integer |  |
| `transcription_seconds_included` | integer | The period's minutes, in seconds: 36,000 on Personal, 180,000 on Pro, 0 without a plan. |
| `scheduled_change` | object or null | A downgrade waiting for the end of the period paid for: the plan, and when it starts. null without one. |
| `scheduled_change.plan` | `personal` or `pro` |  |
| `scheduled_change.at` | time (ISO 8601) |  |

### Me

| Field | Type | Description |
|---|---|---|
| `key` | object |  |
| `key.id` | string |  |
| `key.name` | string |  |
| `key.scope` | `full` or `read` |  |
| `key.api_version` | string |  |
| `limits` | object |  |
| `limits.requests_per_second` | integer | Per key, and for all of your keys together: your plan's. |
| `limits.requests_per_minute` | integer | Per key, and for all of your keys together: your plan's. |
| `limits.api_keys` | integer | Active API keys your plan allows. |
| `limits.webhooks` | integer | Webhooks your plan allows. |
| `limits.sends` | array of [SendLimit](https://agents.chesly.app/docs/api#sendlimit) |  |
| `limits.event_streams` | integer | Event streams (GET /v1/events/stream) your plan lets you hold open at once. |
| `limits.event_retention_days` | integer | How many days your plan keeps your events: an `after` (or Last-Event-ID) older than that is 410 events_expired. |
| `usage` | object |  |
| `usage.period_start` | time (ISO 8601) |  |
| `usage.calls` | integer | This key's calls this UTC month, before this one. |
| `plan` | [PlanSummary](https://agents.chesly.app/docs/api#plansummary) |  |

### Account

| Field | Type | Description |
|---|---|---|
| `id` | string | The account's ID (acct_…). |
| `network` | string |  |
| `display_name` | string or null |  |
| `status` | `connected`, `disconnected` or `needs_attention` |  |
| `connected_at` | time (ISO 8601) or null |  |

### AccountList

| Field | Type | Description |
|---|---|---|
| `accounts` | array of [Account](https://agents.chesly.app/docs/api#account) |  |

### Chat

| Field | Type | Description |
|---|---|---|
| `id` | string | The chat's ID (chat_…). |
| `account_id` | string or null |  |
| `network` | string |  |
| `name` | string or null |  |
| `type` | `dm` or `group` |  |
| `unread_count` | integer |  |
| `last_message_at` | time (ISO 8601) or null |  |
| `is_archived` | boolean |  |
| `is_pinned` | boolean |  |
| `is_muted` | boolean |  |
| `is_message_request` | boolean | A pending request: readable, never answered or marked read. |
| `member_count` | integer |  |

### ChatPage

| Field | Type | Description |
|---|---|---|
| `chats` | array of [Chat](https://agents.chesly.app/docs/api#chat) | Pinned chats first, then the newest. |
| `next_cursor` | string or null | The next page's cursor, or null on the last page. |

### MessageMedia

| Field | Type | Description |
|---|---|---|
| `id` | string | The media's ID (media_…), for GET /v1/media/{media_id}. |
| `mime_type` | string | Optional. |
| `file_name` | string | Optional. |

### DeliveryError

| Field | Type | Description |
|---|---|---|
| `code` | `network_rejected`, `not_logged_in`, `rate_limited_by_network`, `unsupported`, `timeout` or `unknown` |  |
| `message` | string | A fixed sentence for the code. |
| `certain` | boolean | Whether the message certainly didn't arrive (false: it may have). |

### Delivery

How a message sent through the API in the last 30 days is getting on; null for any other.

| Field | Type | Description |
|---|---|---|
| `status` | `queued`, `sent`, `delivered` or `failed` |  |
| `error` | [DeliveryError](https://agents.chesly.app/docs/api#deliveryerror) or null |  |
| `updated_at` | time (ISO 8601) |  |

### EmailAddress

| Field | Type | Description |
|---|---|---|
| `name` | string or null |  |
| `address` | string |  |

### EmailHeaders

An email's headers, on network email only.

| Field | Type | Description |
|---|---|---|
| `subject` | string or null |  |
| `from` | [EmailAddress](https://agents.chesly.app/docs/api#emailaddress) |  |
| `to` | array of [EmailAddress](https://agents.chesly.app/docs/api#emailaddress) |  |
| `cc` | array of [EmailAddress](https://agents.chesly.app/docs/api#emailaddress) |  |

### Message

| Field | Type | Description |
|---|---|---|
| `id` | string | The message's ID (msg_…). |
| `chat_id` | string |  |
| `sender` | object |  |
| `sender.name` | string |  |
| `sender.is_me` | boolean |  |
| `text` | string |  |
| `truncated` | boolean |  |
| `type` | `text`, `image`, `video`, `audio`, `file` or `other` |  |
| `media` | [MessageMedia](https://agents.chesly.app/docs/api#messagemedia) or null |  |
| `sent_at` | time (ISO 8601) or null |  |
| `edited` | boolean |  |
| `deleted` | boolean |  |
| `reply_to` | string or null | The message this one replies to, in the same chat. |
| `delivery` | [Delivery](https://agents.chesly.app/docs/api#delivery) or null |  |
| `email` | [EmailHeaders](https://agents.chesly.app/docs/api#emailheaders) | Optional. |

### MessagePage

| Field | Type | Description |
|---|---|---|
| `messages` | array of [Message](https://agents.chesly.app/docs/api#message) | Newest first. A page can be short, or empty, while next_cursor still leads to older ones. |
| `next_cursor` | string or null |  |

### ReadResult

| Field | Type | Description |
|---|---|---|
| `read` | `true` |  |
| `receipt_sent` | boolean | Whether the network got a read receipt (never for a message request). |

### SearchHit

object.

### SearchResults

| Field | Type | Description |
|---|---|---|
| `messages` | array of [SearchHit](https://agents.chesly.app/docs/api#searchhit) | Newest first. |

### MessagesSince

| Field | Type | Description |
|---|---|---|
| `messages` | array of [Message](https://agents.chesly.app/docs/api#message) | Chats newest first; each chat's messages newest first. |
| `next_cursor` | string or null |  |
| `until` | time (ISO 8601) | Where this walk ends: start the next one from here. |

### CatchUp

| Field | Type | Description |
|---|---|---|
| `chats` | array of object |  |
| `chats[].chat` | [Chat](https://agents.chesly.app/docs/api#chat) |  |
| `chats[].messages` | array of [Message](https://agents.chesly.app/docs/api#message) |  |
| `truncated` | boolean | Whether some messages were left out, or a chat's messages couldn't be read. |

### CliSession

| Field | Type | Description |
|---|---|---|
| `device_code` | string |  |
| `user_code` | string |  |
| `verification_uri` | URL |  |
| `verification_uri_complete` | URL | The approval page with the code filled in. |
| `expires_in` | integer | Seconds until the code expires. |
| `interval` | integer | Seconds to wait between polls. |

### CliSessionRequest

| Field | Type | Description |
|---|---|---|
| `client_name` | string | Labels the key, such as the computer's name. Optional. |

### CliToken

| Field | Type | Description |
|---|---|---|
| `api_key` | string |  |
| `token_type` | `Bearer` |  |

### CliTokenError

| Field | Type | Description |
|---|---|---|
| `error` | `authorization_pending`, `slow_down`, `access_denied`, `expired_token` or `invalid_request` |  |

### CliTokenRequest

| Field | Type | Description |
|---|---|---|
| `device_code` | string |  |

### SendMessage

| Field | Type | Description |
|---|---|---|
| `text` | string | The text, or a file's caption. At most 1,000 characters on Instagram, 2,000 on Discord, 4,096 on Telegram, 100,000 by email and 10,000 elsewhere, counted in UTF-16 code units. In a Google Messages RCS chat, which takes no captions, it follows the file as a message of its own. Optional. |
| `reply_to` | string | The message this one replies to: a message ID (msg_…) of the same chat. Optional. |
| `media_id` | string | A file to send: the ID POST /v1/media answered (media_…). Optional. |

### UploadedMedia

| Field | Type | Description |
|---|---|---|
| `id` | string | The upload's media ID (media_…): send it as media_id. Kept 24 hours. |
| `mime_type` | string |  |
| `size` | integer | In bytes. |
| `file_name` | string |  |

### MediaUpload

| Field | Type | Description |
|---|---|---|
| `file` | bytes | The file, at most 50 MB (50,000,000 bytes). |

### Transcript

| Field | Type | Description |
|---|---|---|
| `message_id` | string | The voice message's ID (msg_…). |
| `text` | string |  |
| `language` | string or null | The language heard, as an ISO 639 code, when it was detected. |
| `duration_seconds` | number or null | The voice message's length, to a tenth of a second. |
| `cached` | boolean | Transcribed before: this answer used none of your plan's minutes. |