Threads

Returns the conversations the caller can see — their own, plus any shared with them or with a space they belong to. Context-agent threads are excluded unless thread_type asks for them.

Pass thread_space to create it inside a space, which requires write access to that space. Without one it is personal to the caller.

Returns the conversation with its agent, its subject and who it is shared with. The messages in it are read separately.

Deactivates the thread and the messages in it.

Applies the thread_-prefixed fields present in the body. Only an owner may change who the thread is shared with.

A server-sent event stream: user_message, assistant_message, lock and presence. This is how a client follows a reply as it is generated rather than polling for it.

Responds with text/event-stream, not JSON — use an SSE client.

Files belonging to this conversation — what was attached to it, and what was generated in it.

Requires any one of media:view, document:view, knowledge-base:view, thread:view, design:view, prompt:view or presentation:view.

Returns who the thread is shared with, and what each of them may do with it.

Only the owner of a personal thread may share it. A thread that lives in a space takes its access from the space instead, so this does not apply to one.

The owner cannot be removed from their own thread.

Heartbeat behind the presence events. Send it periodically while the thread is open.

For conversations attached to something else — a file, a task. Returns the existing thread or starts one.

It is a POST because it writes. If you only want to look, GET /threads?thread_ref=… reads and never creates.

Requires both thread:create and thread:view.

Searches titles and message text, returning matching threads with a highlighted snippet and the message that produced it.

Unless you narrow it yourself, the search covers roughly the last 60 days. Messages are stored in time-partitioned tables, and an unbounded search would read every partition — the window is what keeps it fast.