API reference - BMA Developer Docs

BMA serves one API under $BMA_BASE_URL/v1. Its core is the Anthropic Managed Agents API (beta managed-agents-2026-04-01): agents, environments, sessions, events, files and memory stores, with the paths, bodies and event stream of the official SDKs. How to connect an official SDK, and exactly which fields and endpoints the core serves, is on Use the official Anthropic SDK. On top of that core, BMA adds resources of its own in the same style: machines and machine pools, desktop and terminal sessions with single-use tickets, vaults, skills and project provisioning. This reference is generated from the OpenAPI document of those extensions. Extension fields on Anthropic objects are top-level bma_* properties (for example bma_sequence on events).

The server in the OpenAPI document points at staging (https://api.staging.bma.beeos.ai/v1). The playground here does not send requests; call the API with your own key.

Base URL and headers

Item	Value
Base URL	`$BMA_BASE_URL/v1` (staging: `https://api.staging.bma.beeos.ai/v1`)
`x-api-key`	Your organization API key (`bma_org_v1_…`). The official SDKs send it from `api_key`.
`anthropic-version`	`2023-06-01`. Sent by the SDKs; accepted, not validated.
`anthropic-beta`	`managed-agents-2026-04-01` on the Managed Agents routes. Sent by the SDKs; accepted, not validated.
`x-bma-project-id`	The project to work in. Optional when the key sees only one project. `anthropic-workspace-id` is accepted as an alias.
`Idempotency-Key`	On creates that document it (for example `POST /v1/sessions`, file upload, the extension creates): a replay returns the original result.

curl -sS "$BMA_BASE_URL/v1/agents?limit=5" \
  -H "x-api-key: $BMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "x-bma-project-id: $BMA_PROJECT_ID"

Authentication

Organization API keys (bma_org_v1_…) are created in the dashboard and shown once; an API key can never create another key. Keep keys on your server: a browser or desktop app talks to your backend, and for live connections (remote desktop, terminal) your backend mints a single-use ticket that is the only credential the client holds. Machine tokens (issued per machine) are used only by executors.

Errors

Errors use the Anthropic envelope; BMA adds a machine-readable reason in error.code where it has one:

{
  "type": "error",
  "error": { "type": "invalid_request_error", "code": "conflict", "message": "conflict: machine does not provide a desktop" },
  "request_id": "req_…"
}

401 means a missing or invalid key, 403 a missing permission, 404 that the resource does not exist or is not visible to you (cross-tenant reads are always 404).

Pagination

Lists return {"data": [...], "next_page": "…"}; pass next_page as page for the next page and limit to size it. Event lists also carry bma_sequence on every durable event, for resuming a stream.

​Base URL and headers

​Authentication

​Errors

​Pagination

Base URL and headers

Authentication

Errors

Pagination