---
title: "commands.links"
description: "Shipped links facade — create internal and external links between annotations and locations. Links are held in-memory and are not persisted."
canonical: https://amnesia-docs.pages.dev/api/reference/commands-links/
source: "src/content/docs/api/reference/commands-links.md"
---

# commands.links

:::tip[Shipped — public-stable]
`commands.links` is part of the first-release shipped surface: wired and proven.
:::

:::caution[Links are not persisted]
**Links are held in-memory in the facade and are NOT persisted; persistence is out of current
evidence.** Links you create with this facade exist for the lifetime of the session and are lost on
reload. Do not depend on links surviving a restart, and do not treat them as durable storage.
:::

The links facade creates and navigates links between annotations, locations, and external URLs. All
methods are **asynchronous** — always `await` them.

```js
const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api
const links = await api.commands.links.getLinks();
```

## Methods

| Method | Purpose | Capability |
| --- | --- | --- |
| `createLink(link)` | Create an internal link between annotations/locations; resolves to the created link. | `write-annotations` |
| `createExternalLink(link)` | Create an external (URL) link; resolves to the created link. | `write-annotations` |
| `getLinks()` | List links; resolves to the current in-memory link set. | `read-state` |
| `deleteLink(id)` | Delete a link by id. | `write-annotations` |
| `navigateLink(link)` | Follow/navigate a link. | `read-document` |

Method names are exact. Link payloads use the `AnnotationLink` / `ExternalLink` / `ReaderLink` types from
the API type definitions.

## Behavior notes

- **In-memory only (repeat).** As stated above, links are not persisted. `getLinks()` returns what was
  created this session.
- **Async-only.** Every method returns a `Promise`.
- **Capability-gated writes.** `createLink` / `createExternalLink` / `deleteLink` require
  `write-annotations`; `navigateLink` requires `read-document`; `getLinks` requires `read-state`. A gated
  call on an under-scoped [`connect()`](/api/reference/access/) handle throws
  [`PermissionError`](/api/reference/capabilities/#permissionerror). The `PermissionError` at the facade
  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.

## Events

Link mutations emit `link-*` events on the [events mechanism](/api/reference/events/). These are
**shipped, per-event** — see the [per-event readiness table](/api/reference/events/#per-event-readiness).

## Related

- Guide: [Add notes and links](/api/guides/add-notes-and-links/)
- [`commands.notes`](/api/reference/commands-notes/)

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