Sheets, Slides & Collaboration

Export a spreadsheet

Streams a freshly materialized export artifact (SQLite, XLSX, CSV, or TSV) for a spreadsheet the caller can read. Authentication uses a JWT in the `token` query parameter (self-authenticating, like the WebSocket endpoint, because a browser anchor download cannot easily set `Authorization` headers). The handler verifies the JWT, checks `token_version` revocation, runs the effective-access gate (requires `resolved_kind=spreadsheet` and `can_read`), then drives the grid Durable Object export op and streams the decoded bytes. The response includes a `Content-Disposition: attachment` header. Exports are never cached (`Cache-Control: no-store`) and the content is bounded by the DO's the configured export-cell limit limit.

Auth One-time ?token= ticket

Parameters

Responses

Open BB Sheets grid WebSocket

Upgrades to a WebSocket connection to the `BbSheetGridDO` for a specific spreadsheet. Authentication uses the full session JWT passed as a `?token=` query parameter (not the `Authorization` header — the browser WebSocket API cannot set custom headers). Unlike `POST /v1/collaboration/ticket`, there is no intermediate ticket exchange; the JWT is verified directly. The handler checks `token_version` revocation, runs the spreadsheet effective-access gate (`resolved_kind` must be `spreadsheet`), and derives the socket capability (`read`/`write`) from `can_write`. The Durable Object key is `bbsheet:<orgId>:<documentId>`. The caller must send an `Upgrade: websocket` header.

Auth One-time ?token= ticket

Parameters

Responses

Exchange a JWT for a single-use collaboration WebSocket ticket

Exchanges a valid session JWT (supplied in the standard `Authorization: Bearer` header) for a cryptographically random, single-use, short-lived (60 s) ticket stored in KV. The ticket is then passed as `?ticket=` on the `/v1/collaboration/ws` WebSocket upgrade. This two-step flow is required because the browser WebSocket API does not support custom headers during the HTTP upgrade handshake. Token-version revocation is checked before the ticket is issued.

Auth Session JWT (Bearer)

Request Body

Responses

Open collaboration WebSocket

Upgrades to a WebSocket connection to the `CollaborationDO` for the caller's organization. The preferred authentication path uses a single-use `?ticket=` obtained from `POST /v1/collaboration/ticket`. A deprecated fallback accepts a direct JWT as `?token=` (a deprecation warning is logged; this path will be removed in a future release). The DO key is `collab:<orgId>`. The caller must send an `Upgrade: websocket` header.

Auth One-time ?token= ticket

Parameters

Responses

Get offline sync preferences (client shortcut)

Returns a simplified offline sync preferences summary derived from `api.sync_preferences_get`. This is a client-facing shortcut that normalizes the user's sync settings into a flat object (`enabled`, `max_items`, `sync_on_reconnect`, `storage_limit_mb`). On any database error it returns safe defaults rather than an error response, ensuring the client always has a usable baseline.

Auth Session JWT (Bearer)

Responses

Create a BB Sheets spreadsheet

Atomically creates a spreadsheet catalog row and the backing `bb.bbsheet_documents` row via `api.bbsheet_create`, then grants the creating user WRITE access. After creation the spreadsheet is accessible via the grid WebSocket at `/v1/bbsheet/ws`. `org_id` is pinned from the session and is never accepted in the body. The body is strict — unknown keys are rejected with `VALIDATION_ERROR`. Requires the `documents` system feature flag.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "name": "Q2 Budget Tracker"
}

Responses

List spreadsheet cell comments

Returns all cell comments and their replies for the specified spreadsheet. Serves as the seed source for the client-side comment adapter; comments anchor to cell rectangles via packed integer coordinates. Authorization (project membership + effective spreadsheet READ access) is enforced entirely by `api.bbsheet_comments_list`.

Auth Session JWT (Bearer)

Parameters

Responses

Create a cell comment on a spreadsheet

Creates a new comment thread anchored to a cell rectangle in the spreadsheet. The anchor is specified as two packed integer coordinates (`anchorFrom`/`anchorTo`) produced by the client's pure `cellAnchor` module. An optional client-provided `commentId` (UUID) is used as the database row id so the client list stays consistent. Authorization is enforced by `api.bbsheet_comment_create` via the `spreadsheet` effective-access gate. The body is strict — unknown keys are rejected.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Resolve or reopen a cell comment

