Requests and errors

The rules every endpoint follows: JSON in and out, the same paging, the same errors.

Requests

• Send bodies as JSON with Content-Type: application/json, up to 1 MB.
• Unknown fields are refused with 400, so a typo never fails silently.
• Ids are 21 character strings. Times are UTC, like 2026-11-12T16:40:00Z. Goal and phase dates are days, like 2026-12-31.

Paging

Lists return one page at a time. limit sets the page size (20 by default, 100 at most) and offset skips ahead. Keep going until nextOffset is null.

# First page
curl "https://beta.api.denotes.space/v1/notes?limit=50" -H "Authorization: Bearer dn_live_YOUR_KEY"

# Next page: pass the nextOffset you got back
curl "https://beta.api.denotes.space/v1/notes?limit=50&offset=50" -H "Authorization: Bearer dn_live_YOUR_KEY"

{
  "data": [ ... ],
  "pagination": {
    "limit": 50,
    "offset": 50,
    "total": 120,
    "nextOffset": 100
  }
}

Search pages are smaller: 10 by default, 50 at most.

Filtering by place

Lists of folders, files, notes and goal items can be narrowed to one place with parentId, folderId, fileId or phaseId:

• An id gives only what is inside that place.
• root gives only what is at the top level, or not in any file or phase.
• Leaving the filter out gives everything.

Updating

PATCH changes only the fields you send. To take a note out of its file, or off a goal, send that field as null.

curl -X PATCH https://beta.api.denotes.space/v1/notes/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer dn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true, "fileId": null}'

Notes and Google Drive

Note bodies are kept in your Google Drive, not on our servers. Creating a note, or changing its title, tags or body, writes to Drive, so Drive has to be connected in the app. A note kept only on one device shows contentAvailable: false and its body cannot be read or changed here.

Errors

Errors share one shape. Use code in your code and show message to people. Quote requestId if you contact us.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Note not found"
  },
  "requestId": "6f1c2a9e4b7d"
}

Rate limits

Each key can make 120 requests a minute, counted across the REST API and the MCP server together. Past that you get 429 with a Retry-After header saying how many seconds to wait.