BEEOS CLOUD / DEVELOPER REFERENCE

Appendix: object structures and enums

Every shared object structure and every enum of the Cloud SDK, with field tables, union variants, and the meaning of each allowed value.

This appendix defines the 171 named object structures and 75 enums that the method pages of the Cloud SDK refer to. In a field table, click a type name to jump to its structure here, and the link after a list of allowed values (or the "values" link of a long enum) to see each value on its own row. Descriptions are the OpenAPI document's; a field or value without one shows "—".

Object structures

Schema	Kind	Used by
A2AAgentCard	object	A2A
A2AArtifact	object	A2A
A2ADataPartOut	object	A2A
A2AFilePartOut	object	A2A
A2AMessage	object	A2A
A2AOutputPart	union	A2A
A2ATaskStatus	object	A2A
a2aTaskView	object	A2A
A2ATextPartOut	object	A2A
ActiveConversationResponse	object	Conversations
AgentAgent	object	Agents
agentBindDetailsWire	object	Device bindings
agentBindWire	object	Device bindings
AgentPage	object	Agents
AgentPatch	object	Agents
AgentResponse	object	Agents
AgentSkill	object	Agents
AgentSnapshot	object	Agents
agentTemplateCatalogView	object	Catalog
ApprovalModeResult	object	Conversations
ApprovalModeResultResponse	object	Conversations
ApprovalModeSettings	object	Conversations
Binding	object	Identity
BindingNative	variant structure	Identity
BindingWeb	variant structure	Identity
bindRuntimeWire	object	Device bindings
CancelConversationInput	object	Conversations
CanvasSessionDocument	object	Instances
CanvasShare	object	Canvases
CanvasSnapshot	object	Canvases
CanvasTicketClaims	object	Instances
CatalogSpec	object	Catalog
CatalogSpecValue	object	Catalog
CatalogVariant	object	Catalog
ClearConversationReceipt	object	Conversations
ClearConversationReceiptResponse	object	Conversations
ClientSessionInput	object	Identity
ClientSessionInputNative	variant structure	Identity
ClientSessionInputWeb	variant structure	Identity
ClientSessionResponse	object	Identity
CommandReceipt	object	Conversations
CommandReceiptResponse	object	Conversations
ConnectURLResponse	object	Instances
Conversation	object	Conversations
ConversationPage	object	Conversations
ConversationResponse	object	Conversations
CreateConversationInput	object	Conversations
CreateServerInstanceInput	object	Instances
Deletion	object	Identity
DeletionAccepted	object	Identity
DeployModel	object	Catalog
DeployRegion	object	Catalog
DeviceBindingErrorResponse	object	—
ErrorResponse	object	—
ExternalUserID	`string`	Identity
FileChatUploadContext	object	Files
FileConfirmInput	object	Files
FileFile	object	Files
FileOrigin	object	Files
FilePage	object	Files
FilePrepareUploadInput	object	Files
FileResolution	object	Files
FileShareResponse	object	Files
FileSummary	object	Files
FileTransferDescriptor	object	Files
InstancePage	object	Instances
InstanceSummary	object	Instances
InstanceTemplate	object	Catalog
InstanceTemplatePage	object	Catalog
JSONValue	union	Identity, Catalog, Instances, Messages, Responses, Harnesses, Automations, A2A
Message	object	Messages
MessageContentAgentRefuse	variant structure	Messages
MessageContentAgentReply	variant structure	Messages
MessageContentChatCancel	variant structure	Messages
MessageContentChatMessage	variant structure	Messages
MessageContentDeviceCommand	variant structure	Messages
MessageContentDeviceError	variant structure	Messages
MessageEnvelope	object	Messages
MessageEnvelopeResponse	object	Messages
MessagePage	object	Messages
MessagePartCustom	variant structure	Messages
MessagePartFile	variant structure	Messages
MessagePartSource	variant structure	Messages
MessagePartText	variant structure	Messages
MessagePartThinking	variant structure	Messages
MessagePartToolResult	variant structure	Messages
MessagePartToolUse	variant structure	Messages
ModelPage	object	Catalog
portalBindWire	object	Device bindings
ProtoAutomationInput	object	Automations
ProtoAutomationPatch	object	Automations
ProtoAutomationRule	object	Automations
ProtoAutomationRun	object	Automations
ProtoAutomationRunInput	object	Automations
ProtoAutomationSchedule	object	Automations
ProtoAutomationSession	object	Automations
ProtoAutomationTarget	object	Automations
ProtoAutomationWebhookInput	object	Automations
ProtoListAutomationRunsResponse	object	Automations
ProtoListAutomationsResponse	object	Automations
Provider	object	Catalog
ProviderCapabilities	object	Catalog
ProviderPage	object	Catalog
RealtimeTicketHeader	object	Instances
ReasoningResult	object	Conversations
ReasoningResultResponse	object	Conversations
ReasoningSettings	object	Conversations
RegionPage	object	Catalog
ReplyShareResponse	object	Messages
RuntimeExecResult	object	Instances
RuntimeInstanceResult	object	Instances
RuntimeInstanceStatusResult	object	Instances
RuntimeInstanceSummary	object	Instances
RuntimeLLM	object	Instances
RuntimeLLMModel	object	Instances
RuntimeLLMProvider	object	Instances
RuntimeLLMProviderView	object	Instances
RuntimeLLMView	object	Instances
RuntimeMethodResponse	object	A2A
RuntimeOperationSummary	object	Instances
RuntimeUpgradeJob	object	Instances
ServerUsageSummary	object	Usage
SetConversationModelInput	object	Conversations
TerminalSessionDocument	object	Instances
TerminalTicketClaims	object	Instances
UHPAnnotation	object	Responses
UHPCapabilities	object	Catalog
UHPContentPart	object	Responses
UHPContentPartOutputText	variant structure	Responses
UHPContentPartSummaryText	variant structure	Responses
UHPCreateResponseRequest	object	Responses
UHPDiscovery	object	Catalog
UHPError	object	Responses
UHPErrorEnvelope	object	—
UHPEvent	object	Responses
UHPEventAnnotationAdded	variant structure	Responses
UHPEventApproval	variant structure	Responses
UHPEventContentPart	variant structure	Responses
UHPEventError	variant structure	Responses
UHPEventFunctionCallArgumentsDelta	variant structure	Responses
UHPEventFunctionCallArgumentsDone	variant structure	Responses
UHPEventOutputItem	variant structure	Responses
UHPEventOutputTextDelta	variant structure	Responses
UHPEventOutputTextDone	variant structure	Responses
UHPEventQuestion	variant structure	Responses
UHPEventReasoningSummaryPart	variant structure	Responses
UHPEventReasoningSummaryTextDelta	variant structure	Responses
UHPEventResponse	variant structure	Responses
UHPHarness	object	Harnesses
UHPHarnessCreate	object	Harnesses
UHPHarnessModels	object	Harnesses
UHPMcpServer	object	Harnesses
UHPModel	object	Harnesses
UHPModelCatalog	object	Harnesses
UHPOutputItem	object	Responses
UHPOutputItemFunctionCall	variant structure	Responses
UHPOutputItemFunctionCallOutput	variant structure	Responses
UHPOutputItemMessage	variant structure	Responses
UHPOutputItemReasoning	variant structure	Responses
UHPPlugin	object	Harnesses
UHPPluginManifest	object	Harnesses
UHPPluginMcpServer	object	Harnesses
UHPPluginSkill	object	Harnesses
UHPPluginSkipped	object	Harnesses
UHPResponse	object	Responses
UHPResponseStatus	enum	Responses
UHPSkill	object	Harnesses
UHPSkillFile	object	Harnesses
UHPUsage	object	Responses
UpdateConversationInput	object	Conversations
UpdateServerInstanceInput	object	Instances

A2AAgentCard

—

Used by: A2A

Field	Type	Required	Description
`name`	`string`	yes	Display name of the agent.
`description`	`string`	yes	Description of the agent.
`url`	`string`	no	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`	`string`	yes	Version of the agent: its resource version, a decimal number.
`protocolVersion`	`string`	no	A2A protocol version spoken at `url`. Returned only when the request sends `A2A-Version: 0.3`.
`defaultInputModes`	`array<string>`	yes	Media types the agent accepts as input, for example `text/plain`.
`defaultOutputModes`	`array<string>`	yes	Media types the agent produces as output, for example `text/plain`.
`supportedInterfaces`	`array<object>`	no	Interfaces through which the agent can be reached. Returned unless the request sends `A2A-Version: 0.3`.
`supportedInterfaces[].url`	`string`	yes	URL of the interface.
`supportedInterfaces[].protocolBinding`	`string`	yes	Transport the interface uses: `JSONRPC`.
`supportedInterfaces[].protocolVersion`	`string`	yes	A2A protocol version the interface speaks.

A2AArtifact

—

Used by: A2A

Field	Type	Required	Description
`artifactId`	`string`	yes	ID of the artifact. When the agent supplies none, the server uses `<task ID>-a<index>`, counting from 0.
`name`	`string`	no	Display name of the artifact. Omitted when it is not set.
`description`	`string`	no	Description of the artifact. Omitted when it is not set.
`parts`	array<A2AOutputPart>	yes	Content of the artifact as parts, in order. Each part is a text part, a file part or a data part.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the artifact. Omitted when there is none.
`extensions`	`array<string>`	no	URIs of the protocol extensions that apply to the artifact. Omitted when there are none.

A2ADataPartOut

—

Used by: A2A

Field	Type	Required	Description
`data`	JSONValue	yes	Structured content of the part, as any JSON value. Nullable.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

A2AFilePartOut

—

Used by: A2A

Field	Type	Required	Description
`url`	`string`	no	URL the file can be fetched from. Omitted when it is not set.
`filename`	`string`	no	Name of the file. Omitted when it is not set.
`mediaType`	`string`	no	Media type (MIME type) of the file. Omitted when it is not set.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

A2AMessage

—

Used by: A2A

Field	Type	Required	Description
`messageId`	`string`	yes	ID of the message. The server generates a new ID for every message it renders.
`role`	`string`	yes	Who wrote the message: `ROLE_USER` for the caller or `ROLE_AGENT` for the agent. Allowed values: `"ROLE_USER"` — The message was written by the caller; `"ROLE_AGENT"` — The message was written by the agent. (enum table)
`parts`	array<A2AOutputPart>	yes	Content of the message as parts, in order. Each part is a text part, a file part or a data part.
`contextId`	`string`	no	ID of the context (conversation) the message belongs to. Omitted when it is not set.
`taskId`	`string`	no	ID of the task the message belongs to. Omitted when it is not set.
`referenceTaskIds`	`array<string>`	no	IDs of other tasks this message refers to. Omitted when there are none.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the message. Omitted when there is none.

A2AOutputPart

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.

Used by: A2A

Union: exactly one alternative applies.

Variant: `A2ATextPartOut`

Field	Type	Required	Description
`text`	`string`	yes	Text content of the part.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

Variant: `A2AFilePartOut`

Field	Type	Required	Description
`url`	`string`	no	URL the file can be fetched from. Omitted when it is not set.
`filename`	`string`	no	Name of the file. Omitted when it is not set.
`mediaType`	`string`	no	Media type (MIME type) of the file. Omitted when it is not set.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

Variant: `A2ADataPartOut`

Field	Type	Required	Description
`data`	JSONValue	yes	Structured content of the part, as any JSON value. Nullable.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

A2ATaskStatus

—

Used by: A2A

Field	Type	Required	Description
`state`	`string`	yes	Current state of the task. Allowed values: see the table below, A2ATaskStatus.state values.
`message`	A2AMessage	no	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. Nullable.
`timestamp`	`string`	no	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`.

A2ATaskStatus.state values

Value	Meaning
`"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.

a2aTaskView

—

Used by: A2A

Field	Type	Required	Description
`id`	`string`	yes	ID of the task.
`contextId`	`string`	yes	ID of the context (conversation) the task belongs to.
`status`	A2ATaskStatus	yes	Current status of the task.
`artifacts`	array<A2AArtifact>	no	Outputs the agent produced for the task. Omitted while there are none.
`history`	array<A2AMessage>	no	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`	map<string, JSONValue>	no	Extra metadata of the task. Omitted when there is none.
`caller_principal_id`	`string`	yes	ID of the principal that submitted the task.
`caller_agent_id`	`string`	yes	ID of the agent that submitted the task, if any.
`caller_owner_id`	`string`	yes	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`	`string`	yes	ID of the principal the task was sent to.
`target_agent_id`	`string`	yes	ID of the agent the task was sent to.
`target_owner_id`	`string`	yes	ID of the owner of the receiving side.
`channel_id`	`string`	no	ID of the channel that carries the streaming replies of the task. Omitted when the task does not use channel-based delivery.
`created_at`	`string`	no	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`	`string`	no	Time the task was last updated, in the same format as `created_at`. Omitted when it is not known.
`completed_at`	`string`	no	Time the task finished, in the same format as `created_at`. Omitted until the task is finished.

A2ATextPartOut

—

Used by: A2A

Field	Type	Required	Description
`text`	`string`	yes	Text content of the part.
`metadata`	map<string, JSONValue>	no	Extra metadata attached to the part. Omitted when there is none.

ActiveConversationResponse

—

Used by: Conversations

Field	Type	Required	Description
`response_id`	`string`	yes	ID of the response being produced. Use it with the responses API.
`last_event_id`	`string`	yes	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`	`string`	no	ID of the `chat_message` that started the response. Omitted when it is not recorded.
`reply_message_id`	`string`	no	ID of the message the agent's reply is written to. Omitted until the reply message exists.

AgentAgent

—

Used by: Agents

Field	Type	Required	Description
`id`	`string`	yes	ID of the agent.
`instance_id`	`string`	yes	ID of the instance the agent runs on.
`name`	`string`	yes	Name of the agent.
`avatar_url`	`string`	no	URL of the agent's avatar image. Omitted when none is set.
`display_name`	`string`	no	Human-readable name of the agent. Omitted when none is set.
`description`	`string`	yes	Description of the agent. Empty when none is set.
`resource_version`	`integer`	yes	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`	`string`	yes	Whether the agent is currently provided by its instance. Allowed values: `"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. (enum table)
`visibility`	`string`	yes	Which callers other than the owner can use the agent. Change it with the update operation. Allowed values: see the table below, AgentAgent.visibility values.
`mcp_enabled`	`boolean`	yes	Whether the agent is published as a tool through BeeOS MCP endpoints.
`a2a_enabled`	`boolean`	yes	Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`.
`capabilities`	`map<string, boolean>`	yes	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`	array<AgentSkill>	yes	Skills of the agent.
`conversation_transport`	`string`	yes	How conversation messages reach the agent. New values can be added, so ignore values you do not know. Allowed values: `"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. (enum table)
`created_at`	`string`	yes	Time the agent was created, in RFC 3339 format. Constraints: `format=date-time`.
`updated_at`	`string`	yes	Time the agent was last changed, in RFC 3339 format. Constraints: `format=date-time`.

AgentAgent.visibility values

Value	Meaning
`"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.

agentBindDetailsWire

—

Used by: Device bindings

Field	Type	Required	Description
`bind_id`	`string`	yes	ID of the bind session.
`hostname`	`string`	yes	Host name the device reported.
`fingerprint_short`	`string`	yes	First 16 characters of the device key fingerprint. Show it to the user to compare with the device.
`harness`	`string`	yes	Harness the device runs, as the device reported it.
`os_type`	`string`	no	Operating system the device reported. Omitted when it did not report one.
`expires_at`	`integer`	yes	Time the session expires, in Unix seconds.
`status`	`string`	yes	State of the bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 `not_found` instead. Allowed values: `"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. (enum table)
`server_time`	`integer`	yes	Current server time in Unix seconds. Compare it with `expires_at` to get the remaining time without clock skew.

agentBindWire

—

Used by: Device bindings

Field	Type	Required	Description
`status`	`string`	yes	State of the bind session. After a successful confirmation it is `bound`; a session that is still waiting for confirmation reports `pending`. Allowed values: `"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. (enum table)
`bind_id`	`string`	no	ID of the bind session.
`instance_id`	`string`	no	ID of the instance created for the device. Present once the session is bound.
`public_key`	`string`	no	Public key the device registered for the session.
`hostname`	`string`	no	Host name the device reported.
`expires_at`	`integer`	no	Time the session expires, in Unix seconds.
`runtime_binding`	bindRuntimeWire	no	Addresses a bound self-hosted agent connects to. Present once the session is bound. Nullable.

AgentPage

—

Used by: Agents

Field	Type	Required	Description
`data`	array<AgentAgent>	yes	Agents on this page, newest first.
`total`	`integer`	yes	Total number of agents that match the filters, across all pages.

AgentPatch

Exposure settings to change. Send at least one field; fields you omit keep their current value.

Used by: Agents

Field	Type	Required	Description
`visibility`	`string`	no	New visibility of the agent. The values are described on the `visibility` field of the agent. Allowed values: see the table below, AgentPatch.visibility values.
`mcp_enabled`	`boolean`	no	Set to true to publish the agent as a tool through BeeOS MCP endpoints, or to false to stop publishing it.
`a2a_enabled`	`boolean`	no	Set to true to let the agent accept Agent-to-Agent (A2A) requests, or to false to refuse them with 403 `a2a_disabled`.

AgentPatch.visibility values

Value	Meaning
`"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.

AgentResponse

—

Used by: Agents

Field	Type	Required	Description
`data`	AgentSnapshot	yes	The agent.

AgentSkill

—

Used by: Agents

Field	Type	Required	Description
`id`	`string`	yes	ID of the skill. Empty when the instance did not report one.
`name`	`string`	yes	Name of the skill.
`description`	`string`	yes	What the skill does.
`tags`	`array<string>`	yes	Tags that describe the skill. Empty when there are none.
`enabled`	`boolean`	yes	Whether the skill is currently enabled for the agent.

AgentSnapshot

—

Used by: Agents

Field	Type	Required	Description
`id`	`string`	yes	ID of the agent.
`instance_id`	`string`	yes	ID of the instance the agent runs on.
`name`	`string`	yes	Name of the agent.
`display_name`	`string`	no	Human-readable name of the agent. Omitted when none is set.
`description`	`string`	yes	Description of the agent. Empty when none is set.
`status`	`string`	yes	Whether the agent is currently provided by its instance. Allowed values: `"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. (enum table)
`visibility`	`string`	yes	Which callers other than the owner can use the agent. Change it with the update operation. Allowed values: see the table below, AgentSnapshot.visibility values.
`conversation_transport`	`string`	yes	How conversation messages reach the agent. New values can be added, so ignore values you do not know. Allowed values: `"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. (enum table)
`resource_version`	`integer`	yes	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. Constraints: `minimum=1`, `format=int64`.
`mcp_enabled`	`boolean`	yes	Whether the agent is published as a tool through BeeOS MCP endpoints.
`a2a_enabled`	`boolean`	yes	Whether the agent accepts Agent-to-Agent (A2A) requests. When false, A2A requests for the agent are refused with 403 `a2a_disabled`.
`capabilities`	`map<string, boolean>`	yes	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`	array<AgentSkill>	yes	Skills of the agent.
`created_at`	`string`	yes	Time the agent was created, in RFC 3339 format. Constraints: `format=date-time`.
`updated_at`	`string`	yes	Time the agent was last changed, in RFC 3339 format. Constraints: `format=date-time`.

AgentSnapshot.visibility values

Value	Meaning
`"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.

agentTemplateCatalogView

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the template. Pass it as `template_id` when creating a harness from the template.
`display_name`	`string`	yes	Display name of the template, in the language of `Accept-Language` when a translation exists.
`summary`	`string`	yes	One-line summary of what the template is for, localized like `display_name`.
`description`	`string`	yes	Full description of the template, localized like `display_name`.
`category`	`string`	yes	Category the template is listed under. Use it as the `category` filter of the list operation.
`vibe`	`string`	yes	Short phrase describing the personality of the agent the template creates, localized like `display_name`.
`icon_url`	`string`	yes	URL of the template icon. Empty when the template has none.
`banner_url`	`string`	yes	URL of the template banner image. Empty when the template has none.
`default_model`	`string`	yes	ID of the model the template selects as the agent's primary model.
`tags`	`array<string>`	yes	Tags that describe the template.
`harness`	`string`	yes	Harness (agent runtime) the template is applied to, for example `openclaw`.
`template_version`	`string`	yes	Version of the template package, as a semantic version such as `1.2.0`.

ApprovalModeResult

—

Used by: Conversations

Field	Type	Required	Description
`approval_mode`	`string`	yes	Approval mode now in effect for the conversation. `null` means the instance default applies. Nullable.
`metadata_version`	`integer`	yes	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. Constraints: `minimum=1`, `format=int64`.
`status`	`string`	yes	Outcome of the change at the time the call returned. Allowed values: `"completed"` — The approval mode was changed before the call returned.

ApprovalModeResultResponse

—

Used by: Conversations

Field	Type	Required	Description
`data`	ApprovalModeResult	yes	The result of the change.

ApprovalModeSettings

—

Used by: Conversations

Field	Type	Required	Description
`approval_mode`	`string`	yes	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. Nullable. Constraints: `minLength=1`, `maxLength=32`, `pattern=^[a-z][a-z0-9_]*$`.

Binding

—

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	How the token is bound to the client. Allowed values: `"web"` — Bound to a web page origin, returned in `origin`; `"native"` — Bound to a device key, whose thumbprint is returned in `cnf_jkt`. (enum table) Structure by `client_type`: see the variant table.
`origin`	`string`	no	Origin the token is bound to. Returned when `client_type` is `web`. Constraints: `format=uri`.
`cnf_jkt`	`string`	no	Thumbprint of the device key the token is bound to. Returned when `client_type` is `native`.

Binding by client_type

The structure of Binding depends on its own client_type value.

Value of client_type	Description	Structure
`"web"`	Bound to a web page origin, returned in `origin`.	BindingWeb
`"native"`	Bound to a device key, whose thumbprint is returned in `cnf_jkt`.	BindingNative

BindingNative

Binding of a token to a device key.

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	Always `native`.
`cnf_jkt`	`string`	yes	Thumbprint of the device key the token is bound to. Returned when `client_type` is `native`.

Additional properties are accepted.

BindingWeb

Binding of a token to a web page origin.

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	Always `web`.
`origin`	`string`	yes	Origin the token is bound to. Returned when `client_type` is `web`. Constraints: `format=uri`.

Additional properties are accepted.

bindRuntimeWire

—

Used by: Device bindings

Field	Type	Required	Description
`instance_id`	`string`	yes	ID of the instance the agent is bound to.
`agent_gateway_url`	`string`	yes	Base URL of the API the agent connects to for agent traffic.
`message_service_url`	`string`	yes	Base URL of the API the agent connects to for messages.

CancelConversationInput

—

Used by: Conversations

Field	Type	Required	Description
`target_message_id`	`string`	yes	ID of the `chat_message` whose turn should stop, 1 to 256 characters. Constraints: `minLength=1`, `maxLength=256`.
`reason`	`string`	no	Why the turn is stopped, as free text of at most 256 characters. When it is omitted or empty, `user_request` is recorded. Constraints: `maxLength=256`.

CanvasSessionDocument

—

Used by: Instances

Field	Type	Required	Description
`transport`	`string`	yes	How the ticket connects: always `relay`.
`protocolVersion`	`integer`	yes	Version of the ticket protocol. Currently 1.
`header`	RealtimeTicketHeader	yes	Header of the signed ticket.
`relayUrl`	`string`	yes	WebSocket URL of the canvas relay for the canvas, ending in `/ws/{canvasId}`.
`ticket`	`string`	yes	Signed single-use ticket (a JWT) that authorizes one relay connection. It is valid for 60 seconds.
`issuedAt`	`string`	yes	Time the ticket was issued, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`expiresAt`	`string`	yes	Time the ticket expires, as an RFC 3339 timestamp. Tickets are valid for 60 seconds. Constraints: `format=date-time`.
`claims`	CanvasTicketClaims	yes	Claims contained in the signed ticket.

CanvasShare

—

Used by: Canvases

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the share.
`canvasId`	`string`	yes	ID of the canvas that is shared. A canvas has at most one share.
`slug`	`string`	yes	Public identifier of the share, used to build the share link. It stays the same when the share is updated.
`mode`	`string`	yes	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`	`boolean`	yes	Whether visitors can interact with the canvas. When false, visitors can only view it.
`expiresAt`	`string`	no	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`	`string`	yes	Time the share was first created, as an RFC 3339 timestamp. Updating the share does not change it.

CanvasSnapshot

—

Used by: Canvases

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the snapshot. Pass it to the restore operation.
`canvasId`	`string`	yes	ID of the canvas the snapshot belongs to.
`componentsSnapshot`	`string`	no	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`	`string`	yes	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`	`string`	yes	ID of the actor named by `actorType`. `system` for automatic snapshots with no known actor.
`description`	`string`	no	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`	`integer`	yes	Version of the canvas content the snapshot records. A higher number is newer.
`createdAt`	`string`	yes	Time the snapshot was taken, as an RFC 3339 timestamp.

CanvasTicketClaims

—

Used by: Instances

Field	Type	Required	Description
`iss`	`string`	yes	Issuer of the ticket.
`sub`	`string`	yes	Unused. Cloud does not accept an external user id, so this claim is empty.
`jti`	`string`	yes	Unique ID of the ticket.
`purpose`	`string`	yes	Purpose of the ticket: always `canvas_session`.
`instance_id`	`string`	yes	ID of the instance the canvas belongs to.
`platform_agent_id`	`string`	yes	ID of the agent the canvas session is for, the `platformAgentId` of the request.
`client_id`	`string`	yes	ID generated for this relay client connection.
`conversation_id`	`string`	yes	ID of the conversation the canvas belongs to, the `conversationId` of the request.
`canvas_id`	`string`	yes	ID of the canvas the ticket grants access to.
`role`	`string`	yes	Access role granted on the canvas: `viewer` or `editor`. Allowed values: `"viewer"` — Can view the canvas but not change it; `"editor"` — Can view and edit the canvas. (enum table)
`session_id`	`string`	yes	ID of the realtime session created for this ticket.
`aud`	`array<string>`	yes	Audiences the ticket is intended for: the canvas relay.
`iat`	`integer`	yes	Time the ticket was issued, in Unix seconds.
`exp`	`integer`	yes	Time the ticket expires, in Unix seconds.

CatalogSpec

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	—
`name`	`string`	yes	—
`label`	`string`	yes	—
`values`	array<CatalogSpecValue>	yes	—

CatalogSpecValue

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	—
`name`	`string`	yes	—
`label`	`string`	yes	—
`sort_order`	`integer`	yes	—

CatalogVariant

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the variant. Send it as `variant_id` when creating an instance.
`spec_value_ids`	`array<string>`	yes	—
`sort_order`	`integer`	yes	—

ClearConversationReceipt

—

Used by: Conversations

Field	Type	Required	Description
`request_id`	`string`	yes	ID of the clear operation. Retrying with the same `Idempotency-Key` returns the same ID.
`conversation_id`	`string`	yes	ID of the conversation that was cleared.
`current_generation`	`integer`	yes	History generation after the clear. Messages from earlier generations are no longer part of the conversation history. Constraints: `minimum=0`, `format=int64`.
`status`	`string`	yes	Outcome of the clear at the time the call returned. Allowed values: `"completed"` — The history was cleared before the call returned.

ClearConversationReceiptResponse

—

Used by: Conversations

Field	Type	Required	Description
`data`	ClearConversationReceipt	yes	The receipt of the clear operation.

ClientSessionInput

—

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	How the client token is bound to the client that will use it. It decides whether you send `origin` or `device_attestation`. Allowed values: `"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`. (enum table) Structure by `client_type`: see the variant table.
`requested_capabilities`	`array<string>`	yes	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`. Constraints: `minItems=1`, `uniqueItems`.
`origin`	`string`	no	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`. Constraints: `format=uri`.
`device_attestation`	`object`	no	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`.
`device_attestation.jkt`	`string`	yes	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. Constraints: `minLength=16`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

ClientSessionInput by client_type

The structure of ClientSessionInput depends on its own client_type value.

Value of client_type	Description	Structure
`"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`.	ClientSessionInputWeb
`"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`.	ClientSessionInputNative

ClientSessionInputNative

Request for a token bound to a device key.

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	Always `native`.
`device_attestation`	`object`	yes	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`.
`device_attestation.jkt`	`string`	yes	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. Constraints: `minLength=16`.
`requested_capabilities`	`array<string>`	yes	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`. Constraints: `minItems=1`, `uniqueItems`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

Additional properties are accepted.

ClientSessionInputWeb

Request for a token bound to a web page origin.

Used by: Identity

Field	Type	Required	Description
`client_type`	`string`	yes	Always `web`.
`origin`	`string`	yes	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`. Constraints: `format=uri`.
`requested_capabilities`	`array<string>`	yes	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`. Constraints: `minItems=1`, `uniqueItems`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

Additional properties are accepted.

ClientSessionResponse

—

Used by: Identity

Field	Type	Required	Description
`access_token`	`string`	yes	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. Write-only.
`client_api_url`	`string`	yes	Base URL of the Client API that accepts `access_token`. Allowed values: `"https://client-api.cloud.beeos.ai/v1"` — The production Client API.
`expires_at`	`string`	yes	Actual expiration of the issued token, capped by the remaining session authorization lifetime. Constraints: `format=date-time`.
`session_id`	`string`	yes	ID of the client session. Use it to refresh or revoke the session. Refreshing issues a new token for the same session.
`app_id`	`string`	yes	ID of the app the session belongs to.
`external_user_id`	`string`	yes	Unused. Cloud does not accept an external user id. Stored sessions leave this empty.
`capabilities`	`array<string>`	yes	Operations the token may perform on the Client API. They are the requested capabilities, without duplicates.
`binding`	Binding	yes	How the token is bound to the client, as requested when the session was created.

CommandReceipt

—

Used by: Conversations

Field	Type	Required	Description
`request_id`	`string`	yes	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`	`string`	yes	Outcome of the request at the time the call returned. Allowed values: `"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. (enum table)

CommandReceiptResponse

—

Used by: Conversations

Field	Type	Required	Description
`data`	CommandReceipt	yes	The receipt of the request.

ConnectURLResponse

—

Used by: Instances

Field	Type	Required	Description
`data`	`object`	yes	Connection details for the requested service.
`data.url`	`string`	yes	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.
`data.mode`	`string`	yes	Connection mode: `browser-runtime` for `browser`, `service-websocket` for `acp`. Allowed values: `"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. (enum table)
`data.token`	`string`	yes	Short-lived access token for the browser viewer. Not returned for `acp`.
`data.service`	`string`	yes	Service the URL connects to: `browser` or `acp`. Allowed values: `"browser"` — The browser viewer; `"acp"` — The agent connection over WebSocket. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`data.stream_session_id`	`string`	yes	ID of the viewing client session, the `client_id` sent in the request. Not returned for `acp`.
`data.browser`	`object`	no	Browser access grant. Returned only for `browser`.
`data.browser.grant_id`	`string`	yes	ID of the browser access grant.
`data.browser.generation`	`string`	yes	Generation of the browser the grant is bound to. When `generation` was sent in the request, it equals that value.
`data.browser.expires_at`	`string`	yes	Time the access grant expires, in Unix milliseconds.
`data.browser.role`	`string`	yes	Access role of the grant: `viewer` or `controller`. Allowed values: `"viewer"` — Can watch the browser but not control it; `"controller"` — Can watch and control the browser. (enum table)

Conversation

—

Used by: Conversations

Field	Type	Required	Description
`id`	`string`	yes	ID of the conversation. Constraints: `minLength=1`.
`agent_id`	`string`	yes	ID of the agent the conversation is with, the `id` returned by the agents API. Constraints: `minLength=1`.
`instance_id`	`string`	yes	ID of the instance the agent runs on. Constraints: `minLength=1`.
`title`	`string`	yes	Title of the conversation. Empty when no title was set.
`state`	`string`	yes	Whether the conversation still accepts messages. A closed conversation stays readable but cannot receive new messages. Allowed values: `"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`. (enum table)
`metadata_version`	`integer`	yes	Version of the conversation settings (title, model override, reasoning and approval mode). It increases by one on every change. It always equals `resource_version`. Constraints: `minimum=1`, `format=int64`.
`history_generation`	`integer`	yes	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. Constraints: `minimum=0`, `format=int64`.
`created_at`	`string`	yes	Time the conversation was created, in RFC 3339 format. Constraints: `format=date-time`.
`last_activity_at`	`string`	no	Time of the latest activity in the conversation, in RFC 3339 format. Omitted when no activity is recorded. Constraints: `format=date-time`.
`closed_at`	`string`	no	Time the conversation was closed, in RFC 3339 format. Omitted while the conversation is open. Constraints: `format=date-time`.
`resource_version`	`integer`	yes	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. Constraints: `minimum=1`, `format=int64`.
`model_override_id`	`string`	no	ID of the model that overrides the agent's default model for this conversation. Omitted when no override is set.
`effective_model_id`	`string`	no	Reserved. The Server API does not currently return this field; use `model_override_id`.
`active_response`	ActiveConversationResponse	no	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`	ReasoningSettings	no	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`	`string`	no	Approval mode set for the conversation. Omitted when none is set and the instance default applies. Nullable.

ConversationPage

—

Used by: Conversations

Field	Type	Required	Description
`conversations`	array<Conversation>	yes	Conversations on this page.
`next_cursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false.
`has_more`	`boolean`	yes	Whether more conversations are available after this page.

ConversationResponse

—

Used by: Conversations

Field	Type	Required	Description
`data`	Conversation	yes	The conversation.

CreateConversationInput

—

Used by: Conversations

Field	Type	Required	Description
`title`	`string`	no	Title of the new conversation, at most 512 bytes of valid UTF-8. Omit it to create a conversation without a title. Constraints: `maxLength=256`.

CreateServerInstanceInput

—

Used by: Instances

Field	Type	Required	Description
`name`	`string`	yes	Display name of the instance, 1 to 128 bytes, without leading or trailing whitespace.
`variant_id`	`string`	no	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`	`string`	no	Harness to run in the instance. Only `openclaw` is accepted. Allowed values: `"openclaw"` — The OpenClaw agent runtime.
`llm`	RuntimeLLM	no	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. Nullable.

