Files

Files are content like everything else: upload once, get a fileId, then reference it from the sidebar tree, a page, or a record's file field. Uploads are a single multipart request.

Upload a file

POST /v1/files takes one multipart file field:

curl -X POST "https://api.snoze.dev/v1/files" \
  -H "Authorization: Bearer $SNOZE_API_KEY" \
  -F "file=@roadmap.pdf"

{
  "data": {
    "fileId": "77c0d9e4-…",
    "name": "roadmap.pdf",
    "mimeType": "application/pdf",
    "byteSize": 482113,
    "downloadUrl": "/v1/assets/77c0d9e4-…/…accessKey…"
  }
}

Uploads count against the workspace storage quota, and identical bytes are de-duplicated by checksum. The key needs the files:write scope.

Use the file

The fileId is the canonical, durable reference:

• Sidebar item — POST /v1/items with { "kind": "file", "title": "roadmap.pdf", "fileId": "77c0d9e4-…" }.
• Record field — set a file-kind field's value to the fileId (or an array of them) when writing records.

Download a file

GET /v1/files/{fileId} returns the descriptor with a downloadUrl — a capability URL that serves the bytes without further authentication:

curl "https://api.snoze.dev/v1/files/77c0d9e4-…" \
  -H "Authorization: Bearer $SNOZE_API_KEY"