Threads API

Conversation threads, their messages, and archive lifecycle.

📄️Create thread

Supports the `Idempotency-Key` header: retrying with the same key and body replays the original thread (`Idempotency-Replay: true`); reusing a key with a different body answers 409.

📄️Get thread

Answers the same shape `POST /api/v1/threads/` returns. The lookup is scoped to the caller’s company and, when the thread belongs to an application, requires access to that application.

📄️List messages

`take` is clamped to 50. `cursor` is a message id; only messages older than it are returned. `fields=compact` returns role, text parts, and timestamps only — the right shape for reading a conversation; the default `full` embeds reasoning traces and provider metadata too. The serving model (`metadata.modelProviderId`) is omitted unless the caller is a platform super admin.

📄️Archive thread

Accepts an optional JSON body `{ agentId?, summarize? }`: `summarize=false` archives without a summary, `agentId` selects the insights agent, and no body lets the thread metadata decide. Supports the `Idempotency-Key` header: a retry with the same key and body replays the stored response instead of re-triggering the summary.

📄️List routines in conversation

Routines the caller scheduled in this conversation, with their schedule and next and last run.

📄️Schedule routine in conversation

Schedules a task to run repeatedly in this conversation ('every morning check X and tell me'). Each run posts `prompt` as a message and the assistant answers it in the conversation with the same tools; on a WhatsApp, Slack, Teams or SMS conversation the answer is sent there too (WhatsApp only delivers within 24 hours of the user's last message). At most 5 routines per conversation, each at most hourly.

📄️Change conversation routine

Changes a routine in this conversation: its name, prompt or schedule, or pauses (`enabled: false`) and resumes it. Send only the fields to change.

📄️Delete conversation routine

Stops and deletes a routine. Answers it already gave stay in the conversation.

📄️Run conversation routine now

Starts one run of a routine the assistant scheduled in this conversation. The run is an assistant turn on the thread: its prompt is posted as a user message and the answer is written into the thread. Returns once the turn has started. A routine that is disabled, missing, or whose conversation is archived or still answering is skipped.

📄️Get latest insights snapshot

Snapshots are produced by insight extraction, which runs after agent turns or when a thread is archived with an insights-enabled agent (see `POST /api/v1/threads/{threadId}/archive/`). Answers `null` with status 200, not 404, when the thread exists but has no snapshot yet.

📄️List my conversation routines

Every routine the caller scheduled, across their open conversations (AI chat, WhatsApp, Slack...), with the conversation each one runs in. Change or delete one through its conversation: `/threads/{threadId}/routines/{routineId}/`.