REST API reference

BitsReef exposes a versioned REST API. Everything the dashboard and CLI do is available here.

Base URL: https://v1.api.prod.bitsreef.com/v1
Interactive docs (OpenAPI / Swagger): /v1/docs/
Machine-readable schema: /v1/schema/

The Swagger UI is the always-current source of truth for every endpoint, parameter, and response shape. This page covers the essentials to get you started.

Authentication

The API uses JWT bearer tokens. Exchange your credentials for an access + refresh token pair:

curl -X POST https://v1.api.prod.bitsreef.com/v1/account/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "you", "password": "…"}'
# → { "access": "<jwt>", "refresh": "<jwt>" }

Send the access token on every request:

curl https://v1.api.prod.bitsreef.com/v1/organizations/ \
  -H "Authorization: Bearer <access>"

Access tokens are short-lived. Refresh them:

curl -X POST https://v1.api.prod.bitsreef.com/v1/account/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "<refresh>"}'
# → { "access": "<jwt>" }

Pagination

List endpoints are paginated and return a consistent envelope:

{
  "count": 42,
  "next": "https://…/v1/…?page=2",
  "previous": null,
  "results": [ /* … */ ]
}

Follow next until it’s null to page through everything.

URL structure

Resources are nested by their owner. The common prefixes:

Prefix	Holds
`/v1/account/`	Auth (`token/`, `token/refresh/`), profile (`me/`), registration
`/v1/organizations/{org_id}/`	Org members, projects, registries, billing, storage, alerts, metrics
`/v1/projects/{id}/`	A project and its services, volumes, webhooks, variables; templates
`/v1/services/{id}/`	A service and its deployments, domains, cron jobs, env, metrics

For example:

GET  /v1/organizations/{org_id}/projects/          # list projects in an org
POST /v1/projects/{project_id}/services/           # create a service
GET  /v1/services/{service_id}/deployments/        # a service's deploy history
POST /v1/services/{service_id}/domains/            # attach a custom domain
GET  /v1/services/{service_id}/metrics/current/    # current resource snapshot

Example: create and deploy a service

BASE=https://v1.api.prod.bitsreef.com/v1
AUTH="Authorization: Bearer <access>"

# Create a service in a project
curl -X POST "$BASE/projects/123/services/" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "web",
  "image": "nginx:latest",
  "exposed_port": 80
}'

# Trigger a deployment for it
curl -X POST "$BASE/services/456/deployments/" -H "$AUTH"

Refer to /v1/docs/ for the exact request body each endpoint accepts.

Errors

The API uses standard HTTP status codes. Notable conventions:

401 — missing/expired token (refresh and retry).
403 — your role doesn’t permit the action.
202 — accepted for asynchronous processing (e.g. deploys, project delete).