Deletion

—

Used by: Identity

Field	Type	Required	Description
`id`	`string`	yes	ID of the deletion.
`status`	`string`	yes	State of the deletion. Poll until it is `completed`. Allowed values: `"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. (enum table)
`deleted_resources`	`map<string, integer>`	yes	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.

DeletionAccepted

—

Used by: Identity

Field	Type	Required	Description
`deletion_id`	`string`	yes	ID of the deletion. Use it to read the progress of the deletion.
`status`	`string`	yes	State of the deletion when the request was accepted. Allowed values: `"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. (enum table)

DeployModel

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the model, usually in `provider/model` form.
`name`	`string`	yes	Display name of the model.
`tier`	`string`	no	—
`reasoning`	`boolean`	no	—
`input`	`array<string>`	no	—
`context_window`	`integer`	no	Maximum context window of the model, in tokens.

DeployRegion

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the region.
`name`	`string`	yes	Display name of the region.
`available`	`boolean`	yes	Whether the region is currently available.

DeviceBindingErrorResponse

—

Used by: —

Field	Type	Required	Description
`error`	`string`	yes	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`	`string`	yes	Human-readable explanation of the error. Do not parse it.

ErrorResponse

—

Used by: —

Field	Type	Required	Description
`code`	`string`	yes	Stable machine-readable error code, for example `invalid_request`, `version_mismatch` or `instance_not_found`.
`message`	`string`	yes	Human-readable description of the error. Use `code`, not this text, to branch in code.
`request_id`	`string`	yes	ID of the request, for support and tracing.

ExternalUserID

Opaque App-local identifier. Exact dot-segment values '.' and '..' are reserved by T03-20260905-01.

Used by: Identity

Type: string

Constraints: minLength=1, maxLength=128.

FileChatUploadContext

—

Used by: Files

Field	Type	Required	Description
`instance_id`	`string`	yes	ID of the instance the file is uploaded for. It must belong to your app.
`agent_id`	`string`	no	ID of the agent the file is uploaded for. It must belong to the instance. Optional.

FileConfirmInput

—

Used by: Files

Field	Type	Required	Description
`checksum_sha256`	`string`	no	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`.

FileFile

—

Used by: Files

Field	Type	Required	Description
`file_id`	`string`	yes	Unique ID of the file.
`filename`	`string`	yes	Name of the file, without a path.
`content_type`	`string`	yes	MIME type of the file, for example image/png.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	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`	`string`	yes	Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know. Allowed values: `"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. (enum table)
`resource_version`	`integer`	yes	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`	`string`	yes	Time the file was last changed: created, confirmed or renamed, whichever is latest. RFC 3339 timestamp. Constraints: `format=date-time`.
`title`	`string`	no	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`	`string`	yes	Category of the file, derived from its MIME type and, for generic types such as `application/octet-stream`, from its extension. Allowed values: see the table below, FileFile.file_type values.
`created_at`	`string`	yes	Time the file record was created, when the upload was prepared. RFC 3339 timestamp. Constraints: `format=date-time`.
`confirmed_at`	`string`	no	Time the upload was confirmed. Omitted until the file is ready. RFC 3339 timestamp. Nullable. Constraints: `format=date-time`.
`origin`	FileOrigin	no	Where the file came from, with the instance and agent it belongs to. Nullable.

FileFile.file_type values

Value	Meaning
`"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.

FileOrigin

—

Used by: Files

Field	Type	Required	Description
`source`	`string`	yes	How the file came to exist. New values can be added, so ignore values you do not know. Allowed values: `"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. (enum table)
`instance_id`	`string`	no	ID of the instance the file belongs to. Omitted for files that are not tied to an instance.
`agent_id`	`string`	no	ID of the agent the file belongs to. Omitted for files that are not tied to an agent.
`operation_id`	`string`	no	ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`.
`instance_name`	`string`	no	Current display name of the instance, filled in when the file is returned. Omitted for files without an instance.
`agent_name`	`string`	no	Current display name of the agent, filled in when the file is returned. Omitted for files without an agent.
`avatar_url`	`string`	no	URL of the agent avatar. Omitted for files without an agent.
`harness`	`string`	no	Harness the instance runs, for example `openclaw`. Omitted for files without an instance.
`destroyed`	`boolean`	no	True when the instance has been terminated or deleted. The file stays available. Omitted when false.

FilePage

—

Used by: Files

Field	Type	Required	Description
`data`	array<FileFile>	yes	Files on this page.
`total`	`integer`	yes	Number of files that match the query, across all pages.
`next_since`	`string`	no	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.

FilePrepareUploadInput

—

Used by: Files

Field	Type	Required	Description
`upload_context`	FileChatUploadContext	no	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. Nullable.
`filename`	`string`	yes	Name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\` or control characters.
`content_type`	`string`	yes	MIME type of the file, at most 255 characters and without control characters. The uploaded content must carry this type.
`size_bytes`	`integer`	yes	Size of the file in bytes, from 1 to 104857600 (100 MiB). The uploaded content must have exactly this size.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the content (64 characters). Optional. When sent, the uploaded content must match it and the confirmation verifies it.

FileResolution

—

Used by: Files

Field	Type	Required	Description
`file`	FileFile	yes	The file.
`download`	FileTransferDescriptor	yes	Pre-signed descriptor to download the content with. While the file is still `pending_upload` it carries no usable URL.

FileShareResponse

—

Used by: Files

Field	Type	Required	Description
`file_id`	`string`	yes	ID of the shared file.
`slug`	`string`	yes	Public slug of the share. Pass it to the resolve-share operation to get the file.
`filename`	`string`	yes	Current name of the shared file.
`content_type`	`string`	yes	MIME type of the shared file.
`size_bytes`	`integer`	yes	Size of the shared file in bytes.
`revoked`	`boolean`	yes	True when the share was revoked. A revoked share can no longer be resolved. Creating the share again turns it back on.

FileSummary

—

Used by: Files

Field	Type	Required	Description
`file_count`	`integer`	yes	Number of ready files.
`storage_file_count`	`integer`	yes	Number of ready files that count toward storage. Files provided by template skills are not counted.
`used_bytes`	`integer`	yes	Total size in bytes of the files that count toward storage.
`image_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_IMAGE` category.
`video_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_VIDEO` category.
`document_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_DOCUMENT` category.
`instances`	`array<object>`	yes	Ready files grouped by the agent they belong to, or by instance when they have no agent, largest group first.
`instances[].source`	`string`	yes	How the file came to exist. New values can be added, so ignore values you do not know. Allowed values: `"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. (enum table)
`instances[].instance_id`	`string`	no	ID of the instance the file belongs to. Omitted for files that are not tied to an instance.
`instances[].agent_id`	`string`	no	ID of the agent the file belongs to. Omitted for files that are not tied to an agent.
`instances[].operation_id`	`string`	no	ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`.
`instances[].instance_name`	`string`	no	Current display name of the instance, filled in when the file is returned. Omitted for files without an instance.
`instances[].agent_name`	`string`	no	Current display name of the agent, filled in when the file is returned. Omitted for files without an agent.
`instances[].avatar_url`	`string`	no	URL of the agent avatar. Omitted for files without an agent.
`instances[].harness`	`string`	no	Harness the instance runs, for example `openclaw`. Omitted for files without an instance.
`instances[].destroyed`	`boolean`	no	True when the instance has been terminated or deleted. The file stays available. Omitted when false.
`instances[].count`	`integer`	yes	Number of ready files in this group.

FileTransferDescriptor

—

Used by: Files

Field	Type	Required	Description
`direction`	`string`	yes	Whether the URL is used to upload or to download the file content. Allowed values: `"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. (enum table)
`file_id`	`string`	yes	ID of the file the transfer is for.
`url`	`string`	yes	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`	`string`	yes	HTTP method to use with `url`: `PUT` for an upload, `GET` for a download.
`required_headers`	`map<string, string>`	yes	Headers to send with the transfer request exactly as given. Empty when none are required.
`expires_at`	`string`	yes	Time the URL stops working, as an RFC 3339 timestamp. Upload URLs are valid for 15 minutes and download URLs for 5 minutes. Constraints: `format=date-time`.
`content_type`	`string`	yes	MIME type of the file.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Omitted when no digest is known.

InstancePage

—

Used by: Instances

Field	Type	Required	Description
`data`	array<InstanceSummary>	yes	Instances on this page, newest first.
`total`	`integer`	yes	Total number of instances that match the filters, across all pages.

InstanceSummary

—

Used by: Instances

Field	Type	Required	Description
`has_ever_run`	`boolean`	yes	Whether the instance has ever reached the running state. False means it has never delivered a running service.
`id`	`string`	yes	Unique ID of the instance.
`organization_id`	`string`	yes	ID of the organization that owns the instance.
`app_id`	`string`	yes	ID of the app the instance belongs to.
`developer_id`	`string`	yes	ID of the developer account the instance was created under.
`name`	`string`	yes	Display name of the instance.
`harness`	`string`	yes	Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`).
`provider_id`	`string`	yes	ID of the provider that hosts the instance.
`region`	`string`	yes	Region the instance is deployed in.
`os_type`	`string`	yes	Operating system of the instance: `linux`, `windows`, `android` or `macos`.
`status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, InstanceSummary.status values.
`desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`ms_connection_status`	`string`	yes	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`	`string`	yes	Time the instance was created, as an RFC 3339 UTC timestamp.
`updated_at`	`string`	yes	Time the instance was last updated, as an RFC 3339 UTC timestamp.
`resource_version`	`integer`	yes	Version of the instance record, starting at 1. Send it in the `If-Match` header of write requests so concurrent changes are detected. Constraints: `minimum=1`, `format=int64`.
`image_slot`	`string`	no	Variant trait. Key that selects the execution image for the instance. Not a container repository name.
`worker_image_id`	`string`	no	Variant trait. AgentBay worker image. Never the platform `image_id`.
`model_catalog`	`string`	no	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`	`string`	no	Variant trait. Key into the monthly fee table that prices the instance.
`icon_key`	`string`	no	Variant trait. UI icon selector. Clients must not derive it from `harness`.
`device_control`	`boolean`	no	Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected.
`runtime_profile`	`string`	no	Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`.
`free_plan`	`boolean`	no	Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it.
`cloud_provider`	`string`	no	`agentbay`, `beeos`, or empty when self-hosted.

InstanceSummary.status values

Value	Meaning
`"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.

InstanceTemplate

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the template.
`name`	`string`	yes	Display name of the template.
`description`	`string`	no	Description of the template.
`logo_url`	`string`	no	—
`sort_order`	`integer`	no	—
`harness`	`string`	no	—
`provider_id`	`string`	no	—
`specs`	array<CatalogSpec>	no	—
`variants`	array<CatalogVariant>	no	Deployable variants of the template. Send a variant's `id` as `variant_id` when creating an instance.

InstanceTemplatePage

—

Used by: Catalog

Field	Type	Required	Description
`data`	array<InstanceTemplate>	yes	Templates on the requested page.
`total`	`integer`	yes	Total number of templates that match the filters, across all pages.

JSONValue

A genuinely open JSON value (provider/plugin parameters or arbitrary metadata).

Used by: Identity, Catalog, Instances, Messages, Responses, Harnesses, Automations, A2A

Union: exactly one alternative applies.

boolean
number
string
array<JSONValue>
map<string, JSONValue>

Message

—

Used by: Messages

Field	Type	Required	Description
`id`	`string`	yes	ID of the message.
`conversation_id`	`string`	yes	ID of the conversation the message belongs to.
`type`	`string`	yes	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. Allowed values: see the table below, Message.type values.
`content`	JSONValue	yes	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. Structure by `Message.type`: see the variant table.
`sender`	`string`	yes	Identity that sent the message. Other senders appear as their own identity ID.
`reply_to`	`string`	no	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`	`string`	yes	Time the message was created, in RFC 3339 format. Constraints: `format=date-time`.
`offset`	`integer`	yes	Position of the message in the conversation history. Newer messages have larger offsets. Constraints: `format=int64`.
`history_generation`	`integer`	yes	Generation of the conversation history the message belongs to. Constraints: `format=int64`.
`state`	`string`	no	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. Allowed values: see the table below, Message.state values.
`stop_reason`	`string`	no	Why the message reached a final state. Present only on final messages and can be empty when the reason is unknown. Allowed values: see the table below, Message.stop_reason values.
`body`	`string`	no	Text of the message. For a reply that is still `streaming` it is the text produced so far.
`parts`	array<map<string, JSONValue>>	no	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. Structure by `type`: see the variant table.
`updated_at`	`string`	no	Time the message was last changed, in RFC 3339 format. Omitted when the message was never updated. Constraints: `format=date-time`.
`runtime_dispatch`	map<string, JSONValue>	no	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`	`string`	no	Reserved. The Server API does not currently return this field. Allowed values: `"published"`, `"unconfirmed"`, `"not_republished"`. (enum table)

Message.type values

Value	Meaning
`"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`.

Message.state values

Value	Meaning
`"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.

Message.stop_reason values

Value	Meaning
`"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.

Message.content by Message.type

The structure of Message.content depends on Message.type.

Value of Message.type	Description	Structure
`"chat_message"`	A prompt sent by the caller to the agent.	MessageContentChatMessage
`"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.	MessageContentAgentReply
`"agent_reply_error"`	An error reply from the agent, sent as its own message kind instead of an `agent_reply` that carries an error.	MessageContentAgentReply
`"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`.	MessageContentAgentRefuse
`"agent_busy"`	Older name of `agent.refuse`, still sent by some agent runtimes. Treat it the same way.	MessageContentAgentRefuse
`"chat_cancel"`	A request to stop the agent's turn for an earlier `chat_message`. `content` holds `target_message_id` and an optional `reason`.	MessageContentChatCancel
`"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.	MessageContentDeviceCommand
`"device_error"`	The failure of a `device_command`. `content` holds `error` and `code`.	MessageContentDeviceError

Message.parts[] by type

The structure of Message.parts[] depends on its own type value.

Value of type	Description	Structure
`"text"`	A piece of the reply text.	MessagePartText
`"thinking"`	A piece of the agent's reasoning.	MessagePartThinking
`"tool_use"`	A tool call made by the agent.	MessagePartToolUse
`"tool_result"`	The result of a tool call.	MessagePartToolResult
`"file"`	A file attached to the message. Images, audio and video are all `file` parts; tell them apart by `mime_type`.	MessagePartFile
`"source"`	A cited source or reference.	MessagePartSource
`"custom"`	An extension part for structured content that has no dedicated type. `kind` says what the part is.	MessagePartCustom

MessageContentAgentRefuse

Content of a message in which the agent declines the task.

Used by: Messages

Field	Type	Required	Description
`reason`	`string`	no	Why the agent declined, for example `agent_busy`.
`message`	`string`	no	Readable explanation.

Additional properties are accepted.

MessageContentAgentReply

Content of an agent reply. A successful reply carries text; a failed one carries error.

Used by: Messages

Field	Type	Required	Description
`text`	`string`	no	Text of the reply.
`error`	`string`	no	Error message when the reply is a failure.

Additional properties are accepted.

MessageContentChatCancel

Content of a request to stop the agent's turn.

Used by: Messages

Field	Type	Required	Description
`target_message_id`	`string`	yes	ID of the `chat_message` whose turn should stop.
`reason`	`string`	no	Why the turn should stop: `canceled`, `caller_disconnected` or `timeout`.

Additional properties are accepted.

MessageContentChatMessage

Content of a prompt sent to the agent.

Used by: Messages

Field	Type	Required	Description
`message`	`string`	yes	Text of the prompt.

Additional properties are accepted.

MessageContentDeviceCommand

Content of a device tool call.

Used by: Messages

Field	Type	Required	Description
`tool`	`string`	no	Name of the device tool to run, for example `screenshot`, `click` or `tap`.
`args`	JSONValue	no	Arguments of the tool; they depend on the tool. Nullable.
`channel_id`	`string`	no	ID of the conversation the command belongs to.
`context_id`	`string`	no	ID of the conversation the command belongs to.

Additional properties are accepted.

MessageContentDeviceError

Content of the failure of a device tool call.

Used by: Messages

Field	Type	Required	Description
`error`	`string`	no	Readable error message.
`code`	`string`	no	Kind of failure reported by the device tool, for example `unsupported`, `invalid_args` or `internal_error`.

Additional properties are accepted.

MessageEnvelope

—

Used by: Messages

Field	Type	Required	Description
`id`	`string`	yes	ID of the message.
`conversation_id`	`string`	yes	ID of the conversation the message belongs to.
`type`	`string`	yes	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. Allowed values: see the table below, MessageEnvelope.type values.
`sender`	`string`	yes	Identity that sent the message. Other senders appear as their own identity ID.
`reply_to`	`string`	no	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`	`string`	yes	Text of the message. For a reply that is still `streaming` it is the text produced so far.
`parts`	array<map<string, JSONValue>>	no	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. Structure by `type`: see the variant table.
`state`	`string`	yes	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. Allowed values: see the table below, MessageEnvelope.state values.
`stop_reason`	`string`	no	Why the message reached a final state. Present only on final messages and can be empty when the reason is unknown. Allowed values: see the table below, MessageEnvelope.stop_reason values.
`content`	JSONValue	no	Reserved. The Server API does not currently return this field; read `body` and `parts`.
`created_at`	`string`	no	Time the message was created, in RFC 3339 format. Constraints: `format=date-time`.
`updated_at`	`string`	no	Time the message was last changed, in RFC 3339 format. Omitted when the message was never updated. Constraints: `format=date-time`.

