REST API (v1)

The hosted service exposes a small, read-only REST API for workspace details, API key metadata, and usage. Most of what you do day to day goes through the CLI, MCP, or --json. This API is for dashboards and automation.

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. Workspace admins and owners create and revoke keys in the dashboard under API Keys:

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, and 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, "exampleUrl": "api-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 }
] }

API keys can't create or revoke keys. That takes a signed-in workspace admin or owner, so every key is traceable to the person who made it, and a leaked key can't mint replacements for itself.

GET /usage

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

{
  "requests": 120,
  "bytesIn": 1048576,
  "bytesOut": 9437184,
  "totalBytes": 10485760,
  "lastSeen": "2026-06-03T09:30:00.000Z",
  "series": [
    { "day": "2026-06-02T00:00:00.000Z", "requests": 64, "bytesIn": 524288, "bytesOut": 4718592, "totalBytes": 5242880 }
  ]
}

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: