---
title: "Add notes and links"
description: "Create, read, and search notes, attach a note to a highlight, and link annotations together with the shipped notes and links facades."
canonical: https://amnesia-docs.pages.dev/api/guides/add-notes-and-links/
source: "src/content/docs/api/guides/add-notes-and-links.md"
---

# Add notes and links

This guide walks through creating annotations with the shipped
[`commands.notes`](/api/reference/commands-notes/) and
[`commands.links`](/api/reference/commands-links/) facades.

:::caution[Links are not persisted]
Links created with `commands.links` are **held in-memory and are NOT persisted** — they are lost on
reload. Notes do persist; links do not. Plan accordingly.
:::

## 1. Create and read notes

```js
const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api

// Create a note (requires write-annotations on a scoped handle):
const note = await api.commands.notes.create(/* note payload */);

// List and search:
const all = await api.commands.notes.getNotes();
const hits = await api.commands.notes.searchNotes('chapter 3');
```

## 2. Find the note attached to a highlight

```js
const note = await api.commands.notes.getNoteForHighlight(highlightId);
if (note) {
  // a note exists for this highlight
}
```

## 3. Link annotations and locations

```js
// Internal link between annotations/locations:
const link = await api.commands.links.createLink(/* link payload */);

// External (URL) link:
const ext = await api.commands.links.createExternalLink(/* { url, ... } */);

// Read back the in-memory link set:
const links = await api.commands.links.getLinks();

// Follow a link:
await api.commands.links.navigateLink(link);
```

Remember: `getLinks()` returns only what was created **this session**.

## 4. React to changes (optional)

Notes and links emit shipped `note-*` and `link-*` events. Subscribe and clean up with `Disposable`:

```js
const sub = api.events.on('note-created', (payload) => {
  // update your UI
});
this.register(() => sub.dispose());
```

See [Subscribe to events](/api/guides/subscribe-to-events/) for the full pattern.

## Capabilities

Writes (`create` / `update` / `delete`, `createLink` / `createExternalLink` / `deleteLink`) require
`write-annotations`; reads require `read-state`. On an under-scoped
[`connect()`](/api/reference/access/) handle, a gated call throws
[`PermissionError`](/api/reference/capabilities/#permissionerror). The facade-level `PermissionError` is
shipped and proven; the
[`connect()` capability-scoping](/api/reference/experimental-surfaces/#connect-capability-scoping-behavior)
that makes a handle under-scoped is itself experimental and untested.

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