# Links and other apps

> Copying a link to a note, what a canto:// link holds, the x-callback-url actions Hookmark, Shortcuts and Raycast can call, and your own keys for any menu command.

Applies to Canto 1.0 beta 10 · Updated Nov 2, 2026 · https://lonelyduck.io/docs/canto/links

Every note, canvas and chat in Canto has its own link, such as `canto://note/3f2a…`. Paste it into a calendar event, a to-do in another app, Hookmark or another note, and a click on it brings you straight back to that note in Canto. Links are free on every plan.

A link holds nothing but an id: no text, no key, no permission. It opens only on a Mac that has your vault, so sharing a link shares nothing.

## Copy a link

With a note, canvas or chat in front:

- **Edit › Copy Link** (`⇧⌘C`) copies its link. In apps that take a rich link, such as Mail, Notes or a calendar, it pastes as the note's title, linked. In a plain text field, such as Terminal, it pastes as the address.
- **Edit › Copy Markdown Link** (`⌥⇧⌘C`) copies `[Title](canto://note/…)` for apps that write Markdown.

You'll find the same in more places:

- the note's **Share** menu: **Copy link** and **Copy Markdown link**,
- the menus in the sidebar, in Pinned and in **All notes**: **Copy link**,
- `⌘K`: **Copy link to this note** and **Copy Markdown link to this note** (or canvas, or chat),
- a canvas's ✨ menu, a chat's **⋯** and its menu in the sidebar: **Copy link**.

Canto says **Link copied**: "Opens this note in Canto on Macs with this vault."

Paste a note's link into another Canto note and it becomes a link to that note.

## What a link holds

A `canto://` link names one note, canvas or chat by its id:

| Link | Opens |
|---|---|
| `canto://note/<id>` | a note |
| `canto://canvas/<id>` | a canvas |
| `canto://chat/<id>` | a chat |
| `canto://settings/<page>` | a page of Settings |

