| name | immich |
| description | This skill should be used when the user mentions Immich or asks to browse their photo library, search for photos, find pictures from a trip or date range, list albums, check server stats, or view storage usage. Triggers include: "find photos of", "show my albums", "search Immich", "how many photos do I have", "check my Immich server", or any question about a self-hosted photo library. |
Immich
Self-hosted photo and video management. Talk to it directly over the Immich REST API (served under /api).
How to call it
Prefer scripts/immich-api.sh for common read-only calls. It sources the
generated Immich config or ~/.lab/.env, sends x-api-key on each request, and
exposes ping, version, about, statistics, me, albums, album,
asset, and search.
Read the base URL and API key from the generated plugin config first, falling
back to ~/.lab/.env during migration:
set -a
source "${XDG_CONFIG_HOME:-$HOME/.config}/lab-immich/config.env" 2>/dev/null || source ~/.lab/.env
set +a
: "${IMMICH_URL:?set IMMICH_URL in plugin settings, ~/.config/lab-immich/config.env, or ~/.lab/.env}"
Authentication is the x-api-key: <key> header on every request. Never echo the key.
IMMICH_URL and IMMICH_API_KEY are required. Use a direct backend URL for
scripted API probes when a public route is protected by proxy authentication.
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.
