API overview

This overview covers what every domain of the BeeOS Cloud Server API has in common: 103 operations in 15 domains. It is generated from the OpenAPI document of Server SDK 3.1.0, pinned at beeos-ai/beeos-cloud-sdks@702e47495f47. Each domain has its own page with its methods; shared object structures and enum values are in the appendix. Field descriptions are shown as the OpenAPI document states them; fields without one show "—".

Base URL

Most operations are served from https://api.cloud.beeos.ai/v1. 14 operations (all of responses, harnesses, plus catalog.getDiscovery) are served from https://api.cloud.beeos.ai/uhp/v1 on the same host. Each operation page shows the full path, for example GET /v1/instances and POST /uhp/v1/responses.

Family	Base URL	Operations
Server API	https://api.cloud.beeos.ai/v1	89
UHP	https://api.cloud.beeos.ai/uhp/v1	14

The SDKs take one base URL, https://api.cloud.beeos.ai/v1. For UHP operations they keep the scheme and host and replace the path with /uhp/v1, so you never configure the second URL. With plain HTTP, use the family the operation page shows.

Authentication

Every request carries Authorization: Bearer <key> with a Server API key (prefix bsk_). Keep the key on your backend: never ship it to a browser or mobile app, and read it from configuration (the examples use $BEEOS_API_KEY). catalog.getDiscovery is served without authentication. Install, initialization, and the key model are in Install and authenticate.

curl "https://api.cloud.beeos.ai/v1/instances" \
  -H "Authorization: Bearer $BEEOS_API_KEY"

Common headers

The table lists every header the OpenAPI document declares as a parameter, with the number of operations that declare it and the number that require it. Organization and app come from the server key.

Header	Operations	Required in	Description
Idempotency-Key	22	19	Repeating a key returns the first request's result and does not execute the operation again. Constraints: minLength=1, maxLength=256.
If-Match	9	9	Current resource version as a quoted string, for example "3". A stale version is rejected. Constraints: pattern=^"[1-9][0-9]*"$.
UHP-Version	2	0	—
Last-Event-ID	1	0	ID of the last event received; resumes the event stream after it.
X-BeeOS-Conversation-ID	6	6	—
X-BeeOS-Platform-Agent-ID	6	6	—

Errors

A non-2xx response carries one of three error envelopes, chosen per operation (each operation page lists its documented statuses). The SDKs raise a single error type that holds the HTTP status and the decoded body: TypeScript BeeOSAPIError, Python APIError, Go *APIError; see Install and authenticate. The TypeScript SDK also reads the X-Request-ID response header into requestId.

Status	Schema	Operations
400	ErrorResponse, UHPErrorEnvelope	5
401	ErrorResponse, UHPErrorEnvelope	6
404	ErrorResponse, UHPErrorEnvelope	11
409	UHPErrorEnvelope	3
413	UHPErrorEnvelope	2
422	UHPErrorEnvelope	4
429	ErrorResponse, UHPErrorEnvelope	3
5XX	ErrorResponse	2
502	UHPErrorEnvelope	2
503	UHPErrorEnvelope	3
504	UHPErrorEnvelope	2
other (default)	ErrorResponse, DeviceBindingErrorResponse, UHPErrorEnvelope	103

ErrorResponse

Used by 83 operations in identity, catalog, instances, agents, conversations, messages, files, automations, canvases, a2a, usage, audio.

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.

DeviceBindingErrorResponse

Used by 6 operations in deviceBindings.

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.

UHPErrorEnvelope

Used by 14 operations in catalog, responses, harnesses.

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.

UHPError

Error object inside UHPErrorEnvelope.

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.

Pagination

Pagination differs by operation: page-based operations take page and page_size, cursor-based operations take cursor and limit, and the file list takes limit and offset. The table lists, for every paginated operation, the pagination parameters it accepts and the pagination fields in its response, as the OpenAPI document declares them.

Operation	Request parameters	Response fields
catalog.listInstanceTemplates	page, page_size	total
catalog.listAgentTemplates	page, page_size	total
instances.list	page, page_size	total
agents.list	page, page_size	total
conversations.list	cursor, limit	next_cursor, has_more
messages.list	cursor, limit	next_cursor, has_more
files.list	limit, offset, since	total, next_since
automations.list	cursor, limit	data.nextCursor
automations.listRuns	cursor, limit	data.nextCursor
a2a.listTasks	cursor, limit	total, next_cursor, has_more

Idempotency and versioned writes

Mutating operations take an Idempotency-Key header (required on most of them, as the table above shows). Repeating a key returns the first request's result and does not execute the operation again. Allowed key lengths differ per operation; each operation page shows the constraints. The SDKs never generate a key: pass a stable one per logical operation and reuse it when you retry. Operations that change a versioned resource also take If-Match with the current resource version as a quoted string, for example "3"; a stale version is rejected. TypeScript accepts the number and quotes it; Python and Go take the header value as is.

Domains

Domain	Operations	Description
Identity	5	Client sessions for browser and mobile clients, and external-user data deletion.
Catalog	8	Providers, deploy regions and models, instance and agent templates, and the protocol discovery document.
Instances	15	Create, read, update, start, stop, upgrade, and delete instances; open terminal and canvas sessions; run commands; get connect and stream URLs.
Agents	3	List and read agents and update their exposure settings.
Conversations	11	Create, list, rename, delete, cancel, resume, and clear conversations; set the model, reasoning effort, and approval mode.
Messages	6	List and read conversation messages and manage reply share links.
Responses	6	Run a task on a configured harness and read, stream, cancel, or delete it (UHP).
Harnesses	7	Create, list, read, update, and delete configured harnesses and list the models they can run (UHP).
Files	11	Presigned uploads, file metadata, share links, and the file summary.
Automations	11	Create, update, pause, resume, and delete automations; start and read runs; create webhook automations.
Canvases	6	Canvas share links, snapshots, and conversation canvas sessions.
Device bindings	6	Agent bind sessions and portal bind sessions.
A2A	6	Agent-to-Agent JSON-RPC requests, agent cards, and tasks.
Usage	1	The usage summary.
Audio	1	Audio transcription.

Install the Cloud SDK and configure a client in Install and authenticate, look up a type or enum in the appendix, or generate your own client from the OpenAPI document.