Concepts

Every user has a default org. Workspaces, agents, members, and webhooks belong to an org. Plan and Stripe subscription are attached at the org level, not per-workspace.

Slug: unique across the registry (/{org}/{workspace} URLs are unambiguous across Dock). Renaming the slug keeps old URLs resolving forever via a workspace_slug_aliases table.

The unit humans and agents collaborate on. A workspace is a container of one or more surfaces (the tabs along the top). Each surface is either a typed-row table or a TipTap rich-text doc, and a workspace can hold any combination, one or many of either kind, in any mix. The modefield is a default-view hint for the UI (which tab opens first); it doesn't restrict what surfaces exist. Workspaces live under an org at /{org}/{workspace}.

Visibility is separate from role: private · org · unlisted · public. Visibility controls who can read; writes always require membership regardless.

Every workspace records its creator as a principalId + principalType pair so the UI can show an agent orb or a human avatar on the card. Agent-created workspaces enroll both the agent AND its owning user as owners (so the human stays in the loop), but attribution is explicit: createdBy.principalType === "agent" means the agent actually pressed create. Same pair exists on rows, doc bodies, API keys, and webhooks.

A JSON object keyed by column key. Positions are integer, sortable. Every row has create/update principal IDs (who made the change).

Bulk updates go through PATCH /rows/bulk (all-or-nothing up to 500). Every row mutation emits an event; subscribers fan out over SSE and webhooks.

Doc-mode workspaces have exactly one body. Stored as ProseMirror JSON. Replace-only today (last-write-wins); CRDT merge is Phase 4.

Images embedded in docs are uploaded via POST /api/workspaces/{slug}/upload and referenced by URL in the document tree.

Nine types: text, longtext, number, status, person, date, url, checkbox, select. Each column has a key (stable identifier), label (display), and optional options (for status/select).

Column schema lives on the workspace; rows validate loosely against it. Hidden columns preserve their values but don't show in the table view.

An Agent is a named identity that owns API keys and appears in the events log with its own avatar. Agents count toward the org's agent cap (Free 3 · Pro 10 · Scale 30) when they hold at least one non-revoked key.

Agents are created when you mint a key for a new name. They inherit the creating user's workspace access by default, but can be scoped to a single workspace via the key.

WorkspaceMember rows bind a principal (user or agent) to a workspace with a role. Distinct from org membership, which lives separately on the Org · User link.

Roles per workspace: owner (full control + delete), editor (read + write + invite), writer (read + write only), viewer (read only).

Format: dk_<48 hex>. Stored as a SHA-256 hash; plaintext shown once at creation. Each key belongs to an Agent and can be scoped to a single workspace or the whole org.

Revocable from Settings · API keys. Revocation is immediate, no grace window.

Claude, Cursor, and other MCP-capable clients self-register via Dynamic Client Registration at POST /oauth/register, then walk the user through PKCE at /oauth/authorize. Access tokens expire after an hour; refresh tokens after 30 days.

Every row, doc, member, and webhook change writes a row to the events table. Events are scoped to a workspace; listing them gives you a replay. Subscribers stream events over SSE (GET /workspaces/{slug}/subscribe) and via HMAC-signed webhooks.

Actions: row.created, row.updated, row.deleted, row.sealed, doc.updated, comment.added, comment.deleted, member.invited, member.joined, member.removed, workspace.created, workspace.renamed, workspace.columns_updated, workspace.visibility_changed.

Subscribe an HTTPS URL to one or more event types. Every matching event across every workspace your org owns gets POSTed to you, signed with X-Dock-Signature. Retries follow exponential backoff for up to 24 hours.

See the webhooks reference for signature verification.

Rows support comment threads (useful for review loops). Doc mode has inline annotations within the TipTap tree instead.

Three tiers. Caps on agents, members, workspaces, rows per workspace, API calls per month, webhook deliveries per month. Past Scale's caps, call request_limit_increase.

Hitting a cap returns 402 payment_required with an actionable details payload (the upgrade/increase endpoint + tool names).