Read and share chats

A run saved with history is a chat (chat history). These routes need a signed-in user. With an API key, read an agent's chats through Lab with the lab scope.

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.

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.

Find the chat:

curl "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/chats/?limit=5" \
  -H "Authorization: Bearer $ALO_TOKEN" \
  -H "X-Space-Slug: $WORKSPACE_SLUG"

Rename it with its configurable_agent_id and id:

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"}'

Create a copy link:

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"

{"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

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

Read and share chats

Chats

Share a chat

Example: rename a chat and share a copy

Errors

On this page