Items

Everything a workspace contains is an item: pages, databases, dashboards, canvases, forms, notes, folders, and files all share one envelope and one set of endpoints. What varies by kind is the item's content, not its envelope.

The item object

{
  "id": "0b6f2e6a-9f2c-4e7a-8d31-2c1e7a9f2c4e",
  "workspaceId": "4b81aa0c-…",
  "kind": "database",
  "title": "Launch tasks",
  "parentItemId": null,
  "targetId": "9f2c1e7a-…",
  "order": 3,
  "archived": false,
  "accessMode": "open",
  "metadata": {},
  "createdAt": "2026-07-01T09:12:44.000Z",
  "updatedAt": "2026-07-14T16:03:10.000Z"
}

List items

GET /v1/items returns items the key can read, newest-updated first. Filter with kind and parentId, and page with a cursor:

curl "https://api.snoze.dev/v1/items?kind=database&limit=50" \
  -H "Authorization: Bearer $SNOZE_API_KEY"

{
  "data": {
    "items": [
      { "id": "0b6f2e6a-…", "kind": "database", "title": "Launch tasks", "…": "…" }
    ],
    "cursor": null
  }
}

Pass cursor back as ?cursor= to fetch the next page; a null cursor means you've reached the end. limit defaults to 50 (max 200). Items the key's scopes or grants can't see are filtered out entirely.

Get an item

curl "https://api.snoze.dev/v1/items/0b6f2e6a-9f2c-4e7a-8d31-2c1e7a9f2c4e" \
  -H "Authorization: Bearer $SNOZE_API_KEY"

The response carries the envelope plus type-specific content where the flat surface provides it today:

• kind: "database" → a database object with the full field schema, so you can write records immediately.
• kind: "file" → a file object with the download descriptor (see Files).
• Page and canvas content is not yet exposed over the flat REST surface — agents read and edit page blocks through the MCP server.

Create an item

POST /v1/items accepts kind (folder, page, note, dashboard, canvas, form, database, or file), a title, and optionally parentItemId, icon, color, and order:

curl -X POST "https://api.snoze.dev/v1/items" \
  -H "Authorization: Bearer $SNOZE_API_KEY" \
  -H "Idempotency-Key: 4c9a1c1e-create-tasks" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "database", "title": "Launch tasks" }'

Creating a surface-backed kind (page, note, dashboard, canvas, form) or a database materializes the backing content in the same transaction. For kind: "file", pass the fileId returned by the upload endpoint.

Update and delete

PATCH /v1/items/{id} takes any of title, parentItemId, icon, color, order, archived — set parentItemId, icon, or color to null to clear them. DELETE /v1/items/{id} removes the item and returns its final envelope.