cherami.
API referenceConversations

Read a conversation

GET /v1/threads/{thread_id}

Read as Markdown ↗

GET /v1/threads/{thread_id}

Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.

GET /v1/threads/{thread_id}?limit=20 returns 200 with conversation metadata, plus messages and next_cursor.

Each entry has direction (received or sent), timestamp (ISO service receipt/submission time), and the fields from received detail or sent detail.

Bodies and attachment metadata are included, without attachment bytes. Received attachments use the ordinary download endpoint. Sent thread attachments have id, filename, mime_type, and size in bytes; use ordinary sent detail for their base64 content.

The first page contains the newest messages, chronological within the page. The next page contains older messages. Metadata counts describe the conversation, not just the current page.

Accepts limit 1–100, default 20. Follow next_cursor as a URL-encoded cursor parameter on the same resource URL. Ordering uses service timestamps, not sender-controlled Date headers.

Conversations can update, and pages are not a snapshot. Previously returned thread IDs remain usable while their conversation exists; the returned id may differ from the requested one. Continue a pagination sequence on the same requested URL, and refetch recent context when needed.

Pending, processing, and failed received messages have thread_id: null and are absent from threads. They remain available through message endpoints. Deleted messages disappear; surviving messages remain grouped. Empty, missing, or other-account conversations return 404. Invalid limits/cursors return 400, and unavailable content can return 503.

Each message retains its own labels; threads have no label set. Filters select conversations without filtering their detail pages. Manual merging is not provided. Thread membership is not proof of identity or delivery. Reply using a message resource ID, not the thread ID.

Parameters

ParameterLocationRequiredTypeMeaning
thread_idpathYesstringOwned Cherami resource ID returned by the API.
limitqueryNointegerDecimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20
cursorqueryNostringOpaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null.

curl example

Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.

curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/threads/THREAD_ID" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"

Responses

HTTP 200

Successful operation; inspect resource state and outcome fields.

  • X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

ThreadDetail

{
  "id": "11111111-1111-4111-8111-111111111111",
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "subject": null,
  "last_activity_at": "2026-10-01T00:00:00.000Z",
  "message_count": 0,
  "received_count": 0,
  "accepted_count": 0,
  "rejected_count": 0,
  "unknown_count": 0,
  "messages": [],
  "next_cursor": null
}

HTTP 400

invalid_limit: Use an integer from 1 to 100.

invalid_cursor: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.

  • X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 401

unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.

  • X-Request-ID: Support correlation ID, not an idempotency key.
  • WWW-Authenticate: "Bearer"

Content type: application/json.

Error

HTTP 404

not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

  • X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 500

internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.

  • X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 503

content_unavailable: Expected stored content is unavailable. Retry the read later.

  • X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

Schema: ThreadDetail

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
inbox_idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
subjectYesstring or null
last_activity_atYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
message_countYesintegerminimum: 0
received_countYesintegerminimum: 0
accepted_countYesintegerminimum: 0
rejected_countYesintegerminimum: 0
unknown_countYesintegerminimum: 0
messagesYesarray of ThreadReceivedDetail or ThreadSentDetail
next_cursorYesstring or null

Schema: ThreadReceivedDetail

All of these schemas apply.

Part 1

ReceivedDetail

Part 2

FieldRequiredTypeMeaning and constraints
directionYes"received"
timestampYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

Schema: ReceivedDetail

Exactly one of these shapes applies.

Alternative 1

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
inbox_idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"ready"
labelsYesarray of string
message_idYesstring or null
raw_sizeYesintegerminimum: 0
processed_atYesstring or null
contentYesReceivedContent

Alternative 2

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
inbox_idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
thread_idYesstring or null
envelope_fromYesstring
envelope_toYesstring
subjectYesstring or null
received_atYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
processing_statusYes"pending" or "processing" or "failed"
labelsYesarray of string
message_idYesstring or null
raw_sizeYesintegerminimum: 0
processed_atYesstring or null

Schema: ReceivedContent

FieldRequiredTypeMeaning and constraints
fromYesParsedAddress or null
senderYesParsedAddress or null
reply_toYesarray of ParsedAddress
toYesarray of ParsedAddress
ccYesarray of ParsedAddress
bccYesarray of ParsedAddress
subjectYesstring or null
message_idYesstring or null
in_reply_toYesstring or null
referencesYesstring or null
dateYesstring or null
reply_textYesstring or null
textYesstring or null
htmlYesstring or null
attachmentsYesarray of ReceivedAttachment

Schema: ParsedAddress

Sender-controlled MIME address or group, not verified identity.

Exactly one of these shapes applies.

Alternative 1

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Alternative 2

FieldRequiredTypeMeaning and constraints
nameYesstring
groupYesarray of object

group fields

FieldRequiredTypeMeaning and constraints
nameYesstring
addressYesstring

Schema: ReceivedAttachment

FieldRequiredTypeMeaning and constraints
idYesstring
filenameYesstring or null
sizeYesintegerminimum: 0
mime_typeYesstring
dispositionYesstring or null
content_idYesstring or null
relatedYesboolean

Schema: ThreadSentDetail

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
inbox_idYesstringCherami resource ID, distinct from the RFC Message-ID. Use the returned value.
created_atYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
recipient_countYesintegerminimum: 0
statusYes"accepted" or "rejected" or "unknown"
provider_message_idYesstring or null
error_codeYesstring or null
thread_idYesstring or null
in_reply_toYesstring or null
labelsYesarray of string
directionYes"sent"
timestampYesstringUTC service instant with milliseconds and Z suffix. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
reply_textYesstring or null
submissionYesobject

submission fields

FieldRequiredTypeMeaning and constraints
toYesarray of Mailbox or string
ccYesarray of Mailbox or string
bccYesarray of Mailbox or string
subjectYesstring
textYesstring
htmlNostring
attachmentsYesarray of object
fromYesMailbox or string
headersNoobject

attachments fields

FieldRequiredTypeMeaning and constraints
idYesstring
filenameYesstring
mime_typeYesstring
sizeYesintegerminimum: 0

headers fields

FieldRequiredTypeMeaning and constraints
In-Reply-ToYesstring
ReferencesYesstring

Schema: Mailbox

FieldRequiredTypeMeaning and constraints
addressYesstringBare ASCII address, at most 254 characters, local part at most 64. No display-name header syntax. maxLength: 254
nameNostringUnicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming. x-max-utf8-bytes: 256

Unknown fields are rejected.

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringProgrammatic error code. Handle unrecognized codes by status and operation-specific recovery.
messageYesstringHuman-readable context, not a stable string to match.

HTTP conventions, errors and pagination · Download OpenAPI 3.1

List conversations

GET /v1/inboxes/{inbox_id}/threads

Label a conversation

PATCH /v1/threads/{thread_id}

On this page

Parameterscurl exampleResponsesHTTP 200HTTP 400HTTP 401HTTP 404HTTP 500HTTP 503Schema: ThreadDetailSchema: ThreadReceivedDetailPart 1Part 2Schema: ReceivedDetailAlternative 1Alternative 2Schema: ReceivedContentSchema: ParsedAddressAlternative 1Alternative 2group fieldsSchema: ReceivedAttachmentSchema: ThreadSentDetailsubmission fieldsattachments fieldsheaders fieldsSchema: MailboxSchema: Errorerror fields