Overview

The REST API lives at https://api.snoze.dev and speaks JSON. Every endpoint is defined schema-first, and the full API reference is generated from those schemas — including request/response types and the exact error union per endpoint.

Two surfaces

• The platform surface — flat paths like /v1/items, /v1/databases/{id}/records, /v1/records/{id}, /v1/files. Authenticates only with workspace API keys: the key pins the workspace, so paths carry no workspace segment. This is the surface these guides document, and the one to build integrations on.
• The app surface — everything under /v1/workspaces/{workspaceId}/…. It's the transport the Snoze app itself uses, listed in the reference for completeness. It works with keys too, but it's shaped for the app and changes with it.

Conventions

• Versioning — all routes are prefixed with /v1. Breaking changes ship as a new version.
• Envelope — success bodies wrap the payload as { "data": … }.
• Errors — non-2xx responses return { _tag, error, message, status } with a stable error code (e.g. unauthorized, not_found, conflict) — see Errors.
• Pagination — list endpoints return an opaque cursor (plus hasMore where cheap to compute); pass it back as ?cursor= to fetch the next page, and treat null as the end.
• Idempotency — platform mutations accept an Idempotency-Key header for safe retries; replays return the originally stored response.

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

Reference

The generated API reference covers every endpoint with an interactive playground and request samples — the platform groups (items, records, files) lead the list. The raw OpenAPI 3.1 document is at https://api.snoze.dev/openapi.json — point codegen or your agent at it. Typed SDKs for TypeScript and Python are planned.