API Reference
Threads and Responses API
API surface for conversational threads, messages, and response execution.
Threads group conversational context. Responses project agent execution, streaming events, citations, tool calls, and trace state into an API shape suitable for chat and app integrations.
Prefixes
/api/v1/threads
/api/v1/responsesThreads endpoints
| Method | Path | Purpose |
|---|---|---|
| POST / GET | / | Create threads; list with pagination |
| GET | /{thread_id} | Thread detail with messages and execution context |
| PATCH | /{thread_id} | Update thread settings (title, defaults, pinning) |
| DELETE | /{thread_id} | Delete a thread |
Responses endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | / | Start response execution for a thread input |
| GET | /{response_id} | Response state |
| GET | /{response_id}/detail | Full detail with citations, tool calls, and trace links |
| GET | /{response_id}/events | Paginated response event history |
| GET | /{response_id}/stream | Live SSE stream of response events |
| POST | /{response_id}/cancel | Cancel an in-flight response |
| GET | /by-run/{run_id} | Response timeline for a given run |
Related prefixes
/api/v1/agents— the executing agent and its published version/api/v1/runs— the run behind each response/api/v1/knowledge— citation sources
Notes
- Every response links to its
run_id;GET /by-run/{run_id}goes the other way, so chat output and runtime evidence are always joinable.