https://api.bead.run.
Start with a client
Use the Python SDK, TypeScript SDK, CLI or MCP. They handle authentication and common operation flows. For direct HTTP, authenticate withX-API-Key:
Routes and coverage
The endpoint pages render the public SDK OpenAPI contract. Machine routes include/sandboxes and versioned /v2/sandboxes operations. Follow each endpoint’s request and response schema; field shapes and list responses can differ by version.
This reference covers the SDK contract subset. Shipped signup, account, payments, webhooks, volumes, desktop, networking, template-build and runner-control routes are not all represented here. Use the CLI command reference, SDK references, MCP tools and relevant guides for those operations.
Keep identities and inspect operations
Store the returned machine ID with your application’s job or session. For supported mutations, send a stableIdempotency-Key and reuse the same request when recovering a lost response.
Asynchronous operations return identifiers for later inspection. Follow the documented status route and inspect every member result for fleet and fork operations. A partially successful batch still has machines that require cleanup.
An idempotent create does not make arbitrary command execution safe to repeat. Commands and prompts can have external effects. Inspect existing execution or conversation state before retrying an uncertain action.
Errors and cleanup
Preserve HTTP status, error code and request ID for diagnosis. Read structured limit metadata and retry timing rather than assuming a fixed account limit.402 can require funded credit; use prepaid credit and limits.
Delete machines when their work is complete and verify durable state. Paused machines and saved snapshots retain separately billed storage. See machine lifetime and snapshot retention.