Immich Crosslink

The Immich Crosslink protocol

Version 1.1

Status: version 1.1. Changes within version 1 only add (see Versioning). Proposals are welcome as issues and pull requests on GitHub.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be read as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

1 Purpose

Many apps work with an Immich server: galleries, file managers, editors, backup tools. When several are installed on one computer, a user looking at a photo in one of them should be able to say “show this in that app”. Immich Crosslink is the smallest agreement that makes this work between apps that know nothing about each other:

It does not define an API, a server feature or a way to sign in. Each app keeps its own account; a link only says which item, on which server.

2 Terms

3.1 Form

immich-crosslink://{Immich path}?[{path query}&]server={server address}[&user={user id}]

The Immich path starts with /, so the host is empty and every link starts immich-crosslink:///. For example:

immich-crosslink:///albums/0f8c…/photos/9a1e…?server=https%3A%2F%2Fphotos.example.com
immich-crosslink:///search?query=%7B%22city%22%3A%22Aarhus%22%2C%22country%22%3A%22Denmark%22%7D&server=https%3A%2F%2Fphotos.example.com

3.2 Immich paths

The paths are those of Immich’s web app, defined in web/src/lib/route.ts and web/src/routes/(user)/, which Immich’s mobile app also takes as deep links through my.immich.app. Version 1.0 defines these:

Item Kind Immich path
An asset asset /photos/<asset>
An asset in an album asset /albums/<album>/photos/<asset>
An asset in a person asset /people/<person>/photos/<asset>
An asset in Favorites asset /favorites/photos/<asset>
An asset in Archive asset /archive/photos/<asset>
An asset in a search (such as a place) asset /search/photos/<asset>?query=<search>
An album album /albums/<album>
A person person /people/<person>
A city place /search?query=<search>, <search> = {"city":"<city>","country":"<country>"}
A country place /search?query=<search>, <search> = {"country":"<country>"}
The timeline, albums, people, places, favorites, archive page /photos, /albums, /people, /places, /favorites, /archive

Because the paths are Immich’s own, a crosslink also gives the item’s web address: the server address followed by the Immich path. Senders MAY offer that as Open in Immich.

4 Announcing

A participant announces itself in the metadata it installs, which the operating system indexes and other apps read without starting it. The announcement is the only way to take part: apps never ask each other at run time.

Platform Where Announcement
macOS The app’s Info.plist the key ImmichCrosslink, a dictionary: Version (string, 0.2) and Shows (array of kinds)
Linux The app’s desktop entry X-Immich-Crosslink-Version=0.2 and X-Immich-Crosslink-Shows= (kinds, each followed by ;)
<key>ImmichCrosslink</key>
<dict>
    <key>Version</key>
    <string>0.2</string>
    <key>Shows</key>
    <array>
        <string>asset</string>
        <string>album</string>
        <string>person</string>
    </array>
</dict>
X-Immich-Crosslink-Version=0.2
X-Immich-Crosslink-Shows=asset;album;person;

Apps do not announce themselves at run time (over D-Bus, notifications or sockets): those see only the apps that happen to be running, race at login and go stale after a crash, and on the Mac a sandboxed app’s messages to other apps are restricted. Asking an app what it can do by sending it a link would start every participant.

An announcement the app writes. An app MAY install or remove an announcement itself, not only with its package: a desktop entry it writes in the user’s applications folder ($XDG_DATA_HOME/applications) when a place it shows items in is switched on, or when the user lets it take part, and removes when that ends. It is an announcement like any other: on disk, found whether or not the app runs, and read only through the system’s lists. On macOS a bundle announces only with its Info.plist, which is part of its signature; a Flatpak app, which cannot write there, announces only with the entries it exports.

One app, several participants. An app that shows items in more than one place, such as a gallery and the library as a drive, MAY announce one participant per place, each its own desktop entry with its own id and name (for example “Verso Gallery” and “Verso Drive”), so the user chooses where an item shows. An entry that would show the app twice in the app grid is kept out of it (NoDisplay=true). Each is a participant of its own: it does not list itself, and lists the app’s other participants as it lists any other, which is how the app’s places reach each other. The app’s Immich Crosslink switch covers all of them; its settings MAY give each of its own participants a switch that adds or removes its announcement. On macOS, where an announcement is a bundle’s Info.plist, each participant is a bundle of its own; a Flatpak app exports one entry per participant, each named with its app id as the prefix.

5 Sending

A sender SHOULD offer Show in app for each other participant that announces the item’s kind: one menu item per app, by its name and icon. Where it cannot, because its menu’s items are fixed when it is installed (Finder’s File Provider actions) or because it cannot list the other apps (a Flatpak sandbox), it MAY offer one Show in Another App… instead:

A participant MAY present Show in some other way, as long as it meets the rules below. Where it uses a menu item, the item reads Show in app or Show in Another App…, translated, so a user meets the same words in every app.

6 Receiving

A receiver shows what a link names.

7 Finding participants

A participant registers the scheme immich-crosslink, which delivers links to it, and announces itself. A sender lists the apps registered for the scheme and keeps those with an announcement.

A participant is found when the sender can list it, read its announcement, and start it: its program is there. An app that is installed is found whether or not it was ever started, as the system’s own Open With and share menus list it; one that has no account yet says so when a link arrives (Receiving). Each platform has ways for an app to look present when it is not, and those read as not found:

Platform Registering Listing Reading the announcement Sending to one
macOS CFBundleURLTypes with the scheme immich-crosslink in Info.plist NSWorkspace.urlsForApplications(toOpen:) with an immich-crosslink: URL Bundle(url:).infoDictionary["ImmichCrosslink"] NSWorkspace.open(_:withApplicationAt:configuration:)
Linux (GNOME, KDE and others) MimeType=x-scheme-handler/immich-crosslink; in the desktop entry g_app_info_get_all_for_type("x-scheme-handler/immich-crosslink") (GIO), KApplicationTrader::queryByMimeType (KDE) g_desktop_app_info_get_string, KService::property g_app_info_launch_uris, KIO::ApplicationLauncherJob

8 Settings

Every participant’s settings show the protocol the same way, so a user meets one name in every app:

Participants that come and go. It works like pairing devices, except that pairing is automatic: an app that is found is listed, the switch is the user’s lasting choice, and an app that has gone is remembered until the user, or time, forgets it.

Turning the main switch off stops the app from offering Show in app and from acting on received links. Turning one participant off removes it from the app’s menus. No participant is set apart: a sender lists, offers and names every participant the same way, whoever made it. “Immich Crosslink” is a name and stays in English; “Learn more…” and the words around them are translated. Messages about a link a participant received speak of “a link from another app”, keeping the name for the protocol.

A participant MAY offer Copy Immich Link, which copies the item’s web address: it opens in any browser and in Immich’s own apps, and Open in Immich, which opens it in the default browser. One that offers them SHOULD let the user turn both off with one switch, Open in Immich and Copy Immich Link, apart from the Immich Crosslink switch. A participant MAY also offer a link of its own scheme, for opening the item in itself. Copying a crosslink is not recommended: pasted into a browser or a note, it opens with whichever participant the system picks.

10 Security and privacy

11 Versioning

12 Conformance

13 Relation to Immich

Immich Crosslink is an independent, unofficial project. It is not affiliated with, endorsed by, or sponsored by the Immich project or FUTO. “Immich” is used only to describe the server the apps work with, and remains the mark of its owner.

The protocol follows Immich’s own paths on purpose, so a crosslink, an Immich web address and an Immich mobile deep link name an item the same way. Should Immich define desktop deep links of its own, this protocol means to follow them.