The Dreambase REST API is the deterministic interface for day-to-day application and automation work. Use MCP when an agent needs to explore sources, reason about a question, or create and validate a new dataset. Use REST after the resource and operation are known.

This page lists the live alpha routes verified in the develop-branch define-once registry. The broader OpenAPI document is a design target; unlisted resources and operations should not be treated as available.

Base URL and authorization

Base URL

https://api.dreambase.com/v1

Use the Dreambase OAuth authorization-code flow and send the resulting token in the Authorization header. Every workspace resource also enforces the user’s current membership and role.

Authorization header

Authorization: Bearer <access-token>

When to use REST instead of MCP

• A scheduled job refreshes a known dataset.

• An application lists known dashboards or dataset metadata.

• A service polls a Supabase Health Report to completion.

• The workflow needs a predictable HTTP resource and response shape.

• The operation should run without an LLM choosing tools or interpreting intent.

Live alpha endpoints

GET /workspaces

Scope: workspaces:read

List every workspace the authenticated user belongs to.

GET /workspaces/{workspace_id}/dashboards

Scope: dashboards:read

List dashboard metadata, refresh state, and latest aggregation date. Supports limit and cursor.

GET /workspaces/{workspace_id}/connections

Scope: connections:read

List Supabase, API, and MCP connections as lightweight summaries. Optional type narrows the connection kind.

GET /workspaces/{workspace_id}/datasets

Scope: datasets:read

List dataset handles without rows. Supports limit and cursor.

GET /workspaces/{workspace_id}/datasets/{dataset_id}

Scope: datasets:read

Get one dataset’s complete metadata handle and column profiles.

POST /workspaces/{workspace_id}/datasets/{dataset_id}/refresh

Scope: datasets:read + datasets:write

Re-execute the stored dataset definition and replace its current rows.

POST /workspaces/{workspace_id}/connections/supabase/{connection_id}/health-reports

Scope: health-reports:write

Start a Supabase Health Report. Returns 202 with a report id and generating status.

GET /workspaces/{workspace_id}/connections/supabase/{connection_id}/health-reports

Scope: health-reports:read

List recent health reports for a Supabase connection. Supports limit and cursor.

GET /workspaces/{workspace_id}/connections/supabase/{connection_id}/health-reports/{report_id}

Scope: health-reports:read

Get one health report. Poll until completed to read metrics, measured scores, grade, insights, and recommendations.

List workspaces

Request

curl https://api.dreambase.com/v1/workspaces \ -H "Authorization: Bearer <access-token>"

List and inspect datasets

List

curl "https://api.dreambase.com/v1/workspaces/<workspace-id>/datasets?limit=20" \ -H "Authorization: Bearer <access-token>"

Get one

curl https://api.dreambase.com/v1/workspaces/<workspace-id>/datasets/<dataset-id> \ -H "Authorization: Bearer <access-token>"

List endpoints are keyset-paginated. A page may contain fewer than limit because responses also have a 32 KiB byte budget. Continue whenever nextCursor is present and stop only when it is absent.

Refresh a known dataset

Request

curl -X POST \ https://api.dreambase.com/v1/workspaces/<workspace-id>/datasets/<dataset-id>/refresh \ -H "Authorization: Bearer <access-token>"

Refresh runs the real stored source. It may incur compute or source usage, and API POST or MCP-backed sources may have effects on the connected system. Trigger only from an explicit operation and do not blind-retry an ambiguous failure.

Create and poll a Health Report

Create

curl -X POST \ https://api.dreambase.com/v1/workspaces/<workspace-id>/connections/supabase/<connection-id>/health-reports \ -H "Authorization: Bearer <access-token>"

Poll

curl https://api.dreambase.com/v1/workspaces/<workspace-id>/connections/supabase/<connection-id>/health-reports/<report-id> \ -H "Authorization: Bearer <access-token>"

Errors

Errors use a shared envelope with error, code, and optional details. Common statuses are 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 403 FORBIDDEN, 404 NOT_FOUND, and 409 CONFLICT.

Not available through REST

• No REST whoami route.

• No dataset row endpoint.

• No raw-SQL endpoint.

• No REST query_dataset binding.

• No REST plan_datasets, save_dataset, or promote_dataset binding.

• No stable REST dashboard-creation endpoint.

• No stable REST ask endpoint.

• Datasets — Understand dataset lifecycle, querying, refresh, and agent-driven creation.

• Official Dreambase MCP — Use agents for discovery, exploration, and dataset creation.

• MCP Use Cases — See agent-driven examples before turning the result into repeatable API work.

Availability

These routes are verified in the current develop-branch registry as the live alpha surface, but the entire programmatic surface is gated by PLATFORM_API_ENABLED, deployment configuration, OAuth scopes, and workspace permissions. Code presence does not prove a route is enabled for every customer or establish production reliability.