Workspace REST API - Beam

Send your workspace token as a Bearer token. Start by getting your workspace ID:

curl --fail-with-body https://app.beam.cloud/api/v1/workspace/current \
  -H "Authorization: Bearer $BEAM_TOKEN"

Replace {ws} below with the response’s external_id.

Common Routes

Use https://app.beam.cloud/api/v1 as the base URL:

Area	Method and path under `/api/v1`
Apps	`GET /app/{ws}`, `GET /app/{ws}/latest`, `GET /app/{ws}/{appId}`
Deployments	`GET /deployment/{ws}`, `GET /deployment/{ws}/{deploymentId}`
Deployment URL	`GET /deployment/{deploymentId}/url`
Lifecycle	`POST /deployment/{ws}/start/{deploymentId}`, `POST /deployment/{ws}/stop/{deploymentId}`
Tasks	`GET /task/{ws}`, `GET /task/{ws}/{taskId}`, `GET /task/{ws}/{taskId}/subscribe`
Containers	`GET /container/{ws}`
Databases	`GET /database/{ws}`, `POST /database/{ws}`
Stacks	`GET /stack/{ws}`, `POST /stack/{ws}`, `PUT /stack/{ws}/{stackId}`
Logs	`GET /logs/{ws}`, `GET /logs/{ws}/stream`
Metrics	`GET /metrics/{ws}/stub-timeseries`, `GET /metrics/{ws}/workspace-timeseries`, `GET /metrics/{ws}/pool-timeseries`
Events	`GET /events/{ws}/history`, `GET /events/{ws}/stream`
Webhooks	`GET /webhook/{ws}`, `POST /webhook/{ws}`
Limits	`GET /workspace/{ws}/limits`

List responses may be paginated. Use MCP’s api_routes for the full route list. Its api tool substitutes {ws} automatically. For example, list deployments:

curl --fail-with-body \
  "https://app.beam.cloud/api/v1/deployment/$WORKSPACE_ID" \
  -H "Authorization: Bearer $BEAM_TOKEN"

Handle Errors at Both Layers

Workspace REST errors use HTTP error statuses. The separate gateway API under /api/v1/gateway can return HTTP 200 with ok: false; check its response body too.