---
title: "Connect to the Amnesia API"
description: "Reach the Amnesia plugin API from a plugin or a script automation, and make your first call."
canonical: https://amnesia-docs.pages.dev/api/guides/connect-to-the-api/
source: "src/content/docs/api/guides/connect-to-the-api.md"
---

# 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](/api/reference/access/).

## 1. Get the API handle

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

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

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

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

```js
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](/api/reference/capabilities/) for the honest framing, and treat
[`connect()` scoping behavior](/api/reference/experimental-surfaces/#connect-capability-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](/api/reference/experimental-surfaces/#amnesiaready-handshake):

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

## Next steps

- [Add notes and links](/api/guides/add-notes-and-links/)
- [Subscribe to events](/api/guides/subscribe-to-events/)

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