MessageEnvelope.type values

Value	Meaning
`"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`.

MessageEnvelope.state values

Value	Meaning
`"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.

MessageEnvelope.stop_reason values

Value	Meaning
`"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.

MessageEnvelope.parts[] by type

The structure of MessageEnvelope.parts[] depends on its own type value.

Value of type	Description	Structure
`"text"`	A piece of the reply text.	MessagePartText
`"thinking"`	A piece of the agent's reasoning.	MessagePartThinking
`"tool_use"`	A tool call made by the agent.	MessagePartToolUse
`"tool_result"`	The result of a tool call.	MessagePartToolResult
`"file"`	A file attached to the message. Images, audio and video are all `file` parts; tell them apart by `mime_type`.	MessagePartFile
`"source"`	A cited source or reference.	MessagePartSource
`"custom"`	An extension part for structured content that has no dedicated type. `kind` says what the part is.	MessagePartCustom

MessageEnvelopeResponse

—

Used by: Messages

Field	Type	Required	Description
`data`	MessageEnvelope	yes	The message.

MessagePage

—

Used by: Messages

Field	Type	Required	Description
`messages`	array<Message>	yes	Messages on this page.
`next_cursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false.
`has_more`	`boolean`	yes	Whether more messages are available after this page.
`latest_offset`	`integer`	yes	Upper bound of the offsets scanned for this page. It is not the history boundary; use `history_boundary_offset` for that. Constraints: `format=int64`.
`history_generation`	`integer`	yes	Generation of the conversation history this page was read from. Constraints: `format=int64`.
`history_boundary_offset`	`integer`	yes	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. Constraints: `format=int64`.

MessagePartCustom

An extension part for structured content that has no dedicated type. kind says what the part is.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `custom`.
`kind`	`string`	no	What kind of custom part this is.
`data`	JSONValue	no	Payload of the part as JSON; it depends on `kind`. Nullable.

Additional properties are accepted.

MessagePartFile

A file attached to the message. Images, audio and video are all file parts; tell them apart by mime_type.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `file`.
`url`	`string`	no	URL of the file.
`mime_type`	`string`	no	MIME type of the file, for example `image/png`.
`name`	`string`	no	File name.
`size`	`integer`	no	Size of the file in bytes. Constraints: `format=int64`.

Additional properties are accepted.

MessagePartSource

A cited source or reference.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `source`.
`url`	`string`	no	URL of the source.
`title`	`string`	no	Title of the source.
`snippet`	`string`	no	Excerpt of the source.

Additional properties are accepted.

MessagePartText

A piece of the reply text.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `text`.
`text`	`string`	no	The text.

Additional properties are accepted.

MessagePartThinking

A piece of the agent's reasoning.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `thinking`.
`text`	`string`	no	The reasoning text.
`state`	`string`	no	Whether the reasoning is still being written. Allowed values: `"streaming"` — The part is still being written; `"done"` — The part is complete. A missing state also means done. (enum table)

Additional properties are accepted.

MessagePartToolResult

The result of a tool call.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `tool_result`.
`tool_use_id`	`string`	no	ID of the `tool_use` part this result belongs to.
`content`	JSONValue	no	Result of the tool: a JSON object or a plain string. Nullable.
`is_error`	`boolean`	no	Whether the tool call failed.

Additional properties are accepted.

MessagePartToolUse

A tool call made by the agent.

Used by: Messages

Field	Type	Required	Description
`type`	`string`	yes	Always `tool_use`.
`id`	`string`	no	ID of the tool call. A `tool_result` part refers to it with `tool_use_id`.
`name`	`string`	no	Name of the tool.
`arguments`	JSONValue	no	Arguments of the call as JSON. Nullable.
`state`	`string`	no	Whether the arguments are still being written. Allowed values: `"streaming"` — The part is still being written; `"done"` — The part is complete. A missing state also means done. (enum table)

Additional properties are accepted.

ModelPage

—

Used by: Catalog

Field	Type	Required	Description
`data`	array<DeployModel>	yes	Models that match the filters.
`total`	`integer`	yes	Number of models that match the filters.

portalBindWire

—

Used by: Device bindings

Field	Type	Required	Description
`provider_id`	`string`	no	ID of the provider that hosts the instance. Set when a new instance was created for the device.
`bind_id`	`string`	yes	ID of the bind session. It starts with `portal_`.
`short_code`	`string`	yes	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`	`string`	yes	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. Allowed values: see the table below, portalBindWire.status values.
`instance_id`	`string`	no	ID of the instance bound to the device. Present once the session is bound.
`expires_at`	`integer`	yes	Time the session expires, in Unix seconds. A session is valid for 10 minutes.
`name`	`string`	yes	Display name for the instance created for the device. Defaults to `BeeRunner`.
`qr_payload`	`string`	no	Link to encode in the QR code the device scans. Returned only when the session is created.
`api_base_url`	`string`	no	Base URL of the API the device connects to. Returned only when the session is created.
`relay_url`	`string`	no	URL of the relay the device connects through. Returned only when the session is created.
`desired_status`	`string`	no	Lifecycle phase the created instance is driven toward: `running`. Set when a new instance was created for the device.
`connectivity`	`string`	no	Reachability of the created instance: `unknown`, `online` or `offline`. Set when a new instance was created for the device.
`resource_version`	`integer`	no	Resource version of the created instance. Set when a new instance was created for the device.

portalBindWire.status values

Value	Meaning
`"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.

ProtoAutomationInput

—

Used by: Automations

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`schedule`	ProtoAutomationSchedule	no	When the automation runs. Required.
`session`	ProtoAutomationSession	no	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`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. It must not be after `validUntil`. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. After it the automation becomes `expired`. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.

ProtoAutomationPatch

—

Used by: Automations

Field	Type	Required	Description
`name`	`string`	no	New display name, 1 to 256 characters and not blank.
`prompt`	`string`	no	New prompt sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	New agent the prompt is sent to.
`schedule`	ProtoAutomationSchedule	no	New schedule. It replaces the whole schedule, so send every field the `kind` needs, including `anchorAt` for `every`.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`.
`validFrom`	`string`	no	New earliest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidFrom`. Constraints: `format=date-time`.
`validUntil`	`string`	no	New latest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidUntil`. Constraints: `format=date-time`.
`clearValidFrom`	`boolean`	no	Set to true to remove the lower bound of the validity period. Cannot be combined with `validFrom`.
`clearValidUntil`	`boolean`	no	Set to true to remove the upper bound of the validity period. Cannot be combined with `validUntil`.

ProtoAutomationRule

—

Used by: Automations

Field	Type	Required	Description
`id`	`string`	no	Unique ID of the automation.
`name`	`string`	no	Display name of the automation.
`prompt`	`string`	no	Text sent to the agent on every run.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to.
`schedule`	ProtoAutomationSchedule	no	When the automation runs. Empty (`kind` unset) for `webhook` automations.
`session`	ProtoAutomationSession	no	How runs choose their conversation. Automations created through this API always use `new`.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no lower bound. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no upper bound. Constraints: `format=date-time`.
`status`	`string`	no	State of the automation. Allowed values: `"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`. (enum table)
`nextFireAt`	`string`	no	Time of the next scheduled run, as an RFC 3339 timestamp. Null when the automation is paused or expired and for `webhook` automations. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation was created from. Empty when it was not created from a conversation.
`createdAt`	`string`	no	Time the automation was created, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`updatedAt`	`string`	no	Time the automation was last changed, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`triggerKind`	`string`	no	What starts a run. Automations created before webhook triggers existed can report an empty value; treat it as `schedule`. Allowed values: `"schedule"` — Runs start on the `schedule`; `"webhook"` — Runs start when the event source delivers an event, optionally narrowed by `eventFilter`. (enum table)
`hookId`	`string`	no	ID of the endpoint that receives the events of a `webhook` automation. Empty for `schedule` automations and for Gmail automations.
`source`	`string`	no	Platform that sends the events of a `webhook` automation, for example `github` or `gmail`. Empty for `schedule` automations.
`eventFilter`	`string`	no	Event type that starts a run of a `webhook` automation. Empty when every event starts a run.
`mailbox`	`string`	no	Gmail address a `webhook` automation watches. Empty for other sources.

ProtoAutomationRun

—

Used by: Automations

Field	Type	Required	Description
`id`	`string`	no	Unique ID of the run.
`automationId`	`string`	no	ID of the automation the run belongs to.
`triggerType`	`string`	no	What created the run. Allowed values: `"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. (enum table)
`scheduledAt`	`string`	no	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. Constraints: `format=date-time`.
`createdAt`	`string`	no	Time the run was created, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`status`	`string`	no	Delivery state of the run. It tells whether the prompt reached the agent's conversation, not whether the agent finished the work. Allowed values: `"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. (enum table)
`target`	ProtoAutomationTarget	no	Agent the run delivers to, copied from the automation when the run was created.
`session`	ProtoAutomationSession	no	How the run chooses its conversation, copied from the automation when the run was created. A rerun sets it from `rerunSessionMode`.
`conversationId`	`string`	no	ID of the conversation the prompt is delivered into. Empty until the run is bound to a conversation.
`wakeMessageId`	`string`	no	ID of the conversation message that carries the prompt. It equals the run `id`.
`sourceRunId`	`string`	no	ID of the run this run repeats. Set only for reruns.
`rerunSessionMode`	`string`	no	Which conversation a rerun is delivered into. Empty for runs that are not reruns. Allowed values: `"original"` — The conversation the source run was delivered into; `"new"` — A new conversation. (enum table)
`reasonCode`	`string`	no	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`	`string`	no	Time the prompt was accepted, as an RFC 3339 timestamp. Null until `status` is `dispatched`. Constraints: `format=date-time`.

ProtoAutomationRunInput

—

Used by: Automations

Field	Type	Required	Description
`sourceRunId`	`string`	no	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`	`string`	no	Which conversation the rerun is delivered into. Required when `sourceRunId` is sent and not allowed without it. Allowed values: `"original"` — The conversation the source run was delivered into; `"new"` — A new conversation. (enum table)

ProtoAutomationSchedule

—

Used by: Automations

Field	Type	Required	Description
`kind`	`string`	no	Type of the schedule. It decides which of the other fields are required. Allowed values: `"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`. (enum table)
`tz`	`string`	no	IANA time zone name, for example `Asia/Shanghai`. Required for every kind; `Local` is not accepted.
`at`	`string`	no	Time of the single run, as an RFC 3339 timestamp. Required when `kind` is `at`; not allowed for other kinds. Constraints: `format=date-time`.
`intervalSeconds`	`string`	no	Seconds between runs, as a decimal string. Required and greater than 0 when `kind` is `every`; not allowed for other kinds.
`anchorAt`	`string`	no	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. Constraints: `format=date-time`.
`expression`	`string`	no	Five-field cron expression: minute, hour, day of month, month and day of week. Required when `kind` is `cron`; not allowed for other kinds.

ProtoAutomationSession

—

Used by: Automations

Field	Type	Required	Description
`mode`	`string`	no	How a run chooses the conversation it is delivered into. Allowed values: `"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`. (enum table)
`boundConversationId`	`string`	no	ID of the conversation runs are delivered into. Set only when `mode` is `bound`; empty otherwise.

ProtoAutomationTarget

—

Used by: Automations

Field	Type	Required	Description
`instanceId`	`string`	no	ID of the instance the automation runs on.
`agentId`	`string`	no	ID of the agent that receives the prompt. It must be an active agent of `instanceId` in your app. Required.

ProtoAutomationWebhookInput

—

Used by: Automations

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`session`	ProtoAutomationSession	no	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`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.
`source`	`string`	no	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`	`array<string>`	no	Names of the events to subscribe to at the source, for example the GitHub event types the repository should deliver.
`repoOwner`	`string`	no	Owner of the repository to watch. Required when `source` is `github`.
`repoName`	`string`	no	Name of the repository to watch. Required when `source` is `github`.
`eventFilter`	`string`	no	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`	`string`	no	Gmail address to watch. Required when `source` is `gmail`; leave empty for other sources.

ProtoListAutomationRunsResponse

—

Used by: Automations

Field	Type	Required	Description
`items`	array<ProtoAutomationRun>	no	Runs on this page.
`nextCursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when there are no more runs.

ProtoListAutomationsResponse

—

Used by: Automations

Field	Type	Required	Description
`items`	array<ProtoAutomationRule>	no	Automations on this page.
`nextCursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when there are no more automations.

Provider

—

Used by: Catalog

Field	Type	Required	Description
`id`	`string`	yes	ID of the provider.
`name`	`string`	yes	Display name of the provider.
`description`	`string`	no	—
`capabilities`	ProviderCapabilities	no	—

ProviderCapabilities

—

Used by: Catalog

Field	Type	Required	Description
`long_running`	`boolean`	yes	—
`browser_use`	`boolean`	yes	—
`code_exec`	`boolean`	yes	—
`file_system`	`boolean`	yes	—
`custom_image`	`boolean`	yes	—
`device`	`boolean`	yes	—
`max_duration_sec`	`integer`	yes	—
`cost_model`	`string`	yes	—

ProviderPage

—

Used by: Catalog

Field	Type	Required	Description
`data`	array<Provider>	yes	Providers that match the filters.
`total`	`integer`	yes	Number of providers that match the filters.

RealtimeTicketHeader

—

Used by: Instances

Field	Type	Required	Description
`alg`	`string`	yes	Signature algorithm of the ticket: `RS256`.
`typ`	`string`	yes	Token type: `JWT`.
`kid`	`string`	yes	ID of the key that signed the ticket.

ReasoningResult

—

Used by: Conversations

Field	Type	Required	Description
`metadata_version`	`integer`	yes	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.

ReasoningResultResponse

—

Used by: Conversations

Field	Type	Required	Description
`data`	ReasoningResult	yes	The result of the change.

ReasoningSettings

—

Used by: Conversations

Field	Type	Required	Description
`modelId`	`string`	yes	ID of the model that `reasoningOverrideId` applies to, 1 to 512 characters. Constraints: `minLength=1`, `maxLength=512`.
`reasoningOverrideId`	`string`	yes	ID of the reasoning option to use with the model, 1 to 64 characters. Send `null` to use the model's default. Nullable. Constraints: `minLength=1`, `maxLength=64`.

RegionPage

—

Used by: Catalog

Field	Type	Required	Description
`data`	array<DeployRegion>	yes	Regions that match the filters.
`total`	`integer`	yes	Number of regions that match the filters.

ReplyShareResponse

—

Used by: Messages

Field	Type	Required	Description
`data`	`object`	yes	The shared reply.
`data.slug`	`string`	yes	Public slug that identifies the share.
`data.created_at`	`string`	yes	Time the share was created.
`data.agent`	`object`	yes	The agent that wrote the reply.
`data.agent.name`	`string`	yes	Display name of the agent.
`data.agent.avatar_url`	`string`	yes	URL of the agent's avatar.
`data.agent.framework`	`string`	yes	Agent framework of the instance the agent runs on.
`data.reply`	`object`	yes	The shared reply.
`data.reply.parts`	`array<object>`	yes	Content of the reply. It holds one part of type `text`.
`data.reply.parts[].type`	`string`	yes	Always `text`.
`data.reply.parts[].text`	`string`	yes	Text of the reply.
`data.reply.created_at`	`string`	yes	Time the reply message was created.
`data.sources`	`array<object>`	yes	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`.
`data.sources[].url`	`string`	no	URL of the source.
`data.sources[].title`	`string`	no	Title of the source, when the agent provided one.
`data.files`	`array<object>`	yes	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`.
`data.files[].file_id`	`string`	no	Reserved. The server does not currently return this field; a file is identified by `public_url`.
`data.files[].filename`	`string`	no	Reserved. The server does not currently return this field; the file name is returned as `name`.
`data.files[].content_type`	`string`	no	Reserved. The server does not currently return this field; the MIME type is returned as `mime_type`.
`data.files[].size_bytes`	`integer`	no	Reserved. The server does not currently return this field.

RuntimeExecResult

—

Used by: Instances

Field	Type	Required	Description
`exit_code`	`integer`	yes	Exit code of the command.
`stdout`	`string`	yes	Standard output of the command, at most 64 KiB.
`stderr`	`string`	yes	Standard error of the command, at most 64 KiB.
`truncated`	`boolean`	yes	Whether the output was truncated.

RuntimeInstanceResult

—

Used by: Instances

Field	Type	Required	Description
`data`	RuntimeInstanceSummary	yes	The instance as of this response.
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

RuntimeInstanceStatusResult

—

Used by: Instances

Field	Type	Required	Description
`data`	`object`	yes	Current status of the instance.
`data.id`	`string`	yes	Unique ID of the instance.
`data.name`	`string`	yes	Display name of the instance.
`data.status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, RuntimeInstanceStatusResult.data.status values.
`data.desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`data.connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`operation`	RuntimeOperationSummary	yes	Lifecycle operation that this response reports on.

