Start a chat
/api/v1/chatsStart a chat with an agent. Send it its first message with the send operation; the agent answers in the chat.
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:create, agents:invoke
Any active member who may run the agent. A private agent chats with its owner only. The chat is private to you: workspace owners and admins may only stop its turn or delete it, signed in to the app, and read none of it.
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
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.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A new chat with an agent.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/chats" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "5b0f3c84-6a51-4a9e-9a7e-1d2f0c6b8e21", "title": "Quarterly review" }'{ "chat": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "agent_name": "string", "title": "string", "title_source": "auto", "status": "active", "message_count": 0, "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" } ] } ], "awaiting_input_kind": "question", "is_running": false, "response_alert_kind": "error", "pinned_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}List your chats GET
List the chats you started in this workspace.
Retrieve a chat GET
Retrieve a chat. `is_running` is true while a turn works, and `awaiting_input_kind` names a question or approval the chat waits on. Answer it in the app, or through the interaction operation of the run that asked: the `run_id` of the chat's newest message.