Skip to content

Immich Module API Explanation

The Immich module tracks photo library inventory and storage metrics from the Immich server.

API Execution Logic

The module locates the service definition matching the identifier immich. The API URL is resolved, and the API key is retrieved from the IMMICH_API_KEY environment variable.

Request Execution

A fetch request is dispatched to /api/server/statistics. The request headers include:

  • x-api-key: Populated with the Immich API key.
  • Accept: Set to application/json.
  • Zero-Trust Headers: If configured, Cloudflare Tunnel service token headers (CF-Access-Client-Id and CF-Access-Client-Secret) are injected automatically.

Data Parsing

Upon a successful response, the JSON payload is parsed. The module extracts:

  • photos: The total count of stored photos (primary metric).
  • videos: The total count of stored videos (secondary metric).
  • usage: The disk space utilization in bytes, which is formatted into a human-readable string (e.g. 245.8 GB).

Caching Strategy

Server statistics are cached in memory for 60 seconds (TTL) with a maximum stale window of 300 seconds. A timeout of 5 seconds is enforced per request.