REST API Overview

Every public workspace capability in Dots is a typed HTTP route under /api/v1. The CLI's API-backed families, the web app, and the MCP server front this one surface, so anything they do against the workspace can be done directly against the API.

Envelopes

Responses follow two shapes — a success envelope and an error envelope:

{ "data": ... }

{ "error": { "code": ..., "message": ..., "details"?: ... } }

An unmarked request gets exactly { data }. An agent request that sends the x-dots-agent marker also receives a dbom side-channel alongside data. The byte-identity guarantee is scoped to the unmarked HTTP response: without the marker, the response stays { data }, with no extra sibling.

The tenant is never a wire parameter — companyId is injected server-side from the resolved actor. Row sub-resources are scoped by their Dotabase and human id (/dotabases/:dotabaseId/rows/:humanId); flat operations like bulk row ops and edges are keyed by UUID.

Route Groups

The route table registers 458 operations across 68 groups. 75 of those operations are internal-tier: served live, but stripped from the public document — the cross-tenant operator plane and the internal tooling tier.

The OpenAPI Document

Every public route is documented in an OpenAPI 3.1.0 document — Dots API — served at GET /api/v1/openapi.json. 75 operations are enrolled in the internal tier and stripped from it, so the served document advertises the public surface alone. That document is the exhaustive, always-current contract for the public API — read it (or point a code generator at it) rather than relying on any hand-maintained list. REST reads return JSON row data; the agent-facing Markdown envelope described in Row Envelope Format is produced by the CLI, MCP text output, and the docs export from that row data.

generator: apps/docs/pipeline/generate-reference.ts — regenerate with corepack pnpm --filter @dots/docs docs:generate:reference; a hand edit to this page fails the docs drift gate.