The id never changes, so a link keeps working after you rename the note or move it to another folder. It works on every Mac that has your vault, your other Macs too when [iCloud sync](https://lonelyduck.io/docs/canto/sync) is on. A note in the Trash still opens.

A link doesn't open its note:

- after the note was deleted for good,
- in another vault (a Markdown export imported into another vault makes new notes with new ids),
- on another Mac before sync has brought the note there.

Canto then says **This link's note isn't here**: "It may be in another vault, deleted for good, or not on this Mac yet."

**A published page's link is a different thing.** Publishing puts a copy of the note on the web at an `https://` address that anyone who has it can read. A `canto://` link is a pointer into your own vault, useless to anyone else. A published note's **Share** menu has both: **Copy public link** and **Copy link**. See [Publishing a page](https://lonelyduck.io/docs/canto/publishing).

## Open a link

Click a `canto://` link anywhere on your Mac and Canto shows what it names, even with Canto's window closed or minimized: Canto opens the window and brings it to the front. If Canto isn't running, macOS starts it first.

## Links other apps can call

Apps that drive other apps, such as Hookmark, Shortcuts, Raycast and Alfred, can call Canto with an x-callback-url link:

`canto://x-callback-url/<action>?<parameters>`

Percent-encode the values. Canto reads `+` as a plus sign, so send a space as `%20`. For example, `canto://x-callback-url/open?title=Trip%20to%20Kyoto` opens the note called Trip to Kyoto.

| Action | Parameters | What it does | What comes back |
|---|---|---|---|
| `open` | `id`, or `title` | Opens the note, canvas or chat with that id, or the one note with that title. With several such notes, or none, ⌘K opens with the title so you can pick. | Nothing |
| `search` | `query` | Opens ⌘K's search with the words. | Nothing |
| `open-tag` | `name` (with or without `#`) | Opens the tag's page. | Nothing |
| `open-folder` | `id`, or `path` (such as `Projects/2026`) | Opens the folder in All notes. | Nothing |
| `get-current` | `x-success` (and `x-error`, `x-cancel`, `x-source`) | Asks for the title and link of the note, canvas or chat in front. Canto asks you first. | `title`, `url` and `markdown`, to `x-success` |
| `hook-get-address` | as `get-current` | The same as `get-current`, under the name Hookmark calls. | `title`, `url` and `markdown`, to `x-success` |
| `capture` | `text`, `title`, `url` (a web address) | Opens Quick capture filled in. Nothing is saved until you press Save. | Nothing |

For `get-current`, `url` is the `canto://note/<id>` link (or `canvas` or `chat`) and `markdown` is `[title](url)`.

**Capture.** `canto://x-callback-url/capture?title=Call%20Ana&text=Ask%20about%20the%20budget` opens [Quick capture](https://lonelyduck.io/docs/canto/capture#quick-capture) with the title and text filled in, below anything you had already typed there, and says it was filled in by a link from another app. Nothing is saved until you press `↩` in it. The link itself writes nothing.

### Callbacks

Only `get-current` and `hook-get-address` answer, because only they return something. `open`, `search`, `open-tag`, `open-folder` and `capture` never call back, not even for an app you always allow, so leave `x-success`, `x-error` and `x-cancel` off them. If a link to one of them names a note that isn't here, Canto says so on your screen only, so a link can't test which notes you have.

For `get-current` and `hook-get-address`:

- `x-success`: where Canto sends the answer, with `title`, `url` and `markdown` added. Without it there is nothing to answer.
- `x-error`: where Canto sends a refusal, with `errorCode` and `errorMessage` added.
- `x-cancel`: accepted and checked like the others. Canto doesn't call it in beta 10.
- `x-source`: your app's name. Canto doesn't rely on it: the app it answers is the one macOS opens the callback with.

**Callbacks never go to the web.** Canto refuses a callback that is a web address or could open one: `http`, `https`, `file`, `javascript`, `data`, `blob`, `about`, `mailto`, a browser's own scheme, or `canto` itself. A callback must be another app's own scheme (such as `hook://…`), on one line and at most 2,000 characters. `x-error` and `x-cancel` go only to the same app as `x-success`. A link with a callback Canto refuses is ignored, unanswered.

**Shortcuts' own answers only.** For Shortcuts, Canto opens only the answers its **Open X-Callback URL** action supplies (`shortcuts://x-callback-url/ic-success`, `ic-error` and `ic-cancel`). A custom X-Success URL that runs another shortcut or imports one is refused.

**Only apps you allowed hear back.** Canto answers only an app you allowed, always or for this one question. For any other app, or after **Don't allow**, nothing goes back, not even an error.

**Errors.** An allowed app's `x-error` gets one of these as `errorCode`, with a sentence saying the same as `errorMessage`, such as "No note, canvas or chat is open in Canto."

| `errorCode` | When |
|---|---|
| `no-open-note` | No note, canvas or chat is in front in Canto. |
| `turned-off` | **Let apps ask for the open note's link** is off in Settings. |
| `busy` | Canto is answering another request, or the app asked too often. Try again in a moment. |

**Limits.** A title is at most 300 characters, captured text 20,000 and a search 500. Canto asks about one `get-current` at a time and takes at most ten a minute from one app; a question nobody answers goes away after two minutes. While Canto opens its window, at most five links wait; more are dropped.

## When an app asks for the open note

The first time an app asks for the open note with `get-current` or `hook-get-address`, Canto asks you. The sheet says, for example, "Hookmark wants the link to “Trip to Kyoto”" and "It gets the note's title and its canto:// link. It doesn't get the note's text." Then:

- **Always allow** (`↩`) answers now and every time after, without asking. The app is listed in Settings.
- **Allow once** answers this time. Canto asks again next time.
- **Don't allow** (`Esc`) sends nothing back, not even an error.

The sheet names the app, with its icon, as macOS knows it: the app that will receive the answer, never the name the link gives itself. With Home or another place in front, nothing is asked and nothing is sent.

**Settings › Connections › Links from other apps** holds the rest:

- **Open notes from links**: always on. `canto://` links open notes, chats and canvases.
- **Let apps ask for the open note's link**: on unless you turn it off. Off, no app can ask Canto which note is open, and an allowed app gets `turned-off`.
- **Apps you allowed**: every app you always allow, each with **Remove**. After Remove, Canto asks that app again.
- **Link formats for other apps**: **Guide** opens this page.

## Nothing destructive happens from a link

A link can open things, search, and fill in Quick capture. It can't:

- delete, move, rename or change a note, a folder or a tag,
- change a setting or turn on sync,
- run a model or a web search,
- save anything without your press.

The only action that adds anything is `capture`, and it waits for you to save in Quick capture. Only a title and a link ever go back to another app, never a note's text, tags, folders or a list of notes. No action returns search results.

## Hookmark

[Hookmark](https://hookproductivity.com) links any item to a Canto note. It asks two things of an app, and Canto has both:

- **Get Address**: with Canto's integration, Hookmark asks Canto for the open note with `hook-get-address` (the same as `get-current`) and gets its title and link. The first time, Canto asks you; allow it once, or choose **Always allow** so it doesn't ask every time.
- **Open Item** needs nothing from Canto: Hookmark hands the `canto://` link to macOS, which opens the note in Canto.

**Edit › Copy Markdown Link** copies the same title and link by hand.

## Shortcuts, Raycast and Alfred

They need nothing from Canto beyond the links on this page:

- **Shortcuts**: an **Open URLs** action opens any `canto://` link, and the shortcut goes on by itself. To capture a shortcut's text, put it through **URL Encode**, then open `canto://x-callback-url/capture?text=` followed by the encoded text. To bring the open note's link into a shortcut, use **Open X-Callback URL** with `canto://x-callback-url/get-current`; Shortcuts adds its own answer addresses, and Canto asks you the first time.
- **Raycast**: a Quicklink with the link `canto://x-callback-url/search?query={Query}` searches Canto from Raycast.
- **Alfred**: a custom search, or a workflow's **Open URL**, with `canto://x-callback-url/search?query={query}`. Have Alfred encode spaces as `%20`, not `+`.

Only `get-current` needs an answer, so only it asks you anything.

## Keys for any menu command

**Settings › Keyboard** changes Canto's own shortcuts (see [Keyboard shortcuts](https://lonelyduck.io/docs/canto/shortcuts)), and it won't take keys a menu command already has: it tells you which, such as "⇧⌘G is Vault Graph." For any command in Canto's menu bar, macOS can add keys of your own. For example, `⌘G` for Vault Graph:

1. Open **System Settings › Keyboard** and click **Keyboard Shortcuts…**.
2. Choose **App Shortcuts**, then press **+**.
3. For **Application**, choose **Canto**. For **Menu title**, type `Vault Graph`, exactly as Canto's Go menu shows it. For **Keyboard shortcut**, press `⌘G`. Click **Done**.
4. If Canto was open, quit it and open it again.

`⇧⌘G` keeps working too. In Canto, **Settings › Keyboard › Menu commands › Keys for any menu command** has **Open Keyboard Settings…**, which opens that pane of System Settings.

A few things to know:

- It works only for commands in Canto's menu bar.
- Type the title exactly as the menu shows it. A title that ends in "…" needs three periods, such as `Quick Capture...`. For a command in a submenu, type the path with `->` between the names.
- A key Canto's window already uses, such as `⌘K`, `⌘J` or `⇧⌘H`, wins over an App Shortcut. Choose keys Canto doesn't use.

The same from Terminal, in one line (`@` is ⌘, `$` is ⇧, `~` is ⌥ and `^` is ⌃). Quit Canto and open it again afterwards.

```text
defaults write io.lonelyduck.canto NSUserKeyEquivalents -dict-add "Vault Graph" "@g"
```

## What leaves Canto

Nothing leaves your Mac through a link.

- A link you copy holds only an id. Where you paste it is up to you.
- When an app asks with `get-current` and you allow it, Canto hands that app, on this Mac, the title and the `canto://` link of what's in front. Never the note's text, tags or folder. What the app does with the title and link is up to that app.
- Without your answer on the sheet, or **Always allow** before, nothing goes to any app.

**Settings › Memory & privacy › What leaves this Mac** lists this as **Other apps (links)**, with the same switch as **Let apps ask for the open note's link**. See [What leaves this Mac](https://lonelyduck.io/docs/canto/privacy). For apps that read your notes themselves, see [Other apps (MCP)](https://lonelyduck.io/docs/canto/mcp).