RuntimeInstanceStatusResult.data.status values

Value	Meaning
`"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.

RuntimeInstanceSummary

—

Used by: Instances

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the instance.
`organization_id`	`string`	yes	ID of the organization that owns the instance.
`app_id`	`string`	yes	ID of the app the instance belongs to.
`developer_id`	`string`	yes	ID of the developer account the instance was created under.
`name`	`string`	yes	Display name of the instance.
`harness`	`string`	yes	Product harness name (for example `openclaw`), not a UHP `harness_id` (`chrn_*`).
`provider_id`	`string`	yes	ID of the provider that hosts the instance.
`region`	`string`	yes	Region the instance is deployed in.
`os_type`	`string`	yes	Operating system of the instance: `linux`, `windows`, `android` or `macos`.
`status`	`string`	yes	Lifecycle phase of the instance: `pending`, `provisioning`, `running`, `stopped` or `terminated`. Allowed values: see the table below, RuntimeInstanceSummary.status values.
`desired_status`	`string`	yes	Lifecycle phase the instance is being driven toward: `running`, `stopped` or `terminated`. Allowed values: `"running"` — The instance should be running; `"stopped"` — The instance should be stopped; `"terminated"` — The instance should be deleted. (enum table)
`connectivity`	`string`	yes	Reachability of the instance's agent: `unknown`, `online` or `offline`. Allowed values: `"unknown"` — Reachability has not been determined; `"online"` — The instance's agent is connected; `"offline"` — The instance's agent is not connected. (enum table)
`error_code`	`string`	no	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`	`string`	yes	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`	`string`	no	ID of the platform image the instance runs.
`image_version_id`	`string`	no	ID of the platform image version the instance runs.
`image_version`	`string`	no	Version label of the platform image the instance runs.
`image_ref`	`string`	no	Pinned public image reference. Provider configuration is never included.
`model_primary`	`string`	no	Primary model configured for the instance.
`models`	`array<string>`	no	Models configured for the instance.
`llm`	RuntimeLLMView	no	Model providers and models supplied for the instance, with API keys removed. Nullable.
`hosting_type`	`string`	no	Where the instance is hosted: `cloud` or `selfhosted`.
`cloud_provider`	`string`	no	`agentbay`, `beeos`, or empty when self-hosted.
`image_slot`	`string`	no	Variant trait. Key that selects the execution image for the instance. Not a container repository name.
`worker_image_id`	`string`	no	Variant trait. AgentBay worker image. Never the platform `image_id`.
`model_catalog`	`string`	no	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`	`string`	no	Variant trait. Key into the monthly fee table that prices the instance.
`icon_key`	`string`	no	Variant trait. UI icon selector. Clients must not derive it from `harness`.
`device_control`	`boolean`	yes	Variant trait. Whether the instance accepts device-control commands. False means those commands are rejected.
`runtime_profile`	`string`	no	Variant trait. Profile of the agent runtime the instance uses. Known values are `openclaw`, `hermes` and `beeos-browser`.
`free_plan`	`boolean`	yes	Variant trait. Whether the free plan allows the instance's variant. False means the free plan does not allow it.
`resource_version`	`integer`	yes	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`	`boolean`	yes	Whether the instance has ever reached the running state. False means it has never delivered a running service.
`created_at`	`string`	yes	Time the instance was created, as an RFC 3339 UTC timestamp.
`updated_at`	`string`	yes	Time the instance was last updated, as an RFC 3339 UTC timestamp.
`capabilities`	`object`	yes	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.
`capabilities.computer`	`boolean`	no	—
`capabilities.mobile`	`boolean`	no	—
`capabilities.device`	`boolean`	no	—
`capabilities.terminal`	`boolean`	no	—

RuntimeInstanceSummary.status values

Value	Meaning
`"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.

RuntimeLLM

—

Used by: Instances

Field	Type	Required	Description
`providers`	array<RuntimeLLMProvider>	yes	Model provider endpoints, 1 to 8 entries. Every provider must be referenced by at least one model.
`models`	array<RuntimeLLMModel>	yes	Selectable models, 1 to 256 entries. Exactly one has the `default` role.

RuntimeLLMModel

—

Used by: Instances

Field	Type	Required	Description
`provider_id`	`string`	yes	ID of the provider that serves the model.
`model`	`string`	yes	Model name as the provider API expects it. It is unique per provider.
`role`	`string`	yes	Role of the model: `default`, `fallback` or `available`. Exactly one model is `default`. Automatic failover uses only `fallback` models. Allowed values: `"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. (enum table)
`order`	`integer`	yes	Position of the model, unique across all models. The `default` model has order 0; `fallback` and `available` models have order 1 or more.

RuntimeLLMProvider

—

Used by: Instances

Field	Type	Required	Description
`id`	`string`	yes	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`	`string`	yes	API protocol the endpoint speaks: `openai` or `anthropic`. Allowed values: `"openai"` — The OpenAI-compatible API; `"anthropic"` — The Anthropic Messages API. (enum table)
`base_url`	`string`	yes	HTTPS base URL of the provider API, at most 512 characters. It must not contain credentials, a query string or a fragment.
`api_key`	`string`	no	API key for the provider, 1 to 4096 characters without whitespace. It is write-only and never returned. Write-only.

RuntimeLLMProviderView

—

Used by: Instances

Field	Type	Required	Description
`id`	`string`	yes	ID of the provider, as referenced by models.
`protocol`	`string`	yes	API protocol the endpoint speaks: `openai` or `anthropic`.
`base_url`	`string`	yes	HTTPS base URL of the provider API.

RuntimeLLMView

—

Used by: Instances

Field	Type	Required	Description
`providers`	array<RuntimeLLMProviderView>	yes	Model provider endpoints, without API keys.
`models`	array<RuntimeLLMModel>	yes	Selectable models.

RuntimeMethodResponse

JSON-RPC 2.0 response. It carries result on success and error on failure, never both. Errors are returned with HTTP status 200.

Used by: A2A

Field	Type	Required	Description
`jsonrpc`	`string`	yes	JSON-RPC protocol version: always `2.0`. Allowed values: `"2.0"` — JSON-RPC version 2.0.
`id`	`string \| integer`	yes	ID of the request that this response answers. It is `null` when the request could not be read. Nullable.
`result`	JSONValue	no	Result of the method. Present only on success; its shape depends on the method. Nullable.
`error`	`object`	no	Error of the call. Present only on failure.
`error.code`	`integer`	yes	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).
`error.message`	`string`	yes	Human-readable description of the error.
`error.data`	JSONValue	no	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`. Nullable.

RuntimeOperationSummary

—

Used by: Instances

Field	Type	Required	Description
`id`	`string`	yes	Unique ID of the operation.
`kind`	`string`	yes	Kind of operation: `create`, `start`, `stop`, `delete` or `image_upgrade`. Allowed values: see the table below, RuntimeOperationSummary.kind values.
`phase`	`string`	yes	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. Allowed values: see the table below, RuntimeOperationSummary.phase values.
`error_code`	`string`	no	Stable failure code, the same value as the instance `error_code`. Raw provider errors are never exported.

RuntimeOperationSummary.kind values

Value	Meaning
`"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.

RuntimeOperationSummary.phase values

Value	Meaning
`"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.

RuntimeUpgradeJob

—

Used by: Instances

Field	Type	Required	Description
`job_id`	`string`	yes	Unique ID of the upgrade job.
`image_version_id`	`string`	no	—
`instance_id`	`string`	yes	ID of the instance being upgraded.
`status`	`string`	yes	Status of the job: `upgrade_pending`, `rollback_pending`, `failed` or `succeeded`. Allowed values: `"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. (enum table)
`target`	`string`	yes	Image version the instance is being upgraded to.
`created_at`	`string`	yes	Time the job was created, as an RFC 3339 UTC timestamp.
`completed_at`	`string`	no	Time the job finished, as an RFC 3339 UTC timestamp. Omitted while the job is not finished. Nullable.
`error`	`string`	no	Stable failure code. Omitted unless the job failed. Nullable.

ServerUsageSummary

—

Used by: Usage

Field	Type	Required	Description
`total_bc`	`string`	yes	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`	`integer`	yes	Number of usage records in the period.
`by_category`	`map<string, string>`	yes	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`	`map<string, string>`	no	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`	`map<string, integer>`	yes	Number of usage records per category in the period, keyed by category. Categories without usage in the period are absent.

SetConversationModelInput

—

Used by: Conversations

Field	Type	Required	Description
`model_override_id`	`string`	yes	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. Nullable. Constraints: `maxLength=512`.

TerminalSessionDocument

—

Used by: Instances

Field	Type	Required	Description
`transport`	`string`	yes	How the ticket connects: always `service-websocket`.
`protocolVersion`	`integer`	yes	Version of the ticket protocol. Currently 1.
`header`	RealtimeTicketHeader	yes	Header of the signed ticket.
`websocketUrl`	`string`	yes	WebSocket URL to open the terminal connection on. It already carries the ticket as a query parameter.
`ticket`	`string`	yes	Signed single-use ticket (a JWT) that authorizes one terminal connection. It is valid for 60 seconds.
`issuedAt`	`string`	yes	Time the ticket was issued, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`expiresAt`	`string`	yes	Time the ticket expires, as an RFC 3339 timestamp. Tickets are valid for 60 seconds. Constraints: `format=date-time`.
`claims`	TerminalTicketClaims	yes	Claims contained in the signed ticket.

TerminalTicketClaims

—

Used by: Instances

Field	Type	Required	Description
`iss`	`string`	yes	Issuer of the ticket.
`aud`	`string`	yes	Audience the ticket is intended for: the terminal service.
`sub`	`string`	yes	Unused. Cloud does not accept an external user id, so this claim is empty.
`jti`	`string`	yes	Unique ID of the ticket.
`instance_id`	`string`	yes	ID of the instance the terminal belongs to.
`platform_agent_id`	`string`	yes	ID of the agent the terminal session is for, the `platformAgentId` of the request.
`client_id`	`string`	yes	ID generated for this terminal client connection.
`conversation_id`	`string`	no	ID of the conversation the terminal is attached to. Present only when the request sent `conversationId`.
`resume_terminal_id`	`string`	no	ID of the terminal to resume. Present only when the request sent `resumeTerminalId`.
`iat`	`integer`	yes	Time the ticket was issued, in Unix seconds.
`exp`	`integer`	yes	Time the ticket expires, in Unix seconds.

UHPAnnotation

—

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Kind of the annotation. Allowed values: `"container_file_citation"` — The text refers to a file produced by the agent.
`container_id`	`string`	no	ID of the container that holds the file. BeeOS does not currently set it.
`file_id`	`string`	no	ID of the file. BeeOS does not currently set it.
`filename`	`string`	no	Name of the file.
`download_url`	`string`	no	Absolute URL the file can be downloaded from. Constraints: `format=uri`.
`start_index`	`integer`	no	Start of the cited range in the text, counted in characters. BeeOS sets it to 0.
`end_index`	`integer`	no	End of the cited range in the text, counted in characters. BeeOS sets it to the length of the text.

Additional properties are accepted.

UHPCapabilities

Named booleans. A server reports false for a capability it does not implement rather than omitting it, so a client can distinguish "not supported" from "server predates this field". A client treats an absent key as false.

Used by: Catalog

Field	Type	Required	Description
`streaming`	`boolean`	no	The server can stream a response as server-sent events.
`sessions`	`boolean`	no	The server keeps sessions that later requests can continue.
`cancellation`	`boolean`	no	A running response can be cancelled.
`files_input`	`boolean`	no	The server accepts files as input to a request.
`files_output`	`boolean`	no	The server returns files that a harness produced.
`session_listing`	`boolean`	no	The server can list existing sessions.
`harness_management`	`boolean`	no	Harnesses can be created, updated and deleted through the API.
`session_sharing`	`boolean`	no	The server can share a session with other callers.
`idempotency`	`boolean`	no	The server honors the `Idempotency-Key` header on the writes that accept it.
`plugins`	`boolean`	no	The server installs Agent Plugins packages into harnesses, serves their files, and exports a harness as a package. Optional at every class.
`environments`	`boolean`	no	The server holds environments: a project's files and installed dependencies, built once, read-only at a fixed path in every session that names one. Optional at every class.
`memories`	`boolean`	no	The server holds memories: a tree of memories with access granted per node, records kept by a connected provider, and tools a harness's agent reaches them with. Optional at every class.

Additional properties are accepted.

UHPContentPart

—

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Kind of the part. Allowed values: `"output_text"` — Text of a `message` item, with optional annotations; `"summary_text"` — Summary text of a `reasoning` item. (enum table) Structure by `type`: see the variant table.
`text`	`string`	no	Text of the part.
`annotations`	array<UHPAnnotation>	no	Annotations that refer to ranges of `text`.

Additional properties are accepted.

UHPContentPart by type

The structure of UHPContentPart depends on its own type value.

Value of type	Description	Structure
`"output_text"`	Text of a `message` item, with optional annotations.	UHPContentPartOutputText
`"summary_text"`	Summary text of a `reasoning` item.	UHPContentPartSummaryText

UHPContentPartOutputText

Text of a message item.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `output_text`.
`text`	`string`	no	Text of the part.
`annotations`	array<UHPAnnotation>	no	Annotations that refer to ranges of `text`.

Additional properties are accepted.

UHPContentPartSummaryText

Summary text of a reasoning item.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `summary_text`.
`text`	`string`	no	Text of the part.

Additional properties are accepted.

UHPCreateResponseRequest

—

Used by: Responses

Field	Type	Required	Description
`input`	string \| array<map<string, JSONValue>>	yes	A bare string is shorthand for one user message.
`model`	`string`	no	Model id for this turn. Omitted means the harness default. Any requested id is dispatched as given.
`metadata`	`object`	no	Client metadata, the extension point of the Responses surface. `harness_id` selects the configured harness; `environment` names the environment this task reads, overriding the harness's (capability `environments`), refused with `environment_not_found` or `environment_not_ready` before the task starts.
`metadata.harness_id`	`string`	no	ID of the harness that runs the task. Optional when exactly one harness is in scope; required when there are several.
`metadata.environment`	`string`	no	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`.
`stream`	`boolean`	no	When true the response is streamed as server-sent events; see `UHPEvent`. Otherwise the call returns the finished response. Defaults to false. Default: `false`.
`previous_response_id`	`string`	no	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. Nullable.
`instructions`	`string`	no	Instructions placed before the input text and separated from it by a line containing `---`.
`store`	`boolean`	no	Whether to keep the response so it can be fetched later. Defaults to true. Default: `true`.
`max_output_tokens`	`integer`	no	Reserved and ignored. It is reported in `metadata.ignored_fields` of the response. Nullable.
`max_step`	`integer`	no	Agent step (tool-call round) budget. Nullable.
`timeout_seconds`	`integer`	no	Wall-clock budget. Nullable.
`tools`	array<map<string, JSONValue>>	no	Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in `metadata.ignored_fields` on the response. A UHP harness invokes and executes tools itself and reports them in `output`; there is no input path for a tool result, so the client-executed tool loop this field implies cannot be completed by a conformant server. Configure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.
`include`	`array<string>`	no	Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in `metadata.ignored_fields` on the response. No values are enumerated, so any string a server recognised would be one it named itself. Tasks §1.4.
`background`	`boolean`	no	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. Default: `false`.

Additional properties are accepted.

UHPDiscovery

—

Used by: Catalog

Field	Type	Required	Description
`object`	`string`	yes	Object type: always `uhp.discovery`. Allowed values: `"uhp.discovery"` — A protocol discovery document.
`protocol`	`string`	yes	Protocol the server speaks: always `uhp`, the Unified Harness Protocol. Allowed values: `"uhp"` — The Unified Harness Protocol.
`versions`	`array<string>`	yes	Protocol versions the server speaks, as values of the `UHP-Version` header. Constraints: `minItems=1`.
`default_version`	`string`	yes	Protocol version the server uses when a request does not send a `UHP-Version` header.
`conformance_class`	`string`	yes	Coarse conformance class of the server. Branch on the flags in `capabilities`, which are exact, rather than on the class. Allowed values: `"core"` — Discovery, harness reads, tasks and sessions; `"extended"` — Core plus file input and artifact retrieval; `"full"` — Extended plus harness management, plugins, environments and memories. (enum table)
`capabilities`	UHPCapabilities	yes	What the server can do. A flag is `true` only when the endpoints behind it answer.
`plugin_schemas`	`array<string>`	no	The Agent Plugins manifest schema identifiers this server installs. Present and non-empty when `capabilities.plugins` is true.
`implementation`	`object`	no	Information about the server. Besides `name` and `version` it may carry `availability`, a statement of how model availability is computed.
`implementation.name`	`string`	no	Name of the server implementation: `BeeOS Cloud`.
`implementation.version`	`string`	no	Version of the server implementation. Omitted when it is not known.

