> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace REST API

> Apps, deployments, databases, events, and observability

Send your [workspace token](/v2/getting-started/authentication) as a Bearer token. Start by getting your workspace ID:

```bash theme={null}
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:

```bash theme={null}
curl --fail-with-body \
  "https://app.beam.cloud/api/v1/deployment/$WORKSPACE_ID" \
  -H "Authorization: Bearer $BEAM_TOKEN"
```

## Related Guides

* [Deployment lifecycle and readiness](/v2/hosting/deployments)
* [Databases and credential rotation](/v2/data/databases)
* [Stacks](/v2/hosting/stacks)
* [Logs, metrics, and tasks](/v2/operations/observability)
* [Webhook payloads and signature verification](/v2/operations/webhooks)
* [Workspace MCP](/v2/operations/mcp)

## 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.