IMMICH_API_KEY is required. If IMMICH_URL is unset, this homelab's direct backend is http://100.120.242.29:2283; the public routes are https://immich.tootie.tv / https://photos.tootie.tv.

Common operations

Intent	Request
Health	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server/ping"` → `{"res":"pong"}`
Version	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server/version"`
Server about / info	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server/about"`
Server statistics	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server/statistics"`
Current user (me)	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/users/me"`
Search assets (metadata)	`curl -sS -X POST -H "x-api-key: $IMMICH_API_KEY" -H 'Content-Type: application/json' "$IMMICH_URL/api/search/metadata" -d '{"query":"beach"}'`
Get one asset	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/assets/<id>"`
List albums	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums"`
Get album assets	`curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums/<albumId>"`

Full API reference: https://api.immich.app/ (OpenAPI). The /api/search/metadata body accepts the full Immich search filter (album, person, type, date ranges, etc.).

Configuration

IMMICH_URL and IMMICH_API_KEY are configured through plugin userConfig. The hook writes them to ${XDG_CONFIG_HOME:-~/.config}/lab-immich/config.env with mode 600; ~/.lab/.env is still accepted as a fallback. Verify connectivity:

curl -sS -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server/ping" -w '\nHTTP %{http_code}\n'

When NOT to use this skill

The user is asking about a different homelab service — load that service's skill instead.
The user wants to bulk-upload or sync photos — use the official immich CLI, not ad-hoc curl.

immich

Immich

How to call it