Additional properties are accepted.

UHPError

—

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Category of the error. It follows from the HTTP status. Allowed values: see the table below, UHPError.type values.
`code`	`string`	yes	Specific and machine-readable. Servers may define additional codes for conditions this specification does not cover, and must namespace them with a vendor prefix so a future version cannot collide with them.
`message`	`string`	yes	One sentence, safe to show a user. Must not contain credentials, internal hostnames, file paths, or stack traces.
`param`	`string`	no	Dotted path to the offending field. Nullable.
`detail`	map<string, JSONValue>	no	Additional structured detail about the error, when available. Nullable.

UHPError.type values

Value	Meaning
`"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.

Additional properties are accepted.

UHPErrorEnvelope

—

Used by: —

Field	Type	Required	Description
`error`	UHPError	yes	The error.
`detail`	`string`	no	A human-readable alias of `error.message`, retained for clients written against implementations that predate this envelope. Carries no information not in `error`. Deprecated.

Additional properties are accepted.

UHPEvent

One streamed event. sequence_number starts at 0 and increases by exactly 1 per event, so a client can detect a dropped event rather than silently rendering a gap.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	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. Allowed values: see the table below, UHPEvent.type values. Structure by `type`: see the variant table.
`sequence_number`	`integer`	yes	Position of the event in the stream, starting at 0 and increasing by 1 per event. A gap means an event was lost. Constraints: `minimum=0`.
`response`	UHPResponse	no	Snapshot of the response. Present on lifecycle events.
`item`	UHPOutputItem	no	The output item. Present on `response.output_item.added` and `response.output_item.done`.
`part`	UHPContentPart	no	The content or summary part. Present on content part and reasoning summary part events.
`annotation`	UHPAnnotation	no	The annotation. Present on `response.output_text.annotation.added`.
`delta`	`string`	no	New text, or new function arguments, since the previous delta.
`text`	`string`	no	The complete text. Present on `response.output_text.done`.
`arguments`	`string`	no	The complete function arguments as a JSON string. Present on `response.function_call_arguments.done`.
`item_id`	`string`	no	ID of the output item the event belongs to.
`output_index`	`integer`	no	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`content_index`	`integer`	no	Index of the content part within the item. Constraints: `minimum=0`.
`summary_index`	`integer`	no	Index of the summary part within the item. Constraints: `minimum=0`.
`annotation_index`	`integer`	no	Index of the annotation within the content part. Constraints: `minimum=0`.
`code`	`string`	no	Machine-readable error code. Present on `error` events.
`message`	`string`	no	Readable error message. Present on `error` events.
`param`	`string`	no	Dotted path of the field the error is about, or null. Present on `error` events. Nullable.

UHPEvent.type values

Value	Meaning
`"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.

Additional properties are accepted.

UHPEvent by type

The structure of UHPEvent depends on its own type value.

Value of type	Description	Structure
`"response.created"`	The response was created. `response` is the initial snapshot with status `in_progress`.	UHPEventResponse
`"response.in_progress"`	The response is running. `response` is a snapshot.	UHPEventResponse
`"response.completed"`	The response finished successfully. This is a terminal event: exactly one terminal event ends the stream.	UHPEventResponse
`"response.incomplete"`	The response stopped because of a limit, for example the output limit or the time limit. This is a terminal event.	UHPEventResponse
`"response.failed"`	The response failed or was cancelled; `response.status` is `failed` or `cancelled`. This is a terminal event.	UHPEventResponse
`"response.output_item.added"`	A new output item started. `item` is its initial form and `output_index` its position in the output.	UHPEventOutputItem
`"response.output_item.done"`	An output item is complete. `item` is its final form.	UHPEventOutputItem
`"response.content_part.added"`	A content part was added to a `message` item. `part` is its initial form.	UHPEventContentPart
`"response.content_part.done"`	A content part of a `message` item is complete. `part` is its final form.	UHPEventContentPart
`"response.reasoning_summary_part.added"`	A summary part was added to a `reasoning` item.	UHPEventReasoningSummaryPart
`"response.reasoning_summary_part.done"`	A summary part of a `reasoning` item is complete. `part` is its final form.	UHPEventReasoningSummaryPart
`"response.output_text.delta"`	More text was appended to the text of a `message` item. `delta` is the new text.	UHPEventOutputTextDelta
`"response.reasoning_summary_text.delta"`	More text was appended to the summary of a `reasoning` item. `delta` is the new text.	UHPEventReasoningSummaryTextDelta
`"response.output_text.done"`	The text of a `message` item is complete. `text` is the full text.	UHPEventOutputTextDone
`"response.output_text.annotation.added"`	An annotation, such as a file citation, was added to the text of a `message` item.	UHPEventAnnotationAdded
`"response.function_call_arguments.delta"`	The arguments of a `function_call` item were written. `delta` holds the arguments text.	UHPEventFunctionCallArgumentsDelta
`"response.function_call_arguments.done"`	The arguments of a `function_call` item are complete. `arguments` holds them as a JSON string.	UHPEventFunctionCallArgumentsDone
`"error"`	An error that did not end the response. `code`, `message` and `param` describe it, and a terminal event still follows.	UHPEventError
`"beeos.approval.requested"`	BeeOS extension. The agent asks for approval of an action. The `approval` property holds the approval request document.	UHPEventApproval
`"beeos.approval.resolved"`	BeeOS extension. An approval request was resolved. The `approval` property holds the resolution document.	UHPEventApproval
`"beeos.question.requested"`	BeeOS extension. The agent asks the user a question. The `question` property holds the question request document.	UHPEventQuestion
`"beeos.question.resolved"`	BeeOS extension. A question request was resolved. The `question` property holds the resolution document.	UHPEventQuestion

UHPEventAnnotationAdded

An annotation was added to the text of a message item.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.output_text.annotation.added`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`content_index`	`integer`	yes	Index of the content part within the item. Constraints: `minimum=0`.
`annotation_index`	`integer`	yes	Index of the annotation within the content part. Constraints: `minimum=0`.
`annotation`	UHPAnnotation	yes	The annotation. Present on `response.output_text.annotation.added`.

Additional properties are accepted.

UHPEventApproval

BeeOS extension: an approval request or its resolution.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `beeos.approval.requested`, `beeos.approval.resolved`.
`approval`	JSONValue	yes	The approval document, passed through from the agent host. Nullable.

Additional properties are accepted.

UHPEventContentPart

A content part of a message item was added or finished.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `response.content_part.added`, `response.content_part.done`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`content_index`	`integer`	yes	Index of the content part within the item. Constraints: `minimum=0`.
`part`	UHPContentPart	yes	The content or summary part. Present on content part and reasoning summary part events.

Additional properties are accepted.

UHPEventError

An error that did not end the response.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `error`.
`code`	`string`	yes	Machine-readable error code. Present on `error` events.
`message`	`string`	yes	Readable error message. Present on `error` events.
`param`	`string`	no	Dotted path of the field the error is about, or null. Present on `error` events. Nullable.

Additional properties are accepted.

UHPEventFunctionCallArgumentsDelta

The arguments of a function call were written.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.function_call_arguments.delta`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`delta`	`string`	yes	New text, or new function arguments, since the previous delta.

Additional properties are accepted.

UHPEventFunctionCallArgumentsDone

The arguments of a function call are complete.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.function_call_arguments.done`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`arguments`	`string`	yes	The complete function arguments as a JSON string. Present on `response.function_call_arguments.done`.

Additional properties are accepted.

UHPEventOutputItem

An output item started or finished.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `response.output_item.added`, `response.output_item.done`.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`item`	UHPOutputItem	yes	The output item. Present on `response.output_item.added` and `response.output_item.done`.

Additional properties are accepted.

UHPEventOutputTextDelta

New text of a message item.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.output_text.delta`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`content_index`	`integer`	yes	Index of the content part within the item. Constraints: `minimum=0`.
`delta`	`string`	yes	New text, or new function arguments, since the previous delta.

Additional properties are accepted.

UHPEventOutputTextDone

The text of a message item is complete.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.output_text.done`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`content_index`	`integer`	yes	Index of the content part within the item. Constraints: `minimum=0`.
`text`	`string`	yes	The complete text. Present on `response.output_text.done`.

Additional properties are accepted.

UHPEventQuestion

BeeOS extension: a question request or its resolution.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `beeos.question.requested`, `beeos.question.resolved`.
`question`	JSONValue	yes	The question document, passed through from the agent host. Nullable.

Additional properties are accepted.

UHPEventReasoningSummaryPart

A summary part of a reasoning item was added or finished.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `response.reasoning_summary_part.added`, `response.reasoning_summary_part.done`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`summary_index`	`integer`	yes	Index of the summary part within the item. Constraints: `minimum=0`.
`part`	UHPContentPart	yes	The content or summary part. Present on content part and reasoning summary part events.

Additional properties are accepted.

UHPEventReasoningSummaryTextDelta

New summary text of a reasoning item.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `response.reasoning_summary_text.delta`.
`item_id`	`string`	yes	ID of the output item the event belongs to.
`output_index`	`integer`	yes	Position of the item in the `output` of the response. Constraints: `minimum=0`.
`summary_index`	`integer`	yes	Index of the summary part within the item. Constraints: `minimum=0`.
`delta`	`string`	yes	New text, or new function arguments, since the previous delta.

Additional properties are accepted.

UHPEventResponse

A response lifecycle event that carries a snapshot of the response.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	One of `response.created`, `response.in_progress`, `response.completed`, `response.incomplete`, `response.failed`.
`response`	UHPResponse	yes	Snapshot of the response. Present on lifecycle events.

Additional properties are accepted.

UHPHarness

—

Used by: Harnesses

Field	Type	Required	Description
`id`	`string`	yes	ID of the harness. It starts with `chrn_` and is the `harness_id` to use in other requests. Constraints: `pattern=^chrn_`.
`object`	`string`	no	Object type: always `harness`. Allowed values: `"harness"` — A harness object.
`name`	`string`	yes	Display name of the harness. When the harness has no display name, its name is used, and then its ID.
`base`	`string`	yes	Opaque. Not enumerated by this specification — a client must treat it as a string, or the protocol would need revising every time a harness is released.
`baseLabel`	`string`	no	Human-readable name of `base`: `OpenClaw` for `openclaw` or `Hermes` for `hermes`. Omitted when the base has no known label.
`defaultModel`	`string`	no	ID of the model the harness uses as its primary model. Omitted when it has none.
`systemPrompt`	`string`	no	System prompt of the harness. BeeOS Cloud does not support it, so it is never returned.
`mcpServers`	array<UHPMcpServer>	no	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`	array<UHPSkill>	no	Skills installed on the harness. Returned only by a single-harness read while the instance is running; omitted in listings.
`plugins`	array<UHPPlugin>	no	Installed plugins. Their servers and skills join the harness's own for every turn; `mcpServers` and `skills` above report only what was written to them directly.
`environment`	`string`	no	The environment (`henv_`) this harness's tasks read, mounted read-only at its `mount`; empty when none. A task may name another with its own `environment` field.
`disabledTools`	`array<string>`	no	Names of tools disabled for the harness. BeeOS Cloud does not support it, so it is never returned.
`maxStep`	`integer`	no	Maximum number of steps per run. BeeOS Cloud does not support it, so it is never returned. Nullable.
`timeoutSeconds`	`integer`	no	Run timeout in seconds. BeeOS Cloud does not support it, so it is never returned. Nullable.
`createdAt`	`integer`	no	Unix milliseconds

Additional properties are accepted.

UHPHarnessCreate

—

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	no	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`	`string`	yes	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`	`string`	no	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`	`string`	no	System prompt. BeeOS Cloud does not support it: a non-empty value is rejected with 422 `beeos_field_not_supported`.
`mcp_servers`	array<UHPMcpServer>	no	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`	array<UHPSkill>	no	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`	array<UHPPlugin>	no	Requires the `plugins` capability. Each item needs `files` or `blob`.
`environment`	`string`	no	An environment id of the caller's scope, or empty. Requires the `environments` capability.
`disabled_tools`	`array<string>`	no	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`	`integer`	no	Maximum number of steps per run. BeeOS Cloud does not support it: any value is rejected with 422 `beeos_field_not_supported`. Nullable.
`timeout_seconds`	`integer`	no	Run timeout in seconds. BeeOS Cloud does not support it: any value is rejected with 422 `beeos_field_not_supported`. Nullable.
`instance_id`	`string`	no	BeeOS extension. Instance that hosts a new harness (create only).
`template_id`	`string`	no	BeeOS extension. Agent template applied to the harness.

Additional properties are accepted.

UHPHarnessModels

—

Used by: Harnesses

Field	Type	Required	Description
`harness_id`	`string`	no	ID of the harness the models belong to.
`backend`	`string`	no	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`	`string`	no	ID of the harness's primary model. Omitted when it has none.
`fallback`	`string`	no	Model used when a requested model cannot run. BeeOS Cloud does not report it, so it is never returned.
`models`	array<UHPModel>	yes	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.

UHPMcpServer

A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a disabled entry must not be contacted at all. An unreachable server must not fail the task. Unchanged from 2026-08-11: a process (stdio) server is declared inside a plugin, see PluginMcpServer.

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	yes	Sanitised to a CLI-safe identifier by the server.
`url`	`string`	yes	HTTPS endpoint of the MCP server, at most 2048 characters, without user information or a fragment. Reads report it empty. Constraints: `format=uri`.
`transport`	`string`	no	Transport the server speaks. Defaults to `http` on write. Not returned for a server that uses neither transport. Allowed values: `"http"` — Streamable HTTP; `"sse"` — The older HTTP with server-sent events transport. (enum table) Default: `"http"`.
`enabled`	`boolean`	no	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`. Default: `true`.
`headers`	`map<string, string>`	no	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`	`string`	no	Bearer token, or a server-side reference the server resolves. A server must never return a resolved credential to a client.
`expires_at`	`string`	no	BeeOS extension. Expiry of the supplied short-lived credential; the caller refreshes it with another PUT. Constraints: `format=date-time`.

Additional properties are accepted.

UHPModel

—

Used by: Harnesses

Field	Type	Required	Description
`id`	`string`	yes	ID of the model, usually in `provider/model` form, for example `anthropic/claude-sonnet-5`.
`label`	`string`	no	Display name of the model. BeeOS Cloud does not report one, so it is omitted.
`backend`	`string`	no	Provider family of the model: the part of `id` before the first `/`. Omitted when `id` has none.
`available`	`boolean`	yes	Computed, not asserted: true means the server can serve this model for this harness right now. Listing a model as available and then failing the task is the worst outcome for a client, because a user has already chosen it.
`default`	`boolean`	no	Whether this is the harness's primary model.

Additional properties are accepted.

UHPModelCatalog

—

Used by: Harnesses

Field	Type	Required	Description
`backends`	`map<string, object>`	yes	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.

UHPOutputItem

A client must tolerate item types it does not recognise. A client that renders only message items and ignores the rest is a valid client.

Used by: Responses

Field	Type	Required	Description
`id`	`string`	no	ID of the output item.
`type`	`string`	yes	Kind of the output item. Clients should ignore item types they do not know. Allowed values: `"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`. (enum table) Structure by `type`: see the variant table.
`status`	`string`	no	Progress of the item. Allowed values: `"in_progress"` — The item is still being produced; `"completed"` — The item is complete. (enum table)
`role`	`string`	no	Who wrote a `message` item. Allowed values: `"assistant"` — The agent.
`content`	array<UHPContentPart>	no	Content parts of a `message` item.
`summary`	array<map<string, JSONValue>>	no	Summary of a `reasoning` item.
`call_id`	`string`	no	ID of the function call. A `function_call_output` item refers to its call with the same `call_id`.
`name`	`string`	no	Name of the function the agent called.
`arguments`	`string`	no	JSON, as a string
`output`	`string`	no	Result of the function call, as text.

Additional properties are accepted.

UHPOutputItem by type

The structure of UHPOutputItem depends on its own type value.

Value of type	Description	Structure
`"message"`	A message written by the agent. Its text is in `content`.	UHPOutputItemMessage
`"reasoning"`	The agent's reasoning. Its summary is in `summary`.	UHPOutputItemReasoning
`"function_call"`	A tool call made by the agent, with `name` and `arguments`.	UHPOutputItemFunctionCall
`"function_call_output"`	The result of a tool call, in `output`.	UHPOutputItemFunctionCallOutput

UHPOutputItemFunctionCall

A tool call made by the agent.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `function_call`.
`id`	`string`	no	ID of the output item.
`status`	`string`	no	Progress of the item. Allowed values: `"in_progress"` — The item is still being produced; `"completed"` — The item is complete. (enum table)
`call_id`	`string`	no	ID of the function call. A `function_call_output` item refers to its call with the same `call_id`.
`name`	`string`	no	Name of the function the agent called.
`arguments`	`string`	no	JSON, as a string

