# Core API contract (/docs/api-reference/management)



The generated pages below follow the retained OpenAPI contract. They cover health, team identity, management keys and recorded finance reads. For current CI jobs, wallet, runtime holds, settings and budgets, use the [CI endpoint guide](/docs/api-reference/ci).

The Management API origin is `https://berrybox.io/api/management/v1`. Health is served separately at `/health`.

| Method | Path                                            | Authorization                                 |
| ------ | ----------------------------------------------- | --------------------------------------------- |
| GET    | `/health`                                       | None                                          |
| GET    | `/api/management/v1/team`                       | `teams:read`                                  |
| GET    | `/api/management/v1/api-keys`                   | `keys:read`                                   |
| POST   | `/api/management/v1/api-keys`                   | `keys:write`                                  |
| POST   | `/api/management/v1/api-keys/{apiKeyId}/rotate` | `keys:write`                                  |
| DELETE | `/api/management/v1/api-keys/{apiKeyId}`        | `keys:write`                                  |
| GET    | `/api/management/v1/usage`                      | `billing:read` and a permitted financial role |
| GET    | `/api/management/v1/billing`                    | `billing:read` and a permitted financial role |
| GET    | `/api/management/v1/billing/activity`           | `billing:read` and a permitted financial role |
| GET    | `/api/management/v1/limits`                     | `billing:read` and a permitted financial role |

The authenticated key determines the team. Membership, role, scope, expiry and revocation are rechecked server-side. Lists omit revoked keys and restrict members to their own keys.

## Exact financial values [#exact-financial-values]

Money is a decimal string containing integer micro-USD: `"1000000"` equals $1. Resource quantities may have six decimal places. Preserve exact values rather than converting them through a floating-point number.

Recorded usage reads can be incomplete for a current day or missing snapshot. Do not interpret a null total as zero. For per-job CI charges and current spendable credit, use `/ci/jobs/{jobId}` and `/ci/billing`.

## Key mutations and retries [#key-mutations-and-retries]

Core key mutations accept an `Idempotency-Key` header bound to the caller, team, method, path and body. Conflicting or in-progress work can return 409. The one-time secret from key creation or rotation is not retained for replay; a completed retry can return `idempotency_sensitive_replay` instead of revealing it again.

Prefer `berrybox key-create` or `berrybox key-rotate` with `--output-token FILE` for secret-returning operations.

## Interactive reference [#interactive-reference]

Generated operation pages include an endpoint form. A disposable key you enter stays in that component's memory and clears when you leave or choose Clear. It is not stored in local storage.

The docs proxy permits only the exact documented core paths and bounded inputs. It does not supply credentials, a dashboard session or server secrets, and does not forward arbitrary URLs. Prefer a trusted terminal client for sensitive operations. CI operations use the separate guide and CLI; they are not added to this playground allowlist.