immich

Immich

Self-hosted photo and video management. Talk to it directly over the Immich REST API (served under /api).

How to call it

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="${IMMICH_URL:-http://100.120.242.29:2283}"

Authentication is the x-api-key: <key> header on every request. Never echo the key.

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.