{ "schema_version": "1.0.0", "kind": "symposium.workspace_api.catalog", "title": "Symposium WorkspaceAPI", "api_version": "v1", "description": "Complete machine-readable WorkspaceAPI contract and examples for coding agents and integration tooling.", "canonical_url": "https://app.sym.so/docs.json", "human_documentation_url": "https://app.sym.so/docs", "openapi_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}/openapi.json", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "account_base_url": "https://app.sym.so/v1/account", "account_access_guide": "https://app.sym.so/docs/account-access", "authentication": { "account_api_key": "Authorization: Bearer ; account operations only", "conversation_delegation": "Workspace bearer plus X-Sym-Account-Authorization account bearer; same owning user and both scopes required", "workspace_api_key": "Authorization: Bearer ", "key_authority": "Authority is per endpoint: account keys authorize owned account resources, not workspaces. Workspace keys authorize only their workspace, not personal account inventory. Conversation Pass operations require both credentials, matching owners, current membership/Agent access and both scope sets. Account keys are accepted only at the canonical app.sym.so gateway and never forwarded to workers.", "desktop_session": "Account key bootstrap uses Account Settings. Workspace key lifecycle also supports scoped workspace keys; see each operation.", "raw_secrets": "Raw API keys, webhook signing secrets, OAuth tokens, cookies, and internal worker credentials are never included in this catalog." }, "orca": { "contract_version": "orca-workspace-catalog-v2", "discovery_tool": "workspaceGetDocumentedOperations", "executor_tool": "workspaceExecuteDocumentedOperation", "freshness": "Live discovery and execution fetch this catalog; retained voice resources are rebuilt on resume when prompt, tool schemas or endpoint contracts change.", "delegated_capabilities": "Native profile skills and recording tools are not implied by this API catalog. Delegate to an authorized Agent chat; verify results, not just queue receipts.", "retired_products": [ "Tasks", "notifications" ] }, "conventions": { "format": "application/json unless an endpoint declares another content type", "pagination": "Paginated collections return next_cursor; pass it back in the cursor query parameter.", "idempotency": "Mutating operations that document Idempotency-Key can be safely retried with the same key.", "authorization_failures": "Agent-bound resources use non-enumerating 404 responses when missing or unauthorized.", "durable_operations": "Long-running mutations may return durable operation records instead of pretending work completed synchronously.", "request_ids": "Preserve X-Request-ID values when reporting integration failures.", "realtime_signals": "Every endpoint has one stable signal_id. Successful authorized invocations may emit a tiny workspace.api.invoked event on the workspace realtime connection; the event contains no request or response data.", "realtime_subscription": "Opt in on the existing realtime connection with {\"type\":\"subscribe\",\"topics\":[\"workspace.api.invoked\"]}. Unsubscribed clients receive no invocation signals." }, "chat_runtime_controls": { "conversation_reset": { "supported_via": "send-message", "operation_id": "send-message", "request": { "content": "/new", "client_message_id": "reset-chat-unique-001" }, "target": "The exact agent_id + chat_id current Hermes conversation.", "success_meaning": "The command was durably queued and dispatched; runtime acknowledgement is not guaranteed." }, "create_chat": "Creates a durable chat record; it does not restart the profile runtime or Agent Gateway.", "archive_chat": "Archives and preserves history; it does not reset, terminate, or restart the runtime.", "agent_settings": "Only approval_mode is writable; settings do not expose lifecycle controls.", "unavailable": [ "first-class reset acknowledgement", "session binding rotation/rebind", "chat runtime restart", "profile Agent Gateway restart", "tmux/session kill", "force new runtime" ] }, "security_boundaries": [ "Workspace membership, scopes, Agent visibility, and mutation rights are evaluated live.", "Project-file operations remain under each authorized Agent's guarded project-files root.", "SYM-OS window state, Dock state, Hermes databases, raw credential values, and IAM administration are unavailable; authorized Secrets operations expose configuration status and write-only mutation only.", "The browser tester permits only catalogued JSON GET operations and routes them through authenticated SYM-OS." ], "groups": [ "Account apps & Passes", "Conversation browser Passes", "Identity", "Machine", "API keys", "Agents", "Files & folders", "Chats", "Messages", "Operations", "Webhooks", "Secrets", "Workspace", "OAuth" ], "scopes": [ "browser_passes:read", "browser_passes:write", "workspace:read", "machine:read", "api_keys:read", "api_keys:write", "agents:read", "agents:create", "agents:write", "agents:delete", "files:read", "files:write", "chats:read", "chats:write", "messages:read", "messages:send", "operations:read", "operations:cancel", "webhooks:read", "webhooks:write", "schedules:read", "instructions:read", "instructions:write", "settings:read", "settings:write", "apps:read", "apps:write", "secrets:read", "secrets:write", "connections:read", "connections:write", "search:read" ], "endpoint_count": 82, "generated_openapi_path_count": 61, "generated_openapi_operation_count": 82, "endpoints": [ { "id": "get-agent-model-access", "signal_id": "get_agent_model_access", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/model-access", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Read profile model connections and default", "description": "Read profile model connections and default. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "settings:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "connect-agent-model", "signal_id": "connect_agent_model", "group": "Agents", "method": "POST", "path": "/agents/{agent_id}/model-access/connections", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "label", "provider", "model" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" }, "label": { "type": "string" }, "provider": { "enum": [ "anthropic", "custom" ] }, "api_key": { "type": "string", "writeOnly": true }, "base_url": { "type": "string", "format": "uri" }, "api_mode": { "enum": [ "chat_completions", "responses" ] }, "model": { "type": "string" } } }, "title": "Add or update a verified model connection", "description": "Add or update a verified model connection. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "settings:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "revision": 0, "label": "My provider", "provider": "custom", "base_url": "https://inference.example/v1", "api_mode": "chat_completions", "model": "model-id" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "verify-agent-model", "signal_id": "verify_agent_model", "group": "Agents", "method": "POST", "path": "/agents/{agent_id}/model-access/verify", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "connection_id", "model" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" }, "model": { "type": "string" } } }, "title": "Verify a model on an existing connection", "description": "Verify a model on an existing connection. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "settings:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "revision": 0, "connection_id": "codex", "model": "model-id" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "set-agent-model-default", "signal_id": "set_agent_model_default", "group": "Agents", "method": "POST", "path": "/agents/{agent_id}/model-access/default", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "selection" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "selection": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "connection_id", "model" ], "properties": { "connection_id": { "type": "string" }, "model": { "type": "string" } } } ] } } }, "title": "Set or reset the profile default model", "description": "Set or reset the profile default model. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "settings:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "revision": 0, "selection": null } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "delete-agent-model-connection", "signal_id": "delete_agent_model_connection", "group": "Agents", "method": "POST", "path": "/agents/{agent_id}/model-access/delete", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "connection_id" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" } } }, "title": "Delete an unused model connection", "description": "Delete an unused model connection. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "settings:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "revision": 0, "connection_id": "connection-example" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-chat-model-access", "signal_id": "get_chat_model_access", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}/model-access", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Read conversation model selection and runtime acknowledgement", "description": "Read conversation model selection and runtime acknowledgement. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "chats:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" }, "conversation": { "selection": null, "managed": false, "effective": { "provider": "openai-codex", "model": "example-model" }, "applied": null, "applies": "next_turn" } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "set-chat-model", "signal_id": "set_chat_model", "group": "Agents", "method": "POST", "path": "/agents/{agent_id}/chats/{chat_id}/model-access", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "selection" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "selection": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "connection_id", "model" ], "properties": { "connection_id": { "type": "string" }, "model": { "type": "string" } } } ] } } }, "title": "Set or reset the model for one conversation", "description": "Set or reset the model for one conversation. Reuses existing profile model-access settings.", "authentication": { "type": "bearer", "scope": "chats:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." } ], "request": { "content_type": "application/json", "example": { "revision": 0, "selection": null } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": true, "capability": "model-access-v1", "revision": 1, "can_manage": true, "runtime_ready": true, "connections": [ { "id": "codex", "label": "OpenAI Codex", "provider": "openai-codex", "models": [ "example-model" ], "verified_models": [ "example-model" ], "status": "verified" } ], "profile_default": null, "configured_default": { "provider": "openai-codex", "model": "example-model" }, "conversation": { "selection": null, "managed": false, "effective": { "provider": "openai-codex", "model": "example-model" }, "applied": null, "applies": "next_turn" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "Revision conflict or connection in use; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Revision conflict or connection in use; read back before retrying" } }, { "status": 422, "content_type": "application/json", "description": "Provider verification failed; existing settings kept", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Provider verification failed; existing settings kept" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Model access runtime unavailable", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Model access runtime unavailable" } }, { "status": 504, "content_type": "application/json", "description": "Verification outcome unknown; read back before retrying", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Verification outcome unknown; read back before retrying" } } ], "notes": [ "Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry.", "Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement.", "Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat.", "Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-bridge-apps", "signal_id": "list_bridge_apps", "group": "Account apps & Passes", "method": "GET", "path": "/account/bridge-apps", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "List account Bridge apps", "description": "List account Bridge apps. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "bridge_apps:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "protocol": "bridge-app-management-v2", "instances": [] } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-bridge-app", "signal_id": "get_bridge_app", "group": "Account apps & Passes", "method": "GET", "path": "/account/bridge-apps/{app_id}", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "Inspect app readiness", "description": "Inspect app readiness. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "bridge_apps:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "ready": true, "browserAccess": true, "managementAllowed": true } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-bridge-profiles", "signal_id": "list_bridge_profiles", "group": "Account apps & Passes", "method": "GET", "path": "/account/bridge-apps/{app_id}/profiles", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "List connected Chrome profiles", "description": "List connected Chrome profiles. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "bridge_apps:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "profiles": [ { "profile": "ext:example", "label": "Example browser", "connectionState": "connected", "tabCount": 1 } ] } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-bridge-receipts", "signal_id": "get_bridge_receipts", "group": "Account apps & Passes", "method": "GET", "path": "/account/bridge-apps/{app_id}/receipts", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "Inspect recent app management receipts", "description": "Inspect recent app management receipts. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "bridge_apps:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipts": [] } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "set-bridge-access", "signal_id": "set_bridge_access", "group": "Account apps & Passes", "method": "PATCH", "path": "/account/bridge-apps/{app_id}/access", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "enabled", "request_id", "issued_at" ], "additionalProperties": false }, "title": "Enable or disable app browser access", "description": "Enable or disable app browser access. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "bridge_apps:write", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": "application/json", "example": { "enabled": true, "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "enabled": true } }, "replayed": false } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "App management is the access switch and browser Pass management, not desktop control.", "Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2.", "No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-account-browser-passes", "signal_id": "list_account_browser_passes", "group": "Account apps & Passes", "method": "GET", "path": "/account/browser-passes", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "List account-authorized browser Passes", "description": "List account-authorized browser Passes. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "browser_passes:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "items": [] } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-app-browser-passes", "signal_id": "list_app_browser_passes", "group": "Account apps & Passes", "method": "GET", "path": "/account/bridge-apps/{app_id}/browser-passes", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "List browser Passes on one app", "description": "List browser Passes on one app. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "browser_passes:read", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "passes": [] } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "Metadata does not prove device readiness. No credentials are returned." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-app-browser-pass", "signal_id": "create_app_browser_pass", "group": "Account apps & Passes", "method": "POST", "path": "/account/bridge-apps/{app_id}/browser-passes", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": { "name": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "scope": { "type": "string", "enum": [ "read", "full" ] }, "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "name", "profiles", "scope", "request_id", "issued_at" ], "additionalProperties": false }, "title": "Create an app browser Pass", "description": "Create an app browser Pass. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "browser_passes:write", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": "application/json", "example": { "name": "Example browser access", "profiles": [ "ext:example" ], "scope": "read", "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "pass": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example browser access", "scope": "read", "profiles": [ "ext:example" ] } } }, "replayed": false } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "App management is the access switch and browser Pass management, not desktop control.", "Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2.", "No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "revoke-app-browser-pass", "signal_id": "revoke_app_browser_pass", "group": "Account apps & Passes", "method": "DELETE", "path": "/account/bridge-apps/{app_id}/browser-passes/{pass_id}", "base_url_template": "https://app.sym.so/v1", "request_schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "request_id", "issued_at" ], "additionalProperties": false }, "title": "Revoke a browser Pass on its app", "description": "Revoke a browser Pass on its app. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority.", "authentication": { "type": "account_bearer", "scope": "browser_passes:write", "transport": "Authorization: Bearer ", "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." }, { "name": "pass_id", "in": "path", "type": "string", "required": true, "description": "Required pass_id path identifier." } ], "request": { "content_type": "application/json", "example": { "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "revoked": true } }, "replayed": false } } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Base URL: https://app.sym.so/v1 (not a workspace URL).", "App management is the access switch and browser Pass management, not desktop control.", "Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2.", "No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-conversation-browser-pass", "signal_id": "list_conversation_browser_pass", "group": "Conversation browser Passes", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}/browser-passes", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "List conversation browser Pass", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions.", "authentication": { "type": "dual_bearer", "scope": "browser_passes:read", "workspace_scopes": [ "workspace:read", "browser_passes:read" ], "account_scopes": [ "browser_passes:delegate" ], "transport": "Authorization: Bearer ; X-Sym-Account-Authorization: Bearer ", "same_owner_required": true, "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." }, { "name": "X-Sym-Account-Authorization", "in": "header", "type": "string", "required": true, "description": "Bearer account key with browser_passes:delegate. Authorization separately carries the workspace key." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true, "conversationId": "chat_example", "profileId": "agent_example", "attachments": [], "runtimeReady": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient.", "Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish.", "Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive.", "To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority." ], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "attach-conversation-browser-pass", "signal_id": "attach_conversation_browser_pass", "group": "Conversation browser Passes", "method": "POST", "path": "/agents/{agent_id}/chats/{chat_id}/browser-passes", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "properties": { "device_id": { "type": "string" }, "pass_id": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "full" ] } }, "required": [ "device_id", "pass_id", "scope" ], "additionalProperties": false }, "title": "Attach conversation browser Pass", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions.", "authentication": { "type": "dual_bearer", "scope": "browser_passes:write", "workspace_scopes": [ "workspace:read", "browser_passes:write" ], "account_scopes": [ "browser_passes:delegate" ], "transport": "Authorization: Bearer ; X-Sym-Account-Authorization: Bearer ", "same_owner_required": true, "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." }, { "name": "X-Sym-Account-Authorization", "in": "header", "type": "string", "required": true, "description": "Bearer account key with browser_passes:delegate. Authorization separately carries the workspace key." } ], "request": { "content_type": "application/json", "example": { "device_id": "11111111-1111-4111-8111-111111111111", "pass_id": "11111111-1111-4111-8111-111111111111", "scope": "read" } }, "success": { "status": 201, "content_type": "application/json", "body": { "ok": true, "attachment": { "id": "attachment_example", "scope": "read" } } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient.", "Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish.", "Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive.", "To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "permission-conversation-browser-pass", "signal_id": "permission_conversation_browser_pass", "group": "Conversation browser Passes", "method": "PATCH", "path": "/agents/{agent_id}/chats/{chat_id}/browser-passes/{attachment_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "read", "full" ] } }, "required": [ "scope" ], "additionalProperties": false }, "title": "Permission conversation browser Pass", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions.", "authentication": { "type": "dual_bearer", "scope": "browser_passes:write", "workspace_scopes": [ "workspace:read", "browser_passes:write" ], "account_scopes": [ "browser_passes:delegate" ], "transport": "Authorization: Bearer ; X-Sym-Account-Authorization: Bearer ", "same_owner_required": true, "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." }, { "name": "attachment_id", "in": "path", "type": "string", "required": true, "description": "Required attachment_id path identifier." }, { "name": "X-Sym-Account-Authorization", "in": "header", "type": "string", "required": true, "description": "Bearer account key with browser_passes:delegate. Authorization separately carries the workspace key." } ], "request": { "content_type": "application/json", "example": { "scope": "full" } }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient.", "Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish.", "Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive.", "To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "detach-conversation-browser-pass", "signal_id": "detach_conversation_browser_pass", "group": "Conversation browser Passes", "method": "DELETE", "path": "/agents/{agent_id}/chats/{chat_id}/browser-passes/{attachment_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "Detach conversation browser Pass", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions.", "authentication": { "type": "dual_bearer", "scope": "browser_passes:write", "workspace_scopes": [ "workspace:read", "browser_passes:write" ], "account_scopes": [ "browser_passes:delegate" ], "transport": "Authorization: Bearer ; X-Sym-Account-Authorization: Bearer ", "same_owner_required": true, "workspace_key_compatible": false }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Required chat_id path identifier." }, { "name": "attachment_id", "in": "path", "type": "string", "required": true, "description": "Required attachment_id path identifier." }, { "name": "X-Sym-Account-Authorization", "in": "header", "type": "string", "required": true, "description": "Bearer account key with browser_passes:delegate. Authorization separately carries the workspace key." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "Required account/workspace credential missing, wrong type, expired or revoked.", "body": { "ok": false, "error": "Required API credential unavailable" } }, { "status": 403, "content_type": "application/json", "description": "Scope, matching account ownership or current target access denied.", "body": { "ok": false, "error": "Account or workspace authority denied" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "App management disabled, app busy, stale state or conflicting request. Refresh state; do not blindly retry.", "body": { "ok": false, "error": "Operation unavailable in current state" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "Control service, worker or device unavailable. A mutation may have an unknown outcome.", "body": { "ok": false, "error": "Service unavailable; inspect state before retrying" } } ], "notes": [ "Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient.", "Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish.", "Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive.", "To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-api-root", "signal_id": "get_workspaceapi_root", "group": "Identity", "method": "GET", "path": "/", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get the WorkspaceAPI root", "description": "Confirm the selected workspace API version and discover its documentation route.", "authentication": { "type": "bearer", "scope": "workspace:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "version": "v1", "workspace_id": "workspace_example", "docs": "/docs", "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: workspace:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-openapi", "signal_id": "get_workspaceapi_openapi_contract", "group": "Identity", "method": "GET", "path": "/openapi.json", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get the OpenAPI contract", "description": "Download the worker's generated OpenAPI 3.1 contract for this WorkspaceAPI version.", "authentication": { "type": "public", "scope": "Public contract", "transport": "No credential required." }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "openapi": "3.1.0", "info": { "title": "Symposium WorkspaceAPI", "version": "2.6.1" }, "paths": { "/api-keys": { "get": { "summary": "List my workspace API keys" }, "post": { "summary": "Create a workspace API key" } }, "/agents": { "get": { "summary": "List Agents" } }, "/agents/{agent_id}/settings": { "get": { "summary": "Get Agent runtime settings" }, "put": { "summary": "Update Agent runtime settings" } }, "/agents/{agent_id}/secrets": { "get": { "summary": "List Agent secret configuration" }, "post": { "summary": "Set or remove Agent secrets" } } } } }, "errors": [ { "status": 404, "content_type": "application/json", "description": "The worker does not expose this API version.", "body": { "ok": false, "error": "not found" } }, { "status": 503, "content_type": "application/json", "description": "The generated OpenAPI artifact is unavailable on the worker.", "body": { "ok": false, "error": "OpenAPI contract unavailable" } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-me", "signal_id": "get_current_identity", "group": "Identity", "method": "GET", "path": "/me", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get the current actor", "description": "Resolve the user and workspace represented by this API key. Permissions are evaluated from current workspace membership on every request.", "authentication": { "type": "bearer", "scope": "workspace:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "user": { "id": "user_example", "name": "Example User", "email": "developer@example.com" }, "workspace": { "id": "workspace_example", "name": "Example Workspace" }, "role": "owner", "key": { "id": "key_01J8", "name": "Local integration", "scopes": [ "workspace:read", "agents:read", "chats:read" ] }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: workspace:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-workspace", "signal_id": "get_workspace", "group": "Identity", "method": "GET", "path": "/workspace", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get the workspace", "description": "Return the workspace bound to the key, including capabilities currently available to its owning user.", "authentication": { "type": "bearer", "scope": "workspace:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "workspace": { "id": "workspace_example", "name": "Example Workspace", "handle": "example", "capabilities": [ "agents.create", "files.write", "messages.send" ] }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: workspace:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-machine", "signal_id": "get_safe_machine_state", "group": "Machine", "method": "GET", "path": "/machine", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get machine information", "description": "Return safe identity and capability information for the SYM-node machine serving this workspace without exposing host credentials or private network configuration.", "authentication": { "type": "bearer", "scope": "machine:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "machine": { "id": "worker-example-001", "name": "Example Workspace", "platform": "linux", "architecture": "x86_64", "uptime_seconds": 184320, "sym_node_version": "0.1.45-alpha", "status": "online", "capabilities": [ "agents", "files", "chats", "messages" ] }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: machine:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Exact host paths, IP addresses, service credentials, environment variables, and provider secrets are never returned." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-machine-storage", "signal_id": "get_storage_state", "group": "Machine", "method": "GET", "path": "/machine/storage", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get storage usage", "description": "Return total, used, and available workspace-machine storage with normalized byte counts and percentages.", "authentication": { "type": "bearer", "scope": "machine:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "storage": { "total_bytes": 536870912000, "used_bytes": 193273528320, "available_bytes": 343597383680, "used_percent": 36, "updated_at": "2026-08-04T10:30:00Z" }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: machine:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-machine-memory", "signal_id": "get_memory_state", "group": "Machine", "method": "GET", "path": "/machine/memory", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get memory usage", "description": "Return total, used, available, and cached RAM for the workspace machine.", "authentication": { "type": "bearer", "scope": "machine:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "memory": { "total_bytes": 17179869184, "used_bytes": 7516192768, "available_bytes": 9663676416, "cached_bytes": 3221225472, "used_percent": 43.75, "updated_at": "2026-08-04T10:30:00Z" }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: machine:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Available memory follows the operating system's reclaimable-memory calculation rather than simply total minus used." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-api-keys", "signal_id": "list_workspace_api_keys", "group": "API keys", "method": "GET", "path": "/api-keys", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List my API keys", "description": "List metadata for keys owned by the current WorkspaceAPI actor. Raw secrets are never returned after creation or rotation.", "authentication": { "type": "bearer", "scope": "api_keys:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "key_01J8", "name": "Local integration", "prefix": "sym_ws_x7K2", "last_four": "9Qpf", "scopes": [ "files:read", "chats:read" ], "last_used_at": "2026-08-04T10:30:00Z", "expires_at": null } ], "scopes": [ "workspace:read", "api_keys:read" ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: api_keys:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Only keys owned by the current user in this workspace are returned.", "The scopes catalog is intersected with the caller's own scopes and current workspace permissions." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-api-key", "signal_id": "create_workspace_api_key", "group": "API keys", "method": "POST", "path": "/api-keys", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create an API key", "description": "Create a user-bound key for this workspace. The raw secret is returned exactly once.", "authentication": { "type": "bearer", "scope": "api_keys:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "name", "in": "body", "type": "string", "required": true, "description": "Human-readable key name." }, { "name": "scopes", "in": "body", "type": "string[]", "required": true, "description": "Requested API scopes, capped by the user's permissions." }, { "name": "expires_at", "in": "body", "type": "ISO timestamp | null", "description": "Optional expiry." } ], "request": { "content_type": "application/json", "example": { "name": "Local integration", "scopes": [ "agents:read", "files:read", "files:write", "chats:read", "messages:read", "messages:send" ], "expires_at": null } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "key_01J8", "name": "Local integration", "scopes": [ "agents:read", "files:read", "files:write", "chats:read", "messages:read", "messages:send" ] }, "key": "sym_ws_x7K2...9Qpf", "reveal_once": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: api_keys:write" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "SYM-node stores only a one-way hash, key prefix, and last four characters.", "The new key must be owned by the same user and may only receive scopes the caller already holds.", "The raw key must not be logged and cannot be recovered later." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "rotate-api-key", "signal_id": "rotate_workspace_api_key", "group": "API keys", "method": "POST", "path": "/api-keys/{key_id}/rotate", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Rotate an API key", "description": "Revoke a user-owned key and return a replacement secret once without broadening its scopes.", "authentication": { "type": "bearer", "scope": "api_keys:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "key_id", "in": "path", "type": "string", "required": true, "description": "Key owned by the current WorkspaceAPI actor." } ], "request": { "content_type": null, "example": null }, "success": { "status": 201, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "key_01J9", "name": "Local integration", "scopes": [ "files:read", "chats:read" ] }, "key": "sym_ws_r8M4...2Lka", "reveal_once": true, "previous_key_revoked": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: api_keys:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "A caller cannot rotate a key whose scopes are broader than its own because rotation reveals the replacement secret." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "revoke-api-key", "signal_id": "revoke_workspace_api_key", "group": "API keys", "method": "DELETE", "path": "/api-keys/{key_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Revoke an API key", "description": "Immediately revoke one of the current WorkspaceAPI actor's keys.", "authentication": { "type": "bearer", "scope": "api_keys:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "key_id", "in": "path", "type": "string", "required": true, "description": "User-owned key to revoke." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "key_01J8", "revoked_at": "2026-08-15T02:00:00Z" }, "revoked": true, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: api_keys:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-agents", "signal_id": "list_agents", "group": "Agents", "method": "GET", "path": "/agents", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List available Agents", "description": "List only Agents the key owner can currently access. Staff-only and unassigned Agents are not disclosed.", "authentication": { "type": "bearer", "scope": "agents:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "status", "in": "query", "type": "online | offline | creating", "description": "Optional status filter." }, { "name": "limit", "in": "query", "type": "integer", "description": "Page size, maximum 100." }, { "name": "cursor", "in": "query", "type": "string", "description": "Opaque pagination cursor." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "agent_example", "name": "Example Agent", "status": "online", "can_message": true, "can_manage": true } ], "next_cursor": null, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-agent", "signal_id": "create_agent", "group": "Agents", "method": "POST", "path": "/agents", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create an Agent", "description": "Start creation of a real SYM-node profile, Hermes profile, Gateway, runtime, and initial chat.", "authentication": { "type": "bearer", "scope": "agents:create", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "name", "in": "body", "type": "string", "required": true, "description": "Display name for the Agent." } ], "request": { "content_type": "application/json", "example": { "name": "Research Agent" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "profile_id": "research-agent", "display_name": "Research Agent", "status": "active" }, "created": true, "chat_id": "chat_research-agent_main", "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:create" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "The owning user's current workspace role must allow Agent creation." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-agent", "signal_id": "get_agent", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get an Agent", "description": "Get one authorized Agent and its current runtime state.", "authentication": { "type": "bearer", "scope": "agents:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Stable Agent ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "agent": { "id": "agent_example", "name": "Example Agent", "status": "online", "created_at": "2026-07-01T04:00:00Z", "capabilities": [ "files", "chats", "messages" ] }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-agent", "signal_id": "update_agent", "group": "Agents", "method": "PATCH", "path": "/agents/{agent_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update an Agent", "description": "Rename or archive an Agent when the current user is allowed to manage it.", "authentication": { "type": "bearer", "scope": "agents:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Stable Agent ID." } ], "request": { "content_type": "application/json", "example": { "name": "Research", "archived": false } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "agent": { "id": "research-agent", "name": "Research", "archived": false }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "delete-agent", "signal_id": "delete_agent", "group": "Agents", "method": "DELETE", "path": "/agents/{agent_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Delete an Agent", "description": "Delete an Agent through the same guarded lifecycle used by Workspace Settings.", "authentication": { "type": "bearer", "scope": "agents:delete", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Stable Agent ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "deleted": true, "profile_id": "research-agent", "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:delete" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Staff-only Agents remain staff-only for both visibility and mutation." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-files", "signal_id": "list_agent_files", "group": "Files & folders", "method": "GET", "path": "/agents/{agent_id}/files", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List files and folders", "description": "Browse an Agent's project-files tree using paths relative to its guarded root.", "authentication": { "type": "bearer", "scope": "files:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "query", "type": "string", "description": "Relative folder path; empty means root." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "path": "reports", "items": [ { "name": "august", "path": "reports/august", "type": "folder", "modified_at": "2026-08-04T09:00:00Z" }, { "name": "summary.md", "path": "reports/summary.md", "type": "file", "size": 8421, "mime_type": "text/markdown" } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "read-file", "signal_id": "read_agent_file", "group": "Files & folders", "method": "GET", "path": "/agents/{agent_id}/files/content", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Read a file", "description": "Read a supported project file as content and metadata.", "authentication": { "type": "bearer", "scope": "files:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "query", "type": "string", "required": true, "description": "Relative file path." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "file": { "path": "notes/brief.md", "content": "# Brief\n", "encoding": "utf-8", "size": 8, "modified_at": "2026-08-04T09:00:00Z" }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "write-file", "signal_id": "write_agent_file", "group": "Files & folders", "method": "PUT", "path": "/agents/{agent_id}/files/content", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create or replace a file", "description": "Write a project file. Parent folders may be created explicitly before writing.", "authentication": { "type": "bearer", "scope": "files:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "query", "type": "string", "required": true, "description": "Relative destination path." }, { "name": "If-Match", "in": "header", "type": "string", "description": "Optional version token for conflict-safe replacement." } ], "request": { "content_type": "application/json", "example": { "content": "# Updated brief\n", "encoding": "utf-8" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "file": { "path": "notes/brief.md", "size": 16, "version": "sha256:4f4a..." }, "created": false, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "download-file", "signal_id": "download_agent_file", "group": "Files & folders", "method": "GET", "path": "/agents/{agent_id}/files/download", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Download a file", "description": "Download the raw bytes of a project file.", "authentication": { "type": "bearer", "scope": "files:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "query", "type": "string", "required": true, "description": "Relative file path." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/octet-stream", "body": "Binary file bytes. Content-Disposition contains the safe project filename." }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "ok": false, "error": "scope required: files:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-folder", "signal_id": "create_agent_directory", "group": "Files & folders", "method": "POST", "path": "/agents/{agent_id}/files/directories", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create a folder", "description": "Create a folder under the Agent's project-files root.", "authentication": { "type": "bearer", "scope": "files:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "body", "type": "string", "required": true, "description": "Relative folder path." } ], "request": { "content_type": "application/json", "example": { "path": "reports/august" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "folder": { "path": "reports/august" }, "created": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "move-file", "signal_id": "move_agent_file", "group": "Files & folders", "method": "POST", "path": "/agents/{agent_id}/files/move", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Move or rename a file or folder", "description": "Move one project entry without exposing host filesystem paths.", "authentication": { "type": "bearer", "scope": "files:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." } ], "request": { "content_type": "application/json", "example": { "from": "drafts/report.md", "to": "reports/final-report.md" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "moved": true, "from": "drafts/report.md", "to": "reports/final-report.md", "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "delete-file", "signal_id": "delete_agent_file", "group": "Files & folders", "method": "DELETE", "path": "/agents/{agent_id}/files", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Delete a file or folder", "description": "Delete an entry. Non-empty folders require explicit recursive deletion.", "authentication": { "type": "bearer", "scope": "files:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "path", "in": "query", "type": "string", "required": true, "description": "Relative path." }, { "name": "recursive", "in": "query", "type": "boolean", "description": "Required for non-empty folders." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "deleted": true, "path": "reports/old", "recursive": true, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: files:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Traversal, symlink escape, secret-looking paths, Hermes state, and system paths are blocked." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-chats", "signal_id": "list_agent_chats", "group": "Chats", "method": "GET", "path": "/agents/{agent_id}/chats", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List chats", "description": "List chats owned by one currently accessible Agent.", "authentication": { "type": "bearer", "scope": "chats:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "status", "in": "query", "type": "string", "description": "Optional chat status." }, { "name": "limit", "in": "query", "type": "integer", "description": "Page size, maximum 100." }, { "name": "cursor", "in": "query", "type": "string", "description": "Opaque pagination cursor." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "chat_01J8", "agent": { "id": "agent_example", "name": "Example Agent" }, "title": "Competitor research", "status": "completed", "unread": false, "last_message_preview": "The report is ready.", "updated_at": "2026-08-04T09:30:00Z" } ], "next_cursor": null, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-chat", "signal_id": "create_agent_chat", "group": "Chats", "method": "POST", "path": "/agents/{agent_id}/chats", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create a chat", "description": "Create a durable Agent chat, optionally with an initial user message. This creates a chat record; it does not restart the Agent Gateway or guarantee a fresh profile runtime.", "authentication": { "type": "bearer", "scope": "chats:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Agent that owns the new chat." } ], "request": { "content_type": "application/json", "example": { "title": "Research competitors", "initial_message": "Find the five closest competitors." } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "chat": { "id": "chat_01J9", "agent_id": "agent_example", "title": "Research competitors", "status": "queued" }, "message": { "id": "msg_01J9", "status": "queued" }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-chat", "signal_id": "get_agent_chat", "group": "Chats", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get a chat", "description": "Get one accessible chat and its owning Agent.", "authentication": { "type": "bearer", "scope": "chats:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Durable chat ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "chat": { "id": "chat_01J8", "agent": { "id": "agent_example", "name": "Example Agent" }, "title": "Competitor research", "status": "completed", "archived": false }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-chat", "signal_id": "update_agent_chat", "group": "Chats", "method": "PATCH", "path": "/agents/{agent_id}/chats/{chat_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update a chat", "description": "Rename, archive, unarchive, or mark an accessible chat as read.", "authentication": { "type": "bearer", "scope": "chats:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Durable chat ID." } ], "request": { "content_type": "application/json", "example": { "title": "Australian competitor research", "archived": false, "read": true } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "chat": { "id": "chat_01J8", "title": "Australian competitor research", "archived": false, "unread": false }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "delete-chat", "signal_id": "archive_agent_chat", "group": "Chats", "method": "DELETE", "path": "/agents/{agent_id}/chats/{chat_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Delete a chat", "description": "Archive a chat when the current user has the same permission in Symposium. Archiving preserves history and does not reset or terminate its runtime.", "authentication": { "type": "bearer", "scope": "chats:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Durable chat ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "deleted": true, "id": "chat_01J8", "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "This does not send /new, kill tmux, rotate a Gateway session key, restart the Agent Gateway, or force a new runtime." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-messages", "signal_id": "list_chat_messages", "group": "Messages", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}/messages", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List messages", "description": "Read normalized durable user, assistant, and system messages in chronological order.", "authentication": { "type": "bearer", "scope": "messages:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Accessible chat ID." }, { "name": "limit", "in": "query", "type": "integer", "description": "Page size, maximum 100." }, { "name": "cursor", "in": "query", "type": "string", "description": "Opaque pagination cursor." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "msg_01J8", "role": "user", "sender": { "id": "user_example", "name": "Example User" }, "content": "Prepare the report.", "status": "completed", "created_at": "2026-08-04T09:00:00Z" }, { "id": "msg_01J9", "role": "assistant", "content": "The report is ready.", "status": "completed", "created_at": "2026-08-04T09:01:00Z" } ], "next_cursor": null, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: messages:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "send-message", "signal_id": "send_agent_message", "group": "Messages", "method": "POST", "path": "/agents/{agent_id}/chats/{chat_id}/messages", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Send a message", "description": "Queue a user-authored message through the same durable SYM-node and Gateway flow used by SYM-OS. Hermes slash commands are preserved exactly; send /new to request a reset of this exact chat's current Hermes conversation.", "authentication": { "type": "bearer", "scope": "messages:send", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Accessible chat ID." }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": true, "description": "Client-generated key that prevents duplicate work." }, { "name": "response_context", "in": "body", "type": "object", "description": "Optional per-message presentation metadata: {\"channel\":\"voice\",\"verbosity\":\"concise\"}. Requests a brief conversational reply without reducing task completeness or changing profile instructions. Omit for ordinary text turns. Requires a worker supporting this contract; keep the original content unchanged." } ], "request": { "content_type": "application/json", "example": { "content": "/new", "client_message_id": "reset-chat-unique-001" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "message": { "id": "msg_01JA", "status": "queued" }, "chat": { "id": "chat_01J8", "status": "responding" }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: messages:send" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "A successful response proves durable queueing and dispatch, not that an unhealthy runtime consumed or acknowledged /new.", "WorkspaceAPI currently exposes no first-class session rebind, chat-runtime restart, profile Gateway restart, tmux kill, or force-new-runtime operation." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-message", "signal_id": "get_message", "group": "Messages", "method": "GET", "path": "/messages/{message_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get message status", "description": "Poll one durable message until it completes or fails.", "authentication": { "type": "bearer", "scope": "messages:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "message_id", "in": "path", "type": "string", "required": true, "description": "Durable message ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "message": { "id": "msg_01JA", "role": "user", "status": "completed", "responded_at": "2026-08-04T10:31:12Z" }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: messages:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "stream-chat", "signal_id": "stream_agent_events", "group": "Messages", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}/events", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Stream chat progress", "description": "Open a Server-Sent Events stream for durable message, activity, tool, and chat-state changes.", "authentication": { "type": "bearer", "scope": "messages:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Accessible chat ID." }, { "name": "Accept", "in": "header", "type": "text/event-stream", "required": true, "description": "Requests an SSE stream." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "text/event-stream", "body": "id: 1842\nevent: message.completed\ndata: {\"message_id\":\"msg_01JA\",\"chat_id\":\"chat_01J8\",\"status\":\"completed\"}\n" }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "ok": false, "error": "scope required: messages:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-operations", "signal_id": "list_operations", "group": "Operations", "method": "GET", "path": "/operations", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List operations", "description": "List durable asynchronous operations owned by the current user.", "authentication": { "type": "bearer", "scope": "operations:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "op_01J8", "operation_type": "message.send", "status": "succeeded", "resource_type": "message", "resource_id": "msg_01JA", "completed_at": "2026-08-05T08:30:02Z" } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: operations:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-operation", "signal_id": "get_operation", "group": "Operations", "method": "GET", "path": "/operations/{operation_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get an operation", "description": "Read durable status, result, or safe failure details.", "authentication": { "type": "bearer", "scope": "operations:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "operation_id", "in": "path", "type": "string", "required": true, "description": "Required operation_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "op_01J8", "operation_type": "message.send", "status": "succeeded", "result": { "message_id": "msg_01JA", "dispatched": true }, "error": null }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: operations:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "stream-operation", "signal_id": "stream_operation_events", "group": "Operations", "method": "GET", "path": "/operations/{operation_id}/events", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Resume operation events", "description": "Resume an SSE stream with Last-Event-ID.", "authentication": { "type": "bearer", "scope": "operations:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "operation_id", "in": "path", "type": "string", "required": true, "description": "Required operation_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "text/event-stream", "body": "id: 3\nevent: operation.succeeded\ndata: {\"operation_id\":\"op_01J8\",\"status\":\"succeeded\"}\n" }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "ok": false, "error": "scope required: operations:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "cancel-operation", "signal_id": "cancel_operation", "group": "Operations", "method": "POST", "path": "/operations/{operation_id}/cancel", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Cancel an operation", "description": "Request cancellation without deleting durable history.", "authentication": { "type": "bearer", "scope": "operations:cancel", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "operation_id", "in": "path", "type": "string", "required": true, "description": "Required operation_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "op_01J8", "status": "cancelled", "cancel_requested_at": "2026-08-05T08:31:00Z", "completed_at": "2026-08-05T08:31:00Z" }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: operations:cancel" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-webhooks", "signal_id": "list_webhooks", "group": "Webhooks", "method": "GET", "path": "/webhooks", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List webhooks", "description": "List user-owned signed webhook subscriptions.", "authentication": { "type": "bearer", "scope": "webhooks:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "wh_01J8", "name": "Production events", "url": "https://example.com/symposium", "events": [ "message.completed" ], "status": "active" } ], "supported_events": [ "message.completed" ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "create-webhook", "signal_id": "create_webhook", "group": "Webhooks", "method": "POST", "path": "/webhooks", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Create a webhook", "description": "Create an HTTPS-only subscription. The signing secret is revealed once.", "authentication": { "type": "bearer", "scope": "webhooks:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": "application/json", "example": { "name": "Production events", "url": "https://example.com/symposium", "events": [ "message.completed" ] } }, "success": { "status": 201, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "wh_01J8", "name": "Production events", "url": "https://example.com/symposium", "events": [ "message.completed" ], "status": "active" }, "signing_secret": "whsec_…", "reveal_once": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:write" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-webhook", "signal_id": "update_webhook", "group": "Webhooks", "method": "PATCH", "path": "/webhooks/{webhook_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update a webhook", "description": "Change a user-owned webhook name, HTTPS destination, subscribed events, or active/paused status.", "authentication": { "type": "bearer", "scope": "webhooks:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "webhook_id", "in": "path", "type": "string", "required": true, "description": "User-owned webhook ID." } ], "request": { "content_type": "application/json", "example": { "name": "Production events", "events": [ "message.completed" ], "status": "paused" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "wh_01J8", "name": "Production events", "url": "https://example.com/symposium", "events": [ "message.completed" ], "status": "paused", "updated_at": "2026-08-05T08:32:00Z", "revoked_at": null }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "revoke-webhook", "signal_id": "revoke_webhook", "group": "Webhooks", "method": "DELETE", "path": "/webhooks/{webhook_id}", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Revoke a webhook", "description": "Permanently revoke a user-owned webhook while preserving its durable delivery history.", "authentication": { "type": "bearer", "scope": "webhooks:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "webhook_id", "in": "path", "type": "string", "required": true, "description": "User-owned webhook ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "id": "wh_01J8", "name": "Production events", "url": "https://example.com/symposium", "events": [ "message.completed" ], "status": "revoked", "revoked_at": "2026-08-05T08:33:00Z" }, "revoked": true, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "test-webhook", "signal_id": "test_webhook", "group": "Webhooks", "method": "POST", "path": "/webhooks/{webhook_id}/test", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Queue a webhook test", "description": "Queue a signed webhook.test delivery using a synthetic payload and the normal durable delivery system.", "authentication": { "type": "bearer", "scope": "webhooks:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "webhook_id", "in": "path", "type": "string", "required": true, "description": "Active user-owned webhook ID." } ], "request": { "content_type": "application/json", "example": { "proof": true } }, "success": { "status": 202, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "event_id": "evt_01J8", "queued": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "webhook-deliveries", "signal_id": "list_webhook_deliveries", "group": "Webhooks", "method": "GET", "path": "/webhooks/{webhook_id}/deliveries", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List webhook deliveries", "description": "Inspect retry and response status without exposing payload secrets.", "authentication": { "type": "bearer", "scope": "webhooks:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "webhook_id", "in": "path", "type": "string", "required": true, "description": "Required webhook_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "delivery_01J8", "event_type": "message.completed", "attempt": 1, "status": "delivered", "response_status": 204, "delivered_at": "2026-08-05T08:32:00Z" } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: webhooks:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-agent-apps", "signal_id": "list_agent_apps", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/apps", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List Agent apps", "description": "List apps installed for one accessible Agent, enriched with safe managed-process state.", "authentication": { "type": "bearer", "scope": "apps:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "id": "research-console", "name": "Research Console", "profile_id": "agent_example", "status": "installed", "running": true, "port": 4312 } ], "apps": [ { "id": "research-console", "name": "Research Console", "profile_id": "agent_example", "status": "installed", "running": true, "port": 4312 } ], "count": 1, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: apps:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-agent-secrets", "signal_id": "list_agent_secret_configuration", "group": "Secrets", "method": "GET", "path": "/agents/{agent_id}/secrets", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List Agent secret configuration", "description": "List configured environment-secret names and process-environment instructions for one accessible Agent. Secret values and broker-only storage paths are never returned. Workspace owner/admin permission is required.", "authentication": { "type": "bearer", "scope": "secrets:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "data": { "profile_id": "agent_example", "delivery": "process_environment", "secrets": [ { "name": "EXAMPLE_SERVICE_TOKEN", "configured": true, "reference": "EXAMPLE_SERVICE_TOKEN is available as an environment variable in Agent agent_example's runtime. Use the process environment; do not search for a file or print its value." } ], "configured_count": 1 }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: secrets:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Values are write-only and never appear in reads, logs, audit events, webhooks, or this documentation.", "Both the secrets:read scope and current workspace owner/admin role are required." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-agent-secrets", "signal_id": "set_or_remove_agent_secrets", "group": "Secrets", "method": "POST", "path": "/agents/{agent_id}/secrets", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Set or remove Agent secrets", "description": "Set write-only Agent environment secrets or remove configured names, then restart that Agent's gateway so the new environment takes effect. Workspace owner/admin permission is required.", "authentication": { "type": "bearer", "scope": "secrets:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "values": { "EXAMPLE_SERVICE_TOKEN": "" }, "unset": [ "OBSOLETE_SERVICE_TOKEN" ] } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "data": { "profile_id": "agent_example", "delivery": "process_environment", "secrets": [ { "name": "EXAMPLE_SERVICE_TOKEN", "configured": true, "reference": "EXAMPLE_SERVICE_TOKEN is available as an environment variable in Agent agent_example's runtime. Use the process environment; do not search for a file or print its value." } ], "configured_count": 1, "activation": { "state": "active", "delivery": "process_environment" }, "gateway_restart": { "ok": true, "service": "hermes-gateway-agent_example" } }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: secrets:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } }, { "status": 503, "content_type": "application/json", "description": "The secret was saved but Gateway activation failed; retry is required.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "Secret saved, but Agent environment activation failed; retry required", "data": { "activation": { "state": "pending", "delivery": "process_environment" } } } } ], "notes": [ "Only uppercase environment-style names accepted by SYM-node may be written.", "HTTP 200 means the Agent environment is active; failed activation returns HTTP 503/pending instead of false success.", "The response confirms configuration state but never echoes supplied values." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-app-secrets", "signal_id": "list_app_secret_configuration", "group": "Secrets", "method": "GET", "path": "/agents/{agent_id}/apps/{app_id}/secrets", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List app secret configuration", "description": "List manifest-declared secret names and configured state for one installed Agent app. Secret values are never returned. Workspace owner/admin permission is required.", "authentication": { "type": "bearer", "scope": "secrets:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "data": { "profile_id": "agent_example", "app_id": "research-console", "declared_count": 1, "configured_count": 1, "missing_required": [], "secrets": [ { "name": "EXAMPLE_SERVICE_TOKEN", "description": "Example provider access token", "required": true, "configured": true } ] }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: secrets:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Only secrets declared by the installed app manifest are represented.", "Values are write-only." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-app-secrets", "signal_id": "set_or_remove_app_secrets", "group": "Secrets", "method": "POST", "path": "/agents/{agent_id}/apps/{app_id}/secrets", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Set or remove app secrets", "description": "Set or remove manifest-declared write-only secrets for one installed Agent app, then restart the Agent gateway environment. Workspace owner/admin permission is required.", "authentication": { "type": "bearer", "scope": "secrets:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." }, { "name": "app_id", "in": "path", "type": "string", "required": true, "description": "Required app_id path identifier." } ], "request": { "content_type": "application/json", "example": { "values": { "EXAMPLE_SERVICE_TOKEN": "" }, "unset": [] } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "data": { "profile_id": "agent_example", "app_id": "research-console", "declared_count": 1, "configured_count": 1, "missing_required": [], "secrets": [ { "name": "EXAMPLE_SERVICE_TOKEN", "description": "Example provider access token", "required": true, "configured": true } ], "gateway_restart": { "ok": true, "service": "hermes-gateway-agent_example" } }, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: secrets:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Undeclared secret names are rejected.", "The response never echoes supplied values." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-agent-soul", "signal_id": "get_agent_soul", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/soul", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get Agent soul", "description": "Read the authorized Agent identity layer together with safe effective-instruction metadata.", "authentication": { "type": "bearer", "scope": "instructions:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "scope_type": "profile", "scope_id": "agent_example", "markdown": "Be concise, analytical, and evidence-driven.", "revision": 4, "content_hash": "f5a4c1e2d3b60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0", "can_manage": true, "applies_to": "new_conversations" }, "constitution": { "version": "1", "content_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0", "managed": true }, "workspace": { "revision": 7, "content_hash": "b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef01" }, "effective_order": [ { "layer": "platform_foundation", "managed": true }, { "layer": "workspace_instructions", "managed": false, "revision": 7 }, { "layer": "profile_identity", "managed": false, "revision": 4 } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: instructions:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-agent-soul", "signal_id": "update_agent_soul", "group": "Agents", "method": "PUT", "path": "/agents/{agent_id}/soul", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update Agent soul", "description": "Replace the authorized Agent identity markdown with optimistic revision checking. Workspace admin permission is required.", "authentication": { "type": "bearer", "scope": "instructions:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Required agent_id path identifier." } ], "request": { "content_type": "application/json", "example": { "markdown": "Be concise, analytical, and evidence-driven.", "expected_revision": 4, "reason": "Clarify research behavior" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "scope_type": "profile", "scope_id": "agent_example", "markdown": "Be concise, analytical, and evidence-driven.", "revision": 5, "content_hash": "c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef012", "can_manage": true, "applies_to": "new_conversations" }, "profile_id": "agent_example", "applies_to": "new_conversations", "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: instructions:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 409, "content_type": "application/json", "description": "The supplied expected_revision is stale.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "instruction revision conflict" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-agent-settings", "signal_id": "get_agent_settings", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/settings", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get Agent autonomy settings", "description": "Read the persistent Hermes command-approval mode for one authorized Agent. This is the same per-profile setting shown under right-click Agent → Edit profile identity → Autonomy.", "authentication": { "type": "bearer", "scope": "settings:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "profile_id": "agent_example", "hermes_profile": "agent_example", "approval_mode": "manual", "can_manage": true, "config_present": true }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "manual asks before risky commands, smart uses independent safety review, and off is Full access in SYM-OS.", "The response never exposes the profile configuration file or unrelated Hermes settings.", "This endpoint does not expose chat reset, session rebind, Gateway restart, tmux, or runtime lifecycle controls." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-agent-settings", "signal_id": "update_agent_settings", "group": "Agents", "method": "PUT", "path": "/agents/{agent_id}/settings", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update Agent autonomy settings", "description": "Set the persistent Hermes command-approval mode for one authorized Agent. Workspace owner/admin permission is required.", "authentication": { "type": "bearer", "scope": "settings:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "approval_mode", "in": "body", "type": "manual | smart | off", "required": true, "description": "Persistent command-approval policy. off enables Full access." } ], "request": { "content_type": "application/json", "example": { "approval_mode": "off" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "profile_id": "agent_example", "hermes_profile": "agent_example", "approval_mode": "off", "can_manage": true, "config_present": true, "changed": true }, "applies_immediately": true, "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:write" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Only the approvals.mode field is changed; unrelated Hermes configuration is preserved atomically.", "This operation does not reset or restart any chat, session, Gateway, tmux process, or Agent runtime.", "Full access bypasses ordinary risky-command prompts but does not bypass operating-system permissions, explicit deny rules, workspace/profile authorization, or unrecoverable system-safety blocks." ], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "search-workspace", "signal_id": "search_workspace", "group": "Workspace", "method": "GET", "path": "/search", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Search accessible resources", "description": "Search accessible chats and messages without crossing Agent authorization boundaries.", "authentication": { "type": "bearer", "scope": "search:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "q", "in": "query", "type": "string", "required": true, "description": "Search text containing at least two characters." }, { "name": "limit", "in": "query", "type": "1..100", "description": "Maximum combined results; defaults to 50." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "items": [ { "type": "chat", "id": "chat_launch_report", "agent_id": "agent_example", "title": "Review launch report", "updated_at": 1785890040000 } ], "count": 1, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: search:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-recent-activity", "signal_id": "get_recent_workspace_activity", "group": "Workspace", "method": "GET", "path": "/activity/recent", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get recent workspace activity", "description": "Return a bounded snapshot of the most recent chats for every Agent the current key owner can access, optionally including the latest normalized messages.", "authentication": { "type": "bearer", "scope": "chats:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "per_agent", "in": "query", "type": "1..5", "description": "Maximum recent chats per authorized Agent; defaults to 3." }, { "name": "message_limit", "in": "query", "type": "0..3", "description": "Maximum latest messages per returned chat; defaults to 2." }, { "name": "include_messages", "in": "query", "type": "boolean", "description": "Include bounded message content; defaults true and additionally requires messages:read." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "workspace": { "id": "workspace_example" }, "generated_at": "2026-08-06T14:20:00Z", "agents": [ { "agent": { "id": "agent_example", "name": "Example Agent", "status": "active" }, "recent_chats": [ { "id": "chat_01J8", "title": "Competitor research", "status": "active", "unread_count": 1, "current_message_status": "completed", "active_tool_name": "", "last_activity_at": "2026-08-06T14:18:00Z", "last_message_preview": "The report is ready.", "messages": [ { "id": "msg_01J9", "role": "assistant", "content": "The report is ready.", "status": "completed", "created_at": "2026-08-06T14:18:00Z" } ] } ] } ], "totals": { "authorized_agents": 1, "returned_chats": 1, "unread_chats": 1, "responding_chats": 0 }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: chats:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Only currently authorized Agents are represented.", "Message content is bounded to prevent unbounded workspace dumps." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-workspace-overview", "signal_id": "get_compact_workspace_overview", "group": "Workspace", "method": "GET", "path": "/overview", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get compact workspace overview", "description": "Return small authorization-filtered counts for Agents, chats, and operations without listing resource payloads.", "authentication": { "type": "bearer", "scope": "workspace:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "workspace": { "id": "workspace_example" }, "generated_at": "2026-08-06T14:20:00Z", "agents": { "authorized": 4, "online": 3, "responding": 1 }, "chats": { "active": 12, "unread": 2 }, "operations": { "running": 1, "failed": 0 }, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: workspace:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-agent-brief", "signal_id": "get_agent_brief", "group": "Agents", "method": "GET", "path": "/agents/{agent_id}/brief", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get Agent brief", "description": "Return one authorized Agent's safe state, recent chats and unread-chat count in one bounded response.", "authentication": { "type": "bearer", "scope": "agents:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "agent": { "id": "agent_example", "name": "Example Agent", "status": "active" }, "recent_chats": [ { "id": "chat_01J8", "title": "Competitor research", "status": "active", "unread_count": 0, "last_message_preview": "The report is ready." } ], "unread_chats": 0, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: agents:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [ "Requires both agents:read and chats:read.", "Inaccessible Agents return the same 404 as missing Agents." ], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-chat-tail", "signal_id": "get_latest_chat_messages", "group": "Messages", "method": "GET", "path": "/agents/{agent_id}/chats/{chat_id}/tail", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get latest chat messages", "description": "Return the bounded latest message tail for one authorized Agent chat in chronological order.", "authentication": { "type": "bearer", "scope": "messages:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "agent_id", "in": "path", "type": "string", "required": true, "description": "Authorized Agent ID." }, { "name": "chat_id", "in": "path", "type": "string", "required": true, "description": "Accessible chat ID." }, { "name": "limit", "in": "query", "type": "1..20", "description": "Latest message count; defaults to 5." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "agent_id": "agent_example", "chat": { "id": "chat_01J8", "title": "Competitor research", "status": "active", "last_message_preview": "The report is ready." }, "items": [ { "id": "msg_01J8", "role": "user", "content": "Prepare the report.", "status": "completed", "created_at": "2026-08-06T14:17:00Z" }, { "id": "msg_01J9", "role": "assistant", "content": "The report is ready.", "status": "completed", "created_at": "2026-08-06T14:18:00Z" } ], "count": 2, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: messages:read" } }, { "status": 404, "content_type": "application/json", "description": "The resource is missing or intentionally hidden by authorization.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "not found" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-settings", "signal_id": "get_workspace_settings", "group": "Workspace", "method": "GET", "path": "/settings", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get workspace settings", "description": "Read the safe workspace settings document stored by the worker.", "authentication": { "type": "bearer", "scope": "settings:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "settings": { "timezone": "Australia/Sydney", "locale": "en-AU" }, "source": "worker_metadata", "workspace_id": "workspace_example", "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: settings:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-workspace-instructions", "signal_id": "get_workspace_instructions", "group": "Workspace", "method": "GET", "path": "/workspace/instructions", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get workspace instructions", "description": "Read workspace instruction markdown and safe effective-layer metadata.", "authentication": { "type": "bearer", "scope": "instructions:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "scope_type": "workspace", "scope_id": "workspace_example", "markdown": "Use workspace evidence and cite durable resources.", "revision": 7, "content_hash": "b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef01", "can_manage": true, "applies_to": "new_conversations" }, "constitution": { "version": "1", "content_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0", "managed": true }, "effective_order": [ { "layer": "platform_foundation", "managed": true }, { "layer": "workspace_instructions", "managed": false, "revision": 7 }, { "layer": "profile_identity", "managed": false } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: instructions:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "update-workspace-instructions", "signal_id": "update_workspace_instructions", "group": "Workspace", "method": "PUT", "path": "/workspace/instructions", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Update workspace instructions", "description": "Replace workspace instruction markdown with optimistic revision checking and rematerialize authorized Agent instructions. Workspace admin permission is required.", "authentication": { "type": "bearer", "scope": "instructions:write", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": "application/json", "example": { "markdown": "Use workspace evidence and cite durable resources.", "expected_revision": 7, "reason": "Clarify evidence policy" } }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "item": { "scope_type": "workspace", "scope_id": "workspace_example", "markdown": "Use workspace evidence and cite durable resources.", "revision": 8, "content_hash": "d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0123", "can_manage": true, "applies_to": "new_conversations" }, "rendered_profiles": [ "agent_example" ], "applies_to": "new_conversations", "ok": true } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The request body or parameters are invalid.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid request" } }, { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: instructions:write" } }, { "status": 409, "content_type": "application/json", "description": "The supplied expected_revision is stale.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "instruction revision conflict" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "get-cosmise-connection", "signal_id": "get_safe_cosmise_connection_status", "group": "Workspace", "method": "GET", "path": "/connections/cosmise", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Get safe Cosmise connection status", "description": "Read safe profile-binding and synchronization-job status without exposing connection grants or provider credentials. Workspace admin permission is required.", "authentication": { "type": "bearer", "scope": "connections:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [ { "name": "limit", "in": "query", "type": "integer", "description": "Maximum recent synchronization jobs; defaults to 25." } ], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "bindings": [ { "provider": "cosmise", "external_org_id": "org_synthetic_01", "profile_id": "agent_example", "status": "connected", "updated_at": "2026-08-05T08:35:00Z" } ], "jobs": [ { "id": "sync_01J8", "provider": "cosmise", "status": "succeeded", "created_at": "2026-08-05T08:30:00Z", "updated_at": "2026-08-05T08:35:00Z" } ], "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: connections:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "list-schedules", "signal_id": "list_schedules", "group": "Workspace", "method": "GET", "path": "/schedules", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "List schedules", "description": "Read safe scheduled-job state.", "authentication": { "type": "bearer", "scope": "schedules:read", "transport": "Authorization: Bearer " }, "orca_execution": { "direct": true, "credential": "selected_workspace_bearer", "boundary": "Requires existing scopes, membership, Agent access and user authorization; catalog presence grants no permission." }, "parameters": [], "request": { "content_type": null, "example": null }, "success": { "status": 200, "content_type": "application/json", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "jobs": [ { "id": "schedule_daily_summary", "name": "Daily summary", "schedule": "0 9 * * *", "timezone": "Australia/Sydney", "enabled": true, "next_run_at": "2026-08-06T09:00:00+10:00" } ], "read_only": true, "ok": true } }, "errors": [ { "status": 401, "content_type": "application/json", "description": "The workspace API key is missing, invalid, expired, or revoked.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "invalid API key" } }, { "status": 403, "content_type": "application/json", "description": "The key lacks the required scope or its owner no longer has permission.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "scope required: schedules:read" } }, { "status": 429, "content_type": "application/json", "description": "The key exceeded its current rate limit.", "body": { "worker_id": "worker-example-001", "org_id": "workspace_example", "ok": false, "error": "rate limit exceeded", "retry_after_seconds": 30 } } ], "notes": [], "read_only": true, "browser_tester_available": true, "sources": [ "enriched_contract", "generated_openapi" ] }, { "id": "oauth-token", "signal_id": "exchange_oauth_token", "group": "OAuth", "method": "POST", "path": "/oauth/token", "base_url_template": "https://app.sym.so/v1/workspaces/{workspace_id}", "request_schema": null, "title": "Exchange OAuth token", "description": "Exchange a PKCE authorization code or rotate a refresh token.", "authentication": { "type": "public_oauth_exchange", "scope": "Public OAuth exchange", "transport": "OAuth request body." }, "orca_execution": { "direct": false, "credential": "selected_workspace_bearer", "boundary": "Not directly executable by Orca; requires a different authorized credential/surface." }, "parameters": [], "request": { "content_type": "application/json", "example": { "grant_type": "authorization_code", "client_id": "oauth_client_01J8", "code": "one_time_authorization_code", "code_verifier": "pkce_verifier", "redirect_uri": "https://example.com/callback" } }, "success": { "status": 200, "content_type": "application/json", "body": { "token_type": "Bearer", "access_token": "sym_oa_…", "expires_in": 3600, "refresh_token": "sym_or_…", "scope": "workspace:read" } }, "errors": [ { "status": 400, "content_type": "application/json", "description": "The grant type or required request fields are invalid.", "body": { "error": "invalid_request", "error_description": "unsupported grant type" } }, { "status": 401, "content_type": "application/json", "description": "The authorization code, PKCE verifier, or refresh token is invalid, expired, or revoked.", "body": { "error": "invalid_grant", "error_description": "invalid or expired authorization code" } } ], "notes": [], "read_only": false, "browser_tester_available": false, "sources": [ "enriched_contract", "generated_openapi" ] } ], "openapi": { "openapi": "3.1.0", "info": { "title": "Symposium WorkspaceAPI", "version": "2.7.0", "description": "Workspace-local API. SYM-node performs final authentication, authorization, execution, and data access. Runtime controls are intentionally explicit: a chat-targeted Hermes reset is currently requested by sending /new through send_agent_message; no first-class session rebind, chat-runtime restart, profile Gateway restart, tmux kill, or force-new-runtime operation is exposed. Account app and browser Pass operations are part of WorkspaceAPI but require account credentials. Account routes override the server to https://app.sym.so/v1; conversation delegation requires BOTH credentials." }, "servers": [ { "url": "https://{workspace_worker}/api/v1", "variables": { "workspace_worker": { "default": "worker.example.ts.net" } } } ], "paths": { "/": { "get": { "summary": "Get WorkspaceAPI root", "operationId": "get_workspaceapi_root", "x-symposium-realtime-signal-id": "get_workspaceapi_root", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "workspace:read" } }, "/openapi.json": { "get": { "summary": "Get WorkspaceAPI OpenAPI contract", "operationId": "get_workspaceapi_openapi_contract", "x-symposium-realtime-signal-id": "get_workspaceapi_openapi_contract", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } } } }, "/oauth/token": { "post": { "summary": "Exchange OAuth token", "operationId": "exchange_oauth_token", "x-symposium-realtime-signal-id": "exchange_oauth_token", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/me": { "get": { "summary": "Get current identity", "operationId": "get_current_identity", "x-symposium-realtime-signal-id": "get_current_identity", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "workspace:read" } }, "/workspace": { "get": { "summary": "Get workspace", "operationId": "get_workspace", "x-symposium-realtime-signal-id": "get_workspace", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "workspace:read" } }, "/machine": { "get": { "summary": "Get safe machine state", "operationId": "get_safe_machine_state", "x-symposium-realtime-signal-id": "get_safe_machine_state", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "machine:read" } }, "/machine/storage": { "get": { "summary": "Get storage state", "operationId": "get_storage_state", "x-symposium-realtime-signal-id": "get_storage_state", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "machine:read" } }, "/machine/memory": { "get": { "summary": "Get memory state", "operationId": "get_memory_state", "x-symposium-realtime-signal-id": "get_memory_state", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "machine:read" } }, "/api-keys": { "get": { "summary": "List my workspace API keys", "operationId": "list_workspace_api_keys", "x-symposium-realtime-signal-id": "list_workspace_api_keys", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "items", "scopes" ], "properties": { "ok": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceApiKey" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "api_keys:read" }, "post": { "summary": "Create a workspace API key", "operationId": "create_workspace_api_key", "x-symposium-realtime-signal-id": "create_workspace_api_key", "responses": { "200": { "description": "Success" }, "201": { "description": "Created; raw key revealed once", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item", "key", "reveal_once" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/WorkspaceApiKey" }, "request_id": { "type": "string" }, "key": { "type": "string", "description": "Raw secret returned once. Never logged or returned by list operations." }, "reveal_once": { "type": "boolean" }, "previous_key_revoked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "api_keys:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceApiKeyCreate" } } } } } }, "/api-keys/{key_id}/rotate": { "post": { "summary": "Rotate a workspace API key", "operationId": "rotate_workspace_api_key", "x-symposium-realtime-signal-id": "rotate_workspace_api_key", "responses": { "200": { "description": "Success" }, "201": { "description": "Rotated; replacement key revealed once", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item", "key", "reveal_once" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/WorkspaceApiKey" }, "request_id": { "type": "string" }, "key": { "type": "string", "description": "Raw secret returned once. Never logged or returned by list operations." }, "reveal_once": { "type": "boolean" }, "previous_key_revoked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "api_keys:write", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User-owned workspace API key ID." } ] } }, "/api-keys/{key_id}": { "delete": { "summary": "Revoke a workspace API key", "operationId": "revoke_workspace_api_key", "x-symposium-realtime-signal-id": "revoke_workspace_api_key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/WorkspaceApiKey" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "api_keys:write", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User-owned workspace API key ID." } ] } }, "/agents": { "get": { "summary": "List Agents", "operationId": "list_agents", "x-symposium-realtime-signal-id": "list_agents", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:read" }, "post": { "summary": "Create Agent", "operationId": "create_agent", "x-symposium-realtime-signal-id": "create_agent", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/agents/{agent_id}": { "get": { "summary": "Get Agent", "operationId": "get_agent", "x-symposium-realtime-signal-id": "get_agent", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "summary": "Update Agent", "operationId": "update_agent", "x-symposium-realtime-signal-id": "update_agent", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Delete Agent", "operationId": "delete_agent", "x-symposium-realtime-signal-id": "delete_agent", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/settings": { "get": { "summary": "Get Agent runtime settings", "operationId": "get_agent_settings", "x-symposium-realtime-signal-id": "get_agent_settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/AgentRuntimeSettings" }, "applies_immediately": { "type": "boolean" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Reads the persistent Hermes command-approval mode only. This endpoint does not reset chats, rotate session bindings, restart an Agent Gateway, or control tmux/runtime processes." }, "put": { "summary": "Update Agent runtime settings", "operationId": "update_agent_settings", "x-symposium-realtime-signal-id": "update_agent_settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/AgentRuntimeSettings" }, "applies_immediately": { "type": "boolean" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRuntimeSettingsUpdate" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Updates approval_mode only. It does not reset or restart any chat, session, Gateway, tmux process, or Agent runtime." } }, "/agents/{agent_id}/files": { "get": { "summary": "List Agent files", "operationId": "list_agent_files", "x-symposium-realtime-signal-id": "list_agent_files", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Delete Agent file", "operationId": "delete_agent_file", "x-symposium-realtime-signal-id": "delete_agent_file", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/files/content": { "get": { "summary": "Read Agent file", "operationId": "read_agent_file", "x-symposium-realtime-signal-id": "read_agent_file", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "summary": "Write Agent file", "operationId": "write_agent_file", "x-symposium-realtime-signal-id": "write_agent_file", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/files/download": { "get": { "summary": "Download Agent file", "operationId": "download_agent_file", "x-symposium-realtime-signal-id": "download_agent_file", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/files/directories": { "post": { "summary": "Create Agent directory", "operationId": "create_agent_directory", "x-symposium-realtime-signal-id": "create_agent_directory", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/files/move": { "post": { "summary": "Move Agent file", "operationId": "move_agent_file", "x-symposium-realtime-signal-id": "move_agent_file", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "files:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/chats": { "get": { "summary": "List Agent chats", "operationId": "list_agent_chats", "x-symposium-realtime-signal-id": "list_agent_chats", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Create Agent chat", "operationId": "create_agent_chat", "x-symposium-realtime-signal-id": "create_agent_chat", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentChatCreate" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Creates a durable chat record and optional initial message. A new chat is not a profile-runtime restart and does not guarantee recovery from a stuck Agent Gateway or stale profile-level session restoration." } }, "/agents/{agent_id}/chats/{chat_id}": { "get": { "summary": "Get Agent chat", "operationId": "get_agent_chat", "x-symposium-realtime-signal-id": "get_agent_chat", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "summary": "Update Agent chat", "operationId": "update_agent_chat", "x-symposium-realtime-signal-id": "update_agent_chat", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Archive Agent chat", "operationId": "archive_agent_chat", "x-symposium-realtime-signal-id": "archive_agent_chat", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:write", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Archives the durable chat record and preserves history. It does not send /new, terminate a session, kill tmux, rotate a Gateway session key, or restart the Agent runtime." } }, "/agents/{agent_id}/chats/{chat_id}/messages": { "get": { "summary": "List chat messages", "operationId": "list_chat_messages", "x-symposium-realtime-signal-id": "list_chat_messages", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "messages:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Send Agent message", "operationId": "send_agent_message", "x-symposium-realtime-signal-id": "send_agent_message", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "messages:send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMessageCreate" }, "examples": { "conversation_reset": { "summary": "Request a reset of this chat's current Hermes conversation", "value": { "content": "/new", "client_message_id": "reset-chat-unique-001" } }, "voice_turn": { "summary": "Concise spoken reply for this turn only", "value": { "content": "What should we do next?", "client_message_id": "voice-turn-unique-001", "response_context": { "channel": "voice", "verbosity": "concise" } } } } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Queues a message to this exact Agent chat and its current session binding. Hermes slash commands are preserved exactly; send content /new to request a conversation-scoped Hermes reset. Success proves durable queueing/dispatch, not that a stuck runtime consumed or acknowledged the reset. Optional strict response_context={channel:voice,verbosity:concise} requests a concise spoken reply for this turn only; omit for normal text. Stored separately from content and returned in message.response_context. Does not edit persistent instructions or grant tools.", "x-browser-delegation": { "gateway": "https://app.sym.so/v1/workspaces/{workspace_id}", "header": "X-Sym-Account-Authorization", "scope": "browser_passes:delegate", "requires": [ "matching credential owner", "workspace:read", "messages:send", "content", "client_message_id" ], "raw_account_key_forwarded": false, "worker_ticket_ttl_seconds": 60, "note": "Ordinary authenticated workspace messages reuse the sending user’s existing conversation Browser Pass grants, like UI messages; no account header is required. This optional header retains explicit account-ticket admission. Creating or changing Pass grants still requires separate account authority. Never send account credentials directly to a worker." } } }, "/agents/{agent_id}/chats/{chat_id}/events": { "get": { "summary": "Stream Agent events", "operationId": "stream_agent_events", "x-symposium-realtime-signal-id": "stream_agent_events", "responses": { "200": { "description": "Success", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "messages:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/messages/{message_id}": { "get": { "summary": "Get message", "operationId": "get_message", "x-symposium-realtime-signal-id": "get_message", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "messages:read", "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/operations": { "get": { "summary": "List operations", "operationId": "list_operations", "x-symposium-realtime-signal-id": "list_operations", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "operations:read" } }, "/operations/{operation_id}": { "get": { "summary": "Get operation", "operationId": "get_operation", "x-symposium-realtime-signal-id": "get_operation", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "operations:read", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/operations/{operation_id}/events": { "get": { "summary": "Stream operation events", "operationId": "stream_operation_events", "x-symposium-realtime-signal-id": "stream_operation_events", "responses": { "200": { "description": "Success", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "operations:read", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/operations/{operation_id}/cancel": { "post": { "summary": "Cancel operation", "operationId": "cancel_operation", "x-symposium-realtime-signal-id": "cancel_operation", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "operations:cancel", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/webhooks": { "get": { "summary": "List webhooks", "operationId": "list_webhooks", "x-symposium-realtime-signal-id": "list_webhooks", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:read" }, "post": { "summary": "Create webhook", "operationId": "create_webhook", "x-symposium-realtime-signal-id": "create_webhook", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/webhooks/{webhook_id}": { "patch": { "summary": "Update webhook", "operationId": "update_webhook", "x-symposium-realtime-signal-id": "update_webhook", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Revoke webhook", "operationId": "revoke_webhook", "x-symposium-realtime-signal-id": "revoke_webhook", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:write", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/webhooks/{webhook_id}/test": { "post": { "summary": "Test webhook", "operationId": "test_webhook", "x-symposium-realtime-signal-id": "test_webhook", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/webhooks/{webhook_id}/deliveries": { "get": { "summary": "List webhook deliveries", "operationId": "list_webhook_deliveries", "x-symposium-realtime-signal-id": "list_webhook_deliveries", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "webhooks:read", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/schedules": { "get": { "summary": "List schedules", "operationId": "list_schedules", "x-symposium-realtime-signal-id": "list_schedules", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "schedules:read" } }, "/workspace/instructions": { "get": { "summary": "Get workspace instructions", "operationId": "get_workspace_instructions", "x-symposium-realtime-signal-id": "get_workspace_instructions", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "instructions:read" }, "put": { "summary": "Update workspace instructions", "operationId": "update_workspace_instructions", "x-symposium-realtime-signal-id": "update_workspace_instructions", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "instructions:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/agents/{agent_id}/soul": { "get": { "summary": "Get Agent soul", "operationId": "get_agent_soul", "x-symposium-realtime-signal-id": "get_agent_soul", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "instructions:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "put": { "summary": "Update Agent soul", "operationId": "update_agent_soul", "x-symposium-realtime-signal-id": "update_agent_soul", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "instructions:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/apps": { "get": { "summary": "List Agent apps", "operationId": "list_agent_apps", "x-symposium-realtime-signal-id": "list_agent_apps", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "apps:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/secrets": { "get": { "summary": "List Agent secret configuration", "operationId": "list_agent_secret_configuration", "x-symposium-realtime-signal-id": "list_agent_secret_configuration", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "secrets:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Set or remove Agent secrets", "operationId": "set_or_remove_agent_secrets", "x-symposium-realtime-signal-id": "set_or_remove_agent_secrets", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "secrets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Set or remove write-only profile secrets. Exact-name values automatically satisfy same-profile app declarations; matching running apps refresh, while undeclared and sibling-profile secrets remain excluded. Values are never returned." } }, "/agents/{agent_id}/apps/{app_id}/secrets": { "get": { "summary": "List app secret configuration", "operationId": "list_app_secret_configuration", "x-symposium-realtime-signal-id": "list_app_secret_configuration", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "secrets:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Set, assign, or remove app secrets", "operationId": "set_or_remove_app_secrets", "x-symposium-realtime-signal-id": "set_or_remove_app_secrets", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "secrets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_secret_refs": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "values": { "type": "object", "additionalProperties": { "type": "string" }, "writeOnly": true }, "unset": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } } }, "additionalProperties": false } } } }, "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Configure an alias when a manifest-declared app-secret name differs from an existing same-profile secret, set new write-only app values, or remove app secrets. Exact-name profile secrets bind automatically and do not need profile_secret_refs. Values are resolved inside SYM-node and never returned." } }, "/settings": { "get": { "summary": "Get workspace settings", "operationId": "get_workspace_settings", "x-symposium-realtime-signal-id": "get_workspace_settings", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:read" } }, "/search": { "get": { "summary": "Search accessible chats and messages", "operationId": "search_workspace", "x-symposium-realtime-signal-id": "search_workspace", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "search:read" } }, "/activity/recent": { "get": { "summary": "Get recent workspace activity", "operationId": "get_recent_workspace_activity", "x-symposium-realtime-signal-id": "get_recent_workspace_activity", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:read", "parameters": [ { "name": "per_agent", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } }, { "name": "message_limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 3, "default": 2 } }, { "name": "include_messages", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Including messages additionally requires messages:read." } ] } }, "/overview": { "get": { "summary": "Get compact workspace overview", "operationId": "get_compact_workspace_overview", "x-symposium-realtime-signal-id": "get_compact_workspace_overview", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "workspace:read" } }, "/agents/{agent_id}/brief": { "get": { "summary": "Get Agent brief", "operationId": "get_agent_brief", "x-symposium-realtime-signal-id": "get_agent_brief", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "agents:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/chats/{chat_id}/tail": { "get": { "summary": "Get latest chat messages", "operationId": "get_latest_chat_messages", "x-symposium-realtime-signal-id": "get_latest_chat_messages", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "messages:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } } ] } }, "/connections/cosmise": { "get": { "summary": "Get safe Cosmise connection status", "operationId": "get_safe_cosmise_connection_status", "x-symposium-realtime-signal-id": "get_safe_cosmise_connection_status", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "connections:read" } }, "/account/bridge-apps": { "get": { "summary": "List account Bridge apps", "operationId": "list_bridge_apps", "x-symposium-realtime-signal-id": "list_bridge_apps", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "protocol": "bridge-app-management-v2", "instances": [] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "bridge_apps:read", "description": "List account Bridge apps. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "bridge_apps:read" ] } }, "/account/bridge-apps/{app_id}": { "get": { "summary": "Inspect app readiness", "operationId": "get_bridge_app", "x-symposium-realtime-signal-id": "get_bridge_app", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "ready": true, "browserAccess": true, "managementAllowed": true } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "bridge_apps:read", "description": "Inspect app readiness. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "bridge_apps:read" ] } }, "/account/bridge-apps/{app_id}/profiles": { "get": { "summary": "List connected Chrome profiles", "operationId": "list_bridge_profiles", "x-symposium-realtime-signal-id": "list_bridge_profiles", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "profiles": [ { "profile": "ext:example", "label": "Example browser", "connectionState": "connected", "tabCount": 1 } ] } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "bridge_apps:read", "description": "List connected Chrome profiles. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "bridge_apps:read" ] } }, "/account/bridge-apps/{app_id}/receipts": { "get": { "summary": "Inspect recent app management receipts", "operationId": "get_bridge_receipts", "x-symposium-realtime-signal-id": "get_bridge_receipts", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipts": [] } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "bridge_apps:read", "description": "Inspect recent app management receipts. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "bridge_apps:read" ] } }, "/account/bridge-apps/{app_id}/access": { "patch": { "summary": "Enable or disable app browser access", "operationId": "set_bridge_access", "x-symposium-realtime-signal-id": "set_bridge_access", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "enabled": true } }, "replayed": false } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "bridge_apps:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "enabled", "request_id", "issued_at" ], "additionalProperties": false }, "example": { "enabled": true, "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } } } }, "description": "Enable or disable app browser access. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). App management is the access switch and browser Pass management, not desktop control. Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2. No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "bridge_apps:write" ] } }, "/account/browser-passes": { "get": { "summary": "List account-authorized browser Passes", "operationId": "list_account_browser_passes", "x-symposium-realtime-signal-id": "list_account_browser_passes", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "items": [] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "browser_passes:read", "description": "List account-authorized browser Passes. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "browser_passes:read" ] } }, "/account/bridge-apps/{app_id}/browser-passes": { "get": { "summary": "List browser Passes on one app", "operationId": "list_app_browser_passes", "x-symposium-realtime-signal-id": "list_app_browser_passes", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "passes": [] } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "browser_passes:read", "description": "List browser Passes on one app. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). Metadata does not prove device readiness. No credentials are returned.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "browser_passes:read" ] }, "post": { "summary": "Create an app browser Pass", "operationId": "create_app_browser_pass", "x-symposium-realtime-signal-id": "create_app_browser_pass", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "pass": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example browser access", "scope": "read", "profiles": [ "ext:example" ] } } }, "replayed": false } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "browser_passes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "uniqueItems": true }, "scope": { "type": "string", "enum": [ "read", "full" ] }, "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "name", "profiles", "scope", "request_id", "issued_at" ], "additionalProperties": false }, "example": { "name": "Example browser access", "profiles": [ "ext:example" ], "scope": "read", "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } } } }, "description": "Create an app browser Pass. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). App management is the access switch and browser Pass management, not desktop control. Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2. No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "browser_passes:write" ] } }, "/account/bridge-apps/{app_id}/browser-passes/{pass_id}": { "delete": { "summary": "Revoke a browser Pass on its app", "operationId": "revoke_app_browser_pass", "x-symposium-realtime-signal-id": "revoke_app_browser_pass", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "deviceId": "11111111-1111-4111-8111-111111111111", "result": { "receipt": { "id": "11111111-1111-4111-8111-111111111111", "status": "completed", "result": { "revoked": true } }, "replayed": false } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "accountBearer": [] } ], "x-symposium-scope": "browser_passes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "issued_at": { "type": "integer", "description": "Unix milliseconds within 60 seconds. Example timestamp is illustrative; generate a fresh value." } }, "required": [ "request_id", "issued_at" ], "additionalProperties": false }, "example": { "request_id": "11111111-1111-4111-8111-111111111111", "issued_at": 1800000000000 } } } }, "description": "Revoke a browser Pass on its app. Account API key only; a workspace key, workspace administrator role or attached browser Pass is not account authority. Base URL: https://app.sym.so/v1 (not a workspace URL). App management is the access switch and browser Pass management, not desktop control. Management Off in the native app is a local veto. The app must be connected and support bridge-app-management-v2. No automatic retries: HTTP 200 alone is not mutation success. Check result.receipt.status; outcome_unknown requires receipts/state inspection.", "parameters": [ { "name": "pass_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1" } ], "x-account-scopes": [ "browser_passes:write" ] } }, "/agents/{agent_id}/chats/{chat_id}/browser-passes": { "get": { "summary": "List conversation browser Pass", "operationId": "list_conversation_browser_pass", "x-symposium-realtime-signal-id": "list_conversation_browser_pass", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "conversationId": "chat_example", "profileId": "agent_example", "attachments": [], "runtimeReady": true } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [], "accountDelegation": [] } ], "x-symposium-scope": "browser_passes:read", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions. Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient. Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish. Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive. To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1/workspaces/{workspace_id}", "variables": { "workspace_id": { "default": "workspace-id" } } } ], "x-account-scopes": [ "browser_passes:delegate" ], "x-workspace-scopes": [ "workspace:read", "browser_passes:read" ] }, "post": { "summary": "Attach conversation browser Pass", "operationId": "attach_conversation_browser_pass", "x-symposium-realtime-signal-id": "attach_conversation_browser_pass", "responses": { "200": { "description": "Success" }, "201": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "attachment": { "id": "attachment_example", "scope": "read" } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [], "accountDelegation": [] } ], "x-symposium-scope": "browser_passes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_id": { "type": "string" }, "pass_id": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "full" ] } }, "required": [ "device_id", "pass_id", "scope" ], "additionalProperties": false }, "example": { "device_id": "11111111-1111-4111-8111-111111111111", "pass_id": "11111111-1111-4111-8111-111111111111", "scope": "read" } } } }, "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions. Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient. Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish. Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive. To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1/workspaces/{workspace_id}", "variables": { "workspace_id": { "default": "workspace-id" } } } ], "x-account-scopes": [ "browser_passes:delegate" ], "x-workspace-scopes": [ "workspace:read", "browser_passes:write" ] } }, "/agents/{agent_id}/chats/{chat_id}/browser-passes/{attachment_id}": { "patch": { "summary": "Permission conversation browser Pass", "operationId": "permission_conversation_browser_pass", "x-symposium-realtime-signal-id": "permission_conversation_browser_pass", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [], "accountDelegation": [] } ], "x-symposium-scope": "browser_passes:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "read", "full" ] } }, "required": [ "scope" ], "additionalProperties": false }, "example": { "scope": "full" } } } }, "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions. Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient. Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish. Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive. To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority.", "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1/workspaces/{workspace_id}", "variables": { "workspace_id": { "default": "workspace-id" } } } ], "x-account-scopes": [ "browser_passes:delegate" ], "x-workspace-scopes": [ "workspace:read", "browser_passes:write" ] }, "delete": { "summary": "Detach conversation browser Pass", "operationId": "detach_conversation_browser_pass", "x-symposium-realtime-signal-id": "detach_conversation_browser_pass", "responses": { "200": { "description": "Success; inspect mutation receipt status", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limited" } }, "security": [ { "bearerAuth": [], "accountDelegation": [] } ], "x-symposium-scope": "browser_passes:write", "description": "Requires separate account delegation and workspace authority belonging to the same user, plus current target profile/chat access. Reuses the UI grant lifecycle; never executes browser actions. Workspace key additionally requires workspace:read. Account key requires browser_passes:delegate. Neither credential alone is sufficient. Read/full permission cannot exceed the underlying Pass. Detach revokes only this conversation; already-dispatched actions may finish. Grants expire after 30 days. Reattaching creates a new generation; stale handles must not revive. To use attached Passes, send a message with both credentials. Ordinary workspace-only messages gain no personal browser authority.", "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "servers": [ { "url": "https://app.sym.so/v1/workspaces/{workspace_id}", "variables": { "workspace_id": { "default": "workspace-id" } } } ], "x-account-scopes": [ "browser_passes:delegate" ], "x-workspace-scopes": [ "workspace:read", "browser_passes:write" ] } }, "/agents/{agent_id}/model-access": { "get": { "summary": "Read profile model connections and default", "operationId": "get_agent_model_access", "x-symposium-realtime-signal-id": "get_agent_model_access", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:read", "description": "Read profile model connections and default. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/model-access/connections": { "post": { "summary": "Add or update a verified model connection", "operationId": "connect_agent_model", "x-symposium-realtime-signal-id": "connect_agent_model", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "label", "provider", "model" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" }, "label": { "type": "string" }, "provider": { "enum": [ "anthropic", "custom" ] }, "api_key": { "type": "string", "writeOnly": true }, "base_url": { "type": "string", "format": "uri" }, "api_mode": { "enum": [ "chat_completions", "responses" ] }, "model": { "type": "string" } } }, "example": { "revision": 0, "label": "My provider", "provider": "custom", "base_url": "https://inference.example/v1", "api_mode": "chat_completions", "model": "model-id" } } } }, "description": "Add or update a verified model connection. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/model-access/verify": { "post": { "summary": "Verify a model on an existing connection", "operationId": "verify_agent_model", "x-symposium-realtime-signal-id": "verify_agent_model", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "connection_id", "model" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" }, "model": { "type": "string" } } }, "example": { "revision": 0, "connection_id": "codex", "model": "model-id" } } } }, "description": "Verify a model on an existing connection. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/model-access/default": { "post": { "summary": "Set or reset the profile default model", "operationId": "set_agent_model_default", "x-symposium-realtime-signal-id": "set_agent_model_default", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "selection" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "selection": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "connection_id", "model" ], "properties": { "connection_id": { "type": "string" }, "model": { "type": "string" } } } ] } } }, "example": { "revision": 0, "selection": null } } } }, "description": "Set or reset the profile default model. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/model-access/delete": { "post": { "summary": "Delete an unused model connection", "operationId": "delete_agent_model_connection", "x-symposium-realtime-signal-id": "delete_agent_model_connection", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "settings:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "connection_id" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" } } }, "example": { "revision": 0, "connection_id": "connection-example" } } } }, "description": "Delete an unused model connection. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/agents/{agent_id}/chats/{chat_id}/model-access": { "get": { "summary": "Read conversation model selection and runtime acknowledgement", "operationId": "get_chat_model_access", "x-symposium-realtime-signal-id": "get_chat_model_access", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:read", "description": "Read conversation model selection and runtime acknowledgement. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Set or reset the model for one conversation", "operationId": "set_chat_model", "x-symposium-realtime-signal-id": "set_chat_model", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked credential" }, "403": { "description": "Insufficient live access" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "422": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "429": { "description": "Rate limited" }, "503": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." }, "504": { "description": "Conflict, verification failure, runtime unavailable, or uncertain timeout; inspect before retrying." } }, "security": [ { "bearerAuth": [] } ], "x-symposium-scope": "chats:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "revision", "selection" ], "properties": { "revision": { "type": "integer", "minimum": 0 }, "selection": { "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "connection_id", "model" ], "properties": { "connection_id": { "type": "string" }, "model": { "type": "string" } } } ] } } }, "example": { "revision": 0, "selection": null } } } }, "description": "Set or reset the model for one conversation. Reuses existing profile model-access settings. Credentials are write-only and never returned. Read the current revision before a write; on conflict or timeout read back before deciding whether to retry. Model selections apply at the next main turn; saved settings are not proof of runtime acknowledgement. Profile connection/default writes require settings:write and existing owner/admin authority. Conversation selection requires chats:write and access to the exact profile and chat. Claude requires an Anthropic API key. Custom providers require public HTTPS:443 and OpenAI-compatible Chat Completions or Responses. Verification makes a small inference request.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chat_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "x-symposium-chat-runtime-controls": { "conversationReset": { "supported": true, "operationId": "send_agent_message", "content": "/new", "target": "exact agent_id + chat_id current session binding", "successMeaning": "message durably queued and dispatched; runtime acknowledgement is not guaranteed" }, "createChat": { "runtimeRestart": false, "note": "Creating a chat does not restart the profile runtime or Agent Gateway." }, "archiveChat": { "runtimeControl": false, "note": "Archiving preserves history and does not reset or terminate the runtime." }, "agentSettings": { "writableFields": [ "approval_mode" ], "runtimeControl": false }, "unsupportedOperations": [ "first-class chat reset acknowledgement", "session binding rotation/rebind", "chat runtime restart", "profile Agent Gateway restart", "tmux/session kill", "force new runtime" ] }, "x-symposium-realtime-signals": { "eventType": "workspace.api.invoked", "subscription": { "type": "subscribe", "topics": [ "workspace.api.invoked" ] }, "delivery": "ephemeral_best_effort", "emittedFor": "successful_authorized_invocations", "payloadFields": [ "v", "type", "workspace_id", "signal_id", "request_id" ] }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Workspace API key or OAuth access token" }, "accountBearer": { "type": "http", "scheme": "bearer", "description": "Account API key sym_ac_; workspace-only credentials rejected" }, "accountDelegation": { "type": "apiKey", "in": "header", "name": "X-Sym-Account-Authorization", "description": "Bearer account API key with browser_passes:delegate; same owner as workspace bearer" } }, "schemas": { "WorkspaceApiKey": { "type": "object", "required": [ "id", "name", "prefix", "last_four", "scopes", "created_at", "use_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "last_four": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "use_count": { "type": "integer", "minimum": 0 } } }, "WorkspaceApiKeyCreate": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AgentRuntimeSettings": { "type": "object", "required": [ "profile_id", "approval_mode", "can_manage" ], "properties": { "profile_id": { "type": "string" }, "hermes_profile": { "type": "string" }, "approval_mode": { "type": "string", "enum": [ "manual", "smart", "off" ], "description": "Persistent Hermes command-approval mode. off is Full access in SYM-OS." }, "can_manage": { "type": "boolean" }, "config_present": { "type": "boolean" }, "changed": { "type": "boolean" } } }, "AgentRuntimeSettingsUpdate": { "type": "object", "required": [ "approval_mode" ], "additionalProperties": false, "properties": { "approval_mode": { "type": "string", "enum": [ "manual", "smart", "off" ] } } }, "AgentChatCreate": { "type": "object", "properties": { "chat_id": { "type": "string" }, "title": { "type": "string" }, "session_id": { "type": "string" }, "initial_message": { "type": "string", "description": "Optional first user message. Creating a chat does not restart the Agent Gateway or guarantee a fresh profile runtime." } } }, "ResponseContext": { "type": "object", "additionalProperties": false, "required": [ "channel", "verbosity" ], "properties": { "channel": { "type": "string", "enum": [ "voice" ] }, "verbosity": { "type": "string", "enum": [ "concise" ] } }, "description": "Optional per-turn spoken-response preference. Omit for normal text. Null, partial objects and extra fields are rejected. Never changes persistent profile instructions." }, "AgentMessageCreate": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "User-authored message. Hermes slash commands are preserved exactly. Use /new to request a reset of this chat's current Hermes conversation." }, "client_message_id": { "type": "string", "description": "Stable client-generated message ID for deduplication." }, "attachments": { "type": "array", "items": { "type": "object" } }, "response_context": { "$ref": "#/components/schemas/ResponseContext" } } } } } } }