> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt). # Read and share chats Read and share chats [#read-and-share-chats] A run saved with history is a chat ([chat history](run-and-stream#chat-history)). These routes need a signed-in user. With an API key, read an agent's chats through [Lab](../lab/overview) with the `lab` scope. Chats [#chats] All paths start with `/api/v1/agents-v2` and need `X-Space-Slug`. | Method | URL | Does | Auth | | -------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- | | `GET` | `/agents/chats/?limit=100&offset=0` | The caller's chats with every agent: `id`, `thread_id`, `title`, `configurable_agent_id`, `last_message_at`, `access_level` | Bearer only | | `GET` | `/agents/{agent_id}/chats/` | The caller's chats with one agent | Bearer only | | `GET` | `/agents/{agent_id}/chats/{chat_id}/` | The messages, a list of `{messageId, role, parts, authorEmail, modelDisplayName, …}`; `role` is `user` or `agent` | Bearer only | | `PATCH` | `/agents/{agent_id}/chats/{chat_id}/` | Change `title`, `is_pinned` or `is_unread`; returns the chat | Bearer only | | `GET` | `/agents/{agent_id}/chats/{chat_id}/summary/` | `{summary, last_context_tokens, context_threshold, …}`; `summary` is `null` until the chat is long enough to be summarized | Bearer only | | `DELETE` | `/agents/{agent_id}/chats/{chat_id}/messages/{message_id}/delete-trailing/` | Remove that message and every later one: `200 {"detail": "Message history updated successfully"}` | Bearer only | | `DELETE` | `/agents/{agent_id}/chats/{chat_id}/` | Delete the chat; `204` | Bearer only | | `GET` | `/agents/{agent_id}/chats/{chat_id}/apps/` | Apps built in this chat | Bearer only | | `GET` | `/threads/{thread_id}/sub-agents/` | Delegated runs started from the thread | Bearer only | | `GET` | `/threads/{thread_id}/events/` | The thread's live events, as a server-sent event stream | Bearer only | `messageId` values in a chat are the IDs `delete-trailing` takes. Share a chat [#share-a-chat] Only the chat's owner can share it. | Method | URL | Does | Auth | | -------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------- | | `POST` | `/agents/{agent_id}/chats/{chat_id}/share/?mode=copy` | Create a link; `201 {id, token, url, status, mode, is_public, …}`. `mode` is `copy` (default) or `collaborate` | Bearer only | | `GET` | `/agents/{agent_id}/chats/{chat_id}/share/?mode=copy` | The active link of that mode, or `null` | Bearer only | | `PATCH` | `/agents/{agent_id}/chats/{chat_id}/share/{link_id}/` | `{"is_public": true}` lets anyone with a `copy` link read the chat without signing in; `is_public` is required | Bearer only | | `DELETE` | `/agents/{agent_id}/chats/{chat_id}/share/{link_id}/` | Revoke the link; `204` | Bearer only | | `GET` | `/agents/{agent_id}/chats/{chat_id}/collaborators/` | People who joined through a `collaborate` link | Bearer only | | `DELETE` | `/agents/{agent_id}/chats/{chat_id}/collaborators/{user_id}/` | Remove one; their old link stops working too | Bearer only | | `mode` | Who opens the `url` | What they get | | ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `copy` | Any signed-in user on the platform; anyone when `is_public` is `true` | A frozen copy of the chat up to now, which a signed-in viewer can continue as their own chat | | `collaborate` | A signed-in member of the chat's workspace | The same live chat, with its sandbox, files and app | Send people the `url` from the response. Opening a link (`/agents-v2/shared-chats/{token}/…`) always needs a signed-in user, not a key. Example: rename a chat and share a copy [#example-rename-a-chat-and-share-a-copy] 1. Find the chat: ```bash curl "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/chats/?limit=5" \ -H "Authorization: Bearer $ALO_TOKEN" \ -H "X-Space-Slug: $WORKSPACE_SLUG" ``` 2. Rename it with its `configurable_agent_id` and `id`: ```bash curl -X PATCH "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/36/chats/1/" \ -H "Authorization: Bearer $ALO_TOKEN" \ -H "X-Space-Slug: $WORKSPACE_SLUG" \ -H "Content-Type: application/json" \ -d '{"title": "Readiness check"}' ``` 3. Create a copy link: ```bash curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/36/chats/1/share/?mode=copy" \ -H "Authorization: Bearer $ALO_TOKEN" \ -H "X-Space-Slug: $WORKSPACE_SLUG" ``` ```json {"id": 1, "token": "7BX2…8wWr", "url": "https://platform.alomana.com/shared-chats/7BX2…8wWr", "status": "active", "mode": "copy", "is_public": false, "created_at": "2026-10-20T14:04:32.479937Z", "last_used_at": null} ``` Errors [#errors] | Response | Cause | | ---------------------------------- | ------------------------------------------------------------------- | | `422` `is_public` `Field required` | `PATCH …/share/{link_id}/` without `is_public` | | `404` `Chat not found` | The chat is not the caller's, or `agent_id` is not the chat's agent |