---
title: "Amnesia API overview"
description: "How to reach the Amnesia plugin API, what ships in the first release, the stability labels you will see, and the honest framing of the capability model."
canonical: https://amnesia-docs.pages.dev/api/overview/
source: "src/content/docs/api/overview.md"
---

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

```js
// 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](/api/reference/access/) 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](#stability-labels):

| Surface | What it does |
| --- | --- |
| [`commands.notes`](/api/reference/commands-notes/) | Create, read, update, delete, search, and export notes. |
| [`commands.links`](/api/reference/commands-links/) | Create internal/external links between annotations and locations. |
| [`commands.mupdf`](/api/reference/commands-mupdf/) | Extract text, snap/copy selections, and annotate PDF documents. |
| [`events`](/api/reference/events/) | Subscribe to typed events with `on` / `off` / `once` (delivery mechanism). |
| [Capability model](/api/reference/capabilities/) | Declare intent with `expandCapabilities` / `connect()`; `PermissionError`. |
| [Access mechanism](/api/reference/access/) | 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](/api/reference/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](#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](/api/reference/events/#per-event-readiness).

## 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](/api/reference/capabilities/) 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 — present as existing systems, but still integration/hardening
  gated and not yet part of the stable live capability set.
- **Reader navigation surface** (`state.reader`, `commands.reader`) — scaffolded; navigation calls throw
  at runtime today while the reader bridge registration path remains under hardening.
- **UI extension registries** (`ui.toolbar`, `ui.sidebar`, `ui.contextMenu`) — accept registrations, but
  nothing renders stably yet.
- **Annotations V2** and a **typed OPDS facade** — present in scaffolded form and awaiting hardening before
  production use.
- **Reader, content, navigation, and collection events** — still work-in-progress through integration/hardening
  and are not yet safe for production (see the
  [per-event table](/api/reference/events/#per-event-readiness)).

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](/api/guides/connect-to-the-api/) — entry points and first call.
- [Add notes and links](/api/guides/add-notes-and-links/) — task-oriented annotation walkthrough.
- [Extract and annotate PDFs with MuPDF](/api/guides/render-with-mupdf/) — document primitives.
- [Subscribe to events](/api/guides/subscribe-to-events/) — typed events and clean teardown.

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