---
title: "commands.notes"
description: "Shipped notes facade — create, read, update, delete, search, and export notes, including the note attached to a highlight."
canonical: https://amnesia-docs.pages.dev/api/reference/commands-notes/
source: "src/content/docs/api/reference/commands-notes.md"
---

# commands.notes

:::tip[Shipped — public-stable]
`commands.notes` is part of the first-release shipped surface: wired and proven.
:::

The notes facade manages notes, including the note attached to a highlight. All methods are
**asynchronous** — always `await` them.

```js
const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api
const notes = await api.commands.notes.getNotes();
```

## Methods

| Method | Purpose | Capability |
| --- | --- | --- |
| `create(note)` | Create a note; resolves to the created `Note`. | `write-annotations` |
| `update(note)` | Update an existing note; resolves to the updated `Note`. | `write-annotations` |
| `delete(id)` | Delete a note by id. | `write-annotations` |
| `getNotes()` | List notes; resolves to `Note[]`. | `read-state` |
| `getNote(id)` | Fetch a single note by id, or `null` if absent. | `read-state` |
| `getNoteForHighlight(highlightId)` | Get the note attached to a highlight, or `null`. | `read-state` |
| `searchNotes(query)` | Text-search notes; resolves to `Note[]`. | `read-state` |
| `exportNotes(options)` | Export notes (for example to Markdown); resolves to the exported payload. | `read-state` |

Method names are exact. Parameter and return payloads use the `Note` and related annotation types from
the API type definitions; consult those types for field-level detail.

## Behavior notes

- **Async-only.** Every method returns a `Promise`. The async boundary is part of the contract so the
  engine can batch or offload work without a breaking signature change.
- **Capability-gated writes.** `create` / `update` / `delete` require `write-annotations`; reads require
  `read-state`. A gated call on an under-scoped [`connect()`](/api/reference/access/) handle throws
  [`PermissionError`](/api/reference/capabilities/#permissionerror). The `PermissionError` at the facade
  is shipped and proven; the
  [`connect()` capability-scoping](/api/reference/experimental-surfaces/#connect-capability-scoping-behavior)
  that makes a handle under-scoped is itself experimental and untested.
- **Note ↔ highlight link.** `getNoteForHighlight` resolves the note bound to a given highlight id, which
  is the typical bridge between a reader highlight and its written note.

## Events

Notes mutations emit `note-*` events (for example `note-created`) on the
[events mechanism](/api/reference/events/). These are **shipped, per-event** — see the
[per-event readiness table](/api/reference/events/#per-event-readiness).

## Related

- Guide: [Add notes and links](/api/guides/add-notes-and-links/)
- [`commands.links`](/api/reference/commands-links/)
- [Subscribe to events](/api/guides/subscribe-to-events/)

<sub>Reference verified as of 2026-06-28.</sub>