Toggles the resolved state of a comment thread via `api.bbsheet_comment_resolve`. The body is strict — only `resolved` is accepted. Requires the comment author or an org admin role (enforced by the stored procedure).

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a cell comment thread

Deletes a comment thread and all its replies via `api.bbsheet_comment_delete`. Requires the comment author or an org admin role (enforced by the stored procedure).

Auth Session JWT (Bearer)

Parameters

Responses

Assign a cell comment to an org member

Assigns a comment thread to an active organization member and optionally sends a notification via `api.bbsheet_comment_assign`. The assignee must be an existing org member (enforced by the stored procedure). The body is strict — unknown keys are rejected.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Mark a comment assignment as done

Marks the assignment task on a comment as completed via `api.bbsheet_comment_assignment_done`. Only the assignee or a project admin can perform this action (enforced by the stored procedure). No request body is required.

Auth Session JWT (Bearer)

Parameters

Responses

Reply to a cell comment

Appends a reply to an existing comment thread via `api.bbsheet_comment_reply_create`. An optional client-provided `replyId` is used as the database row id. The body is strict — unknown keys are rejected.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a reply from a cell comment

Deletes a single reply from a comment thread via `api.bbsheet_comment_reply_delete`. Requires the reply author or an org admin role (enforced by the stored procedure).

Auth Session JWT (Bearer)

Parameters

Responses

Create a BB Slides deck

Atomically creates a presentation deck (catalog row with `content_type='application/x-bbslides'`), a backing `bb.bbprove_documents` row, and the owner WRITE grant via `api.bbslides_create`. The deck reuses the BB Docs editor and its CRDT transport lives at `/v1/yjs/ws`. `org_id` is pinned from the session and is never accepted in the body. The body is strict — unknown keys are rejected. Requires the `documents` system feature flag.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "name": "Product Launch Deck"
}

Responses

Delta-sync pull for offline sync

Serves the offline sync engine's bulk download (omit `since`) and incremental changed-since pulls (`since` epoch-ms) with keyset pagination. Supports 6 resource types: `entities`, `relationships`, `documents`, `tasks`, `comments`, `specs`. Incremental items may carry `_deleted: true` tombstones so clients can evict rows. Response is camelCased to the client contract (`items`, `hasMore`, `nextCursor`, `watermark`).

Auth Session JWT (Bearer)

Parameters

Responses

Get organization offline sync configuration

Returns the organization's offline sync configuration, which determines which entity types are allowed for offline access. If no configuration exists, returns a default with an empty allowed-types list. Organization and RLS scope are derived from the access token.

Auth Session JWT (Bearer)

Responses

Update organization offline sync configuration

Replaces the organization's offline sync configuration. Requires the `org.update` permission. Updates which entity types are permitted for offline sync and optional storage/interval caps. Per-org policy is enforced inside the stored procedures via `bb.org_sync_configs`.

Auth Session JWT (Bearer)

Request Body

Responses

Get user offline sync preferences

Returns the authenticated user's offline sync preferences within their current organization. If no preferences exist, returns defaults (empty enabled types, `auto_sync: true`, `sync_on_wifi_only: false`, `max_local_size_mb: 500`).

Auth Session JWT (Bearer)

Responses

Update user offline sync preferences

Replaces the authenticated user's offline sync preferences. The requested `enabled_sync_types` must be a subset of the organization's `allowed_sync_types`; types not permitted by the org config are rejected with `VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Responses

Open Yjs CRDT document WebSocket

Upgrades to a WebSocket connection to the `YjsDocDO` for a specific document. Used by BB Docs, BB Slides, and entity collaborative editing. Authentication is performed via the JWT in the `token` query parameter. The handler verifies the JWT, checks `token_version` revocation, and runs the `api.yjs_document_effective_access` gate to resolve the server-authoritative document kind (`bbprove_document` for BB Docs / BB Slides, or `entity`). The client-supplied `?docKind=` is intentionally ignored; the kind is resolved server-side to prevent doc-kind spoofing attacks. The derived capability (`read`/`write`) and access level are forwarded to the DO; the DO re-verifies on join. The DO key is `yjs:<orgId>:<documentId>`.

Auth One-time ?token= ticket

Parameters

Responses