{ "openapi": "3.1.0", "info": { "title": "BeeOS Cloud Server API", "version": "3.1.0" }, "servers": [ { "url": "https://api.cloud.beeos.ai/v1" } ], "security": [ { "ServerAPIKey": [] } ], "paths": { "/agents/{agentId}/conversations/{conversationId}/approval-mode": { "put": { "operationId": "setConversationApprovalMode", "x-required-scopes": [ "conversations:control" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Version of the conversation the change is based on: its `resource_version` in double quotes, for example `\"3\"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalModeSettings" } } } }, "responses": { "200": { "description": "Approval mode desired state confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalModeResultResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "setApprovalMode", "summary": "Set the conversation approval mode" } }, "/agents/{agentId}/conversations/{conversationId}/reasoning": { "put": { "operationId": "setConversationReasoning", "x-required-scopes": [ "conversations:control" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Version of the conversation the change is based on: its `resource_version` in double quotes, for example `\"3\"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasoningSettings" } } } }, "responses": { "200": { "description": "Reasoning desired state confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasoningResultResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "setReasoning", "summary": "Set the conversation reasoning effort" } }, "/client-sessions": { "post": { "operationId": "createClientSession", "description": "Issue a client token with request-scoped ttl_seconds. The omitted value normalizes to 600 before idempotency comparison; reusing an Idempotency-Key with a different normalized TTL returns 409 idempotency_conflict.", "x-idempotency": "required", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSessionInput" } } } }, "responses": { "200": { "description": "Short-lived client token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSessionResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "identity", "x-sdk-method": "createClientSession", "summary": "Create a client session" } }, "/client-sessions/{sessionId}/refresh": { "post": { "operationId": "refreshClientSession", "description": "Rotate the client token with request-scoped ttl_seconds. The omitted value normalizes to 600 before idempotency comparison; reusing an Idempotency-Key with a different normalized TTL returns 409 idempotency_conflict.", "x-idempotency": "required", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the client session, the `session_id` returned when it was created." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requested_capabilities": { "type": "array", "uniqueItems": true, "items": { "type": "string" }, "description": "Operations the new token may perform. Each must already be granted to the session; the new set can only be equal or narrower. Omit it to keep the current capabilities. Names are listed on `requested_capabilities` of the create operation." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 1800, "default": 600, "description": "Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request." } } } } } }, "responses": { "200": { "description": "Rotated JTI with equal or narrower capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSessionResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "identity", "x-sdk-method": "refreshClientSession", "summary": "Refresh a client session" } }, "/client-sessions/{sessionId}": { "delete": { "operationId": "revokeClientSession", "x-idempotency": "required", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the client session, the `session_id` returned when it was created." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "responses": { "204": { "description": "Session revoked or already revoked" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "identity", "x-sdk-method": "revokeClientSession", "summary": "Revoke a client session" } }, "/external-users/{externalUserId}": { "delete": { "operationId": "deleteExternalUser", "x-idempotency": "required", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserID" }, "description": "ID of the end user whose stored data is deleted. 1 to 128 characters; `.` and `..` are rejected. This is the path resource id, not a request header." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "responses": { "202": { "description": "Asynchronous deletion accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionAccepted" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "identity", "x-sdk-method": "deleteExternalUser", "summary": "Start external user data deletion" } }, "/external-users/{externalUserId}/deletions/{deletionId}": { "get": { "operationId": "getExternalUserDeletion", "x-idempotency": "forbidden", "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserID" }, "description": "ID of the end user whose stored data is deleted. 1 to 128 characters; `.` and `..` are rejected. This is the path resource id, not a request header." }, { "name": "deletionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the deletion, the `deletion_id` returned by the delete operation." } ], "responses": { "200": { "description": "Deletion progress scoped to the authenticated app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deletion" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "identity", "x-sdk-method": "getExternalUserDeletion", "summary": "Get an external user data deletion" } }, "/providers": { "get": { "operationId": "listProviders", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "capability", "in": "query", "schema": { "type": "string" }, "description": "Return only providers that list this capability, for example `instance`." } ], "responses": { "200": { "description": "Provider catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "catalog", "x-sdk-method": "listProviders", "summary": "List providers" } }, "/deploy/regions": { "get": { "operationId": "listDeployRegions", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "provider_id", "in": "query", "schema": { "type": "string" }, "description": "Return only regions of this provider." }, { "name": "available", "in": "query", "schema": { "type": "boolean" }, "description": "`true` returns only available regions and `false` only unavailable ones. Any other value returns 400 `invalid_request`." } ], "responses": { "200": { "description": "Deploy regions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionPage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "catalog", "x-sdk-method": "listRegions", "summary": "List deploy regions" } }, "/deploy/models": { "get": { "operationId": "listDeployModels", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "harness", "in": "query", "schema": { "type": "string" }, "description": "Not supported: sending it returns 400 `invalid_request`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match on the model name." } ], "responses": { "200": { "description": "Deploy models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "catalog", "x-sdk-method": "listModels", "summary": "List deploy models" } }, "/instance-templates": { "get": { "operationId": "listInstanceTemplates", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "1-based page number, from 1 to 1000000. Defaults to 1." }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of templates per page, from 1 to 100. Defaults to 50." }, { "name": "harness", "in": "query", "schema": { "type": "string" }, "description": "Not supported: sending it returns 400 `invalid_request`." }, { "name": "provider_id", "in": "query", "schema": { "type": "string" }, "description": "Not supported: sending it returns 400 `invalid_request`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Not supported: sending it returns 400 `invalid_request`." } ], "responses": { "200": { "description": "Instance templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceTemplatePage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "catalog", "x-sdk-method": "listInstanceTemplates", "summary": "List instance templates" } }, "/instance-templates/{templateId}": { "get": { "operationId": "getInstanceTemplate", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "ID of the instance template." } ], "responses": { "200": { "description": "Instance template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceTemplate" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "catalog", "x-sdk-method": "getInstanceTemplate", "summary": "Get an instance template" } }, "/agent-templates": { "get": { "operationId": "listAgentTemplates", "x-sdk-resource": "catalog", "x-sdk-method": "listAgentTemplates", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only templates in this category, at most 128 characters. It must equal the `category` of the template." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive substring match on the template's display name or summary, at most 256 characters." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1-based page number, from 1 to 1000000. Defaults to 1." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of templates per page, from 1 to 100. Defaults to 50." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/agentTemplateCatalogView" } }, "total": { "type": "integer" } }, "required": [ "data", "total" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List agent templates" } }, "/instances": { "get": { "operationId": "listInstances", "security": [ { "serverKey": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "1-based page number, from 1 to 1000000. Defaults to 1." }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of instances per page, from 1 to 100. Defaults to 20." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Return only instances in this lifecycle phase: `pending`, `provisioning`, `running`, `stopped` or `terminated`. When omitted, terminated instances are not returned." }, { "name": "provider_id", "in": "query", "schema": { "type": "string" }, "description": "Return only instances hosted by this provider, at most 128 characters." }, { "name": "harness", "in": "query", "schema": { "type": "string" }, "description": "Return only instances that run this product harness (for example `openclaw`), at most 128 characters." }, { "name": "cluster_id", "in": "query", "schema": { "type": "string" }, "description": "Return only instances deployed to this cluster, at most 128 characters." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match on the instance name or ID, at most 200 characters." } ], "responses": { "200": { "description": "Tenant-scoped result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "instances", "x-sdk-method": "list", "summary": "List instances" }, "post": { "operationId": "instanceCreate", "x-sdk-resource": "instances", "x-sdk-method": "create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServerInstanceInput" } } } }, "summary": "Create an instance" } }, "/instances/{instanceId}": { "get": { "operationId": "getInstance", "x-sdk-resource": "instances", "x-sdk-method": "get", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an instance" }, "patch": { "operationId": "updateInstanceMetadata", "x-sdk-resource": "instances", "x-sdk-method": "update", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RuntimeInstanceSummary" } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServerInstanceInput" } } } }, "summary": "Update an instance" }, "delete": { "operationId": "deleteInstance", "x-sdk-resource": "instances", "x-sdk-method": "delete", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Delete an instance" } }, "/instances/{instanceId}/status": { "get": { "operationId": "getInstanceStatus", "x-sdk-resource": "instances", "x-sdk-method": "getStatus", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceStatusResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get instance status" } }, "/instances/{instanceId}/start": { "post": { "operationId": "startInstance", "x-sdk-resource": "instances", "x-sdk-method": "start", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Start an instance" } }, "/instances/{instanceId}/stop": { "post": { "operationId": "stopInstance", "x-sdk-resource": "instances", "x-sdk-method": "stop", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Version of the instance the request applies to: the `resource_version` of the representation you last read, optionally in quotes. A stale version returns 412 `version_mismatch`; a missing or invalid one returns 428 `precondition_required`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeInstanceResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Stop an instance" } }, "/instances/{instanceId}/upgrade": { "post": { "operationId": "upgradeInstance", "x-sdk-resource": "instances", "x-sdk-method": "upgrade", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 256 bytes without leading or trailing whitespace. Repeating a request with the same key and body replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeUpgradeJob" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_id": { "type": "string", "description": "ID of the published platform image to upgrade to. Send at least one of `image_id`, `image_ref` and `target_version`; they select among published platform images only." }, "image_ref": { "type": "string", "description": "Pinned public reference of the published platform image to upgrade to." }, "target_version": { "type": "string", "description": "Version of the published platform image to upgrade to." } }, "required": [], "additionalProperties": false } } } }, "summary": "Start an instance upgrade" } }, "/instances/{instanceId}/upgrades/{jobId}": { "get": { "operationId": "getInstanceUpgrade", "x-sdk-resource": "instances", "x-sdk-method": "getUpgrade", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the upgrade job, the `job_id` returned when the upgrade was started." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeUpgradeJob" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an instance upgrade" } }, "/agents": { "get": { "operationId": "listAgents", "x-required-scopes": [ "agents:read" ], "parameters": [ { "name": "instance_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return agents of this instance, at most 128 characters. An instance that does not exist or is not yours returns 404." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return agents in this state: `active` or `inactive`. Omit it to return both." }, { "name": "visibility", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return agents with this visibility: `private`, `unlisted`, `org`, `public` or `marketplace`. Omit it to return all." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return agents whose name, display name or description contains this text, ignoring case. At most 200 characters." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "Page number to return, starting at 1. Defaults to 1." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of agents per page, 1 to 100. Defaults to 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "agents", "x-sdk-method": "list", "summary": "List agents" } }, "/agents/{agentId}": { "get": { "operationId": "getAgent", "x-required-scopes": [ "agents:read" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "agents", "x-sdk-method": "get", "summary": "Get an agent" }, "patch": { "operationId": "updateAgent", "x-required-scopes": [ "agents:manage" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Version of the agent the change is based on: its `resource_version` in double quotes, for example `\"3\"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPatch" } } } }, "x-sdk-resource": "agents", "x-sdk-method": "update", "summary": "Update agent exposure settings" } }, "/agents/{agentId}/conversations": { "post": { "operationId": "createAgentConversation", "x-required-scopes": [ "conversations:write" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationInput" } } } }, "responses": { "201": { "description": "Durable conversation created or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "create", "summary": "Create a conversation" }, "get": { "operationId": "listAgentConversations", "x-required-scopes": [ "conversations:read" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from `next_cursor` of the previous page. Omit it to get the first page. At most 4096 characters." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of conversations to return in one page. Defaults to 50. Values from 1 to 200 are accepted." }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "all" ] }, "description": "Which conversations to list: `open` for conversations that accept messages (default), `closed` for closed conversations such as deleted ones, or `all` for both." } ], "responses": { "200": { "description": "Authorized conversation directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationPage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "list", "summary": "List conversations" } }, "/agents/{agentId}/conversations/{conversationId}": { "get": { "operationId": "getConversation", "x-required-scopes": [ "conversations:read" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." } ], "responses": { "200": { "description": "Authorized conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "get", "summary": "Get a conversation" }, "patch": { "operationId": "updateConversation", "x-required-scopes": [ "conversations:write" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Version of the conversation the change is based on: its `resource_version` in double quotes, for example `\"3\"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationInput" } } } }, "responses": { "200": { "description": "Conversation renamed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "update", "summary": "Rename a conversation" }, "delete": { "operationId": "deleteConversation", "x-required-scopes": [ "conversations:write" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "responses": { "204": { "description": "Conversation deleted" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "delete", "summary": "Delete a conversation" } }, "/agents/{agentId}/conversations/{conversationId}/messages": { "get": { "operationId": "listConversationMessages", "x-required-scopes": [ "messages:read" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor from `next_cursor` of the previous page. Omit it to get the first page. At most 4096 characters." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of messages to return in one page. Defaults to 50. The server accepts values from 1 to 200." } ], "responses": { "200": { "description": "Authoritative message history page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "messages", "x-sdk-method": "list", "summary": "List conversation messages" } }, "/agents/{agentId}/conversations/{conversationId}/messages/{messageId}": { "get": { "operationId": "getConversationMessage", "x-required-scopes": [ "messages:read" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message." } ], "responses": { "200": { "description": "Authoritative v3 message snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEnvelopeResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "messages", "x-sdk-method": "get", "summary": "Get a conversation message" } }, "/agents/{agentId}/conversations/{conversationId}/cancel": { "post": { "operationId": "cancelConversation", "x-required-scopes": [ "conversations:control" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelConversationInput" } } } }, "responses": { "202": { "description": "Cancel accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandReceiptResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "cancel", "summary": "Cancel conversation execution" } }, "/agents/{agentId}/conversations/{conversationId}/clear": { "post": { "operationId": "clearConversation", "x-required-scopes": [ "conversations:control" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "responses": { "202": { "description": "Clear accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearConversationReceiptResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "clear", "summary": "Clear conversation history" } }, "/agents/{agentId}/conversations/{conversationId}/model": { "put": { "operationId": "setConversationModel", "x-required-scopes": [ "conversations:control" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Version of the conversation the change is based on: its `resource_version` in double quotes, for example `\"3\"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConversationModelInput" } } } }, "responses": { "202": { "description": "Model change accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandReceiptResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "conversations", "x-sdk-method": "setModel", "summary": "Set the conversation model override" } }, "/usage/summary": { "get": { "operationId": "getUsageSummary", "x-sdk-resource": "usage", "x-sdk-method": "getSummary", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": "Length of the reporting window, which ends now: `day` for the last 24 hours (default), `week` for the last 7 days or `month` for the last 30 days. The window moves with the current time and does not follow calendar days." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only count usage of this category, one of the keys that appear in `by_category`. Omit it to count all categories." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerUsageSummary" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get the usage summary" } }, "/instances/{instanceId}/terminal-sessions": { "post": { "operationId": "createTerminalSession", "summary": "Create a terminal session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platformAgentId" ], "additionalProperties": false, "properties": { "platformAgentId": { "type": "string", "format": "uuid", "description": "ID of the agent the terminal session is for, as a UUID." }, "conversationId": { "type": "string", "format": "uuid", "description": "ID of the conversation to attach the terminal to, as a UUID. Optional." }, "resumeTerminalId": { "type": "string", "format": "uuid", "description": "ID of an existing terminal to resume, as a UUID. Optional." } } } } } }, "responses": { "201": { "description": "Single-use RS256 terminal ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSessionDocument" } } } }, "400": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "instances", "x-sdk-method": "createTerminalSession", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." } ] } }, "/instances/{instanceId}/canvas-sessions": { "post": { "operationId": "createCanvasSession", "summary": "Create a canvas session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platformAgentId", "conversationId" ], "additionalProperties": false, "properties": { "platformAgentId": { "type": "string", "format": "uuid", "description": "ID of the agent the canvas session is for, as a UUID." }, "conversationId": { "type": "string", "format": "uuid", "description": "ID of the conversation the canvas belongs to, as a UUID." }, "canvasId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Opaque Canvas/A2UI surface identifier; not a UUID" } } } } } }, "responses": { "201": { "description": "Single-use RS256 canvas relay ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanvasSessionDocument" } } } }, "400": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-sdk-resource": "instances", "x-sdk-method": "createCanvasSession", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." } ] } }, "/instances/{instanceId}/exec": { "post": { "operationId": "execInstance", "x-sdk-resource": "instances", "x-sdk-method": "exec", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeExecResult" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "argv": { "type": "array", "items": { "type": "string" }, "description": "Program and arguments as an argument vector; it is never passed through a shell. 1 to 64 entries of at most 4096 bytes each and 16 KiB in total. The first entry must not be blank." }, "timeout_seconds": { "type": "integer", "description": "Maximum run time in seconds, from 1 to 30." } }, "required": [ "argv" ], "additionalProperties": false } } } }, "summary": "Run a command in an instance" } }, "/files/presign-upload": { "post": { "operationId": "presignFileUpload", "x-sdk-resource": "files", "x-sdk-method": "prepareUpload", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileTransferDescriptor" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePrepareUploadInput" } } } }, "summary": "Create a file upload URL" } }, "/files/{fileId}/confirm": { "post": { "operationId": "confirmFileUpload", "x-sdk-resource": "files", "x-sdk-method": "confirmUpload", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFile" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileConfirmInput" } } } }, "summary": "Confirm a file upload" } }, "/files": { "get": { "operationId": "listFiles", "x-sdk-resource": "files", "x-sdk-method": "list", "parameters": [ { "name": "content_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files with exactly this MIME type, at most 255 characters." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor from `next_since` of the previous page. Omit it to start at the oldest file. It applies only to the default chronological listing, that is when none of `status`, `file_type`, `category`, `source`, `q`, `instance_id`, `agent_id`, `sort`, `sort_dir` and `offset` is set. At most 2048 characters." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files in this state: `ready` or `pending_upload`. When omitted, files in both states are returned." }, { "name": "file_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files in this category: `FILE_TYPE_IMAGE`, `FILE_TYPE_VIDEO`, `FILE_TYPE_AUDIO`, `FILE_TYPE_DOCUMENT`, `FILE_TYPE_ARCHIVE` or `FILE_TYPE_OTHER`." }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files in a broad category: `image`, `video`, `document` or `other`. `other` covers every file that is not an image, a video or a document, including audio and archives." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files with this origin: `manual`, `chat_upload`, `runtime_generated` or `template_skill`. Files without a recorded origin count as `manual`." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files whose name contains this text, compared case-insensitively." }, { "name": "instance_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files that belong to this instance." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only files that belong to this agent." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Field to sort by: `created_at` (the default), `updated_at`, `file_name` or `size_bytes`. Ties are ordered by file ID. Any sort, filter or `offset` switches the listing to offset paging." }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort direction: `asc` or `desc`. When sorting or filtering the default is `desc`; the default chronological listing is oldest first." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of files to return, from 0 to 200. Defaults to 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of matching files to skip, 0 or more. Setting it switches the listing to offset paging." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePage" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List files" } }, "/files/{fileId}": { "get": { "operationId": "getFile", "x-sdk-resource": "files", "x-sdk-method": "get", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResolution" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get a file" }, "patch": { "operationId": "renameFile", "x-sdk-resource": "files", "x-sdk-method": "rename", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFile" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\\` or control characters." } }, "required": [ "title" ], "additionalProperties": false } } } }, "summary": "Rename a file" }, "delete": { "operationId": "deleteFile", "x-sdk-resource": "files", "x-sdk-method": "delete", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Delete a file" } }, "/agent-templates/{id}": { "get": { "operationId": "getAgentTemplate", "x-sdk-resource": "catalog", "x-sdk-method": "getAgentTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent template." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/agentTemplateCatalogView" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an agent template" } }, "/files/{fileId}/share": { "post": { "operationId": "createShareFileShare", "x-sdk-resource": "files", "x-sdk-method": "createShare", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileShareResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Create a file share link" }, "get": { "operationId": "getShareFileShare", "x-sdk-resource": "files", "x-sdk-method": "getShare", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileShareResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get a file share link" }, "delete": { "operationId": "revokeShareFileShare", "x-sdk-resource": "files", "x-sdk-method": "revokeShare", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the file, the `file_id` returned when the upload was prepared." } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Revoke a file share link" } }, "/file-shares/{slug}": { "get": { "operationId": "resolveFileShare", "x-sdk-resource": "files", "x-sdk-method": "resolveShare", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public slug of the file share, the `slug` returned when the share was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "slug": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "download": { "$ref": "#/components/schemas/FileTransferDescriptor" } }, "required": [ "file_id", "slug", "filename", "content_type", "size_bytes", "download" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Resolve a file share link" } }, "/files/summary": { "get": { "operationId": "getFilesSummary", "x-sdk-resource": "files", "x-sdk-method": "getSummary", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileSummary" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get the file summary" } }, "/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/share": { "post": { "operationId": "createShareReply", "x-sdk-resource": "messages", "x-sdk-method": "createShare", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string", "description": "Public slug that identifies the share. Use it to resolve the shared reply with the reply share lookup." }, "created_at": { "type": "string", "description": "Time the share was created." } }, "required": [ "slug", "created_at" ], "additionalProperties": false, "description": "The share of the reply." } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Create a reply share link" }, "get": { "operationId": "getShareReply", "x-sdk-resource": "messages", "x-sdk-method": "getShare", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string", "description": "Public slug that identifies the share. Use it to resolve the shared reply with the reply share lookup." }, "created_at": { "type": "string", "description": "Time the share was created." } }, "required": [ "slug", "created_at" ], "additionalProperties": false, "description": "The share of the reply." } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get a reply share link" }, "delete": { "operationId": "revokeShareReply", "x-sdk-resource": "messages", "x-sdk-method": "revokeShare", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message." } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Revoke a reply share link" } }, "/reply-shares/{slug}": { "get": { "operationId": "resolveReplyShare", "x-sdk-resource": "messages", "x-sdk-method": "resolveShare", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public slug of the shared reply, the `data.slug` returned when the share was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyShareResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Resolve a reply share link" } }, "/instances/{instanceId}/connect-url": { "get": { "operationId": "getInstanceConnectURL", "x-sdk-resource": "instances", "x-sdk-method": "getConnectURL", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Service to connect to: `browser` for a browser viewer or `acp` for an agent connection. Required." }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ID you choose for the viewing client session, 1 to 128 characters (letters, digits, `_`, `.`, `:` and `-`, starting with a letter or digit). Required when `service` is `browser`; not accepted for `acp`." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Access role to request: `viewer` or `controller`. Required when `service` is `browser`; not accepted for `acp`." }, { "name": "generation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Browser generation the access grant must be bound to, in the same format as `client_id`. The request fails when the browser's current generation differs. Only for `browser`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectURLResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an instance connect URL" } }, "/instances/{instanceId}/stream-url": { "get": { "operationId": "getInstanceStreamURL", "x-sdk-resource": "instances", "x-sdk-method": "getStreamURL", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance." }, { "name": "viewportWidth", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Viewport width in pixels, greater than 0 and below 100000." }, { "name": "viewportHeight", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Viewport height in pixels, greater than 0 and below 100000." }, { "name": "dpr", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Device pixel ratio, greater than 0 and below 16." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JSONValue" } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an instance stream URL" } }, "/agents/{agentId}/conversations/{conversationId}/resume": { "post": { "operationId": "resumeConversation", "x-sdk-resource": "conversations", "x-sdk-method": "resume", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent, the `id` returned by the agents API." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation, as returned when it was created or listed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "request_id", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Resume a paused conversation" } }, "/automations": { "post": { "operationId": "createAutomation", "x-sdk-resource": "automations", "x-sdk-method": "create", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoAutomationRule" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtoAutomationInput" } } } }, "summary": "Create an automation" }, "get": { "operationId": "listAutomations", "x-sdk-resource": "automations", "x-sdk-method": "list", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only automations in this state: `enabled`, `paused` or `expired`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor from `nextCursor` of the previous page. Omit it to get the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of automations to return in one page, 1 or more, up to the server maximum (at most 1000). Larger values are rejected with 400 `invalid_argument`. Defaults to 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoListAutomationsResponse" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List automations" } }, "/automations/{automationId}": { "get": { "operationId": "getAutomation", "x-sdk-resource": "automations", "x-sdk-method": "get", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/JSONValue" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an automation" }, "patch": { "operationId": "updateAutomation", "x-sdk-resource": "automations", "x-sdk-method": "update", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoAutomationRule" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtoAutomationPatch" } } } }, "summary": "Update an automation" }, "delete": { "operationId": "deleteAutomation", "x-sdk-resource": "automations", "x-sdk-method": "delete", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Delete an automation" } }, "/automations/{automationId}/pause": { "post": { "operationId": "pauseAutomation", "x-sdk-resource": "automations", "x-sdk-method": "pause", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/JSONValue" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Pause an automation" } }, "/automations/{automationId}/resume": { "post": { "operationId": "resumeAutomation", "x-sdk-resource": "automations", "x-sdk-method": "resume", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/JSONValue" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Resume an automation" } }, "/automations/{automationId}/runs": { "post": { "operationId": "createAutomationRun", "x-sdk-resource": "automations", "x-sdk-method": "createRun", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Key that makes the request safe to retry, 1 to 128 bytes and not blank. Repeating a request with the same key and body returns the original run; reusing the key for a different request returns 409 `idempotency_conflict`." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoAutomationRun" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtoAutomationRunInput" } } } }, "summary": "Start an automation run" }, "get": { "operationId": "listAutomationRuns", "x-sdk-resource": "automations", "x-sdk-method": "listRuns", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only runs in this state: `scheduled`, `dispatched`, `failed` or `skipped`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor from `nextCursor` of the previous page. Omit it to get the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of runs to return in one page, 1 or more, up to the server maximum (at most 1000). Larger values are rejected with 400 `invalid_argument`. Defaults to 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoListAutomationRunsResponse" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List automation runs" } }, "/automations/{automationId}/runs/{runId}": { "get": { "operationId": "getAutomationRun", "x-sdk-resource": "automations", "x-sdk-method": "getRun", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the automation, the `id` returned when it was created." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the run, the `id` returned when the run was created or listed." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoAutomationRun" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an automation run" } }, "/automations/webhooks": { "post": { "operationId": "createWebhookAutomation", "x-sdk-resource": "automations", "x-sdk-method": "createWebhook", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ProtoAutomationRule" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtoAutomationWebhookInput" } } } }, "summary": "Create a webhook automation" } }, "/audio/transcribe": { "post": { "operationId": "transcribeAudio", "x-sdk-resource": "audio", "x-sdk-method": "transcribe", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "text": { "type": "string" }, "duration_seconds": { "type": "number" } }, "required": [ "text", "duration_seconds" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": false } } } }, "summary": "Transcribe audio" } }, "/instances/{instanceId}/canvases/{canvasId}/share": { "get": { "operationId": "getShareCanvas", "x-sdk-resource": "canvases", "x-sdk-method": "getShare", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/CanvasShare" }, { "type": "null" } ] } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get a canvas share link" }, "post": { "operationId": "createShareCanvas", "x-sdk-resource": "canvases", "x-sdk-method": "createShare", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/CanvasShare" }, { "type": "null" } ] } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "description": "How visitors get access: `password` to protect the share with `password`, or any other value, for example `link`, to let anyone with the link open the canvas. Required." }, "password": { "type": "string", "description": "Password visitors must enter. Used only when `mode` is `password`; without it no visitor can pass the check." }, "allowInteraction": { "type": "boolean", "description": "Whether visitors can interact with the canvas. Defaults to true. Send false to make the share view-only." } }, "required": [ "mode" ], "additionalProperties": false } } } }, "summary": "Create a canvas share link" }, "delete": { "operationId": "deleteShareCanvas", "x-sdk-resource": "canvases", "x-sdk-method": "deleteShare", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Revoke a canvas share link" } }, "/instances/{instanceId}/canvases/{canvasId}/snapshots": { "get": { "operationId": "listCanvasSnapshots", "x-sdk-resource": "canvases", "x-sdk-method": "listSnapshots", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CanvasSnapshot" } } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List canvas snapshots" } }, "/instances/{instanceId}/canvases/{canvasId}/snapshots/{snapshotId}/restore": { "post": { "operationId": "restoreCanvasSnapshot", "x-sdk-resource": "canvases", "x-sdk-method": "restoreSnapshot", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "canvasId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the canvas, a UUID. The canvas must belong to the conversation and agent named by the headers." }, { "name": "snapshotId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the snapshot to restore, as returned by the snapshot list." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "snapshotId": { "type": "string" }, "canvasId": { "type": "string" }, "restored": { "type": "boolean" }, "version": { "type": "integer" } }, "required": [ "snapshotId", "canvasId", "restored", "version" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Restore a canvas snapshot" } }, "/instances/{instanceId}/canvas-sessions/{conversationId}": { "get": { "operationId": "getCanvasSession", "x-sdk-resource": "canvases", "x-sdk-method": "getSession", "parameters": [ { "name": "instanceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the instance that hosts the agent. It must belong to your app." }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation to look up the canvas session for. It must equal the `X-BeeOS-Conversation-ID` header." }, { "name": "X-BeeOS-Conversation-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the conversation the canvas is used in. For the session lookup it must equal `conversationId` in the path." }, { "name": "X-BeeOS-Platform-Agent-ID", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID of the agent that owns the canvas. It must be an agent of `instanceId`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "canvasId": { "type": "string" }, "sessionId": { "type": "string" }, "instanceId": { "type": "string" }, "linkedAt": { "type": "string" }, "role": { "type": "string" } }, "required": [ "canvasId", "sessionId", "instanceId", "linkedAt", "role" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Resolve a conversation canvas session" } }, "/agent/bind/{id}/details": { "get": { "operationId": "getAgentBindDetails", "x-sdk-resource": "deviceBindings", "x-sdk-method": "getDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent bind session, the `bind_id` returned when the device created it." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/agentBindDetailsWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "x-sdk-error-code-field": "error", "summary": "Get agent bind session details" } }, "/agent/bind/{id}/confirm": { "post": { "operationId": "confirmAgentBind", "x-sdk-resource": "deviceBindings", "x-sdk-method": "confirm", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent bind session to confirm, the `bind_id` returned when the device created it." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/agentBindWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the instance created for the device, up to 128 characters. Defaults to the host name the device reported." }, "modelPrimary": { "type": "string", "description": "Accepted and ignored. The instance keeps the default model of the server." }, "model_primary": { "type": "string", "description": "Snake-case alias of `modelPrimary`, also ignored. If both are sent they must be equal." } }, "required": [], "additionalProperties": false } } } }, "x-sdk-error-code-field": "error", "summary": "Confirm an agent bind session" } }, "/agent/portal/bind-sessions": { "post": { "operationId": "createPortalBind", "x-sdk-resource": "deviceBindings", "x-sdk-method": "createPortal", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/portalBindWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the instance created for the device, up to 128 characters. Defaults to `BeeRunner`." } }, "required": [], "additionalProperties": false } } } }, "x-sdk-error-code-field": "error", "summary": "Create a portal bind session" } }, "/agent/portal/bind-sessions/{id}": { "get": { "operationId": "getPortalBind", "x-sdk-resource": "deviceBindings", "x-sdk-method": "getPortal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/portalBindWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "x-sdk-error-code-field": "error", "summary": "Get a portal bind session" } }, "/agent/portal/bind-sessions/{id}/revoke": { "post": { "operationId": "revokePortalBind", "x-sdk-resource": "deviceBindings", "x-sdk-method": "revokePortal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/portalBindWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "x-sdk-error-code-field": "error", "summary": "Revoke a portal bind session" } }, "/agent/portal/bind-sessions/{id}/resolve": { "post": { "operationId": "resolvePortalBind", "x-sdk-resource": "deviceBindings", "x-sdk-method": "resolvePortal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/portalBindWire" } }, "required": [ "success", "data" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBindingErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "recover", "create" ], "description": "What to do with the device that claimed the session. Required.", "x-enumDescriptions": { "recover": "Bind the device to the existing instance given by `instance_id`.", "create": "Create a new instance for the device." } }, "instance_id": { "type": "string", "description": "ID of the existing instance to bind the device to. Required when `decision` is `recover`; ignored for `create`." } }, "required": [ "decision" ], "additionalProperties": false } } } }, "x-sdk-error-code-field": "error", "summary": "Resolve a portal bind session" } }, "/a2a/{agentId}": { "post": { "operationId": "invokeA2A", "x-sdk-resource": "a2a", "x-sdk-method": "invoke", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeMethodResponse" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ], "description": "JSON-RPC protocol version: must be `2.0`." }, "id": { "type": "string", "description": "ID of the request, echoed in the `id` of the response." }, "method": { "type": "string", "description": "A2A method to call. Each method has an A2A 1.0 name and an A2A 0.3 alias: `SendMessage` (`message/send`) sends a message to the agent and creates a task; `SendStreamingMessage` (`message/stream`) does the same and streams updates as server-sent events; `SubscribeToTask` (`tasks/resubscribe`) resumes the update stream of a task; `GetTask` (`tasks/get`), `CancelTask` (`tasks/cancel`) and `ListTasks` (`tasks/list`) read and cancel tasks; `CompleteTask` (`tasks/complete`) finishes a task with a result or an error message; `UpdateStatus` (`tasks/updateStatus`) sets the state of a task; `CreateTaskPushNotificationConfig` (`SetPushNotificationConfig`, `tasks/pushNotification/set`), `GetTaskPushNotificationConfig` (`GetPushNotificationConfig`, `tasks/pushNotification/get`), `ListTaskPushNotificationConfigs` (`ListPushNotificationConfigs`, `tasks/pushNotification/list`) and `DeleteTaskPushNotificationConfig` (`DeletePushNotificationConfig`, `tasks/pushNotification/delete`) manage push notification settings of a task. An unknown method returns error `-32601`." }, "params": { "$ref": "#/components/schemas/JSONValue", "description": "Parameters of the method. Their shape depends on `method`, as defined by the A2A protocol." } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false } } } }, "summary": "Send an A2A JSON-RPC request" } }, "/a2a/{agentId}/.well-known/agent-card.json": { "get": { "operationId": "getA2AAgentCard", "x-sdk-resource": "a2a", "x-sdk-method": "getAgentCard", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCard" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get the A2A agent card" } }, "/a2a/{agentId}/.well-known/agent.json": { "get": { "operationId": "getA2AAgentCardLegacy", "x-sdk-resource": "a2a", "x-sdk-method": "getAgentCardLegacy", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AAgentCard" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get the A2A agent card (legacy path)" } }, "/a2a/{agentId}/tasks": { "get": { "operationId": "listA2ATasks", "x-sdk-resource": "a2a", "x-sdk-method": "listTasks", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`sent` lists tasks that the agent submitted and `received` lists tasks that were submitted to it. When omitted, both are listed. Any other value is rejected." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return only tasks exchanged with this other agent, at most 128 characters. Whether it is matched as the submitter or the receiver depends on `direction`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor for the next page: the `next_cursor` of the previous response, at most 4096 bytes." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Number of tasks per page, from 1 to 100. Defaults to 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/a2aTaskView" } }, "total": { "type": "integer" }, "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "tasks", "total", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "List A2A tasks" } }, "/a2a/{agentId}/tasks/{taskId}": { "get": { "operationId": "getA2ATask", "x-sdk-resource": "a2a", "x-sdk-method": "getTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the task, at most 256 characters." }, { "name": "history_length", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum number of history messages to return, from 0 to 200. Defaults to 50." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/a2aTaskView" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get an A2A task" } }, "/a2a/{agentId}/tasks/{taskId}/cancel": { "post": { "operationId": "cancelA2ATask", "x-sdk-resource": "a2a", "x-sdk-method": "cancelTask", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the agent. It must belong to your app. For JSON-RPC and agent card requests the agent must also have its A2A protocol enabled, otherwise the request returns 403 `a2a_disabled`; task reads work either way." }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the task, at most 256 characters." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/a2aTaskView" } } } }, "default": { "description": "Cloud Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Cancel an A2A task" } }, "/uhp": { "get": { "tags": [ "Discovery" ], "operationId": "getDiscovery", "summary": "Protocol discovery document", "description": "Served without authentication: a client must be able to learn whether it is talking to a UHP\nserver, and which versions it speaks, before presenting credentials. The document contains\nnothing principal-specific.\n", "security": [], "responses": { "200": { "description": "The discovery document", "headers": { "UHP-Version": { "$ref": "#/components/headers/UHPVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPDiscovery" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "catalog", "x-sdk-method": "getDiscovery", "parameters": [], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/harnesses": { "get": { "tags": [ "Harnesses" ], "operationId": "listHarnesses", "summary": "List configured harnesses", "responses": { "200": { "description": "Harnesses within the caller's scope. May be empty.", "content": { "application/json": { "schema": { "type": "object", "required": [ "harnesses" ], "properties": { "harnesses": { "type": "array", "items": { "$ref": "#/components/schemas/UHPHarness" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "list", "parameters": [], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] }, "post": { "tags": [ "Harnesses" ], "operationId": "createHarness", "summary": "Create a configured harness", "description": "Synchronous: Cloud submits every runtime operation and waits (up to 45s, so use a client timeout of at least 60s) before responding. 502 harness_error lists per-item results in error.detail.operations[]; 504 beeos_harness_update_in_progress means work continues, retry the identical request after Retry-After (a create without an Idempotency-Key is not re-attached and would create a second harness); 409 beeos_harness_busy means a different write is in flight, retry after Retry-After; 409 beeos_idempotency_conflict means the Idempotency-Key was used with a different request; 503 harness_unavailable means the instance is not running or the operation journal is unavailable; 413 means the body exceeds 4 MiB (upload large skills as a Files blob). The optional Idempotency-Key header (1-128 visible ASCII characters) makes a create (POST, or PUT with template_id) safe to resend: the same key and request returns the same harness. instance_id and name are required and base must equal the instance runtime (422); template_id and template_version create the harness from an agent template; default_model is honored only here. a non-empty skills or mcp_servers is rejected on create (422 beeos_field_not_supported); add them with PUT. Not supported by BeeOS Cloud yet (422 beeos_field_not_supported): a non-empty system_prompt, disabled_tools, environment or plugins, or any max_step or timeout_seconds. An unchanged name and empty values are accepted, so a GET-modify-PUT round trip works.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarnessCreate" } } } }, "responses": { "200": { "description": "The created harness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarness" } } } }, "400": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "413": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "422": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "502": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "503": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "504": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Key that makes a request that creates an agent safe to retry, 1 to 128 visible ASCII characters without spaces. It applies to `POST /harnesses` and to `PUT` with a `template_id`; for other updates it is ignored. Repeating a request with the same key and body continues the earlier attempt; reusing the key for a different request returns 409 `beeos_idempotency_conflict`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/harnesses/{harness_id}": { "get": { "tags": [ "Harnesses" ], "operationId": "getHarness", "summary": "Get one harness", "responses": { "200": { "description": "The harness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarness" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "get", "parameters": [ { "name": "harness_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the harness. It starts with `chrn_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] }, "put": { "tags": [ "Harnesses" ], "operationId": "updateHarness", "summary": "Update a harness configuration", "description": "Synchronous: Cloud submits every runtime operation and waits (up to 45s, so use a client timeout of at least 60s) before responding. 502 harness_error lists per-item results in error.detail.operations[]; 504 beeos_harness_update_in_progress means work continues, retry the identical request after Retry-After (a create without an Idempotency-Key is not re-attached and would create a second harness); 409 beeos_harness_busy means a different write is in flight, retry after Retry-After; 409 beeos_idempotency_conflict means the Idempotency-Key was used with a different request; 503 harness_unavailable means the instance is not running or the operation journal is unavailable; 413 means the body exceeds 4 MiB (upload large skills as a Files blob). The optional Idempotency-Key header (1-128 visible ASCII characters) makes a create (POST, or PUT with template_id) safe to resend: the same key and request returns the same harness. An absent field is unchanged; a present list replaces the whole list. When skills is present it is diffed against the installed skills: listed skills with files, content or blob (exactly one) are installed; an installed skill listed with a different enabled flag is updated; installed skills that are omitted are uninstalled unless bundled with the runtime; a listed skill that is not installed and has no files, content or blob returns 422; enabled:false on a fresh install returns 422. When mcp_servers is present it is diffed against the runtime MCP servers: a server sent with a credential (headers or auth plus expires_at, at most 24 hours ahead) is set, a connected server sent without one is kept, omitted servers are unset; the url must be https and transport is http or sse; GET never returns a url or credential. 422 beeos_mcp_not_supported is returned only when the instance runtime has no MCP methods. base is immutable; a name change or a default_model different from the current one (without template_id) returns 422 beeos_field_not_supported. Not supported by BeeOS Cloud yet (422 beeos_field_not_supported): a non-empty system_prompt, disabled_tools, environment or plugins, or any max_step or timeout_seconds. An unchanged name and empty values are accepted, so a GET-modify-PUT round trip works.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarnessCreate" } } } }, "responses": { "200": { "description": "The updated harness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarness" } } } }, "400": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "413": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "422": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "502": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "503": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "504": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "update", "parameters": [ { "name": "harness_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the harness. It starts with `chrn_`." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Key that makes a request that creates an agent safe to retry, 1 to 128 visible ASCII characters without spaces. It applies to `POST /harnesses` and to `PUT` with a `template_id`; for other updates it is ignored. Repeating a request with the same key and body continues the earlier attempt; reusing the key for a different request returns 409 `beeos_idempotency_conflict`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] }, "delete": { "tags": [ "Harnesses" ], "operationId": "deleteHarness", "summary": "Delete a harness", "description": "Not supported by BeeOS Cloud yet: returns 422 beeos_harness_delete_not_supported once the harness is found.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "delete", "parameters": [ { "name": "harness_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the harness. It starts with `chrn_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/models": { "get": { "tags": [ "Harnesses" ], "operationId": "listModels", "summary": "The model catalogue, by backend", "responses": { "200": { "description": "Models grouped by backend, each with computed availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPModelCatalog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "listAllModels", "parameters": [], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/harnesses/{harness_id}/models": { "get": { "tags": [ "Harnesses" ], "operationId": "listHarnessModels", "summary": "Models this harness can run", "responses": { "200": { "description": "The harness's allowed models, default and authorized fallback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPHarnessModels" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "harnesses", "x-sdk-method": "listModels", "parameters": [ { "name": "harness_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the harness. It starts with `chrn_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/responses": { "post": { "tags": [ "Tasks" ], "operationId": "createResponse", "summary": "Run a task", "description": "The core of the protocol. With `stream: false` the server returns one Response object when\nthe task reaches a terminal state. With `stream: true` it returns `text/event-stream`\ncarrying the events defined in the Streaming chapter.\n\nRetries MUST carry `Idempotency-Key`: without one, a retry after a timeout runs the task a\nsecond time while the first may still be running.\n", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repeating a key returns the first request's result and does not re-execute." }, { "name": "UHP-Version", "in": "header", "required": false, "schema": { "type": "string", "examples": [ "2026-08-11" ] }, "description": "Protocol version to use: `2026-10-04` (the default), `2026-09-28`, `2026-09-12` or `2026-08-11`. The version served is echoed in the same header of the response. An unsupported version is rejected with `unsupported_protocol_version`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPCreateResponseRequest" } } } }, "responses": { "200": { "description": "The finished Response (non-streaming), or the event stream (streaming).\n", "headers": { "UHP-Version": { "$ref": "#/components/headers/UHPVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE; each `data:` line is one Event object." } } } }, "400": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "responses", "x-sdk-method": "create", "x-sdk-response-stream": "stream=true returns text/event-stream; stream=false returns UHPResponse", "x-sdk-event-schema": { "$ref": "#/components/schemas/UHPEvent" }, "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/responses/{response_id}": { "get": { "tags": [ "Tasks" ], "operationId": "getResponse", "summary": "Read a task back", "responses": { "200": { "description": "The Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "responses", "x-sdk-method": "get", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the response. It starts with `resp_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] }, "delete": { "tags": [ "Tasks" ], "operationId": "deleteResponse", "summary": "Delete a stored response", "description": "Must not cancel a running task — deletion and cancellation are different intentions.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted response." }, "deleted": { "type": "boolean", "description": "Always true. A response that cannot be deleted returns an error instead." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "responses", "x-sdk-method": "delete", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the response. It starts with `resp_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/responses/{response_id}/input_items": { "get": { "tags": [ "Tasks" ], "operationId": "getResponseInputItems", "summary": "The input the task was created with", "responses": { "200": { "description": "Input items", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "description": "Object type of the list.", "x-enumDescriptions": { "list": "A list of items." }, "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "description": "Input items of the response, as they were sent in the request. A string `input` appears as one `message` item with role `user` and an `input_text` content part." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "responses", "x-sdk-method": "getInputItems", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the response. It starts with `resp_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/responses/{response_id}/cancel": { "post": { "tags": [ "Sessions" ], "operationId": "cancelResponse", "summary": "Cancel a running task", "description": "Idempotent. Cancelling an already-terminal task succeeds and changes nothing — a client\nretrying a cancel after a dropped connection must not be punished for having succeeded.\n", "responses": { "200": { "description": "The Response, now cancelling or terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-resource": "responses", "x-sdk-method": "cancel", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the response. It starts with `resp_`." } ], "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } }, "/responses/{response_id}/events": { "get": { "operationId": "getResponseEvents", "x-sdk-resource": "responses", "x-sdk-method": "getEvents", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the response. It starts with `resp_`." }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Sequence number of the last event the client received. The stream resumes after it. Must be a non-negative integer." }, { "name": "UHP-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Protocol version to use: `2026-10-04` (the default), `2026-09-28`, `2026-09-12` or `2026-08-11`. The version served is echoed in the same header of the response. An unsupported version is rejected with `unsupported_protocol_version`." } ], "responses": { "200": { "description": "Server-sent protocol events", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/UHPEvent" } } } }, "default": { "description": "UHP protocol error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "x-sdk-base-path": "/uhp/v1", "x-sdk-stream": true, "summary": "Stream or resume the events of a response", "servers": [ { "url": "https://api.cloud.beeos.ai/uhp/v1" } ] } } }, "components": { "schemas": { "ExternalUserID": { "type": "string", "minLength": 1, "maxLength": 128, "not": { "enum": [ ".", ".." ] }, "description": "Opaque App-local identifier. Exact dot-segment values '.' and '..' are reserved by T03-20260905-01." }, "ClientSessionInput": { "type": "object", "required": [ "client_type", "requested_capabilities" ], "additionalProperties": false, "properties": { "client_type": { "enum": [ "web", "native" ], "description": "How the client token is bound to the client that will use it. It decides whether you send `origin` or `device_attestation`.", "x-enumDescriptions": { "web": "A browser client. The token is bound to the page origin you send in `origin`, which must be one of the allowed origins configured for the app. `device_attestation` must not be sent. A request that does not match this binding returns 403 `invalid_origin`.", "native": "A native app. The token is bound to a device key whose thumbprint you send in `device_attestation.jkt`. `origin` must not be sent. A request that does not match this binding returns 403 `invalid_origin`." } }, "requested_capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Operations the client token may perform on the Client API, 1 or more distinct names. Each name must be one of `context:read`, `instances:read`, `instances:write`, `agents:read`, `agents:invoke`, `files:read`, `files:write`, `files:delete`, `events:read`, `viewer:connect` and `terminal:connect`, and must be allowed for your app's clients. Any other name returns 403 `invalid_capability`." }, "origin": { "type": "string", "format": "uri", "description": "Origin of the web page that will use the token, for example `https://app.example.com`. Required when `client_type` is `web`, and it must exactly match one of the allowed origins configured for the app; otherwise the request returns 403 `invalid_origin`. Not allowed when `client_type` is `native`, which also returns 403 `invalid_origin`." }, "device_attestation": { "type": "object", "required": [ "jkt" ], "properties": { "jkt": { "type": "string", "minLength": 16, "description": "Thumbprint of the device's public key, the base64url-encoded SHA-256 JWK thumbprint, at least 16 characters. Later Client API requests must be signed with the matching private key." } }, "additionalProperties": false, "description": "Proof of the device key the token is bound to. Required when `client_type` is `native`; not allowed when `client_type` is `web`, which returns 403 `invalid_origin`." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 1800, "default": 600, "description": "Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request." } }, "x-variants": { "property": "client_type", "mapping": { "web": { "$ref": "#/components/x-variantSchemas/ClientSessionInputWeb" }, "native": { "$ref": "#/components/x-variantSchemas/ClientSessionInputNative" } } } }, "Binding": { "type": "object", "required": [ "client_type" ], "properties": { "client_type": { "enum": [ "web", "native" ], "description": "How the token is bound to the client.", "x-enumDescriptions": { "web": "Bound to a web page origin, returned in `origin`.", "native": "Bound to a device key, whose thumbprint is returned in `cnf_jkt`." } }, "origin": { "type": "string", "format": "uri", "description": "Origin the token is bound to. Returned when `client_type` is `web`." }, "cnf_jkt": { "type": "string", "description": "Thumbprint of the device key the token is bound to. Returned when `client_type` is `native`." } }, "x-variants": { "property": "client_type", "mapping": { "web": { "$ref": "#/components/x-variantSchemas/BindingWeb" }, "native": { "$ref": "#/components/x-variantSchemas/BindingNative" } } } }, "ClientSessionResponse": { "type": "object", "required": [ "access_token", "client_api_url", "expires_at", "session_id", "app_id", "external_user_id", "capabilities", "binding" ], "properties": { "access_token": { "type": "string", "writeOnly": true, "description": "Client token to send as the bearer credential to the Client API. It is shown only in this response, so store it securely on the client and never log it." }, "client_api_url": { "description": "Base URL of the Client API that accepts `access_token`.", "x-enumDescriptions": { "https://client-api.cloud.beeos.ai/v1": "The production Client API." }, "enum": [ "https://client-api.cloud.beeos.ai/v1" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Actual expiration of the issued token, capped by the remaining session authorization lifetime." }, "session_id": { "type": "string", "description": "ID of the client session. Use it to refresh or revoke the session. Refreshing issues a new token for the same session." }, "app_id": { "type": "string", "description": "ID of the app the session belongs to." }, "external_user_id": { "type": "string", "description": "Unused. Cloud does not accept an external user id. Stored sessions leave this empty." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Operations the token may perform on the Client API. They are the requested capabilities, without duplicates." }, "binding": { "$ref": "#/components/schemas/Binding", "description": "How the token is bound to the client, as requested when the session was created." } } }, "DeletionAccepted": { "type": "object", "required": [ "deletion_id", "status" ], "properties": { "deletion_id": { "type": "string", "description": "ID of the deletion. Use it to read the progress of the deletion." }, "status": { "enum": [ "pending", "processing", "failed", "completed" ], "description": "State of the deletion when the request was accepted.", "x-enumDescriptions": { "pending": "The deletion is queued and has not started.", "processing": "The deletion is running.", "failed": "The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically.", "completed": "All data of the user was deleted." } } } }, "Deletion": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deletion." }, "status": { "type": "string", "description": "State of the deletion. Poll until it is `completed`.", "x-enumDescriptions": { "pending": "The deletion is queued and has not started.", "processing": "The deletion is running.", "failed": "The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically.", "completed": "All data of the user was deleted." } }, "deleted_resources": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Number of items deleted so far, as an object that maps a kind of data to a count. The counts are final when `status` is `completed`. Kinds can be added, so do not depend on a fixed set of keys." } }, "required": [ "id", "status", "deleted_resources" ], "additionalProperties": false }, "Provider": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "ID of the provider." }, "name": { "type": "string", "description": "Display name of the provider." }, "description": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/ProviderCapabilities" } } }, "DeployRegion": { "type": "object", "required": [ "id", "name", "available" ], "properties": { "id": { "type": "string", "description": "ID of the region." }, "name": { "type": "string", "description": "Display name of the region." }, "available": { "type": "boolean", "description": "Whether the region is currently available." } } }, "DeployModel": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "ID of the model, usually in `provider/model` form." }, "name": { "type": "string", "description": "Display name of the model." }, "tier": { "type": "string" }, "reasoning": { "type": "boolean" }, "input": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer", "description": "Maximum context window of the model, in tokens." } } }, "InstanceTemplate": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "ID of the template." }, "name": { "type": "string", "description": "Display name of the template." }, "description": { "type": "string", "description": "Description of the template." }, "logo_url": { "type": "string" }, "sort_order": { "type": "integer" }, "harness": { "type": "string" }, "provider_id": { "type": "string" }, "specs": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSpec" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogVariant" }, "description": "Deployable variants of the template. Send a variant's `id` as `variant_id` when creating an instance." } } }, "ProviderPage": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" }, "description": "Providers that match the filters." }, "total": { "type": "integer", "description": "Number of providers that match the filters." } } }, "RegionPage": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeployRegion" }, "description": "Regions that match the filters." }, "total": { "type": "integer", "description": "Number of regions that match the filters." } } }, "ModelPage": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeployModel" }, "description": "Models that match the filters." }, "total": { "type": "integer", "description": "Number of models that match the filters." } } }, "InstanceSummary": { "type": "object", "additionalProperties": false, "required": [ "has_ever_run", "id", "organization_id", "app_id", "developer_id", "name", "harness", "provider_id", "region", "os_type", "status", "desired_status", "connectivity", "ms_connection_status", "created_at", "updated_at", "resource_version" ], "properties": { "has_ever_run": { "type": "boolean", "description": "Whether the instance has ever reached the running state. False means it has never delivered a running service." }, "id": { "type": "string", "description": "Unique ID of the instance." }, "organization_id": { "type": "string", "description": "ID of the organization that owns the instance." }, "app_id": { "type": "string", "description": "ID of the app the instance belongs to." }, "developer_id": { "type": "string", "description": "ID of the developer account the instance was created under." }, "name": { "type": "string", "description": "Display name of the instance." }, "harness": { "type": "string", "description": "Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`)." }, "provider_id": { "type": "string", "description": "ID of the provider that hosts the instance." }, "region": { "type": "string", "description": "Region the instance is deployed in." }, "os_type": { "type": "string", "description": "Operating system of the instance: `linux`, `windows`, `android` or `macos`." }, "status": { "type": "string", "description": "Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "pending": "The instance was created and is waiting to be provisioned.", "provisioning": "The instance is being provisioned or started.", "running": "The instance is running.", "stopped": "The instance is stopped and can be started again.", "terminated": "The instance was deleted and cannot be used again." } }, "desired_status": { "type": "string", "description": "Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "running": "The instance should be running.", "stopped": "The instance should be stopped.", "terminated": "The instance should be deleted." } }, "connectivity": { "type": "string", "description": "Reachability of the instance's agent: `unknown`, `online` or `offline`.", "x-enumDescriptions": { "unknown": "Reachability has not been determined.", "online": "The instance's agent is connected.", "offline": "The instance's agent is not connected." } }, "ms_connection_status": { "type": "string", "description": "Status of the instance's message-channel connection: `unknown`, `connecting`, `connected`, `reconnecting`, `disconnected` or `failed`. It is reported independently of connectivity and is `unknown` while the instance is stopped or terminated, or has not reported recently." }, "created_at": { "type": "string", "description": "Time the instance was created, as an RFC 3339 UTC timestamp." }, "updated_at": { "type": "string", "description": "Time the instance was last updated, as an RFC 3339 UTC timestamp." }, "resource_version": { "type": "integer", "format": "int64", "minimum": 1, "description": "Version of the instance record, starting at 1. Send it in the `If-Match` header of write requests so concurrent changes are detected." }, "image_slot": { "type": "string", "description": "Variant trait. Key that selects the execution image for the instance. Not a container repository name." }, "worker_image_id": { "type": "string", "description": "Variant trait. AgentBay worker image. Never the platform `image_id`." }, "model_catalog": { "type": "string", "description": "Variant trait. `served` when Cloud answers model-list and reasoning-level requests, `none` when it answers neither. Empty and unknown values behave as `none`." }, "billing_slot": { "type": "string", "description": "Variant trait. Key into the monthly fee table that prices the instance." }, "icon_key": { "type": "string", "description": "Variant trait. UI icon selector. Clients must not derive it from `harness`." }, "device_control": { "type": "boolean", "description": "Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected." }, "runtime_profile": { "type": "string", "description": "Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`." }, "free_plan": { "type": "boolean", "description": "Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it." }, "cloud_provider": { "type": "string", "description": "`agentbay`, `beeos`, or empty when self-hosted." } } }, "InstancePage": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceSummary" }, "description": "Instances on this page, newest first." }, "total": { "type": "integer", "description": "Total number of instances that match the filters, across all pages." } } }, "ProviderCapabilities": { "type": "object", "properties": { "long_running": { "type": "boolean" }, "browser_use": { "type": "boolean" }, "code_exec": { "type": "boolean" }, "file_system": { "type": "boolean" }, "custom_image": { "type": "boolean" }, "device": { "type": "boolean" }, "max_duration_sec": { "type": "integer" }, "cost_model": { "type": "string" } }, "required": [ "long_running", "browser_use", "code_exec", "file_system", "custom_image", "device", "max_duration_sec", "cost_model" ], "additionalProperties": false }, "CatalogSpecValue": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "sort_order": { "type": "integer" } }, "required": [ "id", "name", "label", "sort_order" ], "additionalProperties": false }, "CatalogSpec": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSpecValue" } } }, "required": [ "id", "name", "label", "values" ], "additionalProperties": false }, "CatalogVariant": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the variant. Send it as `variant_id` when creating an instance." }, "spec_value_ids": { "type": "array", "items": { "type": "string" } }, "sort_order": { "type": "integer" } }, "required": [ "id", "spec_value_ids", "sort_order" ], "additionalProperties": false }, "InstanceTemplatePage": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceTemplate" }, "description": "Templates on the requested page." }, "total": { "type": "integer", "description": "Total number of templates that match the filters, across all pages." } } }, "AgentSnapshot": { "type": "object", "additionalProperties": false, "required": [ "id", "instance_id", "name", "description", "status", "visibility", "conversation_transport", "resource_version", "mcp_enabled", "a2a_enabled", "capabilities", "skills", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "ID of the agent." }, "instance_id": { "type": "string", "description": "ID of the instance the agent runs on." }, "name": { "type": "string", "description": "Name of the agent." }, "display_name": { "type": "string", "description": "Human-readable name of the agent. Omitted when none is set." }, "description": { "type": "string", "description": "Description of the agent. Empty when none is set." }, "status": { "type": "string", "description": "Whether the agent is currently provided by its instance.", "x-enumDescriptions": { "active": "The instance currently provides the agent.", "inactive": "The instance no longer provides the agent, for example because it was removed or replaced by another agent with the same name. The record is kept." } }, "visibility": { "type": "string", "description": "Which callers other than the owner can use the agent. Change it with the update operation.", "x-enumDescriptions": { "private": "Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.", "unlisted": "Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.", "org": "Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.", "public": "Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.", "marketplace": "The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID." } }, "conversation_transport": { "type": "string", "description": "How conversation messages reach the agent. New values can be added, so ignore values you do not know.", "x-enumDescriptions": { "acp": "Conversation messages are exchanged with the agent over its ACP connection.", "message-service": "Conversation messages are delivered to the agent as messages through BeeOS messaging." } }, "resource_version": { "type": "integer", "format": "int64", "minimum": 1, "description": "Version of the agent to send as `If-Match`, in double quotes, when you update it. The same value is returned in the `ETag` header when you read or update a single agent." }, "mcp_enabled": { "type": "boolean", "description": "Whether the agent is published as a tool through BeeOS MCP endpoints." }, "a2a_enabled": { "type": "boolean", "description": "Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`." }, "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Features the agent supports, as an object that maps a feature name to true or false. Known names include `canvas`, `terminal`, `webSsh`, `fileSystem`, `image`, `audio`, `mcp`, `cron`, `streaming`, `pushNotifications`, `a2a`, `extendedAgentCard`, `multipleConversations`, `loadConversation`, `createConversation`, `modelsList`, `modelsSet`, `skillsList`, `skillsInstall`, `skillsUninstall`, `skillsUpdate` and `automationWake`. A name that is absent or false means the agent does not support the feature. New names can be added, so ignore names you do not know." }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkill" }, "description": "Skills of the agent." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the agent was created, in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the agent was last changed, in RFC 3339 format." } } }, "AgentSkill": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the skill. Empty when the instance did not report one." }, "name": { "type": "string", "description": "Name of the skill." }, "description": { "type": "string", "description": "What the skill does." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags that describe the skill. Empty when there are none." }, "enabled": { "type": "boolean", "description": "Whether the skill is currently enabled for the agent." } }, "required": [ "id", "name", "description", "tags", "enabled" ], "additionalProperties": false }, "AgentPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "visibility": { "type": "string", "enum": [ "private", "unlisted", "org", "public", "marketplace" ], "description": "New visibility of the agent. The values are described on the `visibility` field of the agent.", "x-enumDescriptions": { "private": "Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.", "unlisted": "Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.", "org": "Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.", "public": "Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.", "marketplace": "The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID." } }, "mcp_enabled": { "type": "boolean", "description": "Set to true to publish the agent as a tool through BeeOS MCP endpoints, or to false to stop publishing it." }, "a2a_enabled": { "type": "boolean", "description": "Set to true to let the agent accept Agent-to-Agent (A2A) requests, or to false to refuse them with 403 `a2a_disabled`." } }, "description": "Exposure settings to change. Send at least one field; fields you omit keep their current value." }, "AgentResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentSnapshot", "description": "The agent." } } }, "AgentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAgent" }, "description": "Agents on this page, newest first." }, "total": { "type": "integer", "description": "Total number of agents that match the filters, across all pages." } }, "required": [ "data", "total" ], "additionalProperties": false }, "CreateConversationInput": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 256, "description": "Title of the new conversation, at most 512 bytes of valid UTF-8. Omit it to create a conversation without a title." } } }, "Conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "agent_id", "instance_id", "title", "state", "metadata_version", "history_generation", "created_at", "resource_version" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the conversation." }, "agent_id": { "type": "string", "minLength": 1, "description": "ID of the agent the conversation is with, the `id` returned by the agents API." }, "instance_id": { "type": "string", "minLength": 1, "description": "ID of the instance the agent runs on." }, "title": { "type": "string", "description": "Title of the conversation. Empty when no title was set." }, "state": { "type": "string", "enum": [ "open", "closed" ], "description": "Whether the conversation still accepts messages. A closed conversation stays readable but cannot receive new messages.", "x-enumDescriptions": { "open": "The conversation accepts new messages.", "closed": "The conversation was closed, for example by deleting it. `closed_at` is set, and sending to it returns 410 `conversation_closed`." } }, "metadata_version": { "type": "integer", "format": "int64", "minimum": 1, "description": "Version of the conversation settings (title, model override, reasoning and approval mode). It increases by one on every change. It always equals `resource_version`." }, "history_generation": { "type": "integer", "format": "int64", "minimum": 0, "description": "Generation of the conversation history. It increases by one each time the history is cleared, so a larger value means messages sent before the latest clear are no longer part of the history." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the conversation was created, in RFC 3339 format." }, "last_activity_at": { "type": "string", "format": "date-time", "description": "Time of the latest activity in the conversation, in RFC 3339 format. Omitted when no activity is recorded." }, "closed_at": { "type": "string", "format": "date-time", "description": "Time the conversation was closed, in RFC 3339 format. Omitted while the conversation is open." }, "resource_version": { "type": "integer", "format": "int64", "minimum": 1, "description": "Version of the conversation to send as `If-Match`, in double quotes, when you rename it or change its model, reasoning or approval mode. The same value is returned in the `ETag` header when you read or update a single conversation." }, "model_override_id": { "type": "string", "description": "ID of the model that overrides the agent's default model for this conversation. Omitted when no override is set." }, "effective_model_id": { "type": "string", "description": "Reserved. The Server API does not currently return this field; use `model_override_id`." }, "active_response": { "$ref": "#/components/schemas/ActiveConversationResponse", "description": "The response that is currently being produced in the conversation. Returned only when you read a single conversation, and only while a response is in progress." }, "reasoning": { "$ref": "#/components/schemas/ReasoningSettings", "description": "Reasoning selection set for the conversation: the model and the reasoning option chosen for it. Omitted when none is set. It is cleared when `model_override_id` changes." }, "approval_mode": { "anyOf": [ { "type": "string", "description": "Approval mode set for the conversation. Omitted when none is set and the instance default applies." }, { "type": "null" } ] } } }, "ConversationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversation", "description": "The conversation." } } }, "ConversationPage": { "type": "object", "required": [ "conversations", "has_more" ], "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "Conversations on this page." }, "next_cursor": { "type": "string", "description": "Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false." }, "has_more": { "type": "boolean", "description": "Whether more conversations are available after this page." } } }, "Message": { "type": "object", "required": [ "id", "conversation_id", "type", "content", "sender", "created_at", "offset", "history_generation" ], "properties": { "id": { "type": "string", "description": "ID of the message." }, "conversation_id": { "type": "string", "description": "ID of the conversation the message belongs to." }, "type": { "type": "string", "description": "Kind of the message. Use it to tell the caller's prompts from the agent's replies and other messages. New kinds can be added, so ignore values you do not know.", "x-enumDescriptions": { "chat_message": "A prompt sent by the caller to the agent.", "agent_reply": "The agent's reply to a `chat_message`. While `state` is `streaming` the reply is still being written and `body` holds the text produced so far.", "agent_reply_error": "An error reply from the agent, sent as its own message kind instead of an `agent_reply` that carries an error.", "agent.refuse": "The agent declined to handle the message. `content` holds a `reason`, for example `agent_busy` when the agent was already working on another turn, and a readable `message`.", "agent_busy": "Older name of `agent.refuse`, still sent by some agent runtimes. Treat it the same way.", "agent_reply_delta": "A chunk of an agent reply that is still being produced.", "agent_reasoning": "The agent's reasoning (\"thinking\") text. It is stored as its own message next to the `agent_reply` it belongs to, with the same `reply_to`, and the reasoning text is in `body`. It is never the final answer.", "a2a_status_update": "A status change of an Agent-to-Agent (A2A) task.", "a2a_result": "The final outcome of an A2A task, sent when the task completes or cannot be dispatched.", "agent_request": "The task request delivered to an agent for an A2A task.", "a2a_task": "The first message of an A2A task, published when the task is dispatched in queue mode.", "chat_cancel": "A request to stop the agent's turn for an earlier `chat_message`. `content` holds `target_message_id` and an optional `reason`.", "device_command": "One tool call for controlling a device or computer, such as a screenshot, click or typing. The agent runs it on the device without a model turn.", "device_result": "The successful result of a `device_command`. `reply_to` is the ID of the command.", "device_error": "The failure of a `device_command`. `content` holds `error` and `code`." } }, "content": { "description": "Payload of the message as JSON. Its structure depends on `type`; see the variants listed for this field. For current agent replies read `body` and `parts` instead. The server removes the `metadata` and `from` keys before returning it.", "x-variants": { "sibling": "Message.type", "mapping": { "chat_message": { "$ref": "#/components/x-variantSchemas/MessageContentChatMessage" }, "agent_reply": { "$ref": "#/components/x-variantSchemas/MessageContentAgentReply" }, "agent_reply_error": { "$ref": "#/components/x-variantSchemas/MessageContentAgentReply" }, "agent.refuse": { "$ref": "#/components/x-variantSchemas/MessageContentAgentRefuse" }, "agent_busy": { "$ref": "#/components/x-variantSchemas/MessageContentAgentRefuse" }, "chat_cancel": { "$ref": "#/components/x-variantSchemas/MessageContentChatCancel" }, "device_command": { "$ref": "#/components/x-variantSchemas/MessageContentDeviceCommand" }, "device_error": { "$ref": "#/components/x-variantSchemas/MessageContentDeviceError" } } } }, "sender": { "type": "string", "description": "Identity that sent the message. Other senders appear as their own identity ID." }, "reply_to": { "type": "string", "description": "ID of the message this message replies to, for example the `chat_message` an `agent_reply` answers. Omitted for messages that are not replies." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the message was created, in RFC 3339 format." }, "offset": { "type": "integer", "format": "int64", "description": "Position of the message in the conversation history. Newer messages have larger offsets." }, "history_generation": { "type": "integer", "format": "int64", "description": "Generation of the conversation history the message belongs to." }, "state": { "type": "string", "description": "Lifecycle state of the message. A message starts as `streaming` and moves exactly once to one of the final states; a final message never changes again. Messages stored before states existed have an empty state and are final.", "x-enumDescriptions": { "streaming": "The message is still being written. `body` and `parts` can still change.", "completed": "The message was finished normally.", "failed": "The agent failed to finish the message.", "refused": "The agent refused to answer. `body` holds the refusal text.", "cancelled": "The message was stopped on request before it finished." } }, "stop_reason": { "type": "string", "description": "Why the message reached a final state. Present only on final messages and can be empty when the reason is unknown.", "x-enumDescriptions": { "end_turn": "The agent finished its turn normally.", "max_tokens": "The output limit was reached before the agent finished.", "tool_use": "The agent stopped to call a tool.", "user_stop": "The user stopped the agent.", "timeout": "The time limit was reached before the agent finished.", "error": "The agent stopped because of an error.", "refused": "The agent refused to answer.", "content_filter": "The reply was stopped by a content filter.", "agent_lost": "The server ended the message because the agent that was producing it is no longer running, for example because it crashed or was replaced." } }, "body": { "type": "string", "description": "Text of the message. For a reply that is still `streaming` it is the text produced so far." }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "x-variants": { "property": "type", "mapping": { "text": { "$ref": "#/components/x-variantSchemas/MessagePartText" }, "thinking": { "$ref": "#/components/x-variantSchemas/MessagePartThinking" }, "tool_use": { "$ref": "#/components/x-variantSchemas/MessagePartToolUse" }, "tool_result": { "$ref": "#/components/x-variantSchemas/MessagePartToolResult" }, "file": { "$ref": "#/components/x-variantSchemas/MessagePartFile" }, "source": { "$ref": "#/components/x-variantSchemas/MessagePartSource" }, "custom": { "$ref": "#/components/x-variantSchemas/MessagePartCustom" } } } }, "description": "Structured parts of the message in order, such as reasoning, tool calls, files and sources. Each part has a `type`; see the variants listed for the items of this field." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the message was last changed, in RFC 3339 format. Omitted when the message was never updated." }, "runtime_dispatch": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Result of handing the message to the agent runtime, as an object with `status` and `code`. Present only when a dispatch result is recorded for the message; otherwise omitted." }, "realtime_publish_status": { "type": "string", "enum": [ "published", "unconfirmed", "not_republished" ], "description": "Reserved. The Server API does not currently return this field." } } }, "MessagePage": { "type": "object", "required": [ "messages", "has_more", "latest_offset", "history_generation", "history_boundary_offset" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Messages on this page." }, "next_cursor": { "type": "string", "description": "Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false." }, "has_more": { "type": "boolean", "description": "Whether more messages are available after this page." }, "latest_offset": { "type": "integer", "format": "int64", "description": "Upper bound of the offsets scanned for this page. It is not the history boundary; use `history_boundary_offset` for that." }, "history_generation": { "type": "integer", "format": "int64", "description": "Generation of the conversation history this page was read from." }, "history_boundary_offset": { "type": "integer", "format": "int64", "description": "Offset of the history boundary for the current generation: the point a clear or recovery of the history moved the start of the history to." } } }, "MessageEnvelope": { "type": "object", "required": [ "id", "conversation_id", "type", "sender", "body", "state" ], "properties": { "id": { "type": "string", "description": "ID of the message." }, "conversation_id": { "type": "string", "description": "ID of the conversation the message belongs to." }, "type": { "type": "string", "description": "Kind of the message. Use it to tell the caller's prompts from the agent's replies and other messages. New kinds can be added, so ignore values you do not know.", "x-enumDescriptions": { "chat_message": "A prompt sent by the caller to the agent.", "agent_reply": "The agent's reply to a `chat_message`. While `state` is `streaming` the reply is still being written and `body` holds the text produced so far.", "agent_reply_error": "An error reply from the agent, sent as its own message kind instead of an `agent_reply` that carries an error.", "agent.refuse": "The agent declined to handle the message. `content` holds a `reason`, for example `agent_busy` when the agent was already working on another turn, and a readable `message`.", "agent_busy": "Older name of `agent.refuse`, still sent by some agent runtimes. Treat it the same way.", "agent_reply_delta": "A chunk of an agent reply that is still being produced.", "agent_reasoning": "The agent's reasoning (\"thinking\") text. It is stored as its own message next to the `agent_reply` it belongs to, with the same `reply_to`, and the reasoning text is in `body`. It is never the final answer.", "a2a_status_update": "A status change of an Agent-to-Agent (A2A) task.", "a2a_result": "The final outcome of an A2A task, sent when the task completes or cannot be dispatched.", "agent_request": "The task request delivered to an agent for an A2A task.", "a2a_task": "The first message of an A2A task, published when the task is dispatched in queue mode.", "chat_cancel": "A request to stop the agent's turn for an earlier `chat_message`. `content` holds `target_message_id` and an optional `reason`.", "device_command": "One tool call for controlling a device or computer, such as a screenshot, click or typing. The agent runs it on the device without a model turn.", "device_result": "The successful result of a `device_command`. `reply_to` is the ID of the command.", "device_error": "The failure of a `device_command`. `content` holds `error` and `code`." } }, "sender": { "type": "string", "description": "Identity that sent the message. Other senders appear as their own identity ID." }, "reply_to": { "type": "string", "description": "ID of the message this message replies to, for example the `chat_message` an `agent_reply` answers. Omitted for messages that are not replies." }, "body": { "type": "string", "description": "Text of the message. For a reply that is still `streaming` it is the text produced so far." }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "x-variants": { "property": "type", "mapping": { "text": { "$ref": "#/components/x-variantSchemas/MessagePartText" }, "thinking": { "$ref": "#/components/x-variantSchemas/MessagePartThinking" }, "tool_use": { "$ref": "#/components/x-variantSchemas/MessagePartToolUse" }, "tool_result": { "$ref": "#/components/x-variantSchemas/MessagePartToolResult" }, "file": { "$ref": "#/components/x-variantSchemas/MessagePartFile" }, "source": { "$ref": "#/components/x-variantSchemas/MessagePartSource" }, "custom": { "$ref": "#/components/x-variantSchemas/MessagePartCustom" } } } }, "description": "Structured parts of the message in order, such as reasoning, tool calls, files and sources. Each part has a `type`; see the variants listed for the items of this field." }, "state": { "type": "string", "description": "Lifecycle state of the message. A message starts as `streaming` and moves exactly once to one of the final states; a final message never changes again. Messages stored before states existed have an empty state and are final.", "x-enumDescriptions": { "streaming": "The message is still being written. `body` and `parts` can still change.", "completed": "The message was finished normally.", "failed": "The agent failed to finish the message.", "refused": "The agent refused to answer. `body` holds the refusal text.", "cancelled": "The message was stopped on request before it finished." } }, "stop_reason": { "type": "string", "description": "Why the message reached a final state. Present only on final messages and can be empty when the reason is unknown.", "x-enumDescriptions": { "end_turn": "The agent finished its turn normally.", "max_tokens": "The output limit was reached before the agent finished.", "tool_use": "The agent stopped to call a tool.", "user_stop": "The user stopped the agent.", "timeout": "The time limit was reached before the agent finished.", "error": "The agent stopped because of an error.", "refused": "The agent refused to answer.", "content_filter": "The reply was stopped by a content filter.", "agent_lost": "The server ended the message because the agent that was producing it is no longer running, for example because it crashed or was replaced." } }, "content": { "description": "Reserved. The Server API does not currently return this field; read `body` and `parts`." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the message was created, in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the message was last changed, in RFC 3339 format. Omitted when the message was never updated." } } }, "MessageEnvelopeResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MessageEnvelope", "description": "The message." } } }, "UpdateConversationInput": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 256, "description": "New title of the conversation, 1 to 256 characters after leading and trailing whitespace is removed." } } }, "CancelConversationInput": { "type": "object", "additionalProperties": false, "required": [ "target_message_id" ], "properties": { "target_message_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "ID of the `chat_message` whose turn should stop, 1 to 256 characters." }, "reason": { "type": "string", "maxLength": 256, "description": "Why the turn is stopped, as free text of at most 256 characters. When it is omitted or empty, `user_request` is recorded." } } }, "SetConversationModelInput": { "type": "object", "additionalProperties": false, "required": [ "model_override_id" ], "properties": { "model_override_id": { "anyOf": [ { "type": "string", "maxLength": 512, "description": "ID of the model to use for this conversation, at most 512 characters. Send `null` to remove the override so the agent's default model is used again. When the override changes, the conversation's `reasoning` is cleared." }, { "type": "null" } ] } } }, "CommandReceipt": { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "description": "ID of the request. For cancel and resume it identifies the control message that was sent to the agent; for a model change it is the ID of this HTTP request." }, "status": { "type": "string", "description": "Outcome of the request at the time the call returned.", "x-enumDescriptions": { "accepted": "The request was queued for the agent and has not taken effect yet. Read the conversation messages to follow the result.", "completed": "The change was applied before the call returned." } } } }, "CommandReceiptResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CommandReceipt", "description": "The receipt of the request." } } }, "ClearConversationReceipt": { "type": "object", "additionalProperties": false, "required": [ "request_id", "conversation_id", "current_generation", "status" ], "properties": { "request_id": { "type": "string", "description": "ID of the clear operation. Retrying with the same `Idempotency-Key` returns the same ID." }, "conversation_id": { "type": "string", "description": "ID of the conversation that was cleared." }, "current_generation": { "type": "integer", "format": "int64", "minimum": 0, "description": "History generation after the clear. Messages from earlier generations are no longer part of the conversation history." }, "status": { "type": "string", "description": "Outcome of the clear at the time the call returned.", "x-enumDescriptions": { "completed": "The history was cleared before the call returned." } } } }, "ClearConversationReceiptResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ClearConversationReceipt", "description": "The receipt of the clear operation." } } }, "ActiveConversationResponse": { "type": "object", "additionalProperties": false, "required": [ "response_id", "last_event_id" ], "properties": { "response_id": { "type": "string", "description": "ID of the response being produced. Use it with the responses API." }, "last_event_id": { "type": "string", "description": "ID of the latest event recorded for the response. Send it as `Last-Event-ID` to continue the response's event stream after that event." }, "user_message_id": { "type": "string", "description": "ID of the `chat_message` that started the response. Omitted when it is not recorded." }, "reply_message_id": { "type": "string", "description": "ID of the message the agent's reply is written to. Omitted until the reply message exists." } } }, "ReasoningSettings": { "type": "object", "additionalProperties": false, "required": [ "modelId", "reasoningOverrideId" ], "properties": { "modelId": { "type": "string", "minLength": 1, "maxLength": 512, "description": "ID of the model that `reasoningOverrideId` applies to, 1 to 512 characters." }, "reasoningOverrideId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "description": "ID of the reasoning option to use with the model, 1 to 64 characters. Send `null` to use the model's default." }, { "type": "null" } ] } } }, "ReasoningResult": { "type": "object", "properties": { "metadata_version": { "type": "integer", "description": "Version of the conversation settings after this change. Send it, in double quotes, as `If-Match` of the next update. It is also returned in the `ETag` header." } }, "required": [ "metadata_version" ], "additionalProperties": false }, "ReasoningResultResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReasoningResult", "description": "The result of the change." } } }, "ApprovalModeSettings": { "type": "object", "additionalProperties": false, "required": [ "approval_mode" ], "properties": { "approval_mode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z][a-z0-9_]*$", "description": "Approval mode to set for the conversation: lowercase letters, digits and underscores, starting with a letter, at most 32 characters. `ask` and `full` are the modes defined so far. New modes can be added, and an agent treats a mode it does not know as `ask`. Send `null` to remove the setting so the instance default applies." }, { "type": "null" } ] } } }, "ApprovalModeResult": { "type": "object", "additionalProperties": false, "required": [ "approval_mode", "metadata_version", "status" ], "properties": { "approval_mode": { "anyOf": [ { "type": "string", "description": "Approval mode now in effect for the conversation. `null` means the instance default applies." }, { "type": "null" } ] }, "metadata_version": { "type": "integer", "format": "int64", "minimum": 1, "description": "Version of the conversation settings after this change. Send it, in double quotes, as `If-Match` of the next update. It is also returned in the `ETag` header." }, "status": { "type": "string", "description": "Outcome of the change at the time the call returned.", "x-enumDescriptions": { "completed": "The approval mode was changed before the call returned." } } } }, "ApprovalModeResultResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalModeResult", "description": "The result of the change." } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code, for example `invalid_request`, `version_mismatch` or `instance_not_found`." }, "message": { "type": "string", "description": "Human-readable description of the error. Use `code`, not this text, to branch in code." }, "request_id": { "type": "string", "description": "ID of the request, for support and tracing." } }, "required": [ "code", "message", "request_id" ], "additionalProperties": false }, "UHPDiscovery": { "type": "object", "required": [ "object", "protocol", "versions", "default_version", "conformance_class", "capabilities" ], "properties": { "object": { "type": "string", "description": "Object type: always `uhp.discovery`.", "x-enumDescriptions": { "uhp.discovery": "A protocol discovery document." }, "enum": [ "uhp.discovery" ] }, "protocol": { "type": "string", "description": "Protocol the server speaks: always `uhp`, the Unified Harness Protocol.", "x-enumDescriptions": { "uhp": "The Unified Harness Protocol." }, "enum": [ "uhp" ] }, "versions": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Protocol versions the server speaks, as values of the `UHP-Version` header." }, "default_version": { "type": "string", "description": "Protocol version the server uses when a request does not send a `UHP-Version` header." }, "conformance_class": { "type": "string", "enum": [ "core", "extended", "full" ], "description": "Coarse conformance class of the server. Branch on the flags in `capabilities`, which are exact, rather than on the class.", "x-enumDescriptions": { "core": "Discovery, harness reads, tasks and sessions.", "extended": "Core plus file input and artifact retrieval.", "full": "Extended plus harness management, plugins, environments and memories." } }, "capabilities": { "$ref": "#/components/schemas/UHPCapabilities", "description": "What the server can do. A flag is `true` only when the endpoints behind it answer." }, "plugin_schemas": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "The Agent Plugins manifest schema identifiers this server installs. Present and non-empty\nwhen `capabilities.plugins` is true.\n", "examples": [ [ "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" ] ] }, "implementation": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the server implementation: `BeeOS Cloud`." }, "version": { "type": "string", "description": "Version of the server implementation. Omitted when it is not known." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Information about the server. Besides `name` and `version` it may carry `availability`, a statement of how model availability is computed." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPCapabilities": { "type": "object", "description": "Named booleans. A server reports `false` for a capability it does not implement rather than\nomitting it, so a client can distinguish \"not supported\" from \"server predates this field\".\nA client treats an absent key as `false`.\n", "properties": { "streaming": { "type": "boolean", "description": "The server can stream a response as server-sent events." }, "sessions": { "type": "boolean", "description": "The server keeps sessions that later requests can continue." }, "cancellation": { "type": "boolean", "description": "A running response can be cancelled." }, "files_input": { "type": "boolean", "description": "The server accepts files as input to a request." }, "files_output": { "type": "boolean", "description": "The server returns files that a harness produced." }, "session_listing": { "type": "boolean", "description": "The server can list existing sessions." }, "harness_management": { "type": "boolean", "description": "Harnesses can be created, updated and deleted through the API." }, "session_sharing": { "type": "boolean", "description": "The server can share a session with other callers." }, "idempotency": { "type": "boolean", "description": "The server honors the `Idempotency-Key` header on the writes that accept it." }, "plugins": { "type": "boolean", "description": "The server installs Agent Plugins packages into harnesses, serves their files, and exports\na harness as a package. Optional at every class.\n" }, "environments": { "type": "boolean", "description": "The server holds environments: a project's files and installed dependencies, built once,\nread-only at a fixed path in every session that names one. Optional at every class.\n" }, "memories": { "type": "boolean", "description": "The server holds memories: a tree of memories with access granted per node, records kept\nby a connected provider, and tools a harness's agent reaches them with. Optional at every class.\n" } }, "additionalProperties": { "type": "boolean" } }, "UHPHarness": { "type": "object", "required": [ "id", "name", "base" ], "properties": { "id": { "type": "string", "pattern": "^chrn_", "description": "ID of the harness. It starts with `chrn_` and is the `harness_id` to use in other requests." }, "object": { "type": "string", "description": "Object type: always `harness`.", "x-enumDescriptions": { "harness": "A harness object." }, "enum": [ "harness" ] }, "name": { "type": "string", "description": "Display name of the harness. When the harness has no display name, its name is used, and then its ID." }, "base": { "type": "string", "description": "Opaque. Not enumerated by this specification — a client must treat it as a string, or the\nprotocol would need revising every time a harness is released.\n", "examples": [ "codex", "claude-code", "hermes" ] }, "baseLabel": { "type": "string", "description": "Human-readable name of `base`: `OpenClaw` for `openclaw` or `Hermes` for `hermes`. Omitted when the base has no known label." }, "defaultModel": { "type": "string", "description": "ID of the model the harness uses as its primary model. Omitted when it has none." }, "systemPrompt": { "type": "string", "description": "System prompt of the harness. BeeOS Cloud does not support it, so it is never returned." }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/UHPMcpServer" }, "description": "MCP servers attached to the harness. Returned only by a single-harness read while the instance is running, and only when the instance supports MCP servers; omitted in listings." }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/UHPSkill" }, "description": "Skills installed on the harness. Returned only by a single-harness read while the instance is running; omitted in listings." }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/UHPPlugin" }, "description": "Installed plugins. Their servers and skills join the harness's own for every turn;\n`mcpServers` and `skills` above report only what was written to them directly.\n" }, "environment": { "type": "string", "description": "The environment (`henv_`) this harness's tasks read, mounted read-only at its `mount`;\nempty when none. A task may name another with its own `environment` field.\n" }, "disabledTools": { "type": "array", "items": { "type": "string" }, "description": "Names of tools disabled for the harness. BeeOS Cloud does not support it, so it is never returned." }, "maxStep": { "type": [ "integer", "null" ], "description": "Maximum number of steps per run. BeeOS Cloud does not support it, so it is never returned." }, "timeoutSeconds": { "type": [ "integer", "null" ], "description": "Run timeout in seconds. BeeOS Cloud does not support it, so it is never returned." }, "createdAt": { "type": "integer", "description": "Unix milliseconds" } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPMcpServer": { "type": "object", "required": [ "name", "url" ], "description": "A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a\ndisabled entry must not be contacted at all. An unreachable server must not fail the task.\nUnchanged from 2026-08-11: a process (stdio) server is declared inside a plugin, see\nPluginMcpServer.\n", "properties": { "name": { "type": "string", "description": "Sanitised to a CLI-safe identifier by the server." }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint of the MCP server, at most 2048 characters, without user information or a fragment. Reads report it empty." }, "transport": { "type": "string", "enum": [ "http", "sse" ], "default": "http", "description": "Transport the server speaks. Defaults to `http` on write. Not returned for a server that uses neither transport.", "x-enumDescriptions": { "http": "Streamable HTTP.", "sse": "The older HTTP with server-sent events transport." } }, "enabled": { "type": "boolean", "default": true, "description": "Whether the server is enabled. Reads always report `true`. A server can only be set or removed: sending `false` is rejected with 422 `invalid_input`." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers to send to the server, for example credentials. Header names and values must be non-empty. Never returned. Sending headers or `auth` also requires `expires_at`." }, "auth": { "type": "string", "description": "Bearer token, or a server-side reference the server resolves. A server must never return\na resolved credential to a client.\n" }, "expires_at": { "type": "string", "format": "date-time", "description": "BeeOS extension. Expiry of the supplied short-lived credential; the caller refreshes it with another PUT." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPPluginMcpServer": { "type": "object", "required": [ "name" ], "description": "An MCP server a plugin's mcp.json declares, derived by the server. The harness MCP server\nobject plus the `stdio` transport: `url` is required for `http` and `sse`, `command` for\n`stdio`. Placeholders are reported unexpanded; `enabled` is always true, the plugin's own\n`enabled` governs.\n", "properties": { "name": { "type": "string", "description": "Name of the server, as declared in `mcp.json`." }, "transport": { "type": "string", "enum": [ "http", "sse", "stdio" ], "default": "http", "description": "`http` is Streamable HTTP (`streamable-http` in mcp.json); `sse` the older HTTP+SSE\ntransport; `stdio` a process the server launches inside the agent's sandbox.\n", "x-enumDescriptions": { "http": "Streamable HTTP, written `streamable-http` in `mcp.json`.", "sse": "The older HTTP with server-sent events transport.", "stdio": "A local process started by the sandbox, configured with `command`, `args`, `env` and `cwd`." } }, "url": { "type": "string", "format": "uri", "description": "Endpoint (`http` and `sse`)." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Fixed request headers (`http` and `sse`). Never subject to placeholder expansion." }, "command": { "type": "string", "description": "One executable token (`stdio`): a bare name resolved on the sandbox's search path, or a\nplugin-relative path beginning with `./`. Never a shell string, never expanded.\n" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments (`stdio`). `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expand at run time." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment overlay (`stdio`). Must not name PLUGIN_ROOT or PLUGIN_DATA; the server sets\nthose. Values expand at run time.\n" }, "cwd": { "type": "string", "description": "Working directory (`stdio`). Defaults to the plugin root; must stay within the plugin\nroot or PLUGIN_DATA.\n" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the server is enabled. Always `true` for a server derived from a plugin's `mcp.json`." } }, "allOf": [ { "if": { "properties": { "transport": { "enum": [ "stdio" ] } }, "required": [ "transport" ] }, "then": { "required": [ "command" ] }, "else": { "required": [ "url" ] } } ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPSkill": { "type": "object", "required": [ "name" ], "description": "A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent\ncan read it — materialising only SKILL.md breaks every skill carrying references, scripts or\ndata. Round-tripping a harness through GET and PUT must not lose skill contents.\n", "properties": { "name": { "type": "string", "description": "Name of the skill, equal to the name of its folder. It is 1 to 128 lowercase letters, digits, dots, underscores and hyphens, starting with a letter or digit. An installed skill is 2 to 64 lowercase letters, digits and hyphens." }, "enabled": { "type": "boolean", "default": true, "description": "false suppresses the skill, including one inherited from the base." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/UHPSkillFile" }, "description": "The bundle. Must contain a SKILL.md." }, "content": { "type": "string", "description": "Shorthand for a single-file bundle whose only member is SKILL.md." }, "blob": { "type": "string", "description": "Server-assigned handle for a bundle stored out of line. A client receives it, passes it\nback unchanged, and reads the files from the skill files endpoint.\n" }, "sha256": { "type": "string", "description": "BeeOS extension. SHA-256 of the Files bundle referenced by blob." }, "size_bytes": { "type": "string", "description": "BeeOS extension. Decimal byte size of the Files bundle referenced by blob." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPSkillFile": { "type": "object", "required": [ "path" ], "description": "One file of a skill folder or of a plugin package.", "properties": { "path": { "type": "string", "description": "Relative to the skill's own folder, or to the plugin root; nested directories are\nsupported. A server must reject a path that escapes the folder.\n", "examples": [ "SKILL.md", "references/codes.md", "assets/logo.png" ] }, "content": { "type": "string", "description": "Text content." }, "content_b64": { "type": "string", "description": "Base64 for binary content; preserved byte-for-byte." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPPlugin": { "type": "object", "required": [ "name" ], "description": "An Agent Plugins package installed into a harness: `plugin.json` at the root, MCP servers in\n`mcp.json`, skills under `skills/`. A client writes `files` (or passes back `blob`) and\noptionally `name` and `enabled`; the server derives `manifest`, `mcpServers`, `skills` and\n`skipped` from the package on every write and ignores those fields on input. A refused\npackage leaves the harness unchanged.\n", "properties": { "name": { "type": "string", "pattern": "^(?!.*(--|\\.\\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "maxLength": 64, "description": "The manifest's `name`. Optional on write; if sent it must equal the manifest's." }, "enabled": { "type": "boolean", "default": true, "description": "false keeps the plugin installed and inert; nothing in it is materialised or contacted." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/UHPSkillFile" }, "description": "The package. Must contain `plugin.json` at its root." }, "blob": { "type": "string", "description": "Server-assigned handle for a package stored out of line. A client passes it back unchanged\nand reads the files from the plugin files endpoint.\n" }, "manifest": { "$ref": "#/components/schemas/UHPPluginManifest", "description": "The plugin's `plugin.json`, parsed." }, "mcpServers": { "type": "array", "items": { "$ref": "#/components/schemas/UHPPluginMcpServer" }, "description": "Derived from `mcp.json`. Placeholders are reported unexpanded; `enabled` is always true,\nthe plugin's own `enabled` governs.\n" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/UHPPluginSkill" }, "description": "Derived from `skills/`, one entry per immediate child directory with a SKILL.md." }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/UHPPluginSkipped" }, "description": "What the server found and could not load. Present on every plugin object the server\nreturns, empty when nothing was skipped.\n" } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPPluginManifest": { "type": "object", "required": [ "$schema", "name" ], "description": "`plugin.json`, parsed. Mirrors the Agent Plugins 1.0.0 manifest schema\n(https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, Apache-2.0) field for field, and\npermits additional properties because a UHP client ignores fields it does not know. The\nschema a manifest's own `$schema` names is authoritative; a server validates against that.\n", "properties": { "$schema": { "type": "string", "format": "uri", "description": "URI of the manifest schema that the file follows." }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?!.*(--|\\.\\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "description": "Name of the plugin: 1 to 64 lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit." }, "version": { "type": "string", "description": "Version of the plugin." }, "description": { "type": "string", "description": "Description of the plugin." }, "author": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the author." }, "email": { "type": "string", "description": "Email address of the author." }, "url": { "type": "string", "description": "URL of the author's web page." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Author of the plugin." }, "homepage": { "type": "string", "description": "URL of the plugin's home page." }, "repository": { "type": "string", "description": "Location of the plugin's source repository." }, "license": { "type": "string", "description": "License of the plugin." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords that describe the plugin." }, "extensions": { "type": "object", "description": "Client-specific data keyed by reverse-domain namespace, per Agent Plugins §8.", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } } } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPPluginSkill": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The SKILL.md frontmatter name, equal to the directory name." }, "description": { "type": "string", "description": "Description from the frontmatter of the skill's `SKILL.md`." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPPluginSkipped": { "type": "object", "required": [ "path", "reason" ], "properties": { "path": { "type": "string", "description": "Where in the package, e.g. `skills/broken`, `mcp.json#/mcpServers/redline`, `plugin.json#/vendorField`.", "examples": [ "skills/broken", "mcp.json#/mcpServers/redline" ] }, "reason": { "type": "string", "description": "One sentence." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPHarnessCreate": { "type": "object", "required": [ "base" ], "properties": { "name": { "type": "string", "description": "Display name of the harness. Required on create, 1 or more non-blank characters. On update it must equal the current name; renaming is rejected with 422 `beeos_field_not_supported`." }, "base": { "type": "string", "description": "Base (agent runtime) of the harness. On create it must equal the `harness` of the instance named by `instance_id`, otherwise the request fails with 422 `unsupported_base`. On update it must equal the harness's current base, which cannot be changed." }, "default_model": { "type": "string", "description": "BeeOS Cloud honors this only on create; a different value on PUT returns 422 beeos_field_not_supported unless template_id is sent." }, "system_prompt": { "type": "string", "description": "System prompt. BeeOS Cloud does not support it: a non-empty value is rejected with 422 `beeos_field_not_supported`." }, "mcp_servers": { "type": "array", "items": { "$ref": "#/components/schemas/UHPMcpServer" }, "description": "Rejected on create (422 beeos_field_not_supported). On PUT the list is diffed against the runtime MCP servers: listed servers are set, omitted ones are unset; 422 beeos_mcp_not_supported only when the instance runtime has no MCP methods." }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/UHPSkill" }, "description": "Skills the harness should have. Not accepted on create. On update the list is the complete desired set: a skill that carries `files`, `content` or `blob` is installed, a listed installed skill only changes its `enabled` state, and an installed skill that is not listed is uninstalled, except bundled ones." }, "plugins": { "type": "array", "items": { "$ref": "#/components/schemas/UHPPlugin" }, "description": "Requires the `plugins` capability. Each item needs `files` or `blob`." }, "environment": { "type": "string", "description": "An environment id of the caller's scope, or empty. Requires the `environments` capability." }, "disabled_tools": { "type": "array", "items": { "type": "string" }, "description": "Names of tools to disable. BeeOS Cloud does not support it: a non-empty list is rejected with 422 `beeos_field_not_supported`." }, "max_step": { "type": [ "integer", "null" ], "description": "Maximum number of steps per run. BeeOS Cloud does not support it: any value is rejected with 422 `beeos_field_not_supported`." }, "timeout_seconds": { "type": [ "integer", "null" ], "description": "Run timeout in seconds. BeeOS Cloud does not support it: any value is rejected with 422 `beeos_field_not_supported`." }, "instance_id": { "type": "string", "description": "BeeOS extension. Instance that hosts a new harness (create only)." }, "template_id": { "type": "string", "description": "BeeOS extension. Agent template applied to the harness." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPModelCatalog": { "type": "object", "required": [ "backends" ], "properties": { "backends": { "type": "object", "additionalProperties": { "type": "object", "required": [ "default", "models" ], "properties": { "default": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UHPModel" } } } }, "description": "Models the caller's harnesses may use, grouped by provider family. Each key is a provider family, the part of a model ID before the first `/`, for example `anthropic`. Each value holds the family's `default` model ID and its `models`; models whose ID has no family are not listed here." } } }, "UHPHarnessModels": { "type": "object", "required": [ "models" ], "properties": { "harness_id": { "type": "string", "description": "ID of the harness the models belong to." }, "backend": { "type": "string", "description": "Provider family that every listed model belongs to: the part of the model ID before the first `/`, for example `anthropic`. Omitted when the models belong to several families or to none." }, "default": { "type": "string", "description": "ID of the harness's primary model. Omitted when it has none." }, "fallback": { "type": "string", "description": "Model used when a requested model cannot run. BeeOS Cloud does not report it, so it is never returned." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UHPModel" }, "description": "Models the harness may use, in the order of its instance's model list. When that list is empty, only the primary model is listed." } } }, "UHPModel": { "type": "object", "required": [ "id", "available" ], "properties": { "id": { "type": "string", "description": "ID of the model, usually in `provider/model` form, for example `anthropic/claude-sonnet-5`." }, "label": { "type": "string", "description": "Display name of the model. BeeOS Cloud does not report one, so it is omitted." }, "backend": { "type": "string", "description": "Provider family of the model: the part of `id` before the first `/`. Omitted when `id` has none." }, "available": { "type": "boolean", "description": "Computed, not asserted: true means the server can serve this model for this harness right\nnow. Listing a model as available and then failing the task is the worst outcome for a\nclient, because a user has already chosen it.\n" }, "default": { "type": "boolean", "description": "Whether this is the harness's primary model." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPCreateResponseRequest": { "type": "object", "required": [ "input" ], "properties": { "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } } } ], "description": "A bare string is shorthand for one user message." }, "model": { "type": "string", "description": "Model id for this turn. Omitted means the harness default. Any requested id is dispatched as given." }, "metadata": { "type": "object", "description": "Client metadata, the extension point of the Responses surface. `harness_id` selects the\nconfigured harness; `environment` names the environment this task reads, overriding the\nharness's (capability `environments`), refused with `environment_not_found` or\n`environment_not_ready` before the task starts.\n", "properties": { "harness_id": { "type": "string", "description": "ID of the harness that runs the task. Optional when exactly one harness is in scope; required when there are several." }, "environment": { "type": "string", "description": "Name of an environment for the task to read. This server does not serve environments: a non-empty value is rejected with 404 `environment_not_found`." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "stream": { "type": "boolean", "default": false, "description": "When true the response is streamed as server-sent events; see `UHPEvent`. Otherwise the call returns the finished response. Defaults to false." }, "previous_response_id": { "type": [ "string", "null" ], "description": "ID of an earlier response to continue. The new response runs in the same session. The earlier response must exist and belong to the same harness." }, "instructions": { "type": "string", "description": "Instructions placed before the input text and separated from it by a line containing `---`." }, "store": { "type": "boolean", "default": true, "description": "Whether to keep the response so it can be fetched later. Defaults to true." }, "max_output_tokens": { "type": [ "integer", "null" ], "description": "Reserved and ignored. It is reported in `metadata.ignored_fields` of the response." }, "max_step": { "type": [ "integer", "null" ], "description": "Agent step (tool-call round) budget" }, "timeout_seconds": { "type": [ "integer", "null" ], "description": "Wall-clock budget" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. A UHP harness invokes and executes tools\nitself and reports them in `output`; there is no input path for a tool result, so the\nclient-executed tool loop this field implies cannot be completed by a conformant server.\nConfigure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.\n" }, "include": { "type": "array", "items": { "type": "string" }, "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. No values are enumerated, so any string a\nserver recognised would be one it named itself. Tasks §1.4.\n" }, "background": { "type": "boolean", "default": false, "description": "When true on a request that is not streamed, the call returns at once with the response still `in_progress`; fetch the result later. Ignored when `stream` is true." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPResponse": { "type": "object", "required": [ "id", "object", "created_at", "status", "output", "model" ], "properties": { "id": { "type": "string", "pattern": "^resp_", "description": "ID of the response. It starts with `resp_`." }, "object": { "type": "string", "description": "Object type.", "x-enumDescriptions": { "response": "A response object." }, "enum": [ "response" ] }, "created_at": { "type": "integer", "description": "Unix seconds" }, "status": { "$ref": "#/components/schemas/UHPResponseStatus", "description": "Status of the response. See `UHPResponseStatus` for the values." }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UHPError" } ], "description": "Non-null only when status is `failed`." }, "incomplete_details": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Why the response is incomplete. When `status` is `incomplete` it holds `reason`, which is `timeout` when the time limit was reached. The protocol also defines `max_tokens` for the output limit, but this service does not currently produce it. Otherwise null." }, "previous_response_id": { "type": [ "string", "null" ], "description": "ID of the response this one continues, when the request set `previous_response_id`." }, "model": { "type": "string", "description": "The model that actually ran." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/UHPOutputItem" }, "description": "Output items produced so far, in order." }, "store": { "type": "boolean", "description": "Whether the response is kept so it can be fetched later." }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UHPUsage" } ], "description": "null when the server cannot account for usage. A fabricated zero would be worse than an\nhonest absence, because a client cannot tell it from a free task.\n" }, "metadata": { "type": "object", "properties": { "session_id": { "type": "string", "description": "ID of the session the response ran in. Responses chained with `previous_response_id` share it." }, "environment": { "type": "string", "description": "The environment the task read, when it read one (capability `environments`)." }, "requested_model": { "type": "string", "description": "The id the client sent, when the client sent one." }, "model_fallback": { "type": "boolean", "description": "True only when the harness reported it could not switch to the requested model." }, "model_fallback_reason": { "type": "string", "description": "Why the harness ran its default model instead of the requested one. When the harness gives no reason, it is `The harness ran its default model.`" }, "ignored_fields": { "type": "array", "items": { "type": "string" }, "description": "Request fields the server did not act on, by name, in any order. Required when the\nrequest carried `tools` or `include`, which are reserved and ignored. A silently\nignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.\n" } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra information about the run." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPResponseStatus": { "type": "string", "enum": [ "in_progress", "completed", "failed", "incomplete", "cancelled" ], "description": "`incomplete` means a budget stopped the work and is usually worth continuing.\n`failed` means it could not be done. `cancelled` means the client asked for a stop, and must\nnever be reported as `failed`.\n", "x-enumDescriptions": { "in_progress": "The response is still running.", "completed": "The response finished successfully.", "failed": "The work could not be done.", "incomplete": "A limit, such as the output limit or the time limit, stopped the work. It is usually worth continuing.", "cancelled": "The client asked to stop. A cancelled response is never reported as `failed`." } }, "UHPOutputItem": { "type": "object", "required": [ "type" ], "description": "A client must tolerate item types it does not recognise. A client that renders only `message`\nitems and ignores the rest is a valid client.\n", "properties": { "id": { "type": "string", "description": "ID of the output item." }, "type": { "type": "string", "examples": [ "message", "reasoning", "function_call", "function_call_output" ], "description": "Kind of the output item. Clients should ignore item types they do not know.", "x-enumDescriptions": { "message": "A message written by the agent. Its text is in `content`.", "reasoning": "The agent's reasoning. Its summary is in `summary`.", "function_call": "A tool call made by the agent, with `name` and `arguments`.", "function_call_output": "The result of a tool call, in `output`." } }, "status": { "type": "string", "description": "Progress of the item.", "x-enumDescriptions": { "in_progress": "The item is still being produced.", "completed": "The item is complete." } }, "role": { "type": "string", "description": "Who wrote a `message` item.", "x-enumDescriptions": { "assistant": "The agent." } }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/UHPContentPart" }, "description": "Content parts of a `message` item." }, "summary": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "description": "Summary of a `reasoning` item." }, "call_id": { "type": "string", "description": "ID of the function call. A `function_call_output` item refers to its call with the same `call_id`." }, "name": { "type": "string", "description": "Name of the function the agent called." }, "arguments": { "type": "string", "description": "JSON, as a string" }, "output": { "type": "string", "description": "Result of the function call, as text." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "x-variants": { "property": "type", "mapping": { "message": { "$ref": "#/components/x-variantSchemas/UHPOutputItemMessage" }, "reasoning": { "$ref": "#/components/x-variantSchemas/UHPOutputItemReasoning" }, "function_call": { "$ref": "#/components/x-variantSchemas/UHPOutputItemFunctionCall" }, "function_call_output": { "$ref": "#/components/x-variantSchemas/UHPOutputItemFunctionCallOutput" } } } }, "UHPContentPart": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "examples": [ "output_text" ], "description": "Kind of the part.", "x-enumDescriptions": { "output_text": "Text of a `message` item, with optional annotations.", "summary_text": "Summary text of a `reasoning` item." } }, "text": { "type": "string", "description": "Text of the part." }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/UHPAnnotation" }, "description": "Annotations that refer to ranges of `text`." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "x-variants": { "property": "type", "mapping": { "output_text": { "$ref": "#/components/x-variantSchemas/UHPContentPartOutputText" }, "summary_text": { "$ref": "#/components/x-variantSchemas/UHPContentPartSummaryText" } } } }, "UHPAnnotation": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Kind of the annotation.", "x-enumDescriptions": { "container_file_citation": "The text refers to a file produced by the agent." }, "enum": [ "container_file_citation" ] }, "container_id": { "type": "string", "description": "ID of the container that holds the file. BeeOS does not currently set it." }, "file_id": { "type": "string", "description": "ID of the file. BeeOS does not currently set it." }, "filename": { "type": "string", "description": "Name of the file." }, "download_url": { "type": "string", "format": "uri", "description": "Absolute URL the file can be downloaded from." }, "start_index": { "type": "integer", "description": "Start of the cited range in the text, counted in characters. BeeOS sets it to 0." }, "end_index": { "type": "integer", "description": "End of the cited range in the text, counted in characters. BeeOS sets it to the length of the text." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPUsage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "description": "Number of input tokens." }, "output_tokens": { "type": "integer", "minimum": 0, "description": "Number of output tokens." }, "total_tokens": { "type": "integer", "minimum": 0, "description": "Total number of tokens used." }, "cache_read_tokens": { "type": "integer", "minimum": 0, "description": "Input tokens read from the cache." }, "cache_write_tokens": { "type": "integer", "minimum": 0, "description": "Input tokens written to the cache." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/UHPError", "description": "The error." }, "detail": { "type": "string", "deprecated": true, "description": "A human-readable alias of `error.message`, retained for clients written against\nimplementations that predate this envelope. Carries no information not in `error`.\n" } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPError": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "harness_error", "server_error" ], "description": "Category of the error. It follows from the HTTP status.", "x-enumDescriptions": { "invalid_request_error": "The request is invalid or refers to something that does not exist or conflicts with current state.", "authentication_error": "The API key is missing or invalid.", "permission_error": "The API key does not have the scope the call needs.", "rate_limit_error": "Too many requests.", "harness_error": "The harness failed to do what was asked.", "server_error": "The server could not serve the request." } }, "code": { "type": "string", "description": "Specific and machine-readable. Servers may define additional codes for conditions this\nspecification does not cover, and must namespace them with a vendor prefix so a future\nversion cannot collide with them.\n", "examples": [ "unsupported_protocol_version", "invalid_input", "harness_not_found", "response_not_found", "session_not_found", "plugin_not_found", "file_not_found", "session_expired", "harness_mismatch", "session_busy", "plugin_conflict", "file_too_large", "model_unavailable", "unsupported_base", "plugin_invalid", "unsupported_plugin_schema", "environment_not_found", "environment_not_ready", "environment_busy", "environment_exists", "environment_invalid", "environment_unavailable", "unsupported_transport", "missing_credential", "invalid_credential", "insufficient_scope", "rate_limited", "quota_exhausted", "harness_error", "harness_unavailable", "provider_error", "timeout", "cancelled", "preview_unavailable", "preview_failed" ] }, "message": { "type": "string", "description": "One sentence, safe to show a user. Must not contain credentials, internal hostnames, file\npaths, or stack traces.\n" }, "param": { "type": [ "string", "null" ], "description": "Dotted path to the offending field." }, "detail": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Additional structured detail about the error, when available." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEvent": { "type": "object", "required": [ "type", "sequence_number" ], "description": "One streamed event. `sequence_number` starts at 0 and increases by exactly 1 per event, so a\nclient can detect a dropped event rather than silently rendering a gap.\n", "properties": { "type": { "type": "string", "examples": [ "response.created", "response.in_progress", "response.output_item.added", "response.output_item.done", "response.content_part.added", "response.content_part.done", "response.output_text.delta", "response.output_text.done", "response.output_text.annotation.added", "response.reasoning_summary_part.added", "response.reasoning_summary_text.delta", "response.reasoning_summary_part.done", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.completed", "response.incomplete", "response.failed", "error" ], "description": "Kind of the event. Clients should ignore event types they do not know. Exactly one of `response.completed`, `response.incomplete` and `response.failed` ends a stream.", "x-enumDescriptions": { "response.created": "The response was created. `response` is the initial snapshot with status `in_progress`.", "response.in_progress": "The response is running. `response` is a snapshot.", "response.output_item.added": "A new output item started. `item` is its initial form and `output_index` its position in the output.", "response.output_item.done": "An output item is complete. `item` is its final form.", "response.content_part.added": "A content part was added to a `message` item. `part` is its initial form.", "response.content_part.done": "A content part of a `message` item is complete. `part` is its final form.", "response.output_text.delta": "More text was appended to the text of a `message` item. `delta` is the new text.", "response.output_text.done": "The text of a `message` item is complete. `text` is the full text.", "response.output_text.annotation.added": "An annotation, such as a file citation, was added to the text of a `message` item.", "response.reasoning_summary_part.added": "A summary part was added to a `reasoning` item.", "response.reasoning_summary_text.delta": "More text was appended to the summary of a `reasoning` item. `delta` is the new text.", "response.reasoning_summary_part.done": "A summary part of a `reasoning` item is complete. `part` is its final form.", "response.function_call_arguments.delta": "The arguments of a `function_call` item were written. `delta` holds the arguments text.", "response.function_call_arguments.done": "The arguments of a `function_call` item are complete. `arguments` holds them as a JSON string.", "response.completed": "The response finished successfully. This is a terminal event: exactly one terminal event ends the stream.", "response.incomplete": "The response stopped because of a limit, for example the output limit or the time limit. This is a terminal event.", "response.failed": "The response failed or was cancelled; `response.status` is `failed` or `cancelled`. This is a terminal event.", "error": "An error that did not end the response. `code`, `message` and `param` describe it, and a terminal event still follows.", "beeos.approval.requested": "BeeOS extension. The agent asks for approval of an action. The `approval` property holds the approval request document.", "beeos.approval.resolved": "BeeOS extension. An approval request was resolved. The `approval` property holds the resolution document.", "beeos.question.requested": "BeeOS extension. The agent asks the user a question. The `question` property holds the question request document.", "beeos.question.resolved": "BeeOS extension. A question request was resolved. The `question` property holds the resolution document." } }, "sequence_number": { "type": "integer", "minimum": 0, "description": "Position of the event in the stream, starting at 0 and increasing by 1 per event. A gap means an event was lost." }, "response": { "$ref": "#/components/schemas/UHPResponse", "description": "Snapshot of the response. Present on lifecycle events." }, "item": { "$ref": "#/components/schemas/UHPOutputItem", "description": "The output item. Present on `response.output_item.added` and `response.output_item.done`." }, "part": { "$ref": "#/components/schemas/UHPContentPart", "description": "The content or summary part. Present on content part and reasoning summary part events." }, "annotation": { "$ref": "#/components/schemas/UHPAnnotation", "description": "The annotation. Present on `response.output_text.annotation.added`." }, "delta": { "type": "string", "description": "New text, or new function arguments, since the previous delta." }, "text": { "type": "string", "description": "The complete text. Present on `response.output_text.done`." }, "arguments": { "type": "string", "description": "The complete function arguments as a JSON string. Present on `response.function_call_arguments.done`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "content_index": { "type": "integer", "minimum": 0, "description": "Index of the content part within the item." }, "summary_index": { "type": "integer", "minimum": 0, "description": "Index of the summary part within the item." }, "annotation_index": { "type": "integer", "minimum": 0, "description": "Index of the annotation within the content part." }, "code": { "type": "string", "description": "Machine-readable error code. Present on `error` events." }, "message": { "type": "string", "description": "Readable error message. Present on `error` events." }, "param": { "type": [ "string", "null" ], "description": "Dotted path of the field the error is about, or null. Present on `error` events." } }, "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "x-variants": { "property": "type", "mapping": { "response.created": { "$ref": "#/components/x-variantSchemas/UHPEventResponse" }, "response.in_progress": { "$ref": "#/components/x-variantSchemas/UHPEventResponse" }, "response.completed": { "$ref": "#/components/x-variantSchemas/UHPEventResponse" }, "response.incomplete": { "$ref": "#/components/x-variantSchemas/UHPEventResponse" }, "response.failed": { "$ref": "#/components/x-variantSchemas/UHPEventResponse" }, "response.output_item.added": { "$ref": "#/components/x-variantSchemas/UHPEventOutputItem" }, "response.output_item.done": { "$ref": "#/components/x-variantSchemas/UHPEventOutputItem" }, "response.content_part.added": { "$ref": "#/components/x-variantSchemas/UHPEventContentPart" }, "response.content_part.done": { "$ref": "#/components/x-variantSchemas/UHPEventContentPart" }, "response.reasoning_summary_part.added": { "$ref": "#/components/x-variantSchemas/UHPEventReasoningSummaryPart" }, "response.reasoning_summary_part.done": { "$ref": "#/components/x-variantSchemas/UHPEventReasoningSummaryPart" }, "response.output_text.delta": { "$ref": "#/components/x-variantSchemas/UHPEventOutputTextDelta" }, "response.reasoning_summary_text.delta": { "$ref": "#/components/x-variantSchemas/UHPEventReasoningSummaryTextDelta" }, "response.output_text.done": { "$ref": "#/components/x-variantSchemas/UHPEventOutputTextDone" }, "response.output_text.annotation.added": { "$ref": "#/components/x-variantSchemas/UHPEventAnnotationAdded" }, "response.function_call_arguments.delta": { "$ref": "#/components/x-variantSchemas/UHPEventFunctionCallArgumentsDelta" }, "response.function_call_arguments.done": { "$ref": "#/components/x-variantSchemas/UHPEventFunctionCallArgumentsDone" }, "error": { "$ref": "#/components/x-variantSchemas/UHPEventError" }, "beeos.approval.requested": { "$ref": "#/components/x-variantSchemas/UHPEventApproval" }, "beeos.approval.resolved": { "$ref": "#/components/x-variantSchemas/UHPEventApproval" }, "beeos.question.requested": { "$ref": "#/components/x-variantSchemas/UHPEventQuestion" }, "beeos.question.resolved": { "$ref": "#/components/x-variantSchemas/UHPEventQuestion" } } } }, "JSONValue": { "description": "A genuinely open JSON value (provider/plugin parameters or arbitrary metadata).", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JSONValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } } ] }, "RuntimeInstanceSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the instance." }, "organization_id": { "type": "string", "description": "ID of the organization that owns the instance." }, "app_id": { "type": "string", "description": "ID of the app the instance belongs to." }, "developer_id": { "type": "string", "description": "ID of the developer account the instance was created under." }, "name": { "type": "string", "description": "Display name of the instance." }, "harness": { "type": "string", "description": "Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`)." }, "provider_id": { "type": "string", "description": "ID of the provider that hosts the instance." }, "region": { "type": "string", "description": "Region the instance is deployed in." }, "os_type": { "type": "string", "description": "Operating system of the instance: `linux`, `windows`, `android` or `macos`." }, "status": { "type": "string", "description": "Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "pending": "The instance was created and is waiting to be provisioned.", "provisioning": "The instance is being provisioned or started.", "running": "The instance is running.", "stopped": "The instance is stopped and can be started again.", "terminated": "The instance was deleted and cannot be used again." } }, "desired_status": { "type": "string", "description": "Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "running": "The instance should be running.", "stopped": "The instance should be stopped.", "terminated": "The instance should be deleted." } }, "connectivity": { "type": "string", "description": "Reachability of the instance's agent: `unknown`, `online` or `offline`.", "x-enumDescriptions": { "unknown": "Reachability has not been determined.", "online": "The instance's agent is connected.", "offline": "The instance's agent is not connected." } }, "error_code": { "type": "string", "description": "Stable code describing a failure or degraded state reported with a lifecycle result, for example `quota_exceeded`, `capacity_pending`, `provision_failed` or `stop_failed`. Raw provider errors are never exported." }, "ms_connection_status": { "type": "string", "description": "Status of the instance's message-channel connection: `unknown`, `connecting`, `connected`, `reconnecting`, `disconnected` or `failed`. It is reported independently of connectivity and is `unknown` while the instance is stopped or terminated, or has not reported recently." }, "image_id": { "type": "string", "description": "ID of the platform image the instance runs." }, "image_version_id": { "type": "string", "description": "ID of the platform image version the instance runs." }, "image_version": { "type": "string", "description": "Version label of the platform image the instance runs." }, "image_ref": { "type": "string", "description": "Pinned public image reference. Provider configuration is never included." }, "model_primary": { "type": "string", "description": "Primary model configured for the instance." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Models configured for the instance." }, "llm": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeLLMView" }, { "type": "null" } ], "description": "Model providers and models supplied for the instance, with API keys removed." }, "hosting_type": { "type": "string", "description": "Where the instance is hosted: `cloud` or `selfhosted`." }, "cloud_provider": { "type": "string", "description": "`agentbay`, `beeos`, or empty when self-hosted." }, "image_slot": { "type": "string", "description": "Variant trait. Key that selects the execution image for the instance. Not a container repository name." }, "worker_image_id": { "type": "string", "description": "Variant trait. AgentBay worker image. Never the platform `image_id`." }, "model_catalog": { "type": "string", "description": "Variant trait. `served` when Cloud answers model-list and reasoning-level requests, `none` when it answers neither. Empty and unknown values behave as `none`." }, "billing_slot": { "type": "string", "description": "Variant trait. Key into the monthly fee table that prices the instance." }, "icon_key": { "type": "string", "description": "Variant trait. UI icon selector. Clients must not derive it from `harness`." }, "device_control": { "type": "boolean", "description": "Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected." }, "runtime_profile": { "type": "string", "description": "Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`." }, "free_plan": { "type": "boolean", "description": "Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it." }, "resource_version": { "type": "integer", "description": "Version of the instance record, starting at 1. Send it in the `If-Match` header of write requests so concurrent changes are detected." }, "has_ever_run": { "type": "boolean", "description": "Whether the instance has ever reached the running state. False means it has never delivered a running service." }, "created_at": { "type": "string", "description": "Time the instance was created, as an RFC 3339 UTC timestamp." }, "updated_at": { "type": "string", "description": "Time the instance was last updated, as an RFC 3339 UTC timestamp." }, "capabilities": { "type": "object", "properties": { "computer": { "type": "boolean" }, "mobile": { "type": "boolean" }, "device": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [], "additionalProperties": false, "description": "Capabilities declared for the instance when it was provisioned, as flags such as `computer`, `mobile`, `device` and `terminal`. An empty object means none were declared." } }, "required": [ "id", "organization_id", "app_id", "developer_id", "name", "harness", "provider_id", "region", "os_type", "status", "desired_status", "connectivity", "ms_connection_status", "device_control", "free_plan", "resource_version", "has_ever_run", "created_at", "updated_at", "capabilities" ], "additionalProperties": false }, "RuntimeOperationSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the operation." }, "kind": { "type": "string", "description": "Kind of operation: `create`, `start`, `stop`, `delete` or `image_upgrade`.", "x-enumDescriptions": { "create": "Create the instance.", "start": "Start a stopped instance.", "stop": "Stop the instance.", "delete": "Delete the instance.", "image_upgrade": "Upgrade the instance to another platform image." } }, "phase": { "type": "string", "description": "Phase of the operation: `intent`, `reserved`, `admitted`, `provisioning`, `running`, `cleanup_pending`, `failed`, `stop_pending`, `stopped`, `delete_pending`, `deleted`, `upgrade_pending` or `rollback_pending`. It describes durable work, not observed instance health.", "x-enumDescriptions": { "intent": "The create request was recorded and nothing is reserved yet.", "reserved": "The create request was accepted and its resources are reserved.", "admitted": "The create request was admitted and is waiting to be provisioned.", "provisioning": "The instance is being provisioned or started.", "running": "Final phase of a successful create, start or image upgrade.", "cleanup_pending": "A create failed and the resources it reserved are being cleaned up.", "failed": "Final phase of a failed operation. See `error_code`.", "stop_pending": "The instance is being stopped.", "stopped": "Final phase of a successful stop.", "delete_pending": "The instance is being deleted.", "deleted": "Final phase of a successful delete.", "upgrade_pending": "The image upgrade is being applied.", "rollback_pending": "The image upgrade failed and the instance is being rolled back to its previous image." } }, "error_code": { "type": "string", "description": "Stable failure code, the same value as the instance `error_code`. Raw provider errors are never exported." } }, "required": [ "id", "kind", "phase" ], "additionalProperties": false }, "RuntimeInstanceResult": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RuntimeInstanceSummary", "description": "The instance as of this response." }, "operation": { "$ref": "#/components/schemas/RuntimeOperationSummary", "description": "Lifecycle operation that this response reports on." } }, "required": [ "data", "operation" ], "additionalProperties": false }, "RuntimeExecResult": { "type": "object", "properties": { "exit_code": { "type": "integer", "description": "Exit code of the command." }, "stdout": { "type": "string", "description": "Standard output of the command, at most 64 KiB." }, "stderr": { "type": "string", "description": "Standard error of the command, at most 64 KiB." }, "truncated": { "type": "boolean", "description": "Whether the output was truncated." } }, "required": [ "exit_code", "stdout", "stderr", "truncated" ], "additionalProperties": false }, "RuntimeLLM": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeLLMProvider" }, "description": "Model provider endpoints, 1 to 8 entries. Every provider must be referenced by at least one model." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeLLMModel" }, "description": "Selectable models, 1 to 256 entries. Exactly one has the `default` role." } }, "required": [ "providers", "models" ], "additionalProperties": false }, "RuntimeLLMView": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeLLMProviderView" }, "description": "Model provider endpoints, without API keys." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeLLMModel" }, "description": "Selectable models." } }, "required": [ "providers", "models" ], "additionalProperties": false }, "RuntimeLLMProvider": { "type": "object", "properties": { "id": { "type": "string", "description": "Caller-chosen ID that models refer to. It is unique within the request, 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`." }, "protocol": { "type": "string", "enum": [ "openai", "anthropic" ], "description": "API protocol the endpoint speaks: `openai` or `anthropic`.", "x-enumDescriptions": { "openai": "The OpenAI-compatible API.", "anthropic": "The Anthropic Messages API." } }, "base_url": { "type": "string", "description": "HTTPS base URL of the provider API, at most 512 characters. It must not contain credentials, a query string or a fragment." }, "api_key": { "type": "string", "writeOnly": true, "description": "API key for the provider, 1 to 4096 characters without whitespace. It is write-only and never returned." } }, "required": [ "id", "protocol", "base_url" ], "additionalProperties": false }, "RuntimeLLMProviderView": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the provider, as referenced by models." }, "protocol": { "type": "string", "description": "API protocol the endpoint speaks: `openai` or `anthropic`." }, "base_url": { "type": "string", "description": "HTTPS base URL of the provider API." } }, "required": [ "id", "protocol", "base_url" ], "additionalProperties": false }, "RuntimeLLMModel": { "type": "object", "properties": { "provider_id": { "type": "string", "description": "ID of the provider that serves the model." }, "model": { "type": "string", "description": "Model name as the provider API expects it. It is unique per provider." }, "role": { "type": "string", "description": "Role of the model: `default`, `fallback` or `available`. Exactly one model is `default`. Automatic failover uses only `fallback` models.", "x-enumDescriptions": { "default": "The model the instance uses by default. Exactly one model has this role, with order 0.", "fallback": "A model that automatic failover switches to when the default model fails.", "available": "A model that can be selected but is never used for automatic failover." } }, "order": { "type": "integer", "description": "Position of the model, unique across all models. The `default` model has order 0; `fallback` and `available` models have order 1 or more." } }, "required": [ "provider_id", "model", "role", "order" ], "additionalProperties": false }, "RuntimeUpgradeJob": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique ID of the upgrade job." }, "image_version_id": { "type": "string" }, "instance_id": { "type": "string", "description": "ID of the instance being upgraded." }, "status": { "type": "string", "description": "Status of the job: `upgrade_pending`, `rollback_pending`, `failed` or `succeeded`.", "x-enumDescriptions": { "upgrade_pending": "The image upgrade is being applied.", "rollback_pending": "The image upgrade failed and the instance is being rolled back to its previous image.", "failed": "The image upgrade failed. See `error`.", "succeeded": "The image upgrade finished and the instance runs the target version." } }, "target": { "type": "string", "description": "Image version the instance is being upgraded to." }, "created_at": { "type": "string", "description": "Time the job was created, as an RFC 3339 UTC timestamp." }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time the job finished, as an RFC 3339 UTC timestamp. Omitted while the job is not finished." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable failure code. Omitted unless the job failed." } }, "required": [ "job_id", "instance_id", "status", "target", "created_at" ], "additionalProperties": false }, "FileFile": { "type": "object", "properties": { "file_id": { "type": "string", "description": "Unique ID of the file." }, "filename": { "type": "string", "description": "Name of the file, without a path." }, "content_type": { "type": "string", "description": "MIME type of the file, for example image/png." }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes." }, "checksum_sha256": { "type": "string", "description": "Lowercase hex SHA-256 digest of the file content. Empty when no checksum was supplied at upload and none was recorded for the object." }, "status": { "type": "string", "description": "Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know.", "x-enumDescriptions": { "pending_upload": "The upload was prepared but not confirmed yet. The file has no content to download.", "ready": "The upload was confirmed. The file can be downloaded, renamed, shared and deleted." } }, "resource_version": { "type": "integer", "description": "Version of the file record. It starts at 1 and increases when the upload is confirmed and when the file is renamed or deleted." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the file was last changed: created, confirmed or renamed, whichever is latest. RFC 3339 timestamp." }, "title": { "type": "string", "description": "Title read from the document's own metadata. It is extracted for PDF, docx, xlsx and pptx files of up to 8 MiB the first time the file is read by ID, and omitted when the document has no usable title." }, "file_type": { "type": "string", "description": "Category of the file, derived from its MIME type and, for generic types such as `application/octet-stream`, from its extension.", "x-enumDescriptions": { "FILE_TYPE_IMAGE": "An image, for example PNG, JPEG, GIF, WebP or SVG.", "FILE_TYPE_VIDEO": "A video, for example MP4, MOV or WebM.", "FILE_TYPE_AUDIO": "An audio file, for example MP3, WAV or FLAC.", "FILE_TYPE_DOCUMENT": "A text or office document, for example plain text, Markdown, JSON, PDF, Word, Excel, PowerPoint or OpenDocument.", "FILE_TYPE_ARCHIVE": "A compressed or packed archive, for example ZIP, TAR, GZIP, 7z or RAR.", "FILE_TYPE_OTHER": "Any other file." } }, "created_at": { "type": "string", "format": "date-time", "description": "Time the file record was created, when the upload was prepared. RFC 3339 timestamp." }, "confirmed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time the upload was confirmed. Omitted until the file is ready. RFC 3339 timestamp." }, "origin": { "anyOf": [ { "$ref": "#/components/schemas/FileOrigin" }, { "type": "null" } ], "description": "Where the file came from, with the instance and agent it belongs to." } }, "required": [ "file_id", "filename", "content_type", "size_bytes", "status", "resource_version", "updated_at", "file_type", "created_at" ], "additionalProperties": false }, "FileOrigin": { "type": "object", "properties": { "source": { "type": "string", "description": "How the file came to exist. New values can be added, so ignore values you do not know.", "x-enumDescriptions": { "manual": "Uploaded directly through the files API without an upload context. Files without a recorded origin are reported as `manual`.", "chat_upload": "Uploaded with an `upload_context`, to be used in a conversation with the agent named by it.", "runtime_generated": "Generated by an agent while it handled a request. `operation_id` identifies that operation.", "template_skill": "Provided by a template skill. The file is read-only: it cannot be renamed or deleted, and it does not count toward storage usage." } }, "instance_id": { "type": "string", "description": "ID of the instance the file belongs to. Omitted for files that are not tied to an instance." }, "agent_id": { "type": "string", "description": "ID of the agent the file belongs to. Omitted for files that are not tied to an agent." }, "operation_id": { "type": "string", "description": "ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`." }, "instance_name": { "type": "string", "description": "Current display name of the instance, filled in when the file is returned. Omitted for files without an instance." }, "agent_name": { "type": "string", "description": "Current display name of the agent, filled in when the file is returned. Omitted for files without an agent." }, "avatar_url": { "type": "string", "description": "URL of the agent avatar. Omitted for files without an agent." }, "harness": { "type": "string", "description": "Harness the instance runs, for example `openclaw`. Omitted for files without an instance." }, "destroyed": { "type": "boolean", "description": "True when the instance has been terminated or deleted. The file stays available. Omitted when false." } }, "required": [ "source" ], "additionalProperties": false }, "FileTransferDescriptor": { "type": "object", "properties": { "direction": { "type": "string", "description": "Whether the URL is used to upload or to download the file content.", "x-enumDescriptions": { "upload": "Send the file content to `url` with `http_method`. Returned when an upload is prepared.", "download": "Fetch the file content from `url` with `http_method`. Returned when a file or a share is read." } }, "file_id": { "type": "string", "description": "ID of the file the transfer is for." }, "url": { "type": "string", "description": "Pre-signed URL to transfer the file content with. The URL is already signed, so do not send your API key to it." }, "http_method": { "type": "string", "description": "HTTP method to use with `url`: `PUT` for an upload, `GET` for a download." }, "required_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers to send with the transfer request exactly as given. Empty when none are required." }, "expires_at": { "type": "string", "format": "date-time", "description": "Time the URL stops working, as an RFC 3339 timestamp. Upload URLs are valid for 15 minutes and download URLs for 5 minutes." }, "content_type": { "type": "string", "description": "MIME type of the file." }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes." }, "checksum_sha256": { "type": "string", "description": "Lowercase hex SHA-256 digest of the file content. Omitted when no digest is known." } }, "required": [ "direction", "file_id", "url", "http_method", "required_headers", "expires_at", "content_type", "size_bytes" ], "additionalProperties": false }, "FileChatUploadContext": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "ID of the instance the file is uploaded for. It must belong to your app." }, "agent_id": { "type": "string", "description": "ID of the agent the file is uploaded for. It must belong to the instance. Optional." } }, "required": [ "instance_id" ], "additionalProperties": false }, "FilePrepareUploadInput": { "type": "object", "properties": { "upload_context": { "anyOf": [ { "$ref": "#/components/schemas/FileChatUploadContext" }, { "type": "null" } ], "description": "Ties the upload to an instance and optionally an agent. The credential's organization and app own the file. Omit the context for a plain upload." }, "filename": { "type": "string", "description": "Name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\\` or control characters." }, "content_type": { "type": "string", "description": "MIME type of the file, at most 255 characters and without control characters. The uploaded content must carry this type." }, "size_bytes": { "type": "integer", "description": "Size of the file in bytes, from 1 to 104857600 (100 MiB). The uploaded content must have exactly this size." }, "checksum_sha256": { "type": "string", "description": "Lowercase hex SHA-256 digest of the content (64 characters). Optional. When sent, the uploaded content must match it and the confirmation verifies it." } }, "required": [ "filename", "content_type", "size_bytes" ], "additionalProperties": false }, "FileConfirmInput": { "type": "object", "properties": { "checksum_sha256": { "type": "string", "description": "Lowercase hex SHA-256 digest of the uploaded content (64 characters). Optional. When sent, it is compared with the digest of the stored object and a difference fails the confirmation with 409 `checksum_mismatch`." } }, "required": [], "additionalProperties": false }, "FilePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FileFile" }, "description": "Files on this page." }, "total": { "type": "integer", "description": "Number of files that match the query, across all pages." }, "next_since": { "type": "string", "description": "Cursor to pass as `since` to get the next page. Returned only by the default chronological listing, and only when more files follow. Filtered or sorted listings page with `offset` instead." } }, "required": [ "data", "total" ], "additionalProperties": false }, "FileResolution": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/FileFile", "description": "The file." }, "download": { "$ref": "#/components/schemas/FileTransferDescriptor", "description": "Pre-signed descriptor to download the content with. While the file is still `pending_upload` it carries no usable URL." } }, "required": [ "file", "download" ], "additionalProperties": false }, "FileSummary": { "type": "object", "properties": { "file_count": { "type": "integer", "description": "Number of ready files." }, "storage_file_count": { "type": "integer", "description": "Number of ready files that count toward storage. Files provided by template skills are not counted." }, "used_bytes": { "type": "integer", "description": "Total size in bytes of the files that count toward storage." }, "image_count": { "type": "integer", "description": "Number of ready files in the `FILE_TYPE_IMAGE` category." }, "video_count": { "type": "integer", "description": "Number of ready files in the `FILE_TYPE_VIDEO` category." }, "document_count": { "type": "integer", "description": "Number of ready files in the `FILE_TYPE_DOCUMENT` category." }, "instances": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "How the file came to exist. New values can be added, so ignore values you do not know.", "x-enumDescriptions": { "manual": "Uploaded directly through the files API without an upload context. Files without a recorded origin are reported as `manual`.", "chat_upload": "Uploaded with an `upload_context`, to be used in a conversation with the agent named by it.", "runtime_generated": "Generated by an agent while it handled a request. `operation_id` identifies that operation.", "template_skill": "Provided by a template skill. The file is read-only: it cannot be renamed or deleted, and it does not count toward storage usage." } }, "instance_id": { "type": "string", "description": "ID of the instance the file belongs to. Omitted for files that are not tied to an instance." }, "agent_id": { "type": "string", "description": "ID of the agent the file belongs to. Omitted for files that are not tied to an agent." }, "operation_id": { "type": "string", "description": "ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`." }, "instance_name": { "type": "string", "description": "Current display name of the instance, filled in when the file is returned. Omitted for files without an instance." }, "agent_name": { "type": "string", "description": "Current display name of the agent, filled in when the file is returned. Omitted for files without an agent." }, "avatar_url": { "type": "string", "description": "URL of the agent avatar. Omitted for files without an agent." }, "harness": { "type": "string", "description": "Harness the instance runs, for example `openclaw`. Omitted for files without an instance." }, "destroyed": { "type": "boolean", "description": "True when the instance has been terminated or deleted. The file stays available. Omitted when false." }, "count": { "type": "integer", "description": "Number of ready files in this group." } }, "required": [ "source", "count" ], "additionalProperties": false }, "description": "Ready files grouped by the agent they belong to, or by instance when they have no agent, largest group first." } }, "required": [ "file_count", "storage_file_count", "used_bytes", "image_count", "video_count", "document_count", "instances" ], "additionalProperties": false }, "AgentAgent": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the agent." }, "instance_id": { "type": "string", "description": "ID of the instance the agent runs on." }, "name": { "type": "string", "description": "Name of the agent." }, "avatar_url": { "type": "string", "description": "URL of the agent's avatar image. Omitted when none is set." }, "display_name": { "type": "string", "description": "Human-readable name of the agent. Omitted when none is set." }, "description": { "type": "string", "description": "Description of the agent. Empty when none is set." }, "resource_version": { "type": "integer", "description": "Version of the agent to send as `If-Match`, in double quotes, when you update it. The same value is returned in the `ETag` header when you read or update a single agent." }, "status": { "type": "string", "description": "Whether the agent is currently provided by its instance.", "x-enumDescriptions": { "active": "The instance currently provides the agent.", "inactive": "The instance no longer provides the agent, for example because it was removed or replaced by another agent with the same name. The record is kept." } }, "visibility": { "type": "string", "description": "Which callers other than the owner can use the agent. Change it with the update operation.", "x-enumDescriptions": { "private": "Callers other than the owner cannot invoke the agent or read its agent card. It is not listed in catalogs.", "unlisted": "Callers other than the owner can invoke the agent and read its agent card if they know its ID. It is not listed in catalogs.", "org": "Reserved. The value is accepted, but it does not currently give callers other than the owner access to the agent.", "public": "Callers other than the owner can invoke the agent and read its agent card, and it is listed in catalogs.", "marketplace": "The agent is listed in catalogs. That is all this value grants: callers other than the owner cannot invoke the agent or read its agent card by ID." } }, "mcp_enabled": { "type": "boolean", "description": "Whether the agent is published as a tool through BeeOS MCP endpoints." }, "a2a_enabled": { "type": "boolean", "description": "Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`." }, "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Features the agent supports, as an object that maps a feature name to true or false. Known names include `canvas`, `terminal`, `webSsh`, `fileSystem`, `image`, `audio`, `mcp`, `cron`, `streaming`, `pushNotifications`, `a2a`, `extendedAgentCard`, `multipleConversations`, `loadConversation`, `createConversation`, `modelsList`, `modelsSet`, `skillsList`, `skillsInstall`, `skillsUninstall`, `skillsUpdate` and `automationWake`. A name that is absent or false means the agent does not support the feature. New names can be added, so ignore names you do not know." }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkill" }, "description": "Skills of the agent." }, "conversation_transport": { "type": "string", "description": "How conversation messages reach the agent. New values can be added, so ignore values you do not know.", "x-enumDescriptions": { "acp": "Conversation messages are exchanged with the agent over its ACP connection.", "message-service": "Conversation messages are delivered to the agent as messages through BeeOS messaging." } }, "created_at": { "type": "string", "format": "date-time", "description": "Time the agent was created, in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the agent was last changed, in RFC 3339 format." } }, "required": [ "id", "instance_id", "name", "description", "resource_version", "status", "visibility", "mcp_enabled", "a2a_enabled", "capabilities", "skills", "conversation_transport", "created_at", "updated_at" ], "additionalProperties": false }, "A2AMessage": { "type": "object", "properties": { "messageId": { "type": "string", "description": "ID of the message. The server generates a new ID for every message it renders." }, "role": { "type": "string", "description": "Who wrote the message: `ROLE_USER` for the caller or `ROLE_AGENT` for the agent.", "x-enumDescriptions": { "ROLE_USER": "The message was written by the caller.", "ROLE_AGENT": "The message was written by the agent." } }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/A2AOutputPart" }, "description": "Content of the message as parts, in order. Each part is a text part, a file part or a data part." }, "contextId": { "type": "string", "description": "ID of the context (conversation) the message belongs to. Omitted when it is not set." }, "taskId": { "type": "string", "description": "ID of the task the message belongs to. Omitted when it is not set." }, "referenceTaskIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of other tasks this message refers to. Omitted when there are none." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata attached to the message. Omitted when there is none." } }, "required": [ "messageId", "role", "parts" ], "additionalProperties": false }, "A2ATaskStatus": { "type": "object", "properties": { "state": { "type": "string", "description": "Current state of the task.", "x-enumDescriptions": { "TASK_STATE_SUBMITTED": "The task was created and is waiting for the agent to start. It is also reported once the message has reached the agent.", "TASK_STATE_WORKING": "The agent is processing the task.", "TASK_STATE_COMPLETED": "Final state. The task finished successfully.", "TASK_STATE_FAILED": "Final state. The task finished with an error or timed out.", "TASK_STATE_CANCELED": "Final state. The task was canceled before it finished.", "TASK_STATE_INPUT_REQUIRED": "The task is paused: the agent needs more input from the caller to continue.", "TASK_STATE_REJECTED": "Final state. The agent declined the task.", "TASK_STATE_AUTH_REQUIRED": "The task is paused: the agent needs additional authentication to continue." } }, "message": { "anyOf": [ { "$ref": "#/components/schemas/A2AMessage" }, { "type": "null" } ], "description": "Message that explains the state, such as an error text. It is an agent message with one text part. Omitted when there is nothing to report." }, "timestamp": { "type": "string", "description": "Time of the last update of the task, or its creation time when it was never updated, as a UTC timestamp such as `2026-01-02T15:04:05.000Z`." } }, "required": [ "state" ], "additionalProperties": false }, "A2AArtifact": { "type": "object", "properties": { "artifactId": { "type": "string", "description": "ID of the artifact. When the agent supplies none, the server uses `-a`, counting from 0." }, "name": { "type": "string", "description": "Display name of the artifact. Omitted when it is not set." }, "description": { "type": "string", "description": "Description of the artifact. Omitted when it is not set." }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/A2AOutputPart" }, "description": "Content of the artifact as parts, in order. Each part is a text part, a file part or a data part." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata attached to the artifact. Omitted when there is none." }, "extensions": { "type": "array", "items": { "type": "string" }, "description": "URIs of the protocol extensions that apply to the artifact. Omitted when there are none." } }, "required": [ "artifactId", "parts" ], "additionalProperties": false }, "A2ATextPartOut": { "type": "object", "properties": { "text": { "type": "string", "description": "Text content of the part." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata attached to the part. Omitted when there is none." } }, "required": [ "text" ], "additionalProperties": false }, "A2AFilePartOut": { "type": "object", "properties": { "url": { "type": "string", "description": "URL the file can be fetched from. Omitted when it is not set." }, "filename": { "type": "string", "description": "Name of the file. Omitted when it is not set." }, "mediaType": { "type": "string", "description": "Media type (MIME type) of the file. Omitted when it is not set." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata attached to the part. Omitted when there is none." } }, "required": [], "additionalProperties": false }, "A2ADataPartOut": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JSONValue", "description": "Structured content of the part, as any JSON value." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata attached to the part. Omitted when there is none." } }, "required": [ "data" ], "additionalProperties": false }, "a2aTaskView": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the task." }, "contextId": { "type": "string", "description": "ID of the context (conversation) the task belongs to." }, "status": { "$ref": "#/components/schemas/A2ATaskStatus", "description": "Current status of the task." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/A2AArtifact" }, "description": "Outputs the agent produced for the task. Omitted while there are none." }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/A2AMessage" }, "description": "Messages of the task. A single-task read returns at most `history_length` of them. When no history is stored it holds the original request as one message. Omitted when there are none." }, "metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" }, "description": "Extra metadata of the task. Omitted when there is none." }, "caller_principal_id": { "type": "string", "description": "ID of the principal that submitted the task." }, "caller_agent_id": { "type": "string", "description": "ID of the agent that submitted the task, if any." }, "caller_owner_id": { "type": "string", "description": "ID of the owner of the submitting side. Cloud derives it from the credential's organization and app. Callers do not send an end-user id." }, "target_principal_id": { "type": "string", "description": "ID of the principal the task was sent to." }, "target_agent_id": { "type": "string", "description": "ID of the agent the task was sent to." }, "target_owner_id": { "type": "string", "description": "ID of the owner of the receiving side." }, "channel_id": { "type": "string", "description": "ID of the channel that carries the streaming replies of the task. Omitted when the task does not use channel-based delivery." }, "created_at": { "type": "string", "description": "Time the task was created, as a UTC timestamp such as `2026-01-02T15:04:05.000Z`. Omitted when it is not known." }, "updated_at": { "type": "string", "description": "Time the task was last updated, in the same format as `created_at`. Omitted when it is not known." }, "completed_at": { "type": "string", "description": "Time the task finished, in the same format as `created_at`. Omitted until the task is finished." } }, "required": [ "id", "contextId", "status", "caller_principal_id", "caller_agent_id", "caller_owner_id", "target_principal_id", "target_agent_id", "target_owner_id" ], "additionalProperties": false }, "agentTemplateCatalogView": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the template. Pass it as `template_id` when creating a harness from the template." }, "display_name": { "type": "string", "description": "Display name of the template, in the language of `Accept-Language` when a translation exists." }, "summary": { "type": "string", "description": "One-line summary of what the template is for, localized like `display_name`." }, "description": { "type": "string", "description": "Full description of the template, localized like `display_name`." }, "category": { "type": "string", "description": "Category the template is listed under. Use it as the `category` filter of the list operation." }, "vibe": { "type": "string", "description": "Short phrase describing the personality of the agent the template creates, localized like `display_name`." }, "icon_url": { "type": "string", "description": "URL of the template icon. Empty when the template has none." }, "banner_url": { "type": "string", "description": "URL of the template banner image. Empty when the template has none." }, "default_model": { "type": "string", "description": "ID of the model the template selects as the agent's primary model." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags that describe the template." }, "harness": { "type": "string", "description": "Harness (agent runtime) the template is applied to, for example `openclaw`." }, "template_version": { "type": "string", "description": "Version of the template package, as a semantic version such as `1.2.0`." } }, "required": [ "id", "display_name", "summary", "description", "category", "vibe", "icon_url", "banner_url", "default_model", "tags", "harness", "template_version" ], "additionalProperties": false }, "agentBindWire": { "type": "object", "properties": { "status": { "type": "string", "description": "State of the bind session. After a successful confirmation it is `bound`; a session that is still waiting for confirmation reports `pending`.", "x-enumDescriptions": { "pending": "Created by the device and waiting for a user to confirm it. A session that is being confirmed also reports `pending`.", "bound": "Confirmed: the instance exists and the device can connect to it." } }, "bind_id": { "type": "string", "description": "ID of the bind session." }, "instance_id": { "type": "string", "description": "ID of the instance created for the device. Present once the session is bound." }, "public_key": { "type": "string", "description": "Public key the device registered for the session." }, "hostname": { "type": "string", "description": "Host name the device reported." }, "expires_at": { "type": "integer", "description": "Time the session expires, in Unix seconds." }, "runtime_binding": { "anyOf": [ { "$ref": "#/components/schemas/bindRuntimeWire" }, { "type": "null" } ], "description": "Addresses a bound self-hosted agent connects to. Present once the session is bound." } }, "required": [ "status" ], "additionalProperties": false }, "bindRuntimeWire": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "ID of the instance the agent is bound to." }, "agent_gateway_url": { "type": "string", "description": "Base URL of the API the agent connects to for agent traffic." }, "message_service_url": { "type": "string", "description": "Base URL of the API the agent connects to for messages." } }, "required": [ "instance_id", "agent_gateway_url", "message_service_url" ], "additionalProperties": false }, "agentBindDetailsWire": { "type": "object", "properties": { "bind_id": { "type": "string", "description": "ID of the bind session." }, "hostname": { "type": "string", "description": "Host name the device reported." }, "fingerprint_short": { "type": "string", "description": "First 16 characters of the device key fingerprint. Show it to the user to compare with the device." }, "harness": { "type": "string", "description": "Harness the device runs, as the device reported it." }, "os_type": { "type": "string", "description": "Operating system the device reported. Omitted when it did not report one." }, "expires_at": { "type": "integer", "description": "Time the session expires, in Unix seconds." }, "status": { "type": "string", "description": "State of the bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 `not_found` instead.", "x-enumDescriptions": { "pending": "Created by the device and waiting for a user to confirm it.", "confirming": "A user confirmed it and the instance for the device is being created.", "bound": "Confirmed: the instance exists and the device can connect to it." } }, "server_time": { "type": "integer", "description": "Current server time in Unix seconds. Compare it with `expires_at` to get the remaining time without clock skew." } }, "required": [ "bind_id", "hostname", "fingerprint_short", "harness", "expires_at", "status", "server_time" ], "additionalProperties": false }, "portalBindWire": { "type": "object", "properties": { "provider_id": { "type": "string", "description": "ID of the provider that hosts the instance. Set when a new instance was created for the device." }, "bind_id": { "type": "string", "description": "ID of the bind session. It starts with `portal_`." }, "short_code": { "type": "string", "description": "Short code the user can enter on the device instead of scanning the QR code. It uses uppercase letters and digits without look-alike characters." }, "status": { "type": "string", "description": "State of the portal bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 `not_found` instead.", "x-enumDescriptions": { "pending": "Created and waiting for a device to scan the QR code or enter the short code.", "awaiting_confirmation": "A device claimed the session. Call the resolve operation with `decision` to continue.", "confirming": "The decision `create` was accepted and a new instance is being created for the device.", "bound": "The device is bound to an instance, given by `instance_id`.", "revoked": "Revoked with the revoke operation. A revoked session cannot be claimed or resolved." } }, "instance_id": { "type": "string", "description": "ID of the instance bound to the device. Present once the session is bound." }, "expires_at": { "type": "integer", "description": "Time the session expires, in Unix seconds. A session is valid for 10 minutes." }, "name": { "type": "string", "description": "Display name for the instance created for the device. Defaults to `BeeRunner`." }, "qr_payload": { "type": "string", "description": "Link to encode in the QR code the device scans. Returned only when the session is created." }, "api_base_url": { "type": "string", "description": "Base URL of the API the device connects to. Returned only when the session is created." }, "relay_url": { "type": "string", "description": "URL of the relay the device connects through. Returned only when the session is created." }, "desired_status": { "type": "string", "description": "Lifecycle phase the created instance is driven toward: `running`. Set when a new instance was created for the device." }, "connectivity": { "type": "string", "description": "Reachability of the created instance: `unknown`, `online` or `offline`. Set when a new instance was created for the device." }, "resource_version": { "type": "integer", "description": "Resource version of the created instance. Set when a new instance was created for the device." } }, "required": [ "bind_id", "short_code", "status", "expires_at", "name" ], "additionalProperties": false }, "CreateServerInstanceInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the instance, 1 to 128 bytes, without leading or trailing whitespace." }, "variant_id": { "type": "string", "description": "ID of the catalog variant to create the instance from, at most 128 characters. See the instance template catalog for available variants. An unknown ID returns 404 `variant_not_found`." }, "harness": { "type": "string", "enum": [ "openclaw" ], "description": "Harness to run in the instance. Only `openclaw` is accepted.", "x-enumDescriptions": { "openclaw": "The OpenClaw agent runtime." } }, "llm": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeLLM" }, { "type": "null" } ], "description": "Model providers and models the instance uses. Required when the variant or harness needs caller-supplied models; omit it for variants that supply their own models. Provider API keys are write-only." } }, "required": [ "name" ], "additionalProperties": false }, "ServerUsageSummary": { "type": "object", "properties": { "total_bc": { "type": "string", "description": "Total charge in the period, in BC micros (millionths of a BeeOS Credit, BC), as a decimal string. For example `1500000` is 1.5 BC." }, "total_records": { "type": "integer", "description": "Number of usage records in the period." }, "by_category": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Charge per category in the period, in BC micros as decimal strings, keyed by category. Categories without usage in the period are absent." }, "by_app": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Charge per app in BC micros as decimal strings. Server API keys see only their own app, so this field is not returned to them." }, "category_counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Number of usage records per category in the period, keyed by category. Categories without usage in the period are absent." } }, "required": [ "total_bc", "total_records", "by_category", "category_counts" ], "additionalProperties": false }, "RuntimeInstanceStatusResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the instance." }, "name": { "type": "string", "description": "Display name of the instance." }, "status": { "type": "string", "description": "Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "pending": "The instance was created and is waiting to be provisioned.", "provisioning": "The instance is being provisioned or started.", "running": "The instance is running.", "stopped": "The instance is stopped and can be started again.", "terminated": "The instance was deleted and cannot be used again." } }, "desired_status": { "type": "string", "description": "Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`.", "x-enumDescriptions": { "running": "The instance should be running.", "stopped": "The instance should be stopped.", "terminated": "The instance should be deleted." } }, "connectivity": { "type": "string", "description": "Reachability of the instance's agent: `unknown`, `online` or `offline`.", "x-enumDescriptions": { "unknown": "Reachability has not been determined.", "online": "The instance's agent is connected.", "offline": "The instance's agent is not connected." } } }, "required": [ "id", "name", "status", "desired_status", "connectivity" ], "additionalProperties": false, "description": "Current status of the instance." }, "operation": { "$ref": "#/components/schemas/RuntimeOperationSummary", "description": "Lifecycle operation that this response reports on." } }, "required": [ "data", "operation" ], "additionalProperties": false }, "UpdateServerInstanceInput": { "type": "object", "properties": { "name": { "type": "string", "description": "New display name, 1 to 128 characters, without leading or trailing whitespace. Send `name`, `llm` or both." }, "llm": { "$ref": "#/components/schemas/RuntimeLLM", "description": "Replacement model providers and models. It replaces the whole existing llm block. Provider API keys are write-only. When `name` is also sent, the llm block is replaced first." } }, "required": [], "additionalProperties": false }, "FileShareResponse": { "type": "object", "properties": { "file_id": { "type": "string", "description": "ID of the shared file." }, "slug": { "type": "string", "description": "Public slug of the share. Pass it to the resolve-share operation to get the file." }, "filename": { "type": "string", "description": "Current name of the shared file." }, "content_type": { "type": "string", "description": "MIME type of the shared file." }, "size_bytes": { "type": "integer", "description": "Size of the shared file in bytes." }, "revoked": { "type": "boolean", "description": "True when the share was revoked. A revoked share can no longer be resolved. Creating the share again turns it back on." } }, "required": [ "file_id", "slug", "filename", "content_type", "size_bytes", "revoked" ], "additionalProperties": false }, "ReplyShareResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slug": { "type": "string", "description": "Public slug that identifies the share." }, "created_at": { "type": "string", "description": "Time the share was created." }, "agent": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the agent." }, "avatar_url": { "type": "string", "description": "URL of the agent's avatar." }, "framework": { "type": "string", "description": "Agent framework of the instance the agent runs on." } }, "required": [ "name", "avatar_url", "framework" ], "additionalProperties": false, "description": "The agent that wrote the reply." }, "reply": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Always `text`." }, "text": { "type": "string", "description": "Text of the reply." } }, "required": [ "type", "text" ], "additionalProperties": false }, "description": "Content of the reply. It holds one part of type `text`." }, "created_at": { "type": "string", "description": "Time the reply message was created." } }, "required": [ "parts", "created_at" ], "additionalProperties": false, "description": "The shared reply." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the source." }, "title": { "type": "string", "description": "Title of the source, when the agent provided one." } }, "required": [], "additionalProperties": false }, "description": "Web sources the reply cites. Only `https` sources are listed. Each source is returned with `url`, `domain` (its host name) and, when the agent provided one, `title`." }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "Reserved. The server does not currently return this field; a file is identified by `public_url`." }, "filename": { "type": "string", "description": "Reserved. The server does not currently return this field; the file name is returned as `name`." }, "content_type": { "type": "string", "description": "Reserved. The server does not currently return this field; the MIME type is returned as `mime_type`." }, "size_bytes": { "type": "integer", "description": "Reserved. The server does not currently return this field." } }, "required": [], "additionalProperties": false }, "description": "Files the reply links to. Only files published by BeeOS are listed. Each file is returned with `name`, `public_url` and, when known, `mime_type`." } }, "required": [ "slug", "created_at", "agent", "reply", "sources", "files" ], "additionalProperties": false, "description": "The shared reply." } }, "required": [ "data" ], "additionalProperties": false }, "ConnectURLResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to connect to. For `browser` it is the browser viewer URL; for `acp` it is a WebSocket URL that already carries the access ticket as a query parameter." }, "mode": { "type": "string", "description": "Connection mode: `browser-runtime` for `browser`, `service-websocket` for `acp`.", "x-enumDescriptions": { "browser-runtime": "A browser viewer session; connect with `url` and `token`.", "service-websocket": "A WebSocket connection to an agent service; `url` already carries the access ticket." } }, "token": { "type": "string", "description": "Short-lived access token for the browser viewer. Not returned for `acp`." }, "service": { "type": "string", "description": "Service the URL connects to: `browser` or `acp`.", "x-enumDescriptions": { "browser": "The browser viewer.", "acp": "The agent connection over WebSocket." } }, "connectivity": { "type": "string", "description": "Reachability of the instance's agent: `unknown`, `online` or `offline`.", "x-enumDescriptions": { "unknown": "Reachability has not been determined.", "online": "The instance's agent is connected.", "offline": "The instance's agent is not connected." } }, "stream_session_id": { "type": "string", "description": "ID of the viewing client session, the `client_id` sent in the request. Not returned for `acp`." }, "browser": { "type": "object", "properties": { "grant_id": { "type": "string", "description": "ID of the browser access grant." }, "generation": { "type": "string", "description": "Generation of the browser the grant is bound to. When `generation` was sent in the request, it equals that value." }, "expires_at": { "type": "string", "description": "Time the access grant expires, in Unix milliseconds." }, "role": { "type": "string", "description": "Access role of the grant: `viewer` or `controller`.", "x-enumDescriptions": { "viewer": "Can watch the browser but not control it.", "controller": "Can watch and control the browser." } } }, "required": [ "grant_id", "generation", "expires_at", "role" ], "additionalProperties": false, "description": "Browser access grant. Returned only for `browser`." } }, "required": [ "url", "mode", "token", "service", "connectivity", "stream_session_id" ], "additionalProperties": false, "description": "Connection details for the requested service." } }, "required": [ "data" ], "additionalProperties": false }, "ProtoAutomationRule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the automation." }, "name": { "type": "string", "description": "Display name of the automation." }, "prompt": { "type": "string", "description": "Text sent to the agent on every run." }, "target": { "$ref": "#/components/schemas/ProtoAutomationTarget", "description": "Agent the prompt is sent to." }, "schedule": { "$ref": "#/components/schemas/ProtoAutomationSchedule", "description": "When the automation runs. Empty (`kind` unset) for `webhook` automations." }, "session": { "$ref": "#/components/schemas/ProtoAutomationSession", "description": "How runs choose their conversation. Automations created through this API always use `new`." }, "validFrom": { "type": "string", "format": "date-time", "description": "Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no lower bound." }, "validUntil": { "type": "string", "format": "date-time", "description": "Latest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no upper bound." }, "status": { "type": "string", "description": "State of the automation.", "x-enumDescriptions": { "enabled": "Active. A `schedule` automation runs at `nextFireAt`; a `webhook` automation reacts to incoming events.", "paused": "Paused with the pause operation. No runs are created until it is resumed.", "expired": "A `schedule` automation with no run left, for example a finished `at` schedule or one past `validUntil`." } }, "nextFireAt": { "type": "string", "format": "date-time", "description": "Time of the next scheduled run, as an RFC 3339 timestamp. Null when the automation is paused or expired and for `webhook` automations." }, "createdInConversationId": { "type": "string", "description": "ID of the conversation the automation was created from. Empty when it was not created from a conversation." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time the automation was created, as an RFC 3339 timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Time the automation was last changed, as an RFC 3339 timestamp." }, "triggerKind": { "type": "string", "description": "What starts a run. Automations created before webhook triggers existed can report an empty value; treat it as `schedule`.", "x-enumDescriptions": { "schedule": "Runs start on the `schedule`.", "webhook": "Runs start when the event source delivers an event, optionally narrowed by `eventFilter`." } }, "hookId": { "type": "string", "description": "ID of the endpoint that receives the events of a `webhook` automation. Empty for `schedule` automations and for Gmail automations." }, "source": { "type": "string", "description": "Platform that sends the events of a `webhook` automation, for example `github` or `gmail`. Empty for `schedule` automations." }, "eventFilter": { "type": "string", "description": "Event type that starts a run of a `webhook` automation. Empty when every event starts a run." }, "mailbox": { "type": "string", "description": "Gmail address a `webhook` automation watches. Empty for other sources." } }, "required": [], "additionalProperties": false }, "ProtoAutomationTarget": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "ID of the instance the automation runs on." }, "agentId": { "type": "string", "description": "ID of the agent that receives the prompt. It must be an active agent of `instanceId` in your app. Required." } }, "required": [], "additionalProperties": false }, "ProtoAutomationSchedule": { "type": "object", "properties": { "kind": { "type": "string", "description": "Type of the schedule. It decides which of the other fields are required.", "x-enumDescriptions": { "at": "Runs once, at `at`.", "every": "Runs repeatedly, every `intervalSeconds` seconds counted from `anchorAt`.", "cron": "Runs on the five-field cron `expression`, evaluated in the time zone `tz`." } }, "tz": { "type": "string", "description": "IANA time zone name, for example `Asia/Shanghai`. Required for every kind; `Local` is not accepted." }, "at": { "type": "string", "format": "date-time", "description": "Time of the single run, as an RFC 3339 timestamp. Required when `kind` is `at`; not allowed for other kinds." }, "intervalSeconds": { "type": "string", "description": "Seconds between runs, as a decimal string. Required and greater than 0 when `kind` is `every`; not allowed for other kinds." }, "anchorAt": { "type": "string", "format": "date-time", "description": "Time the interval is counted from, as an RFC 3339 timestamp: runs fall on `anchorAt` plus whole multiples of the interval. When creating an `every` schedule it defaults to the creation time; when replacing a schedule it is required. Not allowed for other kinds." }, "expression": { "type": "string", "description": "Five-field cron expression: minute, hour, day of month, month and day of week. Required when `kind` is `cron`; not allowed for other kinds." } }, "required": [], "additionalProperties": false }, "ProtoAutomationSession": { "type": "object", "properties": { "mode": { "type": "string", "description": "How a run chooses the conversation it is delivered into.", "x-enumDescriptions": { "new": "Every run opens a new conversation with the agent. Automations created through this API always use it.", "bound": "Every run is delivered into the conversation named by `boundConversationId`." } }, "boundConversationId": { "type": "string", "description": "ID of the conversation runs are delivered into. Set only when `mode` is `bound`; empty otherwise." } }, "required": [], "additionalProperties": false }, "ProtoAutomationInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the automation, 1 to 256 characters and not blank." }, "prompt": { "type": "string", "description": "Text sent to the agent on every run, up to 65536 bytes and not blank." }, "target": { "$ref": "#/components/schemas/ProtoAutomationTarget", "description": "Agent the prompt is sent to. Required." }, "schedule": { "$ref": "#/components/schemas/ProtoAutomationSchedule", "description": "When the automation runs. Required." }, "session": { "$ref": "#/components/schemas/ProtoAutomationSession", "description": "Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run." }, "validFrom": { "type": "string", "format": "date-time", "description": "Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. It must not be after `validUntil`." }, "validUntil": { "type": "string", "format": "date-time", "description": "Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. After it the automation becomes `expired`." }, "createdInConversationId": { "type": "string", "description": "ID of the conversation the automation is created from, if any. It must be a conversation of the same end user." } }, "required": [], "additionalProperties": false }, "ProtoListAutomationsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProtoAutomationRule" }, "description": "Automations on this page." }, "nextCursor": { "type": "string", "description": "Cursor to pass as `cursor` to get the next page. Empty when there are no more automations." } }, "required": [], "additionalProperties": false }, "ProtoAutomationPatch": { "type": "object", "properties": { "name": { "type": "string", "description": "New display name, 1 to 256 characters and not blank." }, "prompt": { "type": "string", "description": "New prompt sent to the agent on every run, up to 65536 bytes and not blank." }, "target": { "$ref": "#/components/schemas/ProtoAutomationTarget", "description": "New agent the prompt is sent to." }, "schedule": { "$ref": "#/components/schemas/ProtoAutomationSchedule", "description": "New schedule. It replaces the whole schedule, so send every field the `kind` needs, including `anchorAt` for `every`." }, "session": { "$ref": "#/components/schemas/ProtoAutomationSession", "description": "Not accepted by this API: a request that includes it fails with 400 `invalid_argument`." }, "validFrom": { "type": "string", "format": "date-time", "description": "New earliest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidFrom`." }, "validUntil": { "type": "string", "format": "date-time", "description": "New latest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidUntil`." }, "clearValidFrom": { "type": "boolean", "description": "Set to true to remove the lower bound of the validity period. Cannot be combined with `validFrom`." }, "clearValidUntil": { "type": "boolean", "description": "Set to true to remove the upper bound of the validity period. Cannot be combined with `validUntil`." } }, "required": [], "additionalProperties": false }, "ProtoAutomationRun": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the run." }, "automationId": { "type": "string", "description": "ID of the automation the run belongs to." }, "triggerType": { "type": "string", "description": "What created the run.", "x-enumDescriptions": { "schedule": "The automation's schedule came due.", "manual": "A caller started it with the create-run operation.", "rerun": "A caller started it with the create-run operation to repeat the earlier run in `sourceRunId`.", "webhook": "An event arrived for a `webhook` automation." } }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Time the run was due, as an RFC 3339 timestamp: the scheduled time for scheduled runs, the time of the request or event for the others." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time the run was created, as an RFC 3339 timestamp." }, "status": { "type": "string", "description": "Delivery state of the run. It tells whether the prompt reached the agent's conversation, not whether the agent finished the work.", "x-enumDescriptions": { "scheduled": "Created and waiting to be delivered. A `reasonCode` of `dispatch_unconfirmed` means delivery started and its outcome is not confirmed yet.", "dispatched": "The prompt was accepted into the conversation named by `conversationId`.", "failed": "Delivery was rejected before the prompt was sent. `reasonCode` tells why.", "skipped": "Not delivered because a condition no longer held when the run was due. `reasonCode` tells why." } }, "target": { "$ref": "#/components/schemas/ProtoAutomationTarget", "description": "Agent the run delivers to, copied from the automation when the run was created." }, "session": { "$ref": "#/components/schemas/ProtoAutomationSession", "description": "How the run chooses its conversation, copied from the automation when the run was created. A rerun sets it from `rerunSessionMode`." }, "conversationId": { "type": "string", "description": "ID of the conversation the prompt is delivered into. Empty until the run is bound to a conversation." }, "wakeMessageId": { "type": "string", "description": "ID of the conversation message that carries the prompt. It equals the run `id`." }, "sourceRunId": { "type": "string", "description": "ID of the run this run repeats. Set only for reruns." }, "rerunSessionMode": { "type": "string", "description": "Which conversation a rerun is delivered into. Empty for runs that are not reruns.", "x-enumDescriptions": { "original": "The conversation the source run was delivered into.", "new": "A new conversation." } }, "reasonCode": { "type": "string", "description": "Why a run was skipped or failed, or is unconfirmed. Empty otherwise and after the prompt was accepted. Skip reasons include `outside_validity`, `missed_schedule` (the run was not delivered within its window), `automation_paused`, `automation_deleted` and `preparation_stale` (the agent or session of the automation changed after the run was created). A failed run carries an API error code such as `target_not_found`, `permission_denied`, `conversation_unavailable` or `dependency_unavailable`. `dispatch_unconfirmed` means delivery started and its outcome is unknown. New codes can be added, so ignore codes you do not know." }, "dispatchedAt": { "type": "string", "format": "date-time", "description": "Time the prompt was accepted, as an RFC 3339 timestamp. Null until `status` is `dispatched`." } }, "required": [], "additionalProperties": false }, "ProtoAutomationRunInput": { "type": "object", "properties": { "sourceRunId": { "type": "string", "description": "ID of an earlier run of the same automation to repeat. Send it together with `rerunSessionMode`, or send neither for a plain manual run." }, "rerunSessionMode": { "type": "string", "description": "Which conversation the rerun is delivered into. Required when `sourceRunId` is sent and not allowed without it.", "x-enumDescriptions": { "original": "The conversation the source run was delivered into.", "new": "A new conversation." } } }, "required": [], "additionalProperties": false }, "ProtoListAutomationRunsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProtoAutomationRun" }, "description": "Runs on this page." }, "nextCursor": { "type": "string", "description": "Cursor to pass as `cursor` to get the next page. Empty when there are no more runs." } }, "required": [], "additionalProperties": false }, "ProtoAutomationWebhookInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the automation, 1 to 256 characters and not blank." }, "prompt": { "type": "string", "description": "Text sent to the agent on every run, up to 65536 bytes and not blank." }, "target": { "$ref": "#/components/schemas/ProtoAutomationTarget", "description": "Agent the prompt is sent to. Required." }, "session": { "$ref": "#/components/schemas/ProtoAutomationSession", "description": "Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run." }, "validFrom": { "type": "string", "format": "date-time", "description": "Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound." }, "validUntil": { "type": "string", "format": "date-time", "description": "Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound." }, "createdInConversationId": { "type": "string", "description": "ID of the conversation the automation is created from, if any. It must be a conversation of the same end user." }, "source": { "type": "string", "description": "Platform that sends the events, for example `github` or `gmail`, at most 64 characters without whitespace. The agent must have the matching connector set up. Required." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Names of the events to subscribe to at the source, for example the GitHub event types the repository should deliver." }, "repoOwner": { "type": "string", "description": "Owner of the repository to watch. Required when `source` is `github`." }, "repoName": { "type": "string", "description": "Name of the repository to watch. Required when `source` is `github`." }, "eventFilter": { "type": "string", "description": "Event type that starts a run. When set, only events of exactly this type start a run; others are skipped. Empty accepts every event." }, "mailbox": { "type": "string", "description": "Gmail address to watch. Required when `source` is `gmail`; leave empty for other sources." } }, "required": [], "additionalProperties": false }, "RuntimeMethodResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ], "description": "JSON-RPC protocol version: always `2.0`.", "x-enumDescriptions": { "2.0": "JSON-RPC version 2.0." } }, "id": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "description": "ID of the request that this response answers. It is `null` when the request could not be read." }, "result": { "$ref": "#/components/schemas/JSONValue", "description": "Result of the method. Present only on success; its shape depends on the method." }, "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code. `-32700` parse error, `-32600` invalid request, `-32601` method not found, `-32602` invalid params, `-32603` internal error, `-32001` task not found, `-32002` task not cancelable, `-32003` push notifications not supported, `-32004` unsupported operation, `-32005` content type not supported, `-32006` invalid agent response, `-32007` agent card not configured, `-32008` agent busy, `-32009` incompatible `A2A-Version`, `-32010` the connection dropped after the task was dispatched (read the task instead of sending it again), `-32011` task timed out, `-32012` the connection dropped before dispatch (nothing ran; safe to retry)." }, "message": { "type": "string", "description": "Human-readable description of the error." }, "data": { "$ref": "#/components/schemas/JSONValue", "description": "Machine-readable detail of the error: a list with one object of type `type.googleapis.com/google.rpc.ErrorInfo`. Its `reason` is the error name, for example `TASK_NOT_FOUND`, and its `metadata` repeats the `code` and `message`." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error of the call. Present only on failure." } }, "required": [ "jsonrpc", "id" ], "additionalProperties": false, "description": "JSON-RPC 2.0 response. It carries `result` on success and `error` on failure, never both. Errors are returned with HTTP status 200." }, "CanvasShare": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the share." }, "canvasId": { "type": "string", "description": "ID of the canvas that is shared. A canvas has at most one share." }, "slug": { "type": "string", "description": "Public identifier of the share, used to build the share link. It stays the same when the share is updated." }, "mode": { "type": "string", "description": "How visitors get access. `password` requires visitors to enter the password set when the share was created. Any other value, for example `link`, lets anyone who has the link open the canvas." }, "allowInteraction": { "type": "boolean", "description": "Whether visitors can interact with the canvas. When false, visitors can only view it." }, "expiresAt": { "type": "string", "description": "Time the share stops working, as an RFC 3339 timestamp. Omitted when the share does not expire; shares created through this API never expire." }, "createdAt": { "type": "string", "description": "Time the share was first created, as an RFC 3339 timestamp. Updating the share does not change it." } }, "required": [ "id", "canvasId", "slug", "mode", "allowInteraction", "createdAt" ], "additionalProperties": false }, "CanvasSnapshot": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the snapshot. Pass it to the restore operation." }, "canvasId": { "type": "string", "description": "ID of the canvas the snapshot belongs to." }, "componentsSnapshot": { "type": "string", "contentEncoding": "base64", "description": "Content of the canvas when the snapshot was taken, as base64-encoded JSON: an array of surfaces, each with `surfaceId`, `presentation`, `components` and `root`. Omitted when no content was captured." }, "actorType": { "type": "string", "description": "Kind of actor that made most of the changes recorded by the snapshot: `user` for a person (restore points are also recorded as `user`), `agent` for an agent, or `system` for an automatic snapshot with no known actor." }, "actorId": { "type": "string", "description": "ID of the actor named by `actorType`. `system` for automatic snapshots with no known actor." }, "description": { "type": "string", "description": "Short note about the snapshot, for example `Auto-snapshot` for automatic snapshots or `Restored from v3` for a restore point. Omitted when there is none." }, "version": { "type": "integer", "description": "Version of the canvas content the snapshot records. A higher number is newer." }, "createdAt": { "type": "string", "description": "Time the snapshot was taken, as an RFC 3339 timestamp." } }, "required": [ "id", "canvasId", "actorType", "actorId", "version", "createdAt" ], "additionalProperties": false }, "A2AAgentCard": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the agent." }, "description": { "type": "string", "description": "Description of the agent." }, "url": { "type": "string", "description": "URL of the agent's JSON-RPC endpoint. Returned only when the request sends `A2A-Version: 0.3`; version 1.0 lists the endpoint in `supportedInterfaces`." }, "version": { "type": "string", "description": "Version of the agent: its resource version, a decimal number." }, "protocolVersion": { "type": "string", "description": "A2A protocol version spoken at `url`. Returned only when the request sends `A2A-Version: 0.3`." }, "defaultInputModes": { "type": "array", "items": { "type": "string" }, "description": "Media types the agent accepts as input, for example `text/plain`." }, "defaultOutputModes": { "type": "array", "items": { "type": "string" }, "description": "Media types the agent produces as output, for example `text/plain`." }, "supportedInterfaces": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the interface." }, "protocolBinding": { "type": "string", "description": "Transport the interface uses: `JSONRPC`." }, "protocolVersion": { "type": "string", "description": "A2A protocol version the interface speaks." } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "description": "Interfaces through which the agent can be reached. Returned unless the request sends `A2A-Version: 0.3`." } }, "required": [ "name", "description", "version", "defaultInputModes", "defaultOutputModes" ], "additionalProperties": false }, "A2AOutputPart": { "oneOf": [ { "$ref": "#/components/schemas/A2ATextPartOut" }, { "$ref": "#/components/schemas/A2AFilePartOut" }, { "$ref": "#/components/schemas/A2ADataPartOut" } ], "description": "One piece of content in a message or artifact. It is a text part (`text`), a file part (`url`, `filename`, `mediaType`) or a data part (`data`); which one is told by the field it carries." }, "RealtimeTicketHeader": { "type": "object", "properties": { "alg": { "type": "string", "description": "Signature algorithm of the ticket: `RS256`." }, "typ": { "type": "string", "description": "Token type: `JWT`." }, "kid": { "type": "string", "description": "ID of the key that signed the ticket." } }, "required": [ "alg", "typ", "kid" ], "additionalProperties": false }, "TerminalTicketClaims": { "type": "object", "properties": { "iss": { "type": "string", "description": "Issuer of the ticket." }, "aud": { "type": "string", "description": "Audience the ticket is intended for: the terminal service." }, "sub": { "type": "string", "description": "Unused. Cloud does not accept an external user id, so this claim is empty." }, "jti": { "type": "string", "description": "Unique ID of the ticket." }, "instance_id": { "type": "string", "description": "ID of the instance the terminal belongs to." }, "platform_agent_id": { "type": "string", "description": "ID of the agent the terminal session is for, the `platformAgentId` of the request." }, "client_id": { "type": "string", "description": "ID generated for this terminal client connection." }, "conversation_id": { "type": "string", "description": "ID of the conversation the terminal is attached to. Present only when the request sent `conversationId`." }, "resume_terminal_id": { "type": "string", "description": "ID of the terminal to resume. Present only when the request sent `resumeTerminalId`." }, "iat": { "type": "integer", "description": "Time the ticket was issued, in Unix seconds." }, "exp": { "type": "integer", "description": "Time the ticket expires, in Unix seconds." } }, "required": [ "iss", "aud", "sub", "jti", "iat", "exp", "instance_id", "platform_agent_id", "client_id" ], "additionalProperties": false }, "CanvasTicketClaims": { "type": "object", "properties": { "iss": { "type": "string", "description": "Issuer of the ticket." }, "sub": { "type": "string", "description": "Unused. Cloud does not accept an external user id, so this claim is empty." }, "jti": { "type": "string", "description": "Unique ID of the ticket." }, "purpose": { "type": "string", "description": "Purpose of the ticket: always `canvas_session`." }, "instance_id": { "type": "string", "description": "ID of the instance the canvas belongs to." }, "platform_agent_id": { "type": "string", "description": "ID of the agent the canvas session is for, the `platformAgentId` of the request." }, "client_id": { "type": "string", "description": "ID generated for this relay client connection." }, "conversation_id": { "type": "string", "description": "ID of the conversation the canvas belongs to, the `conversationId` of the request." }, "canvas_id": { "type": "string", "description": "ID of the canvas the ticket grants access to." }, "role": { "type": "string", "description": "Access role granted on the canvas: `viewer` or `editor`.", "x-enumDescriptions": { "viewer": "Can view the canvas but not change it.", "editor": "Can view and edit the canvas." } }, "session_id": { "type": "string", "description": "ID of the realtime session created for this ticket." }, "aud": { "type": "array", "items": { "type": "string" }, "description": "Audiences the ticket is intended for: the canvas relay." }, "iat": { "type": "integer", "description": "Time the ticket was issued, in Unix seconds." }, "exp": { "type": "integer", "description": "Time the ticket expires, in Unix seconds." } }, "required": [ "iss", "sub", "jti", "purpose", "instance_id", "platform_agent_id", "client_id", "conversation_id", "canvas_id", "role", "session_id", "aud", "iat", "exp" ], "additionalProperties": false }, "TerminalSessionDocument": { "type": "object", "properties": { "transport": { "type": "string", "description": "How the ticket connects: always `service-websocket`." }, "protocolVersion": { "type": "integer", "description": "Version of the ticket protocol. Currently 1." }, "header": { "$ref": "#/components/schemas/RealtimeTicketHeader", "description": "Header of the signed ticket." }, "websocketUrl": { "type": "string", "description": "WebSocket URL to open the terminal connection on. It already carries the ticket as a query parameter." }, "ticket": { "type": "string", "description": "Signed single-use ticket (a JWT) that authorizes one terminal connection. It is valid for 60 seconds." }, "issuedAt": { "type": "string", "format": "date-time", "description": "Time the ticket was issued, as an RFC 3339 timestamp." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time the ticket expires, as an RFC 3339 timestamp. Tickets are valid for 60 seconds." }, "claims": { "$ref": "#/components/schemas/TerminalTicketClaims", "description": "Claims contained in the signed ticket." } }, "required": [ "transport", "protocolVersion", "header", "websocketUrl", "ticket", "issuedAt", "expiresAt", "claims" ], "additionalProperties": false }, "CanvasSessionDocument": { "type": "object", "properties": { "transport": { "type": "string", "description": "How the ticket connects: always `relay`." }, "protocolVersion": { "type": "integer", "description": "Version of the ticket protocol. Currently 1." }, "header": { "$ref": "#/components/schemas/RealtimeTicketHeader", "description": "Header of the signed ticket." }, "relayUrl": { "type": "string", "description": "WebSocket URL of the canvas relay for the canvas, ending in `/ws/{canvasId}`." }, "ticket": { "type": "string", "description": "Signed single-use ticket (a JWT) that authorizes one relay connection. It is valid for 60 seconds." }, "issuedAt": { "type": "string", "format": "date-time", "description": "Time the ticket was issued, as an RFC 3339 timestamp." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Time the ticket expires, as an RFC 3339 timestamp. Tickets are valid for 60 seconds." }, "claims": { "$ref": "#/components/schemas/CanvasTicketClaims", "description": "Claims contained in the signed ticket." } }, "required": [ "transport", "protocolVersion", "header", "relayUrl", "ticket", "issuedAt", "expiresAt", "claims" ], "additionalProperties": false }, "DeviceBindingErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code. Device-bind routes return `invalid_request`, `unauthorized`, `not_found`, `conflict`, `binding_unavailable` or `bridge_unavailable`. Other codes can be returned for authentication and instance errors, so ignore codes you do not know." }, "message": { "type": "string", "description": "Human-readable explanation of the error. Do not parse it." } }, "required": [ "error", "message" ], "additionalProperties": false } }, "responses": { "Unauthorized": { "description": "Missing, malformed or unknown credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "NotFound": { "description": "No such object in the caller's scope. Servers return 404 rather than 403 for objects outside\nthe caller's scope, so that an id's existence is not disclosed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "Conflict": { "description": "`session_busy` or `harness_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "UnprocessableEntity": { "description": "`model_unavailable` or `unsupported_base`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } }, "RateLimited": { "description": "`rate_limited` or `quota_exhausted`", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UHPErrorEnvelope" } } } } }, "securitySchemes": { "ServerAPIKey": { "type": "http", "scheme": "bearer", "description": "BeeOS Server API key (bsk_)." } }, "headers": { "UHPVersion": { "description": "The protocol version actually used to serve this response.", "required": true, "schema": { "type": "string", "examples": [ "2026-08-11" ] } } }, "x-variantSchemas": { "ClientSessionInputWeb": { "type": "object", "description": "Request for a token bound to a web page origin.", "properties": { "client_type": { "type": "string", "description": "Always `web`." }, "origin": { "type": "string", "format": "uri", "description": "Origin of the web page that will use the token, for example `https://app.example.com`. Required when `client_type` is `web`, and it must exactly match one of the allowed origins configured for the app; otherwise the request returns 403 `invalid_origin`. Not allowed when `client_type` is `native`, which also returns 403 `invalid_origin`." }, "requested_capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Operations the client token may perform on the Client API, 1 or more distinct names. Each name must be one of `context:read`, `instances:read`, `instances:write`, `agents:read`, `agents:invoke`, `files:read`, `files:write`, `files:delete`, `events:read`, `viewer:connect` and `terminal:connect`, and must be allowed for your app's clients. Any other name returns 403 `invalid_capability`." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 1800, "default": 600, "description": "Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request." } }, "required": [ "client_type", "origin", "requested_capabilities" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "ClientSessionInputNative": { "type": "object", "description": "Request for a token bound to a device key.", "properties": { "client_type": { "type": "string", "description": "Always `native`." }, "device_attestation": { "type": "object", "required": [ "jkt" ], "properties": { "jkt": { "type": "string", "minLength": 16, "description": "Thumbprint of the device's public key, the base64url-encoded SHA-256 JWK thumbprint, at least 16 characters. Later Client API requests must be signed with the matching private key." } }, "additionalProperties": false, "description": "Proof of the device key the token is bound to. Required when `client_type` is `native`; not allowed when `client_type` is `web`, which returns 403 `invalid_origin`." }, "requested_capabilities": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Operations the client token may perform on the Client API, 1 or more distinct names. Each name must be one of `context:read`, `instances:read`, `instances:write`, `agents:read`, `agents:invoke`, `files:read`, `files:write`, `files:delete`, `events:read`, `viewer:connect` and `terminal:connect`, and must be allowed for your app's clients. Any other name returns 403 `invalid_capability`." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 1800, "default": 600, "description": "Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request." } }, "required": [ "client_type", "device_attestation", "requested_capabilities" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "BindingWeb": { "type": "object", "description": "Binding of a token to a web page origin.", "properties": { "client_type": { "type": "string", "description": "Always `web`." }, "origin": { "type": "string", "format": "uri", "description": "Origin the token is bound to. Returned when `client_type` is `web`." } }, "required": [ "client_type", "origin" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "BindingNative": { "type": "object", "description": "Binding of a token to a device key.", "properties": { "client_type": { "type": "string", "description": "Always `native`." }, "cnf_jkt": { "type": "string", "description": "Thumbprint of the device key the token is bound to. Returned when `client_type` is `native`." } }, "required": [ "client_type", "cnf_jkt" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentChatMessage": { "type": "object", "description": "Content of a prompt sent to the agent.", "properties": { "message": { "type": "string", "description": "Text of the prompt." } }, "required": [ "message" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentAgentReply": { "type": "object", "description": "Content of an agent reply. A successful reply carries `text`; a failed one carries `error`.", "properties": { "text": { "type": "string", "description": "Text of the reply." }, "error": { "type": "string", "description": "Error message when the reply is a failure." } }, "required": [], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentAgentRefuse": { "type": "object", "description": "Content of a message in which the agent declines the task.", "properties": { "reason": { "type": "string", "description": "Why the agent declined, for example `agent_busy`." }, "message": { "type": "string", "description": "Readable explanation." } }, "required": [], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentChatCancel": { "type": "object", "description": "Content of a request to stop the agent's turn.", "properties": { "target_message_id": { "type": "string", "description": "ID of the `chat_message` whose turn should stop." }, "reason": { "type": "string", "description": "Why the turn should stop: `canceled`, `caller_disconnected` or `timeout`." } }, "required": [ "target_message_id" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentDeviceCommand": { "type": "object", "description": "Content of a device tool call.", "properties": { "tool": { "type": "string", "description": "Name of the device tool to run, for example `screenshot`, `click` or `tap`." }, "args": { "description": "Arguments of the tool; they depend on the tool.", "$ref": "#/components/schemas/JSONValue" }, "channel_id": { "type": "string", "description": "ID of the conversation the command belongs to." }, "context_id": { "type": "string", "description": "ID of the conversation the command belongs to." } }, "required": [], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessageContentDeviceError": { "type": "object", "description": "Content of the failure of a device tool call.", "properties": { "error": { "type": "string", "description": "Readable error message." }, "code": { "type": "string", "description": "Kind of failure reported by the device tool, for example `unsupported`, `invalid_args` or `internal_error`." } }, "required": [], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartText": { "type": "object", "description": "A piece of the reply text.", "properties": { "type": { "type": "string", "description": "Always `text`." }, "text": { "type": "string", "description": "The text." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartThinking": { "type": "object", "description": "A piece of the agent's reasoning.", "properties": { "type": { "type": "string", "description": "Always `thinking`." }, "text": { "type": "string", "description": "The reasoning text." }, "state": { "type": "string", "description": "Whether the reasoning is still being written.", "x-enumDescriptions": { "streaming": "The part is still being written.", "done": "The part is complete. A missing state also means done." } } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartToolUse": { "type": "object", "description": "A tool call made by the agent.", "properties": { "type": { "type": "string", "description": "Always `tool_use`." }, "id": { "type": "string", "description": "ID of the tool call. A `tool_result` part refers to it with `tool_use_id`." }, "name": { "type": "string", "description": "Name of the tool." }, "arguments": { "$ref": "#/components/schemas/JSONValue", "description": "Arguments of the call as JSON." }, "state": { "type": "string", "description": "Whether the arguments are still being written.", "x-enumDescriptions": { "streaming": "The part is still being written.", "done": "The part is complete. A missing state also means done." } } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartToolResult": { "type": "object", "description": "The result of a tool call.", "properties": { "type": { "type": "string", "description": "Always `tool_result`." }, "tool_use_id": { "type": "string", "description": "ID of the `tool_use` part this result belongs to." }, "content": { "$ref": "#/components/schemas/JSONValue", "description": "Result of the tool: a JSON object or a plain string." }, "is_error": { "type": "boolean", "description": "Whether the tool call failed." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartFile": { "type": "object", "description": "A file attached to the message. Images, audio and video are all `file` parts; tell them apart by `mime_type`.", "properties": { "type": { "type": "string", "description": "Always `file`." }, "url": { "type": "string", "description": "URL of the file." }, "mime_type": { "type": "string", "description": "MIME type of the file, for example `image/png`." }, "name": { "type": "string", "description": "File name." }, "size": { "type": "integer", "format": "int64", "description": "Size of the file in bytes." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartSource": { "type": "object", "description": "A cited source or reference.", "properties": { "type": { "type": "string", "description": "Always `source`." }, "url": { "type": "string", "description": "URL of the source." }, "title": { "type": "string", "description": "Title of the source." }, "snippet": { "type": "string", "description": "Excerpt of the source." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "MessagePartCustom": { "type": "object", "description": "An extension part for structured content that has no dedicated type. `kind` says what the part is.", "properties": { "type": { "type": "string", "description": "Always `custom`." }, "kind": { "type": "string", "description": "What kind of custom part this is." }, "data": { "$ref": "#/components/schemas/JSONValue", "description": "Payload of the part as JSON; it depends on `kind`." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventResponse": { "type": "object", "description": "A response lifecycle event that carries a snapshot of the response.", "properties": { "type": { "type": "string", "description": "One of `response.created`, `response.in_progress`, `response.completed`, `response.incomplete`, `response.failed`." }, "response": { "$ref": "#/components/schemas/UHPResponse", "description": "Snapshot of the response. Present on lifecycle events." } }, "required": [ "type", "response" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventOutputItem": { "type": "object", "description": "An output item started or finished.", "properties": { "type": { "type": "string", "description": "One of `response.output_item.added`, `response.output_item.done`." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "item": { "$ref": "#/components/schemas/UHPOutputItem", "description": "The output item. Present on `response.output_item.added` and `response.output_item.done`." } }, "required": [ "type", "output_index", "item" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventContentPart": { "type": "object", "description": "A content part of a `message` item was added or finished.", "properties": { "type": { "type": "string", "description": "One of `response.content_part.added`, `response.content_part.done`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "content_index": { "type": "integer", "minimum": 0, "description": "Index of the content part within the item." }, "part": { "$ref": "#/components/schemas/UHPContentPart", "description": "The content or summary part. Present on content part and reasoning summary part events." } }, "required": [ "type", "item_id", "output_index", "content_index", "part" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventReasoningSummaryPart": { "type": "object", "description": "A summary part of a `reasoning` item was added or finished.", "properties": { "type": { "type": "string", "description": "One of `response.reasoning_summary_part.added`, `response.reasoning_summary_part.done`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "summary_index": { "type": "integer", "minimum": 0, "description": "Index of the summary part within the item." }, "part": { "$ref": "#/components/schemas/UHPContentPart", "description": "The content or summary part. Present on content part and reasoning summary part events." } }, "required": [ "type", "item_id", "output_index", "summary_index", "part" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventOutputTextDelta": { "type": "object", "description": "New text of a `message` item.", "properties": { "type": { "type": "string", "description": "Always `response.output_text.delta`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "content_index": { "type": "integer", "minimum": 0, "description": "Index of the content part within the item." }, "delta": { "type": "string", "description": "New text, or new function arguments, since the previous delta." } }, "required": [ "type", "item_id", "output_index", "content_index", "delta" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventReasoningSummaryTextDelta": { "type": "object", "description": "New summary text of a `reasoning` item.", "properties": { "type": { "type": "string", "description": "Always `response.reasoning_summary_text.delta`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "summary_index": { "type": "integer", "minimum": 0, "description": "Index of the summary part within the item." }, "delta": { "type": "string", "description": "New text, or new function arguments, since the previous delta." } }, "required": [ "type", "item_id", "output_index", "summary_index", "delta" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventOutputTextDone": { "type": "object", "description": "The text of a `message` item is complete.", "properties": { "type": { "type": "string", "description": "Always `response.output_text.done`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "content_index": { "type": "integer", "minimum": 0, "description": "Index of the content part within the item." }, "text": { "type": "string", "description": "The complete text. Present on `response.output_text.done`." } }, "required": [ "type", "item_id", "output_index", "content_index", "text" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventAnnotationAdded": { "type": "object", "description": "An annotation was added to the text of a `message` item.", "properties": { "type": { "type": "string", "description": "Always `response.output_text.annotation.added`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "content_index": { "type": "integer", "minimum": 0, "description": "Index of the content part within the item." }, "annotation_index": { "type": "integer", "minimum": 0, "description": "Index of the annotation within the content part." }, "annotation": { "$ref": "#/components/schemas/UHPAnnotation", "description": "The annotation. Present on `response.output_text.annotation.added`." } }, "required": [ "type", "item_id", "output_index", "content_index", "annotation_index", "annotation" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventFunctionCallArgumentsDelta": { "type": "object", "description": "The arguments of a function call were written.", "properties": { "type": { "type": "string", "description": "Always `response.function_call_arguments.delta`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "delta": { "type": "string", "description": "New text, or new function arguments, since the previous delta." } }, "required": [ "type", "item_id", "output_index", "delta" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventFunctionCallArgumentsDone": { "type": "object", "description": "The arguments of a function call are complete.", "properties": { "type": { "type": "string", "description": "Always `response.function_call_arguments.done`." }, "item_id": { "type": "string", "description": "ID of the output item the event belongs to." }, "output_index": { "type": "integer", "minimum": 0, "description": "Position of the item in the `output` of the response." }, "arguments": { "type": "string", "description": "The complete function arguments as a JSON string. Present on `response.function_call_arguments.done`." } }, "required": [ "type", "item_id", "output_index", "arguments" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventError": { "type": "object", "description": "An error that did not end the response.", "properties": { "type": { "type": "string", "description": "Always `error`." }, "code": { "type": "string", "description": "Machine-readable error code. Present on `error` events." }, "message": { "type": "string", "description": "Readable error message. Present on `error` events." }, "param": { "type": [ "string", "null" ], "description": "Dotted path of the field the error is about, or null. Present on `error` events." } }, "required": [ "type", "code", "message" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventApproval": { "type": "object", "description": "BeeOS extension: an approval request or its resolution.", "properties": { "type": { "type": "string", "description": "One of `beeos.approval.requested`, `beeos.approval.resolved`." }, "approval": { "$ref": "#/components/schemas/JSONValue", "description": "The approval document, passed through from the agent host." } }, "required": [ "type", "approval" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPEventQuestion": { "type": "object", "description": "BeeOS extension: a question request or its resolution.", "properties": { "type": { "type": "string", "description": "One of `beeos.question.requested`, `beeos.question.resolved`." }, "question": { "$ref": "#/components/schemas/JSONValue", "description": "The question document, passed through from the agent host." } }, "required": [ "type", "question" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPOutputItemMessage": { "type": "object", "description": "A message written by the agent.", "properties": { "type": { "type": "string", "description": "Always `message`." }, "id": { "type": "string", "description": "ID of the output item." }, "status": { "type": "string", "description": "Progress of the item.", "x-enumDescriptions": { "in_progress": "The item is still being produced.", "completed": "The item is complete." } }, "role": { "type": "string", "description": "Who wrote a `message` item.", "x-enumDescriptions": { "assistant": "The agent." } }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/UHPContentPart" }, "description": "Content parts of a `message` item." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPOutputItemReasoning": { "type": "object", "description": "The agent's reasoning.", "properties": { "type": { "type": "string", "description": "Always `reasoning`." }, "id": { "type": "string", "description": "ID of the output item." }, "status": { "type": "string", "description": "Progress of the item.", "x-enumDescriptions": { "in_progress": "The item is still being produced.", "completed": "The item is complete." } }, "summary": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "description": "Summary of a `reasoning` item." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPOutputItemFunctionCall": { "type": "object", "description": "A tool call made by the agent.", "properties": { "type": { "type": "string", "description": "Always `function_call`." }, "id": { "type": "string", "description": "ID of the output item." }, "status": { "type": "string", "description": "Progress of the item.", "x-enumDescriptions": { "in_progress": "The item is still being produced.", "completed": "The item is complete." } }, "call_id": { "type": "string", "description": "ID of the function call. A `function_call_output` item refers to its call with the same `call_id`." }, "name": { "type": "string", "description": "Name of the function the agent called." }, "arguments": { "type": "string", "description": "JSON, as a string" } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPOutputItemFunctionCallOutput": { "type": "object", "description": "The result of a tool call.", "properties": { "type": { "type": "string", "description": "Always `function_call_output`." }, "id": { "type": "string", "description": "ID of the output item." }, "status": { "type": "string", "description": "Progress of the item.", "x-enumDescriptions": { "in_progress": "The item is still being produced.", "completed": "The item is complete." } }, "call_id": { "type": "string", "description": "ID of the function call. A `function_call_output` item refers to its call with the same `call_id`." }, "output": { "type": "string", "description": "Result of the function call, as text." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPContentPartOutputText": { "type": "object", "description": "Text of a `message` item.", "properties": { "type": { "type": "string", "description": "Always `output_text`." }, "text": { "type": "string", "description": "Text of the part." }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/UHPAnnotation" }, "description": "Annotations that refer to ranges of `text`." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } }, "UHPContentPartSummaryText": { "type": "object", "description": "Summary text of a `reasoning` item.", "properties": { "type": { "type": "string", "description": "Always `summary_text`." }, "text": { "type": "string", "description": "Text of the part." } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JSONValue" } } } } }