Notes API

The Notes API is available under /apis/v1/notes and requires a Ration bearer token. Notes are tenant-scoped and can be visible through ownership or sharing.

Authorization: Bearer <ration_access_token>
Content-Type: application/json

Concurrency: required for edits

Notes use optimistic concurrency. A note response includes revision and an ETag response header. Send the revision you read on every update or soft delete using either:

If-Match: "note:<note-id>:r<revision>"

or a JSON base_revision field.

When another client has changed the note first, Ration returns 409 with the current title/content and revision. Reload or merge that version, then retry with its revision. Do not overwrite a conflict blindly.

Note model and CRUD

A note response is { "note": { ... } }. Important fields include id, title, content, revision, folder_id, labels, links, invited, role, created_at, updated_at, and soft-delete metadata where applicable.

Method	Path	Request / response
GET	/apis/v1/notes	{ "notes": [...], "next": "…" }; query parameters control listing and pagination.
POST	/apis/v1/notes	Create a note; returns 201 { "note": Note } plus ETag.
GET	/apis/v1/notes/:id	Returns { "note": Note, "role": "…" } plus ETag.
PATCH or PUT	/apis/v1/notes/:id	Update with base_revision or If-Match; returns updated note and ETag.
DELETE	/apis/v1/notes/:id	Soft-delete with base_revision or If-Match; returns deleted note and ETag.

Example update:

{
  "base_revision": 4,
  "title": "Launch brief",
  "content": "<h1>Launch brief</h1><p>Updated content.</p>",
  "labels": ["launch"]
}

DELETE moves the note to trash; it is not permanent deletion.

Revisions, recovery, and export

Revision history

Method	Path	Response
GET	/:id/revisions	{ "revisions": [...] }, newest first; bodies are omitted.
GET	/:id/revisions/:revision	{ "revision": { ... } }, including that revision’s content.

Paths in this table are relative to /apis/v1/notes.

To restore an older revision, fetch it and issue an ordinary update with its desired content and the current note revision. This deliberately preserves concurrency protection.

Trash and permanent deletion

Method	Path	Response
POST	/:id/restore	Restores a soft-deleted note and returns { "note": Note } plus ETag. Optional device_id identifies the client.
DELETE	/:id/purge	Permanently removes a trashed note: { "note": Note, "purged": true }.

Export DOCX

GET /apis/v1/notes/:id/export.docx

Downloads an editable DOCX file. Conversion failures return 503 { "error": "docx_converter_unavailable" } or 502 { "error": "docx_conversion_failed" }.

Sharing and collaboration

Method	Path	Body	Description
POST	/:id/share	Optional role, expires_at.	Create a share link.
POST	/:id/share/regenerate	—	Replace the existing share link.
DELETE	/:id/share	—	Revoke the share link.
PUT	/:id/invited	{ "invited": [...] }	Set invited collaborators.

Each route returns { "note": Note }. role controls the recipient’s permitted access; Ration evaluates sharing and ownership server-side.

Create a linked task

POST /apis/v1/notes/:id/task

{
  "title": "Follow up on launch brief",
  "date": "2026-08-15",
  "priority": "high",
  "assignees": [{ "id": "user-id", "email": "sam@example.com" }]
}

title is required; if omitted, Ration uses the note title when available. The body also accepts task fields such as description, group, assignees, and references.

Response: 201 { "task": { ... }, "note": Note }. The task receives a reference to the note and Ration adds the back-link to the note atomically without consuming a note revision.

Synchronization

Change feed

GET /apis/v1/notes/changes?cursor=…

Use the returned cursor to request changes after the previous checkpoint. When a cursor expires, Ration returns:

{
  "error": "cursor_expired",
  "reset_required": true,
  "hint": "Perform index resync"
}

with status 410 Gone.

Index resynchronization

GET /apis/v1/notes/index?cursor=…

Use this endpoint after an expired cursor or to rebuild the client-side note index. Both feeds return Ration’s note records and cursor metadata.

Note folders

Note folders use /apis/v1/note_folders.

Method	Path	Operation
GET, POST	/note_folders	List or create a folder.
GET, PATCH, PUT, DELETE	/note_folders/:id	Read, update, or delete a folder.
GET	/note_folders/changes?cursor=…	Read folder changes.
GET	/note_folders/index?cursor=…	Rebuild the folder index.

Errors

Status	Meaning
401	Missing or invalid bearer authentication.
403	forbidden or workspace_forbidden.
404	Note, revision, or folder not found or not readable.
409	conflict (with the current note), or deleted when writing a trashed note.
410	Change cursor expired; perform an index resync.
422	Missing/invalid revision, invalid ID, no changes, or invalid data.