API Reference v1

The CloudBooster REST API is served at https://api.cloudbooster.io. This page covers the publicly supported v1 surface — the same surface cbx-cli uses.

The canonical machine-readable spec is the OpenAPI 3.0 document shipped with the CLI at cbx-cli/api/openapi.yaml. Use that file to generate clients or import into Postman / Insomnia.

Authentication

All /v1/... endpoints require a bearer token:

Authorization: Bearer <token>

Tokens are issued by the CLI auth flow. After cbx login, the CLI exchanges its login code for a token via POST /v1/auth/cli-exchange. The same token can be used directly against the API.

The unauthenticated /health endpoint is the only exception.

Rate limiting

Every endpoint may return 429 Too Many Requests with these headers:

Clients should respect Retry-After rather than retrying immediately.

Endpoints

GET /health

Liveness probe. No authentication required. Returns { "status": "ok" } on success.

GET /v1/me

Returns the authenticated user (id, email).

GET /v1/orgs/{id}/projects

Lists projects belonging to organisation {id}. Returns an array of { id, name }.

GET /v1/environments/{environment_id}/cost

Cost summary for an environment: total_cost, unit, start_date, end_date, daily_costs[], profiles_count. Paid tier only — returns 403 otherwise.

GET /v1/environments/{environment_id}/drift

Drift check results: environment_id, checks[]. Paid tier only.

GET /v1/environments/{environment_id}/logs

Logs for the latest deployment run in an environment: environment_id, run_id, logs. Pass ?tail=true to return only the trailing portion. Paid tier only.

POST /v1/auth/cli-exchange

Exchanges a one-time CLI login code ({ "code": "..." }) for an API token ({ "token": "..." }). Used by cbx login; you generally don't call this directly.

Errors

Standard HTTP status codes. Authenticated endpoints share the same shape: