Conversations API: Talk to Hosted Agents

A conversation is a thread between you and a hosted agent. It owns its turns, its transcript, and any files you attach. Each message you send starts a turn, and the agent works through it inside its sandbox. Use these endpoints to drive an agent from your own app or script: open a thread, send messages, follow the work live, and stop a turn that went off course. To control what the agent can reach while it works, see Agent access.

Endpoints

Endpoint	Method and path	What it does
List conversations	`GET /conversations`	List your workspace’s conversations with hosted agents, newest first.
Start a conversation	`POST /conversations`	Open a new shared conversation with a hosted agent.
Get a conversation	`GET /conversations/{conversationId}`	Fetch one conversation with a hosted agent by ID.
List turns	`GET /conversations/{conversationId}/turns`	List the turns in a conversation with a hosted agent.
Send a message (strict)	`POST /conversations/{conversationId}/turns`	Send a message that starts a new turn only when the agent is idle.
Send a message	`POST /conversations/{conversationId}/messages`	Send a message to a hosted agent at any time.
Read the transcript	`GET /conversations/{conversationId}/events`	Read a conversation’s event log in order.
Stream the transcript	`GET /conversations/{conversationId}/stream`	Follow a conversation live with Server-Sent Events.
Upload an attachment	`POST /conversations/{conversationId}/attachments`	Upload a file of up to 10 MB to a conversation, then reference it in your next message so the hosted agent can read it.
Download an attachment	`GET /conversations/{conversationId}/attachments/{attachmentId}`	Download the bytes of a file attached to a conversation, whether you uploaded it or the hosted agent produced it.
Get an attachment’s metadata	`GET /conversations/{conversationId}/attachments/{attachmentId}/meta`	Get a conversation attachment’s name, type, size, and status without downloading the file itself.
Get a short-lived download URL	`GET /conversations/{conversationId}/attachments/{attachmentId}/download-url`	Get a short-lived URL a browser can use to download a conversation attachment directly from storage.
Abort a turn	`POST /turns/{turnId}/abort`	Stop a hosted agent’s running turn.

Next steps

API overview: base URLs, authentication, and pagination
Errors: status codes and the error format
Editions: which endpoints each edition serves

Workspace

Organization

Enterprise

Platform

Conversations API: Talk to Hosted Agents

Endpoints

Next steps

​Related guides

​Endpoints

​Next steps

Related guides

Endpoints

Next steps