List a chat's messages
/api/v1/chats/{chat_id}/messagesList a chat's messages in the order they were written, ending with the newest.
A message you sent appears here once a turn takes it in, with the client_ref you sent it with, and the agent's answer follows it as an assistant message when the turn ends. run_id names the run that wrote an answer.
A page holds the newest limit messages. When has_more is true, pass next_cursor as cursor to read the messages before them.
Required access
Credentials: delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: chats:read
Only the member who started the chat, through their user API key or an integration acting for them: a chat is private to them. Another member's chat answers 404, also to a workspace owner or admin, who may only stop its turn or delete it, signed in to the app, and reads none of it. Automation accounts have no chats.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Path Parameters
uuidQuery Parameters
1 <= value <= 5001000 <= value0Opaque cursor returned by the previous page
Header Parameters
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"{ "messages": [ { "id": 0, "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82", "role": "assistant", "content": "string", "metadata": { "type": "ask_user", "shared_chat": { "token": "string" }, "commentary": [ { "id": "string", "content": "string", "thinking": "string" } ], "activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string", "status": "completed", "duration_ms": 0, "thread": { "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "request_status": "answered" } } ], "approval": { "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "resource_summary": "string", "effect_details": "string", "attachment_files": [ { "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12", "file_name": "string", "media_type": "string", "download_only": false, "file_size": 0, "sha256": "string" } ], "risk_level": "string", "always_asks": false, "asks_under_no_approvals": false }, "correlation_id": "string", "preamble": "string", "questions": [ { "question": "string", "suggestions": [ { "label": "string", "recommended": false } ], "allow_other": true } ], "tool_calls_count": 0, "usage": { "model": "string", "tokens_used": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": 0, "duration_seconds": 0 }, "run_error": { "category": "string", "code": "string", "message": "string", "retryable": false }, "limit_detail": { "error": "limit_exceeded", "limit_type": "account.needs_approval", "scope": "agent", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0, "resets_at": "2019-08-24T14:15:22Z" }, "compacted": false, "stopped": false, "stopped_by": { "principal_type": "agent", "name": "string" }, "run_id": 1, "client_ref": "string" }, "run_id": 0, "created_at": "2019-08-24T14:15:22Z", "references": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "knowledge_type": "file", "created_at": "2019-08-24T14:15:22Z", "summary": "string", "caption": "string", "file_name": "string", "file_path": "string", "file_size": 0, "file_type": "string", "height": 0, "width": 0, "duration": 0, "page_count": 0, "thumbnail_url": "string" } ], "attachments": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "chat_session_id": "eab2a04d-304d-443e-9f8d-1a824a2c4f65", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "uploaded_by_user_id": "9fdcaa70-9955-45b2-9821-39697e7541f8", "file_name": "string", "original_file_name": "string", "file_type": "string", "file_size": 0, "checksum": "string", "status": "deleted", "has_extracted_text": false, "thumbnail_sizes": [ "string" ], "metadata": {}, "error": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "artifacts": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "producer_run_id": 0, "root_run_id": 0, "chat_message_id": 0, "visibility": "org_shared", "status": "deleted", "source_kind": "generated", "file_name": "string", "media_type": "string", "download_only": false, "file_size": 0, "sha256": "string", "description": "string", "is_primary": true, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] } ], "total": 0, "next_cursor": "string", "has_more": false}Stop a chat's turn POST
Stop the turn the chat is working on, as the app's Stop does. Messages still waiting stay, and the next one starts the chat's next turn.
Send a message POST
Send the chat's agent a message, as the app's Send does. The message waits with the chat's others until a turn takes it in, and the agent answers it in the chat.