Access the API

Shipped — public-stable

The access mechanism is part of the first-release shipped surface: the assembled API object and the connect() handle are wired and proven. The connect() capability-scoping behavior is a separate, experimental concern.

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

Entry points

// 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;

Handle	Audience	Returns
app.plugins.plugins['amnesia'].api	Plugins (TypeScript, imported types)	The canonical, typed API root.
window.Amnesia	Script automation that only has app/this in scope	A convenience alias to the same admin-scoped root.

Both handles return the same object. Prefer the canonical plugin handle in real plugins; use the global in script contexts. The global is intentionally minimal — keep your own globals off window.

The API root shape

The root object has this shape:

{
  version,   // string — the API contract version (experimental; see below)
  state,     // read-only reactive stores (experimental)
  commands,  // async method facades — notes / links / mupdf are shipped
  events,    // typed event subscription mechanism (shipped)
  hooks,     // vetoable middleware (experimental)
  ui,        // UI extension registries (not yet available)
  connect,   // capability-scoped handle factory
}

Only commands.notes, commands.links, commands.mupdf, the events mechanism, and the capability model are shipped. version, state.*, and hooks are experimental; ui.* is not yet available.

connect() — a scoped, audited handle

connect(pluginId: string, requestedCapabilities: Capability[]): Promise<AmnesiaAPI>

connect() returns a scoped instance of the API and records the connection in a best-effort, in-memory audit log.

const scoped = await api.connect('my-plugin', ['read-state', 'write-annotations']);
const notes = await scoped.commands.notes.getNotes();

• The handle itself is shipped — calling connect() works and returns a usable API object.
• The capability-scoping behavior is experimental. Scoping is opt-in self-restriction, not a default-applied control: the documented global handle is admin-scoped and ungated, and a consumer can ignore connect() entirely. Do not treat connect() as a security boundary — see Capabilities and permissions.
• The audit log records only consumers who voluntarily call connect(); it is in-memory and cleared on unload.

requestedCapabilities accepts only members of the live capability set (see Capabilities).

Related

• Guide: Connect to the Amnesia API
• Capabilities and permissions
• Experimental surfaces (the version field, the 'amnesia:ready' handshake, connect() scoping)

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