Notes API

35 endpoints, all under /v1/notes/. The notes surface is the largest single domain in ScaiWave — notes carry todos, audio, wiki links, embed expansion, AI assist, and a graph view.

Core CRUD#

Method	Path	Purpose
`GET`	`/v1/notes`	List notes (paginated, filterable).
`POST`	`/v1/notes`	Create.
`GET`	`/v1/notes/{note_id}`	Read with full body, frontmatter, wiki resolutions.
`PUT`	`/v1/notes/{note_id}`	Update body / title / frontmatter.
`DELETE`	`/v1/notes/{note_id}`	Archive (soft-delete; restorable).

POST /v1/notes#

json
{
  "title": "Meeting notes 2026-05-17",
  "body": "# Agenda\n\n- Topic 1\n- [ ] Action item ^todo-abc12",
  "workspace_id": "ws-…",
  "frontmatter": {"category": "meeting", "tags": ["q3", "engineering"]}
}

GET /v1/notes — query parameters#

workspace_id — filter to one workspace.
q — full-text search (BM25).
status — published (default), draft, archived.
tag — repeat for AND-filter on tags.
category — exact match.
pinned_only=true.
limit, offset.

Views#

Method	Path	Purpose
`GET`	`/v1/notes/inbox`	Recent notes you haven't categorised yet.
`GET`	`/v1/notes/categories`	All categories used across your notes.
`GET`	`/v1/notes/tags`	All tags used.
`GET`	`/v1/notes/todos`	Cross-workspace todos (the Today view feed).
`GET`	`/v1/notes/graph`	Node + edge data for the graph view.
`POST`	`/v1/notes/query`	Run a `todos`-block YAML query (structured filter).

Wiki linking#

Method	Path	Purpose
`GET`	`/v1/notes/suggest`	Suggest a note for a wiki-link autocomplete (`q=...`).
`GET`	`/v1/notes/embed-expand`	Resolve `![[embed]]` references for a body.

AI assist#

Method	Path	Purpose
`POST`	`/v1/notes/{note_id}/ai-assist`	Apply an AI action to a note (rewrite, summarise, extract todos, suggest links).

Body:

json
{
  "action": "rewrite|summarise|extract_todos|suggest_links|auto_title|auto_tag|auto_category",
  "selection": "optional text selection to act on",
  "instruction": "free-text instruction for rewrite/summarise"
}

Returns the updated body / title / frontmatter, depending on the action. Idempotent for read-only actions; mutating actions emit a swp.note.updated event.

Aliases#

Method	Path	Purpose
`GET`	`/v1/notes/{id}/aliases`	List aliases for this note.
`POST`	`/v1/notes/{id}/aliases`	Add an alias (alternative wiki-link name).
`DELETE`	`/v1/notes/{id}/aliases/{alias_id}`	Remove.

Audio#

Method	Path	Purpose
`POST`	`/v1/notes/{id}/audio`	Upload an audio recording.
`GET`	`/v1/notes/{id}/audio`	List audio attached to a note.
`GET`	`/v1/notes/{id}/audio/{audio_id}/download`	Download the file.
`DELETE`	`/v1/notes/{id}/audio/{audio_id}`	Remove.

Uploaded audio is auto-transcribed (async). The transcript appears as a separate ephemeral message in the note's comment thread once ready, with a "Insert into note" button.

Method	Path	Purpose
`GET`	`/v1/notes/{id}/suggested-links`	AI-suggested wiki links not yet promoted.
`POST`	`/v1/notes/{id}/suggested-links/{link_id}/accept`	Promote to a real wiki link.
`POST`	`/v1/notes/{id}/suggested-links/{link_id}/reject`	Dismiss.

Permissions#

Notes inherit visibility from their workspace:

viewer — read.
editor — read + write + delete.
owner — all of the above + share.

Public notes (one in the personal workspace marked visibility=public) can be read without auth via a public URL — useful for sharing reference docs.

Errors#

SW_NOTE_NOT_FOUND
SW_NOTE_FORBIDDEN
SW_NOTE_CONFLICT — concurrent edit (CRDT path is preferred for collaboration; REST writes can conflict).
SW_NOTE_QUOTA_EXCEEDED — workspace note count limit reached.