How do I install the Immich API skill?

Run npx skillmds@latest add dvcrn/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?

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

Immich API by dvcrn — Agent Skill

Name: Immich API
Rating: 4.2 (5 reviews)
Author: dvcrn

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

dvcrn Updated Sep 8, 2026 32 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):**```bashexport 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```bashpython scripts/upload_photos.py --url "https://your-immich.com" --api-key "your-key" --folder ./photospython scripts/download_album.py --url "https://your-immich.com" --api-key "your-key" --album-id "abc123" --output ./downloads```## Quick Start### Authentication```bash# Test connectioncurl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/server-info/ping"```### Base URL```{IMMICH_URL}/api```## Common Operations### Albums```bash# List albumscurl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/albums"# Create albumcurl -X POST -H "x-api-key: $IMMICH_API_KEY" -H "Content-Type: application/json" \ -d '{"albumName":"My Album"}' "$IMMICH_URL/api/albums"# Get album assetscurl -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 assetcurl -X POST -H "x-api-key: $IMMICH_API_KEY" \ -F "file=@/path/to/photo.jpg" \ "$IMMICH_URL/api/assets"# Get thumbnailcurl -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/assets/{assetId}/thumbnail?format=jpeg" -o thumb.jpg# Get original filecurl -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/assets/{assetId}/original" -o original.jpg```### Users```bash# List userscurl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/users"# Get current usercurl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/user/me"```### Search```bash# Search assetscurl -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 librariescurl -H "x-api-key: $IMMICH_API_KEY" "$IMMICH_URL/api/libraries"# Scan librarycurl -X POST -H "x-api-key: $IMMICH_API_KEY" \ "$IMMICH_URL/api/libraries/{libraryId}/scan"```### Jobs```bash# Get job statusescurl -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 UsageUse 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 librarySee `references/api-endpoints.md` for complete endpoint reference.

Frequently asked questions