# API reference (/docs/api-reference)



Use the Management API at **`https://berrybox.io/api/management/v1`**. Authenticate with a scoped BerryBox API key. A browser session is not an API credential.

<Cards>
  <Card title="CI endpoints" description="Jobs, logs, waiting, settings, wallet and budget." href="/docs/api-reference/ci" />

  <Card title="Core API contract" description="Generated reference for identity, keys and recorded finance." href="/docs/api-reference/management" />
</Cards>

The [OpenAPI document](/openapi.yaml) covers the generated core reference. CI operations are documented in the [CI endpoint guide](/docs/api-reference/ci) and exposed by the CLI and MCP tool schemas. The OpenAPI document is not yet a complete specification of every Management API operation.

## Authentication [#authentication]

Send `Authorization: Bearer YOUR_KEY` over HTTPS. Resolve the key from a private credentials file or secure environment, rather than hard-coding it. The server derives the team from the key; callers cannot override it with another team's ID.

The key's stored scopes and expiry and its creator's current membership and role all apply. Use a read-only key for exploratory work. [Key guide](/docs/teams-and-billing/management-keys).

## Money and errors [#money-and-errors]

Money is an exact **decimal string of integer micro-USD** over JSON: `"1000000"` means $1. Use `BigInt` or exact decimal arithmetic; do not convert large monetary integers through floating-point numbers.

Errors are structured JSON. Check the HTTP status and returned code/message; do not infer success from a redirect or retry a mutation blindly. A 401/403 needs an authentication or permissions fix; a 429 needs backoff, and a revision conflict needs a fresh read.

Prefer the CLI or MCP when you do not need a custom HTTP integration. They share an operation catalog and keep input shapes consistent.