Additional properties are accepted.

UHPOutputItemFunctionCallOutput

The result of a tool call.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `function_call_output`.
`id`	`string`	no	ID of the output item.
`status`	`string`	no	Progress of the item. Allowed values: `"in_progress"` — The item is still being produced; `"completed"` — The item is complete. (enum table)
`call_id`	`string`	no	ID of the function call. A `function_call_output` item refers to its call with the same `call_id`.
`output`	`string`	no	Result of the function call, as text.

Additional properties are accepted.

UHPOutputItemMessage

A message written by the agent.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `message`.
`id`	`string`	no	ID of the output item.
`status`	`string`	no	Progress of the item. Allowed values: `"in_progress"` — The item is still being produced; `"completed"` — The item is complete. (enum table)
`role`	`string`	no	Who wrote a `message` item. Allowed values: `"assistant"` — The agent.
`content`	array<UHPContentPart>	no	Content parts of a `message` item.

Additional properties are accepted.

UHPOutputItemReasoning

The agent's reasoning.

Used by: Responses

Field	Type	Required	Description
`type`	`string`	yes	Always `reasoning`.
`id`	`string`	no	ID of the output item.
`status`	`string`	no	Progress of the item. Allowed values: `"in_progress"` — The item is still being produced; `"completed"` — The item is complete. (enum table)
`summary`	array<map<string, JSONValue>>	no	Summary of a `reasoning` item.

Additional properties are accepted.

UHPPlugin

An Agent Plugins package installed into a harness: plugin.json at the root, MCP servers in mcp.json, skills under skills/. A client writes files (or passes back blob) and optionally name and enabled; the server derives manifest, mcpServers, skills and skipped from the package on every write and ignores those fields on input. A refused package leaves the harness unchanged.

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	yes	The manifest's `name`. Optional on write; if sent it must equal the manifest's. Constraints: `maxLength=64`, `pattern=^(?!.(--\|\.\.))[a-z0-9]([a-z0-9.-][a-z0-9])?$`.
`enabled`	`boolean`	no	false keeps the plugin installed and inert; nothing in it is materialised or contacted. Default: `true`.
`files`	array<UHPSkillFile>	no	The package. Must contain `plugin.json` at its root.
`blob`	`string`	no	Server-assigned handle for a package stored out of line. A client passes it back unchanged and reads the files from the plugin files endpoint.
`manifest`	UHPPluginManifest	no	The plugin's `plugin.json`, parsed.
`mcpServers`	array<UHPPluginMcpServer>	no	Derived from `mcp.json`. Placeholders are reported unexpanded; `enabled` is always true, the plugin's own `enabled` governs.
`skills`	array<UHPPluginSkill>	no	Derived from `skills/`, one entry per immediate child directory with a SKILL.md.
`skipped`	array<UHPPluginSkipped>	no	What the server found and could not load. Present on every plugin object the server returns, empty when nothing was skipped.

Additional properties are accepted.

UHPPluginManifest

plugin.json, parsed. Mirrors the Agent Plugins 1.0.0 manifest schema (https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, Apache-2.0) field for field, and permits additional properties because a UHP client ignores fields it does not know. The schema a manifest's own $schema names is authoritative; a server validates against that.

Used by: Harnesses

Field	Type	Required	Description
`$schema`	`string`	yes	URI of the manifest schema that the file follows. Constraints: `format=uri`.
`name`	`string`	yes	Name of the plugin: 1 to 64 lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit. Constraints: `minLength=1`, `maxLength=64`, `pattern=^(?!.(--\|\.\.))[a-z0-9]([a-z0-9.-][a-z0-9])?$`.
`version`	`string`	no	Version of the plugin.
`description`	`string`	no	Description of the plugin.
`author`	`object`	no	Author of the plugin.
`author.name`	`string`	no	Name of the author.
`author.email`	`string`	no	Email address of the author.
`author.url`	`string`	no	URL of the author's web page.
`homepage`	`string`	no	URL of the plugin's home page.
`repository`	`string`	no	Location of the plugin's source repository.
`license`	`string`	no	License of the plugin.
`keywords`	`array<string>`	no	Keywords that describe the plugin.
`extensions`	map<string, map<string, JSONValue>>	no	Client-specific data keyed by reverse-domain namespace, per Agent Plugins §8.

Additional properties are accepted.

UHPPluginMcpServer

An MCP server a plugin's mcp.json declares, derived by the server. The harness MCP server object plus the stdio transport: url is required for http and sse, command for stdio. Placeholders are reported unexpanded; enabled is always true, the plugin's own enabled governs.

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	yes	Name of the server, as declared in `mcp.json`.
`transport`	`string`	no	`http` is Streamable HTTP (`streamable-http` in mcp.json); `sse` the older HTTP+SSE transport; `stdio` a process the server launches inside the agent's sandbox. Allowed values: `"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`. (enum table) Default: `"http"`.
`url`	`string`	no	Endpoint (`http` and `sse`). Constraints: `format=uri`.
`headers`	`map<string, string>`	no	Fixed request headers (`http` and `sse`). Never subject to placeholder expansion.
`command`	`string`	no	One executable token (`stdio`): a bare name resolved on the sandbox's search path, or a plugin-relative path beginning with `./`. Never a shell string, never expanded.
`args`	`array<string>`	no	Arguments (`stdio`). `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expand at run time.
`env`	`map<string, string>`	no	Environment overlay (`stdio`). Must not name PLUGIN_ROOT or PLUGIN_DATA; the server sets those. Values expand at run time.
`cwd`	`string`	no	Working directory (`stdio`). Defaults to the plugin root; must stay within the plugin root or PLUGIN_DATA.
`enabled`	`boolean`	no	Whether the server is enabled. Always `true` for a server derived from a plugin's `mcp.json`. Default: `true`.

Additional properties are accepted.

UHPPluginSkill

—

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	yes	The SKILL.md frontmatter name, equal to the directory name.
`description`	`string`	no	Description from the frontmatter of the skill's `SKILL.md`.

Additional properties are accepted.

UHPPluginSkipped

—

Used by: Harnesses

Field	Type	Required	Description
`path`	`string`	yes	Where in the package, e.g. `skills/broken`, `mcp.json#/mcpServers/redline`, `plugin.json#/vendorField`.
`reason`	`string`	yes	One sentence.

Additional properties are accepted.

UHPResponse

—

Used by: Responses

Field	Type	Required	Description
`id`	`string`	yes	ID of the response. It starts with `resp_`. Constraints: `pattern=^resp_`.
`object`	`string`	yes	Object type. Allowed values: `"response"` — A response object.
`created_at`	`integer`	yes	Unix seconds
`status`	UHPResponseStatus	yes	Status of the response. See `UHPResponseStatus` for the values. Allowed values: see the table below, UHPResponseStatus values.
`error`	UHPError	no	Non-null only when status is `failed`. Nullable.
`incomplete_details`	map<string, JSONValue>	no	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. Nullable.
`previous_response_id`	`string`	no	ID of the response this one continues, when the request set `previous_response_id`. Nullable.
`model`	`string`	yes	The model that actually ran.
`output`	array<UHPOutputItem>	yes	Output items produced so far, in order.
`store`	`boolean`	no	Whether the response is kept so it can be fetched later.
`usage`	UHPUsage	no	null when the server cannot account for usage. A fabricated zero would be worse than an honest absence, because a client cannot tell it from a free task. Nullable.
`metadata`	`object`	no	Extra information about the run.
`metadata.session_id`	`string`	no	ID of the session the response ran in. Responses chained with `previous_response_id` share it.
`metadata.environment`	`string`	no	The environment the task read, when it read one (capability `environments`).
`metadata.requested_model`	`string`	no	The id the client sent, when the client sent one.
`metadata.model_fallback`	`boolean`	no	True only when the harness reported it could not switch to the requested model.
`metadata.model_fallback_reason`	`string`	no	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.`
`metadata.ignored_fields`	`array<string>`	no	Request fields the server did not act on, by name, in any order. Required when the request carried `tools` or `include`, which are reserved and ignored. A silently ignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.

UHPResponseStatus values

Value	Meaning
`"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`.

Additional properties are accepted.

UHPSkill

A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent can read it — materialising only SKILL.md breaks every skill carrying references, scripts or data. Round-tripping a harness through GET and PUT must not lose skill contents.

Used by: Harnesses

Field	Type	Required	Description
`name`	`string`	yes	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`	`boolean`	no	false suppresses the skill, including one inherited from the base. Default: `true`.
`files`	array<UHPSkillFile>	no	The bundle. Must contain a SKILL.md.
`content`	`string`	no	Shorthand for a single-file bundle whose only member is SKILL.md.
`blob`	`string`	no	Server-assigned handle for a bundle stored out of line. A client receives it, passes it back unchanged, and reads the files from the skill files endpoint.
`sha256`	`string`	no	BeeOS extension. SHA-256 of the Files bundle referenced by blob.
`size_bytes`	`string`	no	BeeOS extension. Decimal byte size of the Files bundle referenced by blob.

Additional properties are accepted.

UHPSkillFile

One file of a skill folder or of a plugin package.

Used by: Harnesses

Field	Type	Required	Description
`path`	`string`	yes	Relative to the skill's own folder, or to the plugin root; nested directories are supported. A server must reject a path that escapes the folder.
`content`	`string`	no	Text content.
`content_b64`	`string`	no	Base64 for binary content; preserved byte-for-byte.

Additional properties are accepted.

UHPUsage

—

Used by: Responses

Field	Type	Required	Description
`input_tokens`	`integer`	no	Number of input tokens. Constraints: `minimum=0`.
`output_tokens`	`integer`	no	Number of output tokens. Constraints: `minimum=0`.
`total_tokens`	`integer`	no	Total number of tokens used. Constraints: `minimum=0`.
`cache_read_tokens`	`integer`	no	Input tokens read from the cache. Constraints: `minimum=0`.
`cache_write_tokens`	`integer`	no	Input tokens written to the cache. Constraints: `minimum=0`.

Additional properties are accepted.

UpdateConversationInput

—

Used by: Conversations

Field	Type	Required	Description
`title`	`string`	yes	New title of the conversation, 1 to 256 characters after leading and trailing whitespace is removed. Constraints: `minLength=1`, `maxLength=256`.

UpdateServerInstanceInput

—

Used by: Instances

Field	Type	Required	Description
`name`	`string`	no	New display name, 1 to 128 characters, without leading or trailing whitespace. Send `name`, `llm` or both.
`llm`	RuntimeLLM	no	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.

Enums

Each table lists every allowed value of one field or parameter. An enum with more than 4 values that belongs to a field of an object structure is printed right after that structure's field table and only linked from here. The meaning column shows the x-enumDescriptions of the OpenAPI document; a value without one shows "—".

Enum	Values	Defined in
A2AMessage.role values	`"ROLE_USER"`, `"ROLE_AGENT"`	A2AMessage
A2ATaskStatus.state values	`"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_AUTH_REQUIRED"`	A2ATaskStatus
AgentAgent.conversation_transport values	`"acp"`, `"message-service"`	AgentAgent
AgentAgent.status values	`"active"`, `"inactive"`	AgentAgent
AgentAgent.visibility values	`"private"`, `"unlisted"`, `"org"`, `"public"`, `"marketplace"`	AgentAgent
agentBindDetailsWire.status values	`"pending"`, `"confirming"`, `"bound"`	agentBindDetailsWire
agentBindWire.status values	`"pending"`, `"bound"`	agentBindWire
AgentPatch.visibility values	`"private"`, `"unlisted"`, `"org"`, `"public"`, `"marketplace"`	AgentPatch
AgentSnapshot.conversation_transport values	`"acp"`, `"message-service"`	AgentSnapshot
AgentSnapshot.status values	`"active"`, `"inactive"`	AgentSnapshot
AgentSnapshot.visibility values	`"private"`, `"unlisted"`, `"org"`, `"public"`, `"marketplace"`	AgentSnapshot
Binding.client_type values	`"web"`, `"native"`	Binding
CanvasTicketClaims.role values	`"viewer"`, `"editor"`	CanvasTicketClaims
ClientSessionInput.client_type values	`"web"`, `"native"`	ClientSessionInput
CommandReceipt.status values	`"accepted"`, `"completed"`	CommandReceipt
ConnectURLResponse.data.browser.role values	`"viewer"`, `"controller"`	ConnectURLResponse
ConnectURLResponse.data.connectivity values	`"unknown"`, `"online"`, `"offline"`	ConnectURLResponse
ConnectURLResponse.data.mode values	`"browser-runtime"`, `"service-websocket"`	ConnectURLResponse
ConnectURLResponse.data.service values	`"browser"`, `"acp"`	ConnectURLResponse
Conversation.state values	`"open"`, `"closed"`	Conversation
conversations.list state values	`"open"`, `"closed"`, `"all"`	`conversations.list`
Deletion.status values	`"pending"`, `"processing"`, `"failed"`, `"completed"`	Deletion
DeletionAccepted.status values	`"pending"`, `"processing"`, `"failed"`, `"completed"`	DeletionAccepted
deviceBindings.resolvePortal request.decision values	`"recover"`, `"create"`	`deviceBindings.resolvePortal`
FileFile.file_type values	`"FILE_TYPE_IMAGE"`, `"FILE_TYPE_VIDEO"`, `"FILE_TYPE_AUDIO"`, `"FILE_TYPE_DOCUMENT"`, `"FILE_TYPE_ARCHIVE"`, `"FILE_TYPE_OTHER"`	FileFile
FileFile.status values	`"pending_upload"`, `"ready"`	FileFile
FileOrigin.source values	`"manual"`, `"chat_upload"`, `"runtime_generated"`, `"template_skill"`	FileOrigin
FileSummary.instances[].source values	`"manual"`, `"chat_upload"`, `"runtime_generated"`, `"template_skill"`	FileSummary
FileTransferDescriptor.direction values	`"upload"`, `"download"`	FileTransferDescriptor
InstanceSummary.connectivity values	`"unknown"`, `"online"`, `"offline"`	InstanceSummary
InstanceSummary.desired_status values	`"running"`, `"stopped"`, `"terminated"`	InstanceSummary
InstanceSummary.status values	`"pending"`, `"provisioning"`, `"running"`, `"stopped"`, `"terminated"`	InstanceSummary
Message.realtime_publish_status values	`"published"`, `"unconfirmed"`, `"not_republished"`	Message
Message.state values	`"streaming"`, `"completed"`, `"failed"`, `"refused"`, `"cancelled"`	Message
Message.stop_reason values	`"end_turn"`, `"max_tokens"`, `"tool_use"`, `"user_stop"`, `"timeout"`, `"error"`, `"refused"`, `"content_filter"`, `"agent_lost"`	Message
Message.type values	`"chat_message"`, `"agent_reply"`, `"agent_reply_error"`, `"agent.refuse"`, `"agent_busy"`, `"agent_reply_delta"`, `"agent_reasoning"`, `"a2a_status_update"`, `"a2a_result"`, `"agent_request"`, `"a2a_task"`, `"chat_cancel"`, `"device_command"`, `"device_result"`, `"device_error"`	Message
MessageEnvelope.state values	`"streaming"`, `"completed"`, `"failed"`, `"refused"`, `"cancelled"`	MessageEnvelope
MessageEnvelope.stop_reason values	`"end_turn"`, `"max_tokens"`, `"tool_use"`, `"user_stop"`, `"timeout"`, `"error"`, `"refused"`, `"content_filter"`, `"agent_lost"`	MessageEnvelope
MessageEnvelope.type values	`"chat_message"`, `"agent_reply"`, `"agent_reply_error"`, `"agent.refuse"`, `"agent_busy"`, `"agent_reply_delta"`, `"agent_reasoning"`, `"a2a_status_update"`, `"a2a_result"`, `"agent_request"`, `"a2a_task"`, `"chat_cancel"`, `"device_command"`, `"device_result"`, `"device_error"`	MessageEnvelope
MessagePartThinking.state values	`"streaming"`, `"done"`	MessagePartThinking
MessagePartToolUse.state values	`"streaming"`, `"done"`	MessagePartToolUse
portalBindWire.status values	`"pending"`, `"awaiting_confirmation"`, `"confirming"`, `"bound"`, `"revoked"`	portalBindWire
ProtoAutomationRule.status values	`"enabled"`, `"paused"`, `"expired"`	ProtoAutomationRule
ProtoAutomationRule.triggerKind values	`"schedule"`, `"webhook"`	ProtoAutomationRule
ProtoAutomationRun.rerunSessionMode values	`"original"`, `"new"`	ProtoAutomationRun
ProtoAutomationRun.status values	`"scheduled"`, `"dispatched"`, `"failed"`, `"skipped"`	ProtoAutomationRun
ProtoAutomationRun.triggerType values	`"schedule"`, `"manual"`, `"rerun"`, `"webhook"`	ProtoAutomationRun
ProtoAutomationRunInput.rerunSessionMode values	`"original"`, `"new"`	ProtoAutomationRunInput
ProtoAutomationSchedule.kind values	`"at"`, `"every"`, `"cron"`	ProtoAutomationSchedule
ProtoAutomationSession.mode values	`"new"`, `"bound"`	ProtoAutomationSession
RuntimeInstanceStatusResult.data.connectivity values	`"unknown"`, `"online"`, `"offline"`	RuntimeInstanceStatusResult
RuntimeInstanceStatusResult.data.desired_status values	`"running"`, `"stopped"`, `"terminated"`	RuntimeInstanceStatusResult
RuntimeInstanceStatusResult.data.status values	`"pending"`, `"provisioning"`, `"running"`, `"stopped"`, `"terminated"`	RuntimeInstanceStatusResult
RuntimeInstanceSummary.connectivity values	`"unknown"`, `"online"`, `"offline"`	RuntimeInstanceSummary
RuntimeInstanceSummary.desired_status values	`"running"`, `"stopped"`, `"terminated"`	RuntimeInstanceSummary
RuntimeInstanceSummary.status values	`"pending"`, `"provisioning"`, `"running"`, `"stopped"`, `"terminated"`	RuntimeInstanceSummary
RuntimeLLMModel.role values	`"default"`, `"fallback"`, `"available"`	RuntimeLLMModel
RuntimeLLMProvider.protocol values	`"openai"`, `"anthropic"`	RuntimeLLMProvider
RuntimeOperationSummary.kind values	`"create"`, `"start"`, `"stop"`, `"delete"`, `"image_upgrade"`	RuntimeOperationSummary
RuntimeOperationSummary.phase values	`"intent"`, `"reserved"`, `"admitted"`, `"provisioning"`, `"running"`, `"cleanup_pending"`, `"failed"`, `"stop_pending"`, `"stopped"`, `"delete_pending"`, `"deleted"`, `"upgrade_pending"`, `"rollback_pending"`	RuntimeOperationSummary
RuntimeUpgradeJob.status values	`"upgrade_pending"`, `"rollback_pending"`, `"failed"`, `"succeeded"`	RuntimeUpgradeJob
UHPContentPart.type values	`"output_text"`, `"summary_text"`	UHPContentPart
UHPDiscovery.conformance_class values	`"core"`, `"extended"`, `"full"`	UHPDiscovery
UHPError.type values	`"invalid_request_error"`, `"authentication_error"`, `"permission_error"`, `"rate_limit_error"`, `"harness_error"`, `"server_error"`	UHPError
UHPEvent.type values	`"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"`, `"beeos.approval.requested"`, `"beeos.approval.resolved"`, `"beeos.question.requested"`, `"beeos.question.resolved"`	UHPEvent
UHPMcpServer.transport values	`"http"`, `"sse"`	UHPMcpServer
UHPOutputItem.status values	`"in_progress"`, `"completed"`	UHPOutputItem
UHPOutputItem.type values	`"message"`, `"reasoning"`, `"function_call"`, `"function_call_output"`	UHPOutputItem
UHPOutputItemFunctionCall.status values	`"in_progress"`, `"completed"`	UHPOutputItemFunctionCall
UHPOutputItemFunctionCallOutput.status values	`"in_progress"`, `"completed"`	UHPOutputItemFunctionCallOutput
UHPOutputItemMessage.status values	`"in_progress"`, `"completed"`	UHPOutputItemMessage
UHPOutputItemReasoning.status values	`"in_progress"`, `"completed"`	UHPOutputItemReasoning
UHPPluginMcpServer.transport values	`"http"`, `"sse"`, `"stdio"`	UHPPluginMcpServer
UHPResponseStatus values	`"in_progress"`, `"completed"`, `"failed"`, `"incomplete"`, `"cancelled"`	—
usage.getSummary period values	`"day"`, `"week"`, `"month"`	`usage.getSummary`

A2AMessage.role values

Who wrote the message: ROLE_USER for the caller or ROLE_AGENT for the agent.

Defined in: A2AMessage

Value	Meaning
`"ROLE_USER"`	The message was written by the caller.
`"ROLE_AGENT"`	The message was written by the agent.

AgentAgent.conversation_transport values

How conversation messages reach the agent. New values can be added, so ignore values you do not know.

Defined in: AgentAgent

Value	Meaning
`"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.

