REST API (v1)

The hosted service exposes a small REST API for managing your workspace's API keys and reading usage. Most of what you do day to day goes through the CLI, MCP, or --json — this API is for dashboards, automation, and provisioning keys in code.

This is the hosted control-plane API. A self-hosted (OSS) edge has no control plane; manage its access via tokens.json instead.

Base URL & authentication

All routes are under /api/v1 on the control-plane host and authenticate with a workspace API key as a Bearer token (create one in the dashboard or with POST /tokens):

curl https://beamd.ai/api/v1/workspace \
  -H "Authorization: Bearer $BEAMD_API_KEY"

The key scopes every request to its workspace automatically. Responses are JSON; CORS is open (Access-Control-Allow-Origin: *) so a browser dashboard can call it directly.

Endpoints

GET /workspace

The workspace the key belongs to.

{ "slug": "acme", "name": "Acme Inc", "provisioned": true, "tunnelBase": "acme.beamd.run" }

GET /tokens

List the workspace's API keys (never the secret values).

{ "tokens": [
  { "id": "tok_123", "label": "ci", "createdAt": "2026-06-01T12:00:00.000Z", "lastUsedAt": "2026-06-03T09:30:00.000Z", "revokedAt": null }
] }

POST /tokens

Mint a new workspace-scoped key. The raw token is returned once — store it now.

// request body
{ "label": "ci" }              // optional, ≤ 80 chars
// response
{ "id": "tok_456", "token": "<raw key — shown once>", "label": "ci", "createdAt": "2026-06-03T10:00:00.000Z" }

DELETE /tokens/{id}

Revoke a key. Returns 404 if it doesn't exist or is already revoked.

{ "id": "tok_456", "revoked": true }

GET /usage

Aggregate traffic plus a per-day series. Query: days (1–365, default 30).

{
  "totalBytes": 10485760,
  "peakTunnels": 4,
  "eventCount": 120,
  "lastSeen": "2026-06-03T09:30:00.000Z",
  "series": [ { "day": "2026-06-02T00:00:00.000Z", "bytes": 5242880, "peakTunnels": 3 } ]
}

GET /openapi.json

The full OpenAPI 3 document for these routes (public, no auth) — point a client generator or API explorer at it.

Errors

Non-2xx responses carry an error code: