REST API

The DollarBox REST API lets you manage containers, volumes, orgs, members, and kubectl credentials from scripts, CI, or the Terraform provider. Everything the dashboard does for these resources, the API can do too.

The API is versioned in the URL. The current version is v1, served under:

https://app.dollarbox.dev/api/v1/

Breaking changes ship under a new version prefix (/api/v2/); v1 stays stable for existing integrations.

Get a token

The API authenticates with personal API tokens.

1. Open Account → API tokens in the control panel (https://app.dollarbox.dev/settings/api-tokens/).
2. Click Create token, give it a name, and choose a scope:
   • Read-only — GET requests only.
   • Read & write — full access for the token's user.
3. Optionally restrict the token to a single org, and optionally set an expiry.
4. Copy the token shown on the next screen. It is displayed only once. If you lose it, revoke it and create another.

If your account has two-factor authentication enabled, you'll be asked to re-authenticate before a token is created.

Send the token as a bearer credential on every request:

curl -H "Authorization: Bearer dbx_xxxxxxxxxxxx_..." \
  https://app.dollarbox.dev/api/v1/containers/

Tokens carry the permissions of the user who created them, constrained by the org's role model (owner / admin / member). Writes additionally require the token's write scope. Revoke a token any time from the same page; revoked or expired tokens are rejected immediately.

Choose an org

Most resources belong to an org. The API resolves the target org in this order:

1. The token's org, if it was created as org-scoped.
2. An explicit org slug, via the X-Dollarbox-Org header or the ?org=<slug> query parameter.
3. Your only org, if you belong to exactly one.

If you belong to several orgs and don't specify one, write requests return an org_required error.

curl -H "Authorization: Bearer $DOLLARBOX_TOKEN" \
  -H "X-Dollarbox-Org: my-org" \
  https://app.dollarbox.dev/api/v1/containers/

Resources

A complete, machine-readable description lives in the OpenAPI schema:

• Schema: https://app.dollarbox.dev/api/v1/schema/
• Interactive docs (Swagger UI): https://app.dollarbox.dev/api/v1/docs/

Both require you to be signed in to the control panel.

Provisioning is asynchronous

Creating a container or volume returns immediately with a status of pending; provisioning happens in the background. Poll the resource until its status settles:

• Containers: pending → provisioning → running (or failed).
• Volumes: pending → provisioning → bound (or failed).

# Create a container
curl -X POST https://app.dollarbox.dev/api/v1/containers/ \
  -H "Authorization: Bearer $DOLLARBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web", "image": "nginx:1.27"}'

# Poll until it is running
curl https://app.dollarbox.dev/api/v1/containers/123/ \
  -H "Authorization: Bearer $DOLLARBOX_TOKEN"

A container's name is fixed once created — change other fields in place, but recreate the container to rename it. Volumes are immutable once created; delete and recreate to change size.

kubectl credentials

If an org has kubectl mode enabled, you can issue your own kubeconfig over the API. The kubeconfig (with a freshly bound token) is returned only in the create response:

curl -X POST https://app.dollarbox.dev/api/v1/kubectl-credentials/ \
  -H "Authorization: Bearer $DOLLARBOX_TOKEN" \
  -H "X-Dollarbox-Org: my-org"

Pagination

List endpoints use cursor pagination:

{
  "next": "https://app.dollarbox.dev/api/v1/containers/?cursor=cD0y",
  "previous": null,
  "results": [ ... ]
}

Use ?limit= to set the page size and follow the next URL (or its cursor) to page forward.

Errors

Errors use a stable envelope. The code is a machine-readable string you can switch on; it won't change without a version bump.

{
  "error": {
    "code": "quota_exceeded",
    "message": "This would exceed your plan's limit of 5 containers. You are using 5.",
    "detail": { "resource": "containers", "limit": 5, "current": 5 }
  }
}

Common codes include authentication_failed, permission_denied, not_found, validation_error, quota_exceeded, rate_limited, and api_disabled.

Rate limits

Requests are rate limited per token. When you exceed the limit you'll get a 429 with a Retry-After header (in seconds) and the rate_limited error code. Back off and retry after the indicated delay.

Terraform

The official Terraform provider is built on this API — declare your containers, volumes, and org membership as code. (Provider availability is tracked separately; until it ships, the API above is the supported integration surface.)