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.

📄️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.

📄️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.