Skip to content
Amnesia Docs

commands.links

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

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

Methods

Section titled “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

Section titled “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() handle throws PermissionError. The PermissionError at the facade is shipped and proven; the connect() capability-scoping that makes a handle under-scoped is itself experimental and untested.

Events

Section titled “Events”

Link mutations emit link-* events on the events mechanism. These are shipped, per-event — see the per-event readiness table.

Section titled “Related”

Reference verified as of 2026-06-28.