---
title: "Access the API"
description: "The shipped access mechanism — the window.Amnesia container, the canonical plugin handle, and the connect() handle."
canonical: https://amnesia-docs.pages.dev/api/reference/access/
source: "src/content/docs/api/reference/access.md"
---

# Access the API

:::tip[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](/api/reference/experimental-surfaces/) concern.
:::

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

## Entry points

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

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

```ts
{
  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](/api/reference/experimental-surfaces/); `ui.*` is
[not yet available](/api/overview/#not-yet-available).

## `connect()` — a scoped, audited handle

```ts
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.

```js
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](/api/reference/capabilities/).
- 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](/api/reference/capabilities/#the-capability-set)).

## Related

- Guide: [Connect to the Amnesia API](/api/guides/connect-to-the-api/)
- [Capabilities and permissions](/api/reference/capabilities/)
- [Experimental surfaces](/api/reference/experimental-surfaces/) (the `version` field, the `'amnesia:ready'` handshake, `connect()` scoping)

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