Connect to the Amnesia API

This guide shows the fastest way to reach the Amnesia plugin API and make a first call. For full detail, see Access the API.

1. Get the API handle

From a plugin (TypeScript), use the canonical handle:

const api = this.app.plugins.plugins['amnesia']?.api;
if (!api) {
  // Amnesia is not installed/enabled — degrade gracefully.
  return;
}

From a script automation (Templater, QuickAdd, DataviewJS), use the convenience global:

const api = window.Amnesia;

Both return the same API root object: { version, state, commands, events, hooks, ui, connect }.

2. Make a first call

Every commands.* method is asynchronous — await it:

const notes = await api.commands.notes.getNotes();
console.log(`There are ${notes.length} notes.`);

3. (Optional) Use a scoped handle

If you want to declare the capabilities your code intends to use, request a scoped handle:

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

The connect() handle is shipped, but its scoping is opt-in self-restriction, not a security boundary — the global handle is admin-scoped and ungated. See Capabilities and permissions for the honest framing, and treat connect() scoping behavior as experimental.

4. Wait for the API if you load early (optional)

If your code may run before Amnesia finishes loading, prefer polling the canonical handle. A one-shot 'amnesia:ready' workspace event also exists, but it is experimental:

this.app.workspace.on('amnesia:ready', ({ api }) => {
  // api is now available
});

Next steps

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