Amnesia API overview

The Amnesia plugin exposes a programmatic API so other Obsidian plugins and script automations (Templater, QuickAdd, DataviewJS) can read and annotate what a reader is working with. This overview explains how to reach the API, what is part of the first-release shipped surface, and how to read the stability labels that travel with every page.

You need no internal project knowledge to use these pages. Reach the API through one of the documented handles below and call the shipped facades — that is the whole contract.

Reaching the API

There are two entry points to the same API object, plus an optional scoped handle:

// Plugin (TypeScript) — the canonical handle:
const api = this.app.plugins.plugins['amnesia']?.api;

// Script automation (Templater / QuickAdd / DataviewJS) — the convenience global:
const api = window.Amnesia;

// Optional: a capability-scoped, audited instance (opt-in self-restriction — see Capabilities):
const scoped = await api.connect('my-plugin', ['read-state']);

Both app.plugins.plugins['amnesia'].api and window.Amnesia return the same API root object. The shape of that root is { version, state, commands, events, hooks, ui, connect }. See Access the API for the full details and caveats.

What ships in the first release

These surfaces are shipped (public-stable) — they are wired into the live API, proven, and safe to depend on under the versioning policy:

Surface	What it does
commands.notes	Create, read, update, delete, search, and export notes.
commands.links	Create internal/external links between annotations and locations.
commands.mupdf	Extract text, snap/copy selections, and annotate PDF documents.
events	Subscribe to typed events with on / off / once (delivery mechanism).
Capability model	Declare intent with expandCapabilities / connect(); PermissionError.
Access mechanism	The window.Amnesia container and the connect() handle.

Everything else carries an explicit experimental label or is not yet available — see below.

Stability labels

Every reference page shows a label so you know how much to depend on it.

• Shipped (public-stable) — wired, proven, and safe to depend on. Breaking changes only happen on a major version bump, with a deprecation window.
• Experimental (public-experimental) — wired and runtime-backed, but not yet proven by a test of that surface. It may change or break without a major version bump and carries no compatibility promise. See Experimental surfaces.
• Not yet available — specified or scaffolded, but not reachable through the live API today. It is documented nowhere as callable. See Not yet available.

The .events delivery mechanism is shipped, but each individual event is labeled separately by the facade that emits it — see the per-event readiness table.

Capabilities are intent, not a sandbox

The capability model lets a consumer declare what it intends to use and records that declaration in a best-effort, in-memory audit log. It is useful for intent, auditing, and preventing honest mistakes — but it is not a security boundary, sandbox, or isolation guarantee. Obsidian provides no sandbox, and the documented global handle is admin-scoped and ungated. Read Capabilities and permissions before relying on any of this framing.

Performance and platform

• All commands.* methods are asynchronous and must be awaited, so the engine can throttle or move work off the main thread without changing a signature.
• commands.mupdf is the highest performance-risk surface. It is async, capability-gated, and never hands you the shared rendering bridge object — only the facade methods.
• The reader path depends on native rendering; treat any document-rendering call as desktop-first and probe availability before use.

Not yet available

These areas are specified or scaffolded but not reachable through the live API today. They are excluded until wired — do not call them in production, and treat their presence in type definitions as not an availability promise:

• Collections, Export, and Modes APIs — not assembled into the live API; their capability tokens are not part of the live capability set.
• Reader navigation surface (state.reader, commands.reader) — scaffolded; navigation calls throw at runtime because the reader bridge is not registered.
• UI extension registries (ui.toolbar, ui.sidebar, ui.contextMenu) — accept registrations, but nothing renders them yet.
• Annotations V2 and a typed OPDS facade — not assembled / not built.
• Reader, content, navigation, and collection events — do not fire today (see the per-event table).

When one of these is wired and proven, it will gain its own reference page and a label.

Where to go next

• Connect to the Amnesia API — entry points and first call.
• Add notes and links — task-oriented annotation walkthrough.
• Extract and annotate PDFs with MuPDF — document primitives.
• Subscribe to events — typed events and clean teardown.

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