{ "openapi": "3.1.0", "info": { "title": "Dock REST API", "version": "1.0.1", "description": "Dock's REST API. Bearer auth on every endpoint (except auth magic-link send). Returns JSON. Every mutation emits an event that streams over SSE and delivers to org-scoped webhooks.", "contact": { "name": "Dock Support", "url": "https://trydock.ai/docs/support/contact" } }, "servers": [ { "url": "https://trydock.ai" } ], "security": [ { "bearer": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (dk_live_…) or OAuth access token (oat_…)" } }, "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code. See /docs/api/errors for the catalog.", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "You don't have access to this workspace." } }, "required": [ "code", "message" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "example": "ws_01J5Z6Q7…" }, "slug": { "type": "string", "example": "launch-plan" }, "name": { "type": "string", "example": "Launch plan" }, "mode": { "type": "string", "enum": [ "table", "doc" ], "description": "Default-view hint (which tab opens first). A workspace can hold any combination of table + doc surfaces regardless of mode." }, "visibility": { "type": "string", "enum": [ "private", "org", "unlisted", "public" ], "description": "Who can see and edit. `private` = explicit members only. `org` = every org member is virtual editor. `unlisted` = anyone with the URL can read. `public` = indexed by search." }, "createdAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pinnedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the calling principal pinned the workspace; null if not pinned by them. Pin is per-user, not org-wide." }, "role": { "type": "string", "enum": [ "owner", "editor", "commenter", "viewer" ], "description": "The calling principal's effective role." }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/Principal" }, { "type": [ "object", "null" ], "description": "Null on legacy rows from before attribution shipped." } ] }, "org": { "type": "object", "properties": { "slug": { "type": "string" } }, "required": [ "slug" ] }, "primarySurface": { "$ref": "#/components/schemas/Surface" } }, "required": [ "id", "slug", "name", "mode", "visibility", "createdAt", "archivedAt", "pinnedAt", "role", "createdBy", "org" ] }, "ColumnDef": { "type": "object", "required": [ "key", "label", "type", "position" ], "properties": { "key": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer" }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } } } }, "Row": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": true }, "createdByPrincipalId": { "type": "string" }, "updatedByPrincipalId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BillingSummary": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "pro", "scale" ] }, "monthlyPriceCents": { "type": "integer" }, "activeAgents": { "type": "integer" }, "agentCap": { "type": "integer" }, "activeMembers": { "type": "integer" }, "memberCap": { "type": "integer" }, "activeWorkspaces": { "type": "integer" }, "workspaceCap": { "type": "integer" }, "totalRows": { "type": "integer" }, "rowsPerWorkspaceCap": { "type": "integer" }, "apiCallsPerMonthCap": { "type": "integer" }, "webhooksPerMonthCap": { "type": "integer" }, "monthlyTotalCents": { "type": "integer" } } }, "Surface": { "type": "object", "properties": { "id": { "type": "string", "example": "srf_01J5Z…" }, "slug": { "type": "string", "example": "table" }, "kind": { "type": "string", "enum": [ "table", "doc" ] } }, "required": [ "id", "slug", "kind" ] }, "Principal": { "type": "object", "properties": { "principalType": { "type": "string", "enum": [ "user", "agent" ], "description": "Whether the actor is a human user or a Dock-managed agent." }, "id": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ] } }, "required": [ "principalType", "id", "name", "avatarUrl" ] } } }, "paths": { "/api/auth": { "post": { "tags": [ "Auth" ], "summary": "Send magic-link email", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "OK. Magic link sent, or { waitlisted: true }.", "content": { "application/json": {} } }, "429": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/me": { "get": { "tags": [ "Auth" ], "summary": "Current user + org", "responses": { "200": { "description": "OK.", "content": { "application/json": {} } }, "401": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Auth" ], "summary": "Update profile (name, avatarUrl)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri", "nullable": true } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": {} } } } } }, "/api/me/sessions": { "delete": { "tags": [ "Auth" ], "summary": "Sign out everywhere", "responses": { "200": { "description": "OK. Returns { revokedSessions: number }.", "content": { "application/json": {} } } } } }, "/api/me/export": { "get": { "tags": [ "Auth" ], "summary": "GDPR data export", "responses": { "200": { "description": "JSON bundle.", "content": { "application/json": {} } } } } }, "/api/workspaces/{slug}/columns": { "get": { "summary": "List a workspace's column schema", "description": "Returns every column on the workspace's primary table surface, in display order. Use this before `create_row` / `update_row` so an agent knows which keys are valid. Empty array on doc-only workspaces (columns auto-seed on first row write).", "tags": [ "Columns" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Column list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} } } }, "required": [ "columns" ] } } } }, "403": { "description": "Caller has no read access to this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Replace the full column schema", "description": "Idempotent full-array replacement. Editor role required. Position values must be contiguous from 0. Renaming a column key triggers comment-anchor migration so existing comments on the old key keep resolving. Use POST instead when only appending one column.", "tags": [ "Columns" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} } } }, "required": [ "columns" ] } } } }, "responses": { "200": { "description": "Replaced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} } } }, "required": [ "columns" ] } } } }, "400": { "description": "Body shape failed validation, or position values aren't contiguous.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Read-only role cannot modify columns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Append a single column", "description": "Server auto-positions the new column as next-after-max so the contiguity invariant holds; any `position` in the request body is ignored. 409 if the key already exists. Editor role required.", "tags": [ "Columns" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "column": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type" ], "additionalProperties": {} } }, "required": [ "column" ] } } } }, "responses": { "200": { "description": "Appended; returns the new column plus the full updated list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "column": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} } } }, "required": [ "column", "columns" ] } } } }, "403": { "description": "Read-only role cannot modify columns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A column with the same key already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/events": { "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "get": { "tags": [ "Events" ], "summary": "Audit log", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 } }, { "in": "query", "name": "action", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": {} } } } } }, "/api/workspaces/{slug}/subscribe": { "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "get": { "tags": [ "Events" ], "summary": "Server-Sent Events stream", "responses": { "200": { "description": "text/event-stream", "content": { "text/event-stream": {} } } } } }, "/api/keys": { "get": { "tags": [ "Keys" ], "summary": "List keys", "responses": { "200": { "description": "OK.", "content": { "application/json": {} } } } }, "post": { "tags": [ "Keys" ], "summary": "Create key (shown once)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentName": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created. `secret` shown once.", "content": { "application/json": {} } } } } }, "/api/keys/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Keys" ], "summary": "Revoke key", "responses": { "204": { "description": "Revoked." } } } }, "/api/support": { "get": { "tags": [ "Support" ], "summary": "List tickets for your org", "responses": { "200": { "description": "OK.", "content": { "application/json": {} } } } }, "post": { "tags": [ "Support" ], "summary": "File ticket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "title", "body" ], "properties": { "kind": { "type": "string", "enum": [ "bug", "feature", "billing", "question", "other" ] }, "title": { "type": "string", "minLength": 3, "maxLength": 200 }, "body": { "type": "string", "minLength": 5, "maxLength": 10000 }, "context": { "type": "object" }, "attachmentUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 4 } } } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": {} } } } } }, "/api/support/upload": { "post": { "tags": [ "Support" ], "summary": "Upload screenshot (multipart/form-data)", "responses": { "200": { "description": "OK. Returns blob URL.", "content": { "application/json": {} } } } } }, "/api/referrals/me": { "get": { "tags": [ "Referrals" ], "summary": "Your referral code + progress", "responses": { "200": { "description": "OK.", "content": { "application/json": {} } } } } }, "/api/workspaces": { "get": { "summary": "List workspaces", "description": "List every workspace the caller can access. Pass `?archived=1` to list soft-archived workspaces only; the default view excludes them.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "1" ], "description": "Set to `1` to list archived workspaces only." }, "required": false, "description": "Set to `1` to list archived workspaces only.", "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Workspace list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "workspaces" ] } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a workspace", "description": "Create a new workspace. Returns the created row. The caller becomes its owner. Visibility defaults to the org's default if omitted.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Launch plan" }, "slug": { "type": "string", "description": "URL slug. Auto-derived from `name` if omitted. Must be unique within the org.", "example": "launch-plan" }, "mode": { "type": "string", "enum": [ "table", "doc" ], "description": "Default `table`. Auto-resolves to `doc` if `initialMarkdown` is set." }, "visibility": { "type": "string", "enum": [ "private", "org", "unlisted", "public" ], "description": "Inherits the org's default visibility if omitted." }, "initialMarkdown": { "type": "string", "description": "Seed the doc body in the same call. Mode auto-resolves to `doc`. Supports CommonMark + GFM + Dock's rich format set (mermaid, math, callouts, cross-refs, embeds)." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "workspace" ] } } } }, "400": { "description": "Body failed schema validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Workspace cap reached for the current plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug already exists in the org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}": { "get": { "summary": "Get workspace detail", "description": "Fetch a workspace by slug, including columns, member count, mode, and visibility.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "example": "launch-plan" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Workspace detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "workspace" ] } } } }, "403": { "description": "Not a member of this workspace's org or the workspace itself.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found (or visibility hides it from the caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a workspace", "description": "Rename, change mode, or change visibility. Editor or owner role required.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "visibility": { "type": "string", "enum": [ "private", "org", "unlisted", "public" ], "description": "Who can see and edit. `private` = explicit members only. `org` = every org member is virtual editor. `unlisted` = anyone with the URL can read. `public` = indexed by search." }, "mode": { "type": "string", "enum": [ "table", "doc" ], "description": "Default-view hint (which tab opens first). A workspace can hold any combination of table + doc surfaces regardless of mode." } }, "description": "All fields optional. Send only what you want to change." } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "workspace" ] } } } }, "403": { "description": "Caller lacks editor role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Archive a workspace", "description": "Soft-archive. Stamps `archivedAt` + `archivedByPrincipalId`. Rows, doc body, members, and event log stay intact for restore via `POST /api/workspaces/{slug}/unarchive`. Editor role required.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } } } }, "403": { "description": "Caller lacks editor role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/unarchive": { "post": { "summary": "Restore an archived workspace", "description": "Reverse a soft-archive. Idempotent on workspaces that aren't archived. Emits a `workspace.unarchived` event carrying the previous archive timestamp. Editor role required.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Restored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "workspace" ] } } } } } } }, "/api/workspaces/{slug}/pin": { "post": { "summary": "Pin a workspace", "description": "Personal pin. Writes `WorkspaceMember.pinnedAt = now`. The sidebar Pinned section orders by pinnedAt desc. Pin is per-user; one user pinning doesn't pin for the whole org. Requires an actual membership row (org-visibility virtual viewers can't pin).", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Pinned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "slug": { "type": "string" }, "pinnedAt": { "type": "string", "format": "date-time" } }, "required": [ "workspaceId", "slug", "pinnedAt" ] } } } } } }, "delete": { "summary": "Unpin a workspace", "description": "Remove the calling principal's pin. Idempotent.", "tags": [ "Workspaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Unpinned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } } } } } } }, "/api/workspaces/{slug}/surfaces": { "get": { "summary": "List surfaces in a workspace", "description": "Returns every surface (tab) in the workspace, in tab order.", "tags": [ "Surfaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Surface list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "surfaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "srf_01J5Z…" }, "slug": { "type": "string", "example": "table-2" }, "name": { "type": "string", "example": "Backlog" }, "kind": { "type": "string", "enum": [ "table", "doc" ], "description": "Whether this tab is a typed-row table or a TipTap rich-text doc." }, "position": { "type": "integer", "description": "Tab order within the workspace, 0-indexed." }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Column schema for table surfaces. `null` on doc/html surfaces." } }, "required": [ "id", "slug", "name", "kind", "position" ] } } }, "required": [ "surfaces" ] } } } }, "403": { "description": "Caller can't access this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a surface (tab)", "description": "Append a new surface to the workspace. Editor role required.", "tags": [ "Surfaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table", "doc" ], "description": "Whether this tab is a typed-row table or a TipTap rich-text doc." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name. Auto-generated if omitted." }, "slug": { "type": "string", "description": "URL slug. Auto-derived from name if omitted." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Optional initial columns for `kind: 'table'`. Defaults to Title/Status/Notes when omitted. Ignored on doc surfaces." } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "object", "properties": { "id": { "type": "string", "example": "srf_01J5Z…" }, "slug": { "type": "string", "example": "table-2" }, "name": { "type": "string", "example": "Backlog" }, "kind": { "type": "string", "enum": [ "table", "doc" ], "description": "Whether this tab is a typed-row table or a TipTap rich-text doc." }, "position": { "type": "integer", "description": "Tab order within the workspace, 0-indexed." }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Column schema for table surfaces. `null` on doc/html surfaces." } }, "required": [ "id", "slug", "name", "kind", "position" ] } }, "required": [ "surface" ] } } } }, "403": { "description": "Caller lacks editor role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/surfaces/{surfaceSlug}": { "patch": { "summary": "Rename, reslug, reorder, OR replace a surface's column schema", "description": "Rename, change the URL slug, move a surface within its workspace's tab strip, OR replace the column schema (table surfaces only). Pass any subset of `name`, `slug`, `position`, `columns`. Position uses 0-based indexing and other tabs shift to keep positions contiguous. Column replace fires `surface.columns_updated`; row.data keys not in the new schema are preserved on disk. Editor role required. Slug renames preserve old URLs via the surface alias table.", "tags": [ "Surfaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "surfaceSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "New display name." }, "slug": { "type": "string", "description": "New URL slug. Lowercase kebab-case, 3-64 chars. Must be unique within the workspace; old slug stays redirectable via the surface alias table." }, "position": { "type": "integer", "minimum": 0, "description": "Optional reorder. Equivalent to POST /surfaces/{slug}/move when only repositioning." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Wholesale replacement of the table surface's column schema. Table surfaces only — doc/html surfaces 400 with a table-only error. Each ColumnDef: `{ key, label, type, position, width?, hidden?, description?, options? }`. `type` ∈ text | longtext | url | status | owner | date | number. `options` is required on status/owner. Existing row.data keys not in the new column set are preserved on disk (they just stop rendering until a column with that key is added back). Fires `surface.columns_updated`." } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "object", "properties": { "id": { "type": "string", "example": "srf_01J5Z…" }, "slug": { "type": "string", "example": "table-2" }, "name": { "type": "string", "example": "Backlog" }, "kind": { "type": "string", "enum": [ "table", "doc" ], "description": "Whether this tab is a typed-row table or a TipTap rich-text doc." }, "position": { "type": "integer", "description": "Tab order within the workspace, 0-indexed." }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Column schema for table surfaces. `null` on doc/html surfaces." } }, "required": [ "id", "slug", "name", "kind", "position" ] } }, "required": [ "surface" ] } } } }, "403": { "description": "Caller lacks editor role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug collides with another surface in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a surface", "description": "Remove a tab. The workspace must keep at least one surface; deleting the last one returns 400.", "tags": [ "Surfaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "surfaceSlug", "in": "path" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } } } }, "400": { "description": "Workspace would have no surfaces left.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/surfaces/{surfaceSlug}/move": { "post": { "summary": "Reorder a surface", "description": "Change a surface's tab position. Other tabs shift accordingly.", "tags": [ "Surfaces" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "surfaceSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "New 0-indexed tab position. Other tabs shift to accommodate." } }, "required": [ "position" ] } } } }, "responses": { "200": { "description": "Moved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "type": "object", "properties": { "id": { "type": "string", "example": "srf_01J5Z…" }, "slug": { "type": "string", "example": "table-2" }, "name": { "type": "string", "example": "Backlog" }, "kind": { "type": "string", "enum": [ "table", "doc" ], "description": "Whether this tab is a typed-row table or a TipTap rich-text doc." }, "position": { "type": "integer", "description": "Tab order within the workspace, 0-indexed." }, "columns": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "text", "longtext", "number", "status", "person", "date", "url", "checkbox", "select" ] }, "position": { "type": "integer", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": 0 }, "hidden": { "type": "boolean" }, "description": { "type": "string", "maxLength": 280 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "color": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "label", "type", "position" ], "additionalProperties": {} }, "description": "Column schema for table surfaces. `null` on doc/html surfaces." } }, "required": [ "id", "slug", "name", "kind", "position" ] } }, "required": [ "surface" ] } } } } } } }, "/api/workspaces/{slug}/rows": { "get": { "summary": "List rows in a workspace", "description": "Returns rows from the workspace's primary table surface unless `?surface=` is passed. Newest-first by default.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "description": "Surface slug to scope to. Omit for the primary table surface." }, "required": false, "description": "Surface slug to scope to. Omit for the primary table surface.", "name": "surface", "in": "query" }, { "schema": { "type": "string", "description": "Page size. Default 50, max 500." }, "required": false, "description": "Page size. Default 50, max 500.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Offset-based pagination cursor." }, "required": false, "description": "Offset-based pagination cursor.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Row list with total count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "rows", "total", "limit", "offset" ] } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a row", "description": "Add a new row to a table surface. `data` keys must match column ids on the surface; values are coerced to the column type. Multi-surface workspaces accept `surface` (slug) or `surfaceId` to pick which sheet the row lands on; omit both to fall through to the workspace's primary table surface.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "position": { "type": "integer", "minimum": 0 }, "auto_create_columns": { "type": "boolean" }, "surfaceId": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "surface_slug": { "type": "string", "minLength": 1 } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "row": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "required": [ "row" ] } } } }, "400": { "description": "Invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Row cap reached for the current plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/rows/{id}": { "get": { "summary": "Get a single row", "description": "Fetch one row by id, including its current cell values.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Row detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "row": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "required": [ "row" ] } } } }, "404": { "description": "Row not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a row", "description": "Patch the `data` field on an existing row. Only the column keys you include get updated; other cells are left alone. Setting `surface` (slug) or `surfaceId` to a different sheet MOVES the row there: position recomputes to the destination's tail (override with `position`) and a `row.moved_surface` event fires. Same-surface is a no-op move.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "position": { "type": "number" }, "auto_create_columns": { "type": "boolean" }, "surfaceId": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "surface_slug": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "row": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "required": [ "row" ] } } } } } }, "delete": { "summary": "Delete a row", "description": "Permanent. No soft-delete on individual rows.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } } } } } } }, "/api/workspaces/{slug}/rows/bulk": { "post": { "summary": "Bulk row operations", "description": "Atomic create + update + delete in a single request. Up to 500 ops per call. All ops apply in one Prisma transaction so partial-success scenarios don't happen.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "create": { "type": "array", "items": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "position": { "type": "integer", "minimum": 0 }, "auto_create_columns": { "type": "boolean" }, "surfaceId": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "surface_slug": { "type": "string", "minLength": 1 } }, "required": [ "data" ] } }, "patch": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "data" ] } }, "delete": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Bulk applied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "patched": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "r_01J5Z…" }, "surfaceId": { "type": "string" }, "position": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {}, "description": "Cell values keyed by column id. Types match the column schema." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Principal id (user OR agent)." }, "updatedBy": { "type": "string" } }, "required": [ "id", "surfaceId", "position", "data", "createdAt", "updatedAt", "createdBy", "updatedBy" ] } }, "deleted": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/workspaces/{slug}/rows/move": { "post": { "summary": "Move rows to a different surface", "description": "Atomic batch move. All rows move to the target surface (specified by `surfaceId` or `surface` slug). Positions are recomputed at the destination tail.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rowIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500 }, "surfaceId": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "surface_slug": { "type": "string", "minLength": 1 } }, "required": [ "rowIds" ] } } } }, "responses": { "200": { "description": "Moved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "moved": { "type": "integer" } }, "required": [ "moved" ] } } } } } } }, "/api/workspaces/{slug}/rows/{id}/history": { "get": { "summary": "Row change history", "description": "Per-cell change history for one row. Returns chronological diffs with author + timestamp.", "tags": [ "Rows" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "History entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "history": { "type": "array", "items": { "type": "object", "properties": { "changedAt": { "type": "string", "format": "date-time" }, "changedBy": { "type": "string" }, "changedByPrincipalType": { "type": "string", "enum": [ "user", "agent" ] }, "diff": { "type": "object", "additionalProperties": { "type": "object", "properties": { "from": {}, "to": {} } }, "description": "Per-column diffs. Keys are column ids; values describe the before/after." } }, "required": [ "changedAt", "changedBy", "changedByPrincipalType", "diff" ] } } }, "required": [ "history" ] } } } } } } }, "/api/workspaces/{slug}/doc": { "get": { "summary": "Read the doc body", "description": "Returns the workspace's doc body as ProseMirror JSON. 403 if the workspace is in table mode.", "tags": [ "Doc body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "description": "Surface slug for multi-doc workspaces. Omit for the primary doc surface." }, "required": false, "description": "Surface slug for multi-doc workspaces. Omit for the primary doc surface.", "name": "surface", "in": "query" }, { "schema": { "type": "string", "enum": [ "json", "markdown", "text" ], "description": "Response shape: `json` (ProseMirror, default) · `markdown` (CommonMark + GFM, useful for LLM context or textual diff) · `text` (plain text, no formatting marks). Overrides `Accept` header." }, "required": false, "description": "Response shape: `json` (ProseMirror, default) · `markdown` (CommonMark + GFM, useful for LLM context or textual diff) · `text` (plain text, no formatting marks). Overrides `Accept` header.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "Doc body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "ProseMirror JSON. Returned when `?format` is omitted or `?format=json`." }, "markdown": { "type": "string", "description": "CommonMark + GFM. Returned when `?format=markdown` (or `Accept: text/markdown` with no `?format`)." }, "text": { "type": "string", "description": "Plain text, formatting marks stripped. Returned when `?format=text` (or `Accept: text/plain` with no `?format`)." }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": [ "updatedAt", "updatedBy" ] } } } }, "403": { "description": "Workspace is in table mode (no doc surface).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Replace the doc body", "description": "Send either `content` (ProseMirror JSON) or `markdown` (string). When both are present, `content` wins. Markdown gets converted server-side via remark + remark-gfm + Dock's rich format set (mermaid, math, callouts, cross-refs, embeds).", "tags": [ "Doc body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": {}, "markdown": { "type": "string", "maxLength": 500000 } } } } } }, "responses": { "200": { "description": "Replaced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "ProseMirror JSON. Returned when `?format` is omitted or `?format=json`." }, "markdown": { "type": "string", "description": "CommonMark + GFM. Returned when `?format=markdown` (or `Accept: text/markdown` with no `?format`)." }, "text": { "type": "string", "description": "Plain text, formatting marks stripped. Returned when `?format=text` (or `Accept: text/plain` with no `?format`)." }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": [ "updatedAt", "updatedBy" ] } } } }, "400": { "description": "Body shape failed validation, OR doc body exceeded byte/depth/node-count cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/doc/sections": { "post": { "summary": "Append a markdown section to the doc", "description": "Append-only counterpart to PUT /doc. Saves the round-trip cost of fetch+merge+PUT for agents producing content in chunks (changelog updates, daily standups, ingest pipelines).", "tags": [ "Doc body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "minLength": 1, "maxLength": 500000 } }, "required": [ "markdown" ] } } } }, "responses": { "200": { "description": "Appended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "ProseMirror JSON. Returned when `?format` is omitted or `?format=json`." }, "markdown": { "type": "string", "description": "CommonMark + GFM. Returned when `?format=markdown` (or `Accept: text/markdown` with no `?format`)." }, "text": { "type": "string", "description": "Plain text, formatting marks stripped. Returned when `?format=text` (or `Accept: text/plain` with no `?format`)." }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": [ "updatedAt", "updatedBy" ] } } } } } }, "patch": { "summary": "Replace a single section by heading", "description": "Targeted-edit counterpart to PUT /doc (full replacement) and POST /doc/sections (append). Finds the FIRST heading whose plain text matches `heading` (case-sensitive, trimmed), then replaces everything from that heading up to the next heading at the same or shallower level. `markdown` is the FULL replacement INCLUDING the heading line; pass an empty string to delete the section. Returns 404 when no matching heading exists, by design, so a misremembered heading fails loudly. Same byte/depth/node-count guard as PUT /doc; same writeDocBody attribution path.", "tags": [ "Doc body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 500 }, "markdown": { "type": "string", "maxLength": 500000 }, "allowBlockLoss": { "type": "boolean" } }, "required": [ "heading", "markdown" ] } } } }, "responses": { "200": { "description": "Replaced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "ProseMirror JSON. Returned when `?format` is omitted or `?format=json`." }, "markdown": { "type": "string", "description": "CommonMark + GFM. Returned when `?format=markdown` (or `Accept: text/markdown` with no `?format`)." }, "text": { "type": "string", "description": "Plain text, formatting marks stripped. Returned when `?format=text` (or `Accept: text/plain` with no `?format`)." }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": [ "updatedAt", "updatedBy" ] } } } }, "400": { "description": "Body shape failed validation, OR doc body exceeded byte/depth/node-count cap after the section was substituted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No heading on the doc matches `heading` exactly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/workspaces/{slug}/html": { "get": { "summary": "Read an HTML surface body", "description": "Returns the resolved html surface's body (html, css, js). Empty fields when the surface exists but no body has been written yet. 404 when `?surface_slug=` doesn't match a live html surface.", "tags": [ "HTML body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "description": "Surface slug for multi-html workspaces. Omit for the primary html surface (lowest position)." }, "required": false, "description": "Surface slug for multi-html workspaces. Omit for the primary html surface (lowest position).", "name": "surface_slug", "in": "query" }, { "schema": { "type": "string", "description": "Legacy alias for `surface_slug`. Same semantics. Prefer `surface_slug` in new code." }, "required": false, "description": "Legacy alias for `surface_slug`. Same semantics. Prefer `surface_slug` in new code.", "name": "surface", "in": "query" } ], "responses": { "200": { "description": "Resolved html body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "description": "Sanitized HTML body. Empty string when the surface exists but no body has been written yet." }, "css": { "type": "string", "description": "CSS source. Applied inside the sandboxed iframe." }, "js": { "type": "string", "description": "JS source. Stored but NOT executed at v1 — the sandbox iframe is scripts-off. Interactive mode lands in a later PR." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedBy": { "type": [ "string", "null" ] }, "updatedByPrincipalType": { "type": [ "string", "null" ] }, "surfaceSlug": { "type": [ "string", "null" ], "description": "Slug of the resolved html surface. Null when the workspace has no html surface yet." } }, "required": [ "html", "css", "js", "updatedAt", "updatedBy", "updatedByPrincipalType", "surfaceSlug" ] } } } }, "404": { "description": "`surface_slug` didn't match any live html surface in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Replace fields on an HTML surface body", "description": "Partial-update friendly. Any of `html` / `css` / `js` can be omitted to leave the column unchanged; pass empty string to clear. HTML is sanitized at write time (see UpdateHtmlSchema). Emits `html.created` on first write to a surface, `html.updated` on subsequent writes — both carry per-field byte counts so webhooks can fan out a meaningful signal. Requires editor role.", "tags": [ "HTML body" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "surface_slug": { "type": "string", "description": "Optional html surface slug. Omit to write to the primary html surface (lowest position)." }, "html": { "type": "string", "description": "Sanitized at write time. Caps: 50 KB per field. Omit to leave the column unchanged; pass empty string to clear. Sanitizer strips