AgentAgent.status values

Whether the agent is currently provided by its instance.

Defined in: AgentAgent

Value	Meaning
`"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.

agentBindDetailsWire.status values

State of the bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 not_found instead.

Defined in: agentBindDetailsWire

Value	Meaning
`"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.

agentBindWire.status values

State of the bind session. After a successful confirmation it is bound; a session that is still waiting for confirmation reports pending.

Defined in: agentBindWire

Value	Meaning
`"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.

AgentSnapshot.conversation_transport values

How conversation messages reach the agent. New values can be added, so ignore values you do not know.

Defined in: AgentSnapshot

Value	Meaning
`"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.

AgentSnapshot.status values

Whether the agent is currently provided by its instance.

Defined in: AgentSnapshot

Value	Meaning
`"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.

Binding.client_type values

How the token is bound to the client.

Defined in: Binding

Value	Meaning
`"web"`	Bound to a web page origin, returned in `origin`.
`"native"`	Bound to a device key, whose thumbprint is returned in `cnf_jkt`.

CanvasTicketClaims.role values

Access role granted on the canvas: viewer or editor.

Defined in: CanvasTicketClaims

Value	Meaning
`"viewer"`	Can view the canvas but not change it.
`"editor"`	Can view and edit the canvas.

ClientSessionInput.client_type values

How the client token is bound to the client that will use it. It decides whether you send origin or device_attestation.

Defined in: ClientSessionInput

Value	Meaning
`"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`.

CommandReceipt.status values

Outcome of the request at the time the call returned.

Defined in: CommandReceipt

Value	Meaning
`"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.

ConnectURLResponse.data.browser.role values

Access role of the grant: viewer or controller.

Defined in: ConnectURLResponse

Value	Meaning
`"viewer"`	Can watch the browser but not control it.
`"controller"`	Can watch and control the browser.

ConnectURLResponse.data.connectivity values

Reachability of the instance's agent: unknown, online or offline.

Defined in: ConnectURLResponse

Value	Meaning
`"unknown"`	Reachability has not been determined.
`"online"`	The instance's agent is connected.
`"offline"`	The instance's agent is not connected.

ConnectURLResponse.data.mode values

Connection mode: browser-runtime for browser, service-websocket for acp.

Defined in: ConnectURLResponse

Value	Meaning
`"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.

ConnectURLResponse.data.service values

Service the URL connects to: browser or acp.

Defined in: ConnectURLResponse

Value	Meaning
`"browser"`	The browser viewer.
`"acp"`	The agent connection over WebSocket.

Conversation.state values

Whether the conversation still accepts messages. A closed conversation stays readable but cannot receive new messages.

Defined in: Conversation

Value	Meaning
`"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`.

conversations.list state values

Defined in: conversations.list

Value	Meaning
`"open"`	—
`"closed"`	—
`"all"`	—

Deletion.status values

State of the deletion. Poll until it is completed.

Defined in: Deletion

Value	Meaning
`"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.

DeletionAccepted.status values

State of the deletion when the request was accepted.

Defined in: DeletionAccepted

Value	Meaning
`"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.

deviceBindings.resolvePortal request.decision values

What to do with the device that claimed the session. Required.

Defined in: deviceBindings.resolvePortal

Value	Meaning
`"recover"`	Bind the device to the existing instance given by `instance_id`.
`"create"`	Create a new instance for the device.

FileFile.status values

Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know.

Defined in: FileFile

Value	Meaning
`"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.

FileOrigin.source values

How the file came to exist. New values can be added, so ignore values you do not know.

Defined in: FileOrigin

Value	Meaning
`"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.

FileSummary.instances[].source values

How the file came to exist. New values can be added, so ignore values you do not know.

Defined in: FileSummary

Value	Meaning
`"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.

FileTransferDescriptor.direction values

Whether the URL is used to upload or to download the file content.

Defined in: FileTransferDescriptor

Value	Meaning
`"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.

InstanceSummary.connectivity values

Reachability of the instance's agent: unknown, online or offline.

Defined in: InstanceSummary

Value	Meaning
`"unknown"`	Reachability has not been determined.
`"online"`	The instance's agent is connected.
`"offline"`	The instance's agent is not connected.

InstanceSummary.desired_status values

Lifecycle phase the instance is being driven toward: running, stopped or terminated.

Defined in: InstanceSummary

Value	Meaning
`"running"`	The instance should be running.
`"stopped"`	The instance should be stopped.
`"terminated"`	The instance should be deleted.

Message.realtime_publish_status values

Reserved. The Server API does not currently return this field.

Defined in: Message

Value	Meaning
`"published"`	—
`"unconfirmed"`	—
`"not_republished"`	—

MessagePartThinking.state values

Whether the reasoning is still being written.

Defined in: MessagePartThinking

Value	Meaning
`"streaming"`	The part is still being written.
`"done"`	The part is complete. A missing state also means done.

MessagePartToolUse.state values

Whether the arguments are still being written.

Defined in: MessagePartToolUse

Value	Meaning
`"streaming"`	The part is still being written.
`"done"`	The part is complete. A missing state also means done.

ProtoAutomationRule.status values

State of the automation.

Defined in: ProtoAutomationRule

Value	Meaning
`"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`.

ProtoAutomationRule.triggerKind values

What starts a run. Automations created before webhook triggers existed can report an empty value; treat it as schedule.

Defined in: ProtoAutomationRule

Value	Meaning
`"schedule"`	Runs start on the `schedule`.
`"webhook"`	Runs start when the event source delivers an event, optionally narrowed by `eventFilter`.

ProtoAutomationRun.rerunSessionMode values

Which conversation a rerun is delivered into. Empty for runs that are not reruns.

Defined in: ProtoAutomationRun

Value	Meaning
`"original"`	The conversation the source run was delivered into.
`"new"`	A new conversation.

ProtoAutomationRun.status values

Delivery state of the run. It tells whether the prompt reached the agent's conversation, not whether the agent finished the work.

Defined in: ProtoAutomationRun

Value	Meaning
`"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.

ProtoAutomationRun.triggerType values

What created the run.

Defined in: ProtoAutomationRun

Value	Meaning
`"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.

ProtoAutomationRunInput.rerunSessionMode values

Which conversation the rerun is delivered into. Required when sourceRunId is sent and not allowed without it.

Defined in: ProtoAutomationRunInput

Value	Meaning
`"original"`	The conversation the source run was delivered into.
`"new"`	A new conversation.

ProtoAutomationSchedule.kind values

Type of the schedule. It decides which of the other fields are required.

Defined in: ProtoAutomationSchedule

Value	Meaning
`"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`.

ProtoAutomationSession.mode values

How a run chooses the conversation it is delivered into.

Defined in: ProtoAutomationSession

Value	Meaning
`"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`.

RuntimeInstanceStatusResult.data.connectivity values

Reachability of the instance's agent: unknown, online or offline.

Defined in: RuntimeInstanceStatusResult

Value	Meaning
`"unknown"`	Reachability has not been determined.
`"online"`	The instance's agent is connected.
`"offline"`	The instance's agent is not connected.

RuntimeInstanceStatusResult.data.desired_status values

Lifecycle phase the instance is being driven toward: running, stopped or terminated.

Defined in: RuntimeInstanceStatusResult

Value	Meaning
`"running"`	The instance should be running.
`"stopped"`	The instance should be stopped.
`"terminated"`	The instance should be deleted.

RuntimeInstanceSummary.connectivity values

Reachability of the instance's agent: unknown, online or offline.

Defined in: RuntimeInstanceSummary

Value	Meaning
`"unknown"`	Reachability has not been determined.
`"online"`	The instance's agent is connected.
`"offline"`	The instance's agent is not connected.

RuntimeInstanceSummary.desired_status values

Lifecycle phase the instance is being driven toward: running, stopped or terminated.

Defined in: RuntimeInstanceSummary

Value	Meaning
`"running"`	The instance should be running.
`"stopped"`	The instance should be stopped.
`"terminated"`	The instance should be deleted.

RuntimeLLMModel.role values

Role of the model: default, fallback or available. Exactly one model is default. Automatic failover uses only fallback models.

Defined in: RuntimeLLMModel

Value	Meaning
`"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.

RuntimeLLMProvider.protocol values

API protocol the endpoint speaks: openai or anthropic.

Defined in: RuntimeLLMProvider

Value	Meaning
`"openai"`	The OpenAI-compatible API.
`"anthropic"`	The Anthropic Messages API.

RuntimeUpgradeJob.status values

Status of the job: upgrade_pending, rollback_pending, failed or succeeded.

Defined in: RuntimeUpgradeJob

Value	Meaning
`"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.

UHPContentPart.type values

Kind of the part.

Defined in: UHPContentPart

Value	Meaning
`"output_text"`	Text of a `message` item, with optional annotations.
`"summary_text"`	Summary text of a `reasoning` item.

UHPDiscovery.conformance_class values

Coarse conformance class of the server. Branch on the flags in capabilities, which are exact, rather than on the class.

Defined in: UHPDiscovery

Value	Meaning
`"core"`	Discovery, harness reads, tasks and sessions.
`"extended"`	Core plus file input and artifact retrieval.
`"full"`	Extended plus harness management, plugins, environments and memories.

UHPMcpServer.transport values

Transport the server speaks. Defaults to http on write. Not returned for a server that uses neither transport.

Defined in: UHPMcpServer

Value	Meaning
`"http"`	Streamable HTTP.
`"sse"`	The older HTTP with server-sent events transport.

UHPOutputItem.status values

Progress of the item.

Defined in: UHPOutputItem

Value	Meaning
`"in_progress"`	The item is still being produced.
`"completed"`	The item is complete.

UHPOutputItem.type values

Kind of the output item. Clients should ignore item types they do not know.

Defined in: UHPOutputItem

Value	Meaning
`"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`.

UHPOutputItemFunctionCall.status values

Progress of the item.

Defined in: UHPOutputItemFunctionCall

Value	Meaning
`"in_progress"`	The item is still being produced.
`"completed"`	The item is complete.

UHPOutputItemFunctionCallOutput.status values

Progress of the item.

Defined in: UHPOutputItemFunctionCallOutput

Value	Meaning
`"in_progress"`	The item is still being produced.
`"completed"`	The item is complete.

UHPOutputItemMessage.status values

Progress of the item.

Defined in: UHPOutputItemMessage

Value	Meaning
`"in_progress"`	The item is still being produced.
`"completed"`	The item is complete.

UHPOutputItemReasoning.status values

Progress of the item.

Defined in: UHPOutputItemReasoning

Value	Meaning
`"in_progress"`	The item is still being produced.
`"completed"`	The item is complete.

UHPPluginMcpServer.transport values

http is Streamable HTTP (streamable-http in mcp.json); sse the older HTTP+SSE transport; stdio a process the server launches inside the agent's sandbox.

Defined in: UHPPluginMcpServer

Value	Meaning
`"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`.

usage.getSummary period values

Defined in: usage.getSummary

Value	Meaning
`"day"`	—
`"week"`	—
`"month"`	—

BeeOS CloudBack to documentation

Appendix: object structures and enums

Object structures

A2AAgentCard

A2AArtifact

A2ADataPartOut

A2AFilePartOut

A2AMessage

A2AOutputPart

Variant: A2ATextPartOut

Variant: A2AFilePartOut

Variant: A2ADataPartOut

A2ATaskStatus

A2ATaskStatus.state values

a2aTaskView

A2ATextPartOut

ActiveConversationResponse

AgentAgent

AgentAgent.visibility values

agentBindDetailsWire

agentBindWire

AgentPage

AgentPatch

AgentPatch.visibility values

AgentResponse

AgentSkill

AgentSnapshot

AgentSnapshot.visibility values

agentTemplateCatalogView

ApprovalModeResult

ApprovalModeResultResponse

ApprovalModeSettings

Binding

Binding by client_type

BindingNative

BindingWeb

bindRuntimeWire

CancelConversationInput

CanvasSessionDocument

CanvasShare

CanvasSnapshot

CanvasTicketClaims

CatalogSpec

CatalogSpecValue

CatalogVariant

ClearConversationReceipt

ClearConversationReceiptResponse

ClientSessionInput

ClientSessionInput by client_type

ClientSessionInputNative

ClientSessionInputWeb

ClientSessionResponse

CommandReceipt

CommandReceiptResponse

ConnectURLResponse

Conversation

ConversationPage

ConversationResponse

CreateConversationInput

CreateServerInstanceInput

Deletion

DeletionAccepted

DeployModel

DeployRegion

DeviceBindingErrorResponse

ErrorResponse

ExternalUserID

FileChatUploadContext

FileConfirmInput

FileFile

FileFile.file_type values

FileOrigin

FilePage

FilePrepareUploadInput

FileResolution

FileShareResponse

FileSummary

FileTransferDescriptor

InstancePage

InstanceSummary

InstanceSummary.status values

Variant: `A2ATextPartOut`

Variant: `A2AFilePartOut`

Variant: `A2ADataPartOut`