Skip to content
Knobs Docs

Sheets

Knobs Sheets are collaborative workbooks. The REST surface covers workbook lifecycle and sharing.

Grid content has no REST path. Cell and structural edits happen over the app’s realtime connection after a workbook is opened — there is no endpoint to read or write cell values. If you need sheet data programmatically today, the supported patterns are the app itself and workspace search over indexed content; a data API is on the roadmap.

All routes are workspace-scoped and accept a session JWT or API key. Workbooks are private by default with the same per-object ACL model as Docs: no view access reads as 404.

Endpoints

Section titled “Endpoints”
Endpoint Description
GET /v1/workspaces/{wid}/sheets List workbooks you can read (?limit=)
POST /v1/workspaces/{wid}/sheets Create {title} → 201 — metadata only, private to you
GET /v1/workspaces/{wid}/sheets/{sid} Workbook metadata (incl. whether it’s currently “hot” and the snapshot pointer)
POST /v1/workspaces/{wid}/sheets/{sid}/open Claim + hydrate the live grid for collaborative editing (used by the apps)
GET /v1/workspaces/{wid}/sheets/{sid}/access Sharing panel: {ownerUid, workspaceAccess, grants} (owner or workspace admin)
PUT /v1/workspaces/{wid}/sheets/{sid}/access Wholesale replace of {workspaceAccess, grants}

Examples

Section titled “Examples”

Create a workbook:

Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/sheets \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Q3 budget"}'

List what you can see:

Terminal window
curl -H "Authorization: Bearer knak_..." \
  https://api.knobs.io/v1/workspaces/{wid}/sheets
{
  "sheets": [
    { "id": "s_4be2…", "title": "Q3 budget", "ownerUid": "u_9f2c…", "updatedAt": "2026-07-16T14:20:00Z" }
  ]
}

Share it workspace-wide as view, with edit for one group:

Terminal window
curl -X PUT https://api.knobs.io/v1/workspaces/{wid}/sheets/{sid}/access \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"workspaceAccess": "view", "grants": {"grp_finance…": "edit"}}'

Notes

Section titled “Notes”
  • POST /v1/workspaces/{wid}/sheets/{sid}/open may return 409 with code hydrating while another client’s open is hydrating the live grid — retry after ~500 ms.
  • Access levels are view, comment, edit; workspaceAccess may also be none. Grant principals are user uids or group ids (grp_…).
  • Workspace admins/owners implicitly hold owner-level access on every workbook.