Guest Machines
API referenceChats

Update a chat

PATCH/api/v1/chats/{chat_id}

Rename a chat, archive it or make it active again, or pin it to the top of your list. An archived chat takes no messages.

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:edit

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.

Authorization

AuthorizationBearer <token>

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

chat_id*Chat Id
Formatuuid

Header Parameters

X-Org-Id?|

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.

What to change about a chat; fields left out stay as they are.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/v1/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "title": "Q3 planning",    "pinned": true  }'
{  "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"  }}

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.

Delete a chat DELETE

Permanently delete a chat with its messages, its attachments and the messages still waiting. Runs it started stay in the run history.