OpenAPI

The Server API is described by one OpenAPI 3.1.0 document: 103 operations, 135 schemas, document version 3.1.0 (the same version as the Cloud SDK). The Cloud SDK method pages and the Cloud SDKs are generated from it.

Download the specification

The copy on this site is the one the Cloud SDK pages are built from. It omits extension fields that only record how the document was produced; all operations, schemas, and x-sdk-resource / x-sdk-method names are unchanged.

Servers and authentication

The document declares the server https://api.cloud.beeos.ai/v1. The 14 operations of the UHP surface declare their own server, https://api.cloud.beeos.ai/uhp/v1, so their paths are relative to that server; check that your generator honors operation-level servers, and otherwise override the base URL for those operations.

Security scheme ServerAPIKey: HTTP bearer authentication with a Server API key (prefix bsk_). Send it as Authorization: Bearer <key> from your backend only.

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

x-sdk-resource and x-sdk-method on each operation name its domain and the SDK method; x-sdk-base-path marks the operations under /uhp/v1. The remaining extension keys (x-enumDescriptions, x-idempotency, x-required-scopes, x-sdk-error-code-field, x-sdk-event-schema, x-sdk-response-stream, x-sdk-stream, x-variantSchemas, x-variants) steer SDK generation or annotate operations and can be ignored by other tools.

Generate a client

Download the document from the link above, save it as server.openapi.json, then run one of the generators. Each command writes into a new directory or file; review the output before you use it.

npx @openapitools/openapi-generator-cli generate \
  -i server.openapi.json \
  -g typescript-fetch \
  -o ./beeos-client

openapi-generator supports many languages through -g (for example python or go). openapi-typescript emits types only, so call the API with fetch or a client such as openapi-fetch. This document is OpenAPI 3.1: use openapi-typescript 7 or newer, and check that your version of oapi-codegen accepts 3.1 before relying on it.

Official SDKs or a generated client

Use the official Cloud SDKs for TypeScript, Python, and Go. They are generated from this same document and add what a generic generator does not know about: the UHP base path is switched for you, organization and app come from the server key, errors surface as one error type that keeps the status and the decoded body, and hand-written helpers cover streaming Responses and webhook signature verification.

Generate your own client when you need another language, a different HTTP stack, or only the types. You then own those pieces: the base URL of the UHP operations, the Authorization, Idempotency-Key, and If-Match headers, server-sent event streams, and signature verification for webhooks.