commands.notes

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.

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() handle throws PermissionError. The PermissionError at the facade is shipped and proven; the connect() capability-scoping 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. These are shipped, per-event — see the per-event readiness table.

Related

• Guide: Add notes and links
• commands.links
• Subscribe to events

_{Reference verified as of 2026-06-28.}