---
audience: developer
summary: 'Full notes surface: CRUD, AI assist, todos, audio, aliases, graph, embed
  expansion, suggested links.'
title: Notes API
path: reference/api/notes
status: published
---

# 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.

## Suggested links

| 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.