> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations API: Talk to Hosted Agents

> Start conversations with a hosted agent, send messages, stream the transcript, and share files through the OneCLI API.

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](https://onecli.sh/docs/guides/agent-access.md).

## Related guides

* [Agent access: grant credentials to agents](https://onecli.sh/docs/guides/agent-access.md)
* [How it works: the gateway injects credentials](https://onecli.sh/docs/how-it-works.md)

## Endpoints

| Endpoint | Method and path | What it does |
| - | - | - |
| [List conversations](https://onecli.sh/docs/api-reference/conversations/list-conversations.md) | `GET /conversations` | List your workspace's conversations with hosted agents, newest first. |
| [Start a conversation](https://onecli.sh/docs/api-reference/conversations/start-a-conversation.md) | `POST /conversations` | Open a new shared conversation with a hosted agent. |
| [Get a conversation](https://onecli.sh/docs/api-reference/conversations/get-a-conversation.md) | `GET /conversations/{conversationId}` | Fetch one conversation with a hosted agent by ID. |
| [List turns](https://onecli.sh/docs/api-reference/conversations/list-turns.md) | `GET /conversations/{conversationId}/turns` | List the turns in a conversation with a hosted agent. |
| [Send a message (strict)](https://onecli.sh/docs/api-reference/conversations/send-a-message-strict.md) | `POST /conversations/{conversationId}/turns` | Send a message that starts a new turn only when the agent is idle. |
| [Send a message](https://onecli.sh/docs/api-reference/conversations/send-a-message.md) | `POST /conversations/{conversationId}/messages` | Send a message to a hosted agent at any time. |
| [Read the transcript](https://onecli.sh/docs/api-reference/conversations/read-the-transcript.md) | `GET /conversations/{conversationId}/events` | Read a conversation's event log in order. |
| [Stream the transcript](https://onecli.sh/docs/api-reference/conversations/stream-the-transcript.md) | `GET /conversations/{conversationId}/stream` | Follow a conversation live with Server-Sent Events. |
| [Upload an attachment](https://onecli.sh/docs/api-reference/conversations/upload-an-attachment.md) | `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](https://onecli.sh/docs/api-reference/conversations/download-an-attachment.md) | `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](https://onecli.sh/docs/api-reference/conversations/get-an-attachments-metadata.md) | `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](https://onecli.sh/docs/api-reference/conversations/get-a-short-lived-download-url.md) | `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](https://onecli.sh/docs/api-reference/conversations/abort-a-turn.md) | `POST /turns/{turnId}/abort` | Stop a hosted agent's running turn. |

## Next steps

* [API overview](https://onecli.sh/docs/api-reference.md): base URLs, authentication, and pagination
* [Errors](https://onecli.sh/docs/api-reference/errors.md): status codes and the error format
* [Editions](https://onecli.sh/docs/api-reference/editions.md): which endpoints each edition serves


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.