How do I install the Immich API skill?

Run npx skillmds@latest add modbender/immich-api in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Immich API safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: WARNING. Capability flags: executes scripts, makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Immich API?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Immich API free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Immich API?

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Immich API by modbender — Agent Skill

Name: Immich API
Rating: 4.5 (4 reviews)
Author: modbender

Immich API

Immich Photo Management API Bridge. Use for interacting with self-hosted Immich instances via REST API. Triggers when: (1) User wants to manage photos, albums, or assets in Immich, (2) Building automation around photo backups, (3) Searching or organizing media, (4) User management in Immich, (5) Upload/download photos via API, (6) Getting album or library information, (7) Working with Immich jobs/queues, (8) Any Immich-related photo tasks

modbender Updated Sep 9, 2026 12 repo stars

File contents

Immich API Bridge

Configuration

Option 1: Environment Variables

Windows (PowerShell):

$env:IMMICH_URL = "https://your-immich-instance.com"
$env:IMMICH_API_KEY = "your-api-key-here"

Linux/macOS (bash):

export IMMICH_URL="https://your-immich-instance.com"
export IMMICH_API_KEY="your-api-key-here"

Generate API Key in Immich: User Profile → API Keys → Create API Key

Option 2: CLI Arguments

python scripts/upload_photos.py --url "https://your-immich.com" --api-key "your-key" --folder ./photos
python scripts/download_album.py --url "https://your-immich.com" --api-key "your-key" --album-id "abc123" --output ./downloads

Quick Start

Authentication

# Test connection
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server-info/ping"

Base URL

{IMMICH_URL}/api

Common Operations

Albums

# List albums
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums"

# Create album
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
  -d '{"albumName":"My Album"}' "$IMMICH_URL/api/albums"

# Get album assets
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums/{albumId}"

Assets

# Get all assets (paginated)
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/assets?limit=100"

# Upload asset
curl -X POST -H "x-api-key: $IMMICH_API_KEY" \
  -F "file=@/path/to/photo.jpg" \
  "$IMMICH_URL/api/assets"

# Get thumbnail
curl -H "x-api-key: $IMMICH_API_KEY" \
  "$IMMICH_URL/api/assets/{assetId}/thumbnail?format=jpeg" -o thumb.jpg

# Get original file
curl -H "x-api-key: $IMMICH_API_KEY" \
  "$IMMICH_URL/api/assets/{assetId}/original" -o original.jpg

Users

# List users
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/users"

# Get current user
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/user/me"

Search

# Search assets
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"beach","take":10}' "$IMMICH_URL/api/search/assets"

Libraries

# List libraries
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/libraries"

# Scan library
curl -X POST -H "x-api-key: $IMMICH_API_KEY" \
  "$IMMICH_URL/api/libraries/{libraryId}/scan"

Jobs

# Get job statuses
curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/jobs"

# Trigger job (e.g., thumbnail generation)
curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \
  -d '{"jobName":"thumbnail-generation","force":true}' "$IMMICH_URL/api/jobs"

Script Usage

Use the bundled scripts in scripts/ for complex operations:

upload_photos.py - Bulk upload photos
download_album.py - Download entire album
sync_library.py - Sync external library

See references/api-endpoints.md for complete endpoint reference.

---name: immich-apidescription: Immich Photo Management API Bridge. Use for interacting with self-hosted Immich instances via REST API. Triggers when: (1) User wants to manage photos, albums, or assets in Immich, (2) Building automation around photo backups, (3) Searching or organizing media, (4) User management in Immich, (5) Upload/download photos via API, (6) Getting album or library information, (7) Working with Immich jobs/queues, (8) Any Immich-related photo tasks--- # Immich API Bridge ## Configuration ### Option 1: Environment Variables **Windows (PowerShell):** ```powershell $env:IMMICH_URL = "https://your-immich-instance.com" $env:IMMICH_API_KEY = "your-api-key-here" ``` **Linux/macOS (bash):** ```bash export IMMICH_URL="https://your-immich-instance.com" export IMMICH_API_KEY="your-api-key-here" ``` **Generate API Key in Immich:** User Profile → API Keys → Create API Key ### Option 2: CLI Arguments ```bash python scripts/upload_photos.py --url "https://your-immich.com" --api-key "your-key" --folder ./photos python scripts/download_album.py --url "https://your-immich.com" --api-key "your-key" --album-id "abc123" --output ./downloads ``` ## Quick Start ### Authentication ```bash # Test connection curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server-info/ping" ``` ### Base URL ``` {IMMICH_URL}/api ``` ## Common Operations ### Albums ```bash # List albums curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums" # Create album curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \ -d '{"albumName":"My Album"}' "$IMMICH_URL/api/albums" # Get album assets curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums/{albumId}" ``` ### Assets ```bash # Get all assets (paginated) curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/assets?limit=100" # Upload asset curl -X POST -H "x-api-key: $IMMICH_API_KEY" \ -F "file=@/path/to/photo.jpg" \ "$IMMICH_URL/api/assets" # Get thumbnail curl -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/assets/{assetId}/thumbnail?format=jpeg" -o thumb.jpg # Get original file curl -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/assets/{assetId}/original" -o original.jpg ``` ### Users ```bash # List users curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/users" # Get current user curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/user/me" ``` ### Search ```bash # Search assets curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \ -d '{"query":"beach","take":10}' "$IMMICH_URL/api/search/assets" ``` ### Libraries ```bash # List libraries curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/libraries" # Scan library curl -X POST -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/libraries/{libraryId}/scan" ``` ### Jobs ```bash # Get job statuses curl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/jobs" # Trigger job (e.g., thumbnail generation) curl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \ -d '{"jobName":"thumbnail-generation","force":true}' "$IMMICH_URL/api/jobs" ``` ## Script Usage Use the bundled scripts in `scripts/` for complex operations: - `upload_photos.py` - Bulk upload photos - `download_album.py` - Download entire album - `sync_library.py` - Sync external library See `references/api-endpoints.md` for complete endpoint reference.

Frequently asked questions