> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Integrate the sandbox API using versioned machine routes, durable operations, SDK contracts, and idempotency keys.

Use the bead sandbox API to provision Linux machines and integrate their lifecycle into your application. The public API origin is `https://api.bead.run`.

## Start with a client

Use the [Python SDK](https://docs.bead.run/sdks/python/quickstart.md), [TypeScript SDK](https://docs.bead.run/sdks/typescript/quickstart.md), [CLI](https://docs.bead.run/cli/overview.md) or [MCP](https://docs.bead.run/mcp/connect.md). They handle authentication and common operation flows.

For direct HTTP, [authenticate](https://docs.bead.run/api-reference/authentication.md) with `X-API-Key`:

```bash theme={null}
curl -sS https://api.bead.run/v2/sandboxes   -H "X-API-Key: $BEAD_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](https://docs.bead.run/cli/overview.md), [SDK references](https://docs.bead.run/sdks/python/reference.md), [MCP tools](https://docs.bead.run/mcp/tools.md) 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 stable `Idempotency-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](https://docs.bead.run/platform/prepaid-credit.md) and [limits](https://docs.bead.run/platform/limits.md).

Delete machines when their work is complete and verify durable state. Paused machines and saved snapshots retain separately billed storage. See [machine lifetime](https://docs.bead.run/run-work/lifetime.md) and [snapshot retention](https://docs.bead.run/snapshots/retention.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.