Quickstart

Everything below is one curl at a time against the platform surface, the flat /v1/... routes an API key is made for. Replace $SNOZE_API_KEY with a key from Workspace settings → API keys (how to create one).

1. Check the key

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

A 200 with a data.items array means the key works and is pinned to a workspace. A 401 means the key is wrong or revoked; a 403 means it lacks a scope. See Errors.

2. Find a database

Items are everything in the sidebar: pages, databases, dashboards, canvases, folders. Filter by kind.

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

{
  "data": {
    "items": [
      {
        "id": "9f2c1e7a-3b58-4d0c-8e27-6a1f9d4b3c85",
        "kind": "database",
        "title": "Production board"
      }
    ],
    "cursor": null
  }
}

Keep the id. When cursor is not null, pass it back as ?cursor= to get the next page.

3. Read its records

curl "https://api.snoze.dev/v1/databases/9f2c1e7a-3b58-4d0c-8e27-6a1f9d4b3c85/records?limit=20" \
  -H "Authorization: Bearer $SNOZE_API_KEY"

Two useful filters: viewId returns the records a saved view shows, with that view's filters and sort applied, and search matches against titles. Each record carries title and a data object keyed by the database's field keys. The shape of data is in Database records.

4. Create a record

curl -X POST "https://api.snoze.dev/v1/databases/9f2c1e7a-3b58-4d0c-8e27-6a1f9d4b3c85/records" \
  -H "Authorization: Bearer $SNOZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Localisation pass", "data": { "status": "todo", "priority": "medium" } }'

The response is the full record, including its new id. Field keys and option keys are the database's own; read one existing record first to see them.

5. Update it

curl -X PATCH "https://api.snoze.dev/v1/records/1d8a44e0-7c93-4f21-b60a-3e8d2f5a9c14" \
  -H "Authorization: Bearer $SNOZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "status": "doing" } }'

PATCH merges: send only the fields that changed. Set "archived": true to archive instead of deleting.

Where next

• Push instead of poll: Webhooks deliver signed events for record and item changes.
• Give an agent the workspace: the MCP server exposes the same operations to Claude, Cursor and other clients, with the same permissions and approval rules the in-app assistant has.
• Files: upload and attach with the files endpoints.
• Limits: rate limits and how to back off.