immich-mcp
Provides tools for managing an Immich instance via the official Immich API, covering assets, albums, people, tags, search, memories, shared links, users, jobs, libraries, trash, stacks, faces, activities, duplicates, sessions, API keys, queues, backups, and admin configuration. Supports uploading and downloading files, with optional filtering and read-only mode.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@immich-mcp search my library for beach photos from last summer and add them to a new album"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
immich-mcp
A free and open-source Model Context Protocol (MCP) server for managing an Immich instance.
It exposes every operation of the official Immich API (276 tools, generated from the
OpenAPI specification) to any MCP client such as Claude Desktop, Claude Code, Cursor, Windsurf,
OpenCode or the MCP Inspector. The runtime is built on the official
@immich/sdk, so requests are typed and generated
from the same source as the Immich web client.
Note: This project is honestly vibecoded — built with heavy AI assistance for personal use. It is not affiliated with the Immich team. Read the Safety section and use it at your own risk (it can modify and delete data).
Features
Complete coverage — 276 tools across 41 API groups (Assets, Albums, People, Tags, Search, Memories, Shared links, Users, Jobs, Libraries, Trash, Stacks, Faces, Activities, Duplicates, Sessions, API keys, Queues, Backups, admin config, …).
Flattened request bodies — DTO fields are exposed as first-class tool arguments, so an LLM does not have to nest everything under
body.File uploads & downloads — multipart uploads accept a local file path (or a data URL); binary responses are written to the download directory and their path is returned.
Two transports —
stdio(local clients) and streamablehttp(remote/hosted), or both.Filtering & safety — expose only selected groups/tools, or run in read-only mode.
Resources & prompts — server/user/library metadata as MCP resources plus ready-made prompts.
Auto-generated & version-locked — a code generator turns the OpenAPI spec into the tool manifest and cross-checks the derived SDK parameter names against
@immich/sdkat build time.
Related MCP server: Immich MCP Server
Requirements
Node.js 18+ (Node 20+ recommended for
Filesupport during uploads)An Immich API key (Account Settings → API Keys) or an access token.
Installation
git clone <this-repo> immich-mcp
cd immich-mcp
npm install
npm run buildConfiguration
All configuration is via environment variables:
Variable | Required | Default | Description |
| yes | — | Immich API base URL, e.g. |
| one of | — | Immich API key. |
| one of | — | Bearer access token (used if no API key is set). |
| no |
| Extra JSON headers sent with every request. |
| no |
|
|
| no |
| HTTP bind host ( |
| no |
| HTTP port. |
| no |
| HTTP endpoint path. |
| no | — | If set, HTTP requests must send |
| no |
| Where downloaded/binary files are written. |
| no |
| Truncate large tool results. |
| no | — | Comma-separated group allow-list (e.g. |
| no | — | Comma-separated group deny-list. |
| no | — | Comma-separated tool allow-list. |
| no | — | Comma-separated tool deny-list. |
| no |
| Set to |
| no |
|
|
See .env.example for a copy-paste template.
Usage
stdio (Claude Desktop / Cursor / Windsurf)
Add an entry to your MCP client configuration, for example claude_desktop_config.json:
{
"mcpServers": {
"immich": {
"command": "node",
"args": ["/absolute/path/to/immich-mcp/dist/index.js"],
"env": {
"IMMICH_BASE_URL": "http://localhost:2283/api",
"IMMICH_API_KEY": "your-api-key"
}
}
}
}OpenCode
OpenCode (V2) configures MCP servers under mcp.servers. Secrets are best referenced with
{env:NAME} substitution so they never live in the config file.
A ready-to-copy file is in examples/opencode.jsonc.
Local server (stdio) — add to opencode.jsonc in your project, or to the global
~/.config/opencode/opencode.jsonc:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"immich": {
"type": "local",
"command": ["node", "/absolute/path/to/immich-mcp/dist/index.js"],
"environment": {
"IMMICH_BASE_URL": "http://localhost:2283/api",
"IMMICH_API_KEY": "{env:IMMICH_API_KEY}"
}
}
}
}
}Remote server (streamable HTTP) — first run this server with IMMICH_MCP_TRANSPORT=http
and an auth token (see Streamable HTTP), then point OpenCode at it:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"immich": {
"type": "remote",
"url": "http://127.0.0.1:3000/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:IMMICH_MCP_HTTP_AUTH_TOKEN}"
}
}
}
}
}Add it from the CLI instead of editing JSON:
# global (all projects) or omit --global for project-local
opencode mcp add immich --global -- node /absolute/path/to/immich-mcp/dist/index.js
opencode mcp add immich --url http://127.0.0.1:3000/mcp # remote
opencode mcp list # show connection stateThen open the MCP panel with /mcps to connect or inspect the server.
A few OpenCode-specific notes:
OpenCode names tools
<server>_<tool>. With the server namedimmich,immich_search_assetsis exposed asimmich_immich_search_assets; under the default Code Mode you call it astools.immich.immich_search_assets(...). Set"codemode": falseto expose the native tool names.Immich exposes 276 tools (~300 KiB of schemas), which consumes model context. Consider narrowing the surface, e.g. add to
environment:"IMMICH_MCP_TAGS": "Assets,Albums,People,Search,Memories"or"IMMICH_MCP_READONLY": "1".Use
"disabled": trueto keep the server configured without connecting it.Timeouts can be tuned under
mcp.timeout(e.g."execution"for long uploads/downloads).
Streamable HTTP
IMMICH_BASE_URL=http://localhost:2283/api \
IMMICH_API_KEY=your-api-key \
IMMICH_MCP_TRANSPORT=http \
IMMICH_MCP_HTTP_AUTH_TOKEN=secret \
node dist/index.js
# MCP endpoint: http://127.0.0.1:3000/mcp (health: /health)Point an HTTP-capable MCP client at http://127.0.0.1:3000/mcp.
Docker
docker compose up --builddocker-compose.yml runs the server in HTTP mode on port 3000 and reads IMMICH_BASE_URL
and IMMICH_API_KEY from the environment/.env.
Every docker build refreshes the Immich API definitions. The build downloads the current
OpenAPI specification and @immich/sdk typings, regenerates the MCP tool manifest, and only then
compiles — so a rebuilt image never uses stale tools. To also bump the Immich SDK (and therefore
the API version) at build time, pass IMMICH_SDK_VERSION:
# Update to the newest published Immich SDK/spec:
IMMICH_SDK_VERSION=latest docker compose build
# Or pin a specific version:
docker build --build-arg IMMICH_SDK_VERSION=3.3.0 -t immich-mcp .Docker caches layers, so the download only re-runs when an input changes. To force a fresh refresh
anyway (CI does this automatically via github.run_id), pass a changing IMMICH_REFRESH value:
IMMICH_REFRESH=$(date +%s) docker compose buildPublished images are multi-architecture (linux/amd64 and linux/arm64), so Apple Silicon
Macs pull a native arm64 image. Locally, docker build / docker compose build produce an image
for the host architecture automatically.
CLI helpers
node dist/index.js --help # usage
node dist/index.js --list-tools # every tool: name, method/path, summary
node dist/index.js --list-groups # tool counts per API groupTool naming
Tools are named immich_<snake_case operationId>, e.g.:
Tool | Operation |
|
|
|
|
|
|
|
|
|
|
|
|
| queue/job control |
Each tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients
can request confirmation for destructive actions.
API groups
4 Activities 8 Memories 6 Sessions
13 Albums 12 People 9 Shared links
7 API keys 4 Plugins 7 Stacks
4 Asset files 5 Queues 4 Sync
26 Assets 10 Search 4 System config
17 Authentication 14 Server 4 System metadata
1 Authentication (admin) 5 Database Backups 9 Tags
16 Users 11 Users (admin) 2 Timeline
... ... 3 Trash
8 WorkflowsRun --list-groups for the exact, current list.
Resources
URI | Contents |
| Version & build info |
| Server version |
| Disk usage per storage location |
| Aggregate statistics |
| Authenticated user profile |
| All albums |
| All people |
| All tags |
| Current memories |
Prompts
search_media— guided asset search.organize_album— create/update an album from search criteria.library_report— summarise library health.
Safety
This server can modify and delete data. Recommendations:
Create a dedicated Immich API key and restrict its permissions.
Use
IMMICH_MCP_EXCLUDE_TAGS/IMMICH_MCP_EXCLUDE_TOOLSto hide destructive tools (e.g.Maintenance (admin),Database Backups (admin)).Set
IMMICH_MCP_READONLY=1for a strictly read-only server.When using HTTP, always set
IMMICH_MCP_HTTP_AUTH_TOKENand terminate TLS in front of it.
Updating
Update immich-mcp itself
git pull
npm install
npm run buildThen restart the MCP client so it picks up the new code (see Reconnect clients).
Move to a newer Immich release
Tools are generated from a version-pinned OpenAPI specification, so upgrading is three steps:
# 1. point the SDK at the new Immich version
npm install @immich/sdk@latest
# 2. re-download the matching spec + SDK typings and regenerate the manifest
npm run spec:fetch
npm run generate
# 3. rebuild and test
npm run build
npm testWhat each step does:
npm run spec:fetchdownloadsspec/immich-openapi-specs.jsonandspec/sdk-client.d.tsfor the installed@immich/sdkversion (falling back to the range inpackage.json). Pass an explicit version if needed:node scripts/fetch-spec.mjs 3.3.0.npm run generaterewritessrc/generated/manifest.tsand prints a cross-check against the real SDK declarations. Warnings mean the spec and the SDK disagree — do not ignore them; they usually indicate a version mismatch between@immich/sdkand the downloaded spec.npm testrebuilds first (viapretest) and runs the integration tests against a mock Immich.
Commit package.json, package-lock.json, spec/ and src/generated/manifest.ts together so
the generated tools stay reproducible. Generation is deterministic (it records a hash of the spec,
not a timestamp), so CI can verify the committed manifest is current with
git diff --exit-code -- src/generated/manifest.ts.
If a release renames an operation, the tool name follows automatically
(immich_<snake_case operationId>). Diff the tool list before and after:
node dist/index.js --list-tools > /tmp/tools-before.txt
# update...
node dist/index.js --list-tools > /tmp/tools-after.txt
diff /tmp/tools-before.txt /tmp/tools-after.txtDocker
The Docker build always refreshes the Immich API definitions (see Docker), so a rebuild is enough to pick up the latest spec for the pinned SDK version. To also update the SDK/API version:
git pull
IMMICH_SDK_VERSION=latest docker compose build
docker compose up -dReconnect MCP clients after an update
The server binary changes on disk, so already-running clients keep the old code until restarted:
stdio clients (Claude Desktop, Cursor, Windsurf): restart the client, or toggle the server off/on, so it respawns
dist/index.js.OpenCode: reconnect the server from
/mcps(or restart OpenCode).opencode mcp listshows the connection state.Streamable HTTP: restart the process/container. The server runs stateless, so no session migration is needed.
Development
npm run spec:fetch # download the OpenAPI spec + SDK typings for the pinned SDK version
npm run generate # regenerate src/generated/manifest.ts
npm run build # generate + compile
npm run dev # run from source with tsx
npm test # build + run the integration tests against a mock Immich
npm run typecheck # type-check without emittingHow it works
scripts/fetch-spec.mjsdownloadsimmich-openapi-specs.jsonand the@immich/sdkfetch-client.d.tsfor the installed SDK version (falling back to the range inpackage.json) intospec/.scripts/generate.mjswalks the spec and emitssrc/generated/manifest.ts. For every operation it records the parameters, the request body, and the exact parameter names the SDK expects (including its$-prefixed reserved words and camelCased header names). It cross-checks these against the real SDK declarations and fails loudly on drift.At runtime
src/json-schema.tsconverts the OpenAPI/JSON schemas into Zod,src/tools.tsbuilds the MCP input schemas, andsrc/invoke.tsmaps validated arguments back onto the@immich/sdkfunction and formats the result (JSON, text, or a downloaded file).
Because generation is pinned to a specific API version, tool names and DTO shapes stay in sync
with the SDK. To move to a newer Immich release, bump @immich/sdk in package.json, run
npm run spec:fetch, then npm run build.
Build & CI
The repository ships GitHub Actions workflows:
.github/workflows/ci.yml— on pushes and pull requests: type-check, generate + build (Node 20 and 22), verify the committed manifest is current, run tests, produce an npm tarball artifact, and build the Docker image (amd64 + arm64) without pushing..github/workflows/docker.yml— on pushes tomainandv*tags, builds and publishes a multi-architecture image (linux/amd64andlinux/arm64, so Apple Silicon Macs get a native arm64 image) to the GitHub Container Registry (ghcr.io/<owner>/<repo>). Every build refreshes the Immich API definitions; a manual run accepts an optionalimmich_sdk_versioninput to publish an image built against a specific Immich SDK/API version.
The same checks locally:
npm ci
npm run typecheck
npm run build
git diff --exit-code -- src/generated/manifest.ts
npm testContributing
Contributions are welcome — this is a community, open-source project. See CONTRIBUTING.md for details.
Fork the repository and create a feature branch.
Make the change, keeping the docs in sync (see AGENTS.md).
Run the checks:
npm install npm run typecheck npm run build git diff --exit-code -- src/generated/manifest.ts npm testOpen a pull request describing the change.
Please do not commit API keys or other secrets. If you find a security issue, report it privately rather than opening a public issue.
License
immich-mcp is open source, released under the MIT License.
It is an independent community project and is not affiliated with or endorsed by the Immich team. "Immich" is the property of its respective owners.
Available Tools
276 toolsimmich_accept_cluster_group_requestAccept a cluster group requestB
Accept a cluster group request
Join the cluster group the request was created for.
Immich operation: POST /cluster-groups/requests/{id}/accept · tag: Cluster groups
Inputs: id (required).
immich_add_assets_to_albumAdd assets to an albumBIdempotent
Add assets to an album
Add multiple assets to a specific album by its ID.
Immich operation: PUT /albums/{id}/assets · tag: Albums
Inputs: id (required), ids (required).
immich_add_assets_to_albumsAdd assets to albumsBIdempotent
Add assets to albums
Send a list of asset IDs and album IDs to add each asset to each album.
Immich operation: PUT /albums/assets · tag: Albums
Inputs: albumIds (required), assetIds (required).
immich_add_memory_assetsAdd assets to a memoryBIdempotent
Add assets to a memory
Add a list of asset IDs to a specific memory.
Immich operation: PUT /memories/{id}/assets · tag: Memories
Inputs: id (required), ids (required).
immich_add_users_to_albumShare album with usersBIdempotent
Share album with users
Share an album with multiple users. Each user can be given a specific role in the album.
Immich operation: PUT /albums/{id}/users · tag: Albums
Inputs: id (required), albumUsers (required).
immich_bulk_tag_assetsTag assetsBIdempotent
Tag assets
Add multiple tags to multiple assets in a single request.
Immich operation: PUT /tags/assets · tag: Tags
Inputs: tagIds (required), assetIds (required).
immich_change_passwordChange passwordB
Change password
Change the password of the current user.
Immich operation: POST /auth/change-password · tag: Authentication
Inputs: password (required), newPassword (required), invalidateSessions.
immich_change_pin_codeChange pin codeCIdempotent
Change pin code
Change the pin code for the current user.
Immich operation: PUT /auth/pin-code · tag: Authentication
Inputs: newPinCode (required), pinCode, password.
immich_check_bulk_uploadCheck bulk uploadB
Check bulk upload
Determine which assets have already been uploaded to the server based on their SHA1 checksums.
Immich operation: POST /assets/bulk-upload-check · tag: Assets
Inputs: assets (required).
immich_cluster_group_regenerate_peopleRegenerate people of users in cluster groupB
Regenerate people of users in cluster group
Forcefully re-run facial recognition for all faces of users in this group.
Immich operation: POST /cluster-groups/{id}/regenerate-people · tag: Cluster groups
Inputs: id (required).
immich_copy_assetCopy assetBIdempotent
Copy asset
Copy asset information like albums, tags, etc. from one asset to another.
Immich operation: PUT /assets/copy · tag: Assets
Inputs: sourceId (required), targetId (required), stack, albums, +3 more.
immich_create_activityCreate an activityB
Create an activity
Create a like or a comment for an album, or an asset in an album.
Immich operation: POST /activities · tag: Activities
Inputs: type (required), albumId (required), assetId, comment.
immich_create_albumCreate an albumB
Create an album
Create a new album. The album can also be created with initial users and assets.
Immich operation: POST /albums · tag: Albums
Inputs: albumName (required), assetIds, albumUsers, description.
immich_create_api_keyCreate an API keyC
Create an API key
Creates a new API key. It will be limited to the permissions specified.
Immich operation: POST /api-keys · tag: API keys
Inputs: permissions (required), name.
immich_create_cluster_group_requestCreate a cluster group requestAIdempotent
Create a cluster group request
Ask another user to join the cluster group of the current user.
Immich operation: PUT /cluster-groups/{id}/requests · tag: Cluster groups
Inputs: id (required), userId (required).
immich_create_faceCreate a faceB
Create a face
Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face.
Immich operation: POST /faces · tag: Faces
Inputs: x (required), y (required), width (required), height (required), +4 more.
immich_create_jobCreate a manual jobB
Create a manual job
Run a specific job. Most jobs are queued automatically, but this endpoint allows for manual creation of a handful of jobs, including various cleanup tasks, as well as creating a new database backup.
Immich operation: POST /jobs · tag: Jobs
Inputs: name (required).
immich_create_libraryCreate a libraryB
Create a library
Create a new external library.
Immich operation: POST /libraries · tag: Libraries
Inputs: ownerId (required), name, importPaths, exclusionPatterns.
immich_create_memoryCreate a memoryC
Create a memory
Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.
Immich operation: POST /memories · tag: Memories
Inputs: data (required), type (required), memoryAt (required), hideAt, +4 more.
immich_create_notificationCreate a notificationB
Create a notification
Create a new notification for a specific user.
Immich operation: POST /admin/notifications · tag: Notifications (admin)
Inputs: title (required), userId (required), data, type, +3 more.
immich_create_partnerCreate a partnerC
Create a partner
Create a new partner to share assets with.
Immich operation: POST /partners · tag: Partners
Inputs: sharedWithId (required).
immich_create_partner_deprecatedCreate a partnerB
Create a partner
Create a new partner to share assets with.
Immich operation: POST /partners/{id} · tag: Partners
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required).
immich_create_personCreate a personC
Create a person
Create a new person that can have multiple faces assigned to them.
Immich operation: POST /people · tag: People
Inputs: name, color, isHidden, birthDate, +1 more.
immich_create_profile_imageCreate user profile imageB
Create user profile image
Upload and set a new profile image for the current user.
Immich operation: POST /users/profile-image · tag: Users
Inputs: file (required).
immich_create_sessionCreate a sessionB
Create a session
Create a session as a child to the current session. This endpoint is used for casting.
Immich operation: POST /sessions · tag: Sessions
Inputs: deviceOS, duration, deviceType.
immich_create_stackCreate a stackB
Create a stack
Create a new stack by providing a name and a list of asset IDs to include in the stack. If any of the provided asset IDs are primary assets of an existing stack, the existing stack will be merged into the newly created stack.
Immich operation: POST /stacks · tag: Stacks
Inputs: assetIds (required).
immich_create_tagCreate a tagB
Create a tag
Create a new tag by providing a name and optional color.
Immich operation: POST /tags · tag: Tags
Inputs: name (required), color, parentId.
immich_create_user_adminCreate a userC
Create a user
Create a new user.
Immich operation: POST /admin/users · tag: Users (admin)
Inputs: name (required), email (required), password (required), notify, +6 more.
immich_create_workflowCreate a workflowB
Create a workflow
Create a new workflow, the workflow can also be created with empty filters and actions.
Immich operation: POST /workflows · tag: Workflows
Inputs: trigger (required), name, steps, enabled, +2 more.
immich_delete_activityDelete an activityBDestructiveIdempotent
Delete an activity
Removes a like or comment from a given album or asset in an album.
Immich operation: DELETE /activities/{id} · tag: Activities
Inputs: id (required).
immich_delete_albumDelete an albumADestructiveIdempotent
Delete an album
Delete a specific album by its ID. Note the album is initially trashed and then immediately scheduled for deletion, but relies on a background job to complete the process.
Immich operation: DELETE /albums/{id} · tag: Albums
Inputs: id (required).
immich_delete_all_sessionsDelete all sessionsADestructiveIdempotent
Delete all sessions
Delete all sessions for the user. This will not delete the current session.
Immich operation: DELETE /sessions · tag: Sessions
Inputs: no named parameters.
immich_delete_api_keyDelete an API keyADestructiveIdempotent
Delete an API key
Deletes an API key identified by its ID. The current user must own this API key.
Immich operation: DELETE /api-keys/{id} · tag: API keys
Inputs: id (required).
immich_delete_asset_fileDelete an asset fileBDestructiveIdempotent
Delete an asset file
Delete a file and remove it from the database.
Immich operation: DELETE /asset-files/{id} · tag: Asset files
Inputs: id (required).
immich_delete_asset_metadataDelete asset metadata by keyBDestructiveIdempotent
Delete asset metadata by key
Delete a specific metadata key-value pair associated with the specified asset.
Immich operation: DELETE /assets/{id}/metadata/{key} · tag: Assets
Inputs: id (required), key (required).
immich_delete_assetsDelete assetsCDestructiveIdempotent
Delete assets
Deletes multiple assets at the same time.
Immich operation: DELETE /assets · tag: Assets
Inputs: ids (required), force.
immich_delete_bulk_asset_metadataDelete asset metadataADestructiveIdempotent
Delete asset metadata
Delete metadata key-value pairs for multiple assets.
Immich operation: DELETE /assets/metadata · tag: Assets
Inputs: items (required).
immich_delete_cluster_group_requestDecline a cluster group requestBDestructiveIdempotent
Decline a cluster group request
Delete a pending request to join a cluster group.
Immich operation: DELETE /cluster-groups/requests/{id} · tag: Cluster groups
Inputs: id (required).
immich_delete_database_backupDelete database backupBDestructiveIdempotent
Delete database backup
Delete a backup by its filename
Immich operation: DELETE /admin/database-backups · tag: Database Backups (admin)
Inputs: backups (required).
immich_delete_duplicateDismiss a duplicate groupADestructiveIdempotent
Dismiss a duplicate group
Dismiss a duplicate group by its ID, unlinking all assets in the group without deleting them.
Immich operation: DELETE /duplicates/{id} · tag: Duplicates
Inputs: id (required).
immich_delete_duplicatesDelete duplicatesBDestructiveIdempotent
Delete duplicates
Delete multiple duplicate assets specified by their IDs.
Immich operation: DELETE /duplicates · tag: Duplicates
Inputs: ids (required).
immich_delete_faceDelete a faceCDestructiveIdempotent
Delete a face
Delete a face identified by the id. Optionally can be force deleted.
Immich operation: DELETE /faces/{id} · tag: Faces
Inputs: id (required), force (required).
immich_delete_integrity_reportDelete integrity report itemADestructiveIdempotent
Delete integrity report item
Delete a given report item and perform corresponding deletion (e.g. trash asset, delete file)
Immich operation: DELETE /admin/integrity/report/{id} · tag: Maintenance (admin)
Inputs: id (required).
immich_delete_libraryDelete a libraryBDestructiveIdempotent
Delete a library
Delete an external library by its ID.
Immich operation: DELETE /libraries/{id} · tag: Libraries
Inputs: id (required).
immich_delete_memoryDelete a memoryADestructiveIdempotent
Delete a memory
Delete a specific memory by its ID.
Immich operation: DELETE /memories/{id} · tag: Memories
Inputs: id (required).
immich_delete_notificationDelete a notificationCDestructiveIdempotent
Delete a notification
Delete a specific notification.
Immich operation: DELETE /notifications/{id} · tag: Notifications
Inputs: id (required).
immich_delete_notificationsDelete notificationsCDestructiveIdempotent
Delete notifications
Delete a list of notifications at once.
Immich operation: DELETE /notifications · tag: Notifications
Inputs: ids (required).
immich_delete_peopleDelete peopleBDestructiveIdempotent
Delete people
Bulk delete a list of people at once.
Immich operation: DELETE /people · tag: People
Inputs: ids (required).
immich_delete_personDelete personCDestructiveIdempotent
Delete person
Delete an individual person.
Immich operation: DELETE /people/{id} · tag: People
Inputs: id (required).
immich_delete_profile_imageDelete user profile imageBDestructiveIdempotent
Delete user profile image
Delete the profile image of the current user.
Immich operation: DELETE /users/profile-image · tag: Users
Inputs: no named parameters.
immich_delete_server_licenseDelete server product keyADestructiveIdempotent
Delete server product key
Delete the currently set server product key.
Immich operation: DELETE /server/license · tag: Server
Inputs: no named parameters.
immich_delete_sessionDelete a sessionADestructiveIdempotent
Delete a session
Delete a specific session by id.
Immich operation: DELETE /sessions/{id} · tag: Sessions
Inputs: id (required).
immich_delete_stackDelete a stackBDestructiveIdempotent
Delete a stack
Delete a specific stack by its ID.
Immich operation: DELETE /stacks/{id} · tag: Stacks
Inputs: id (required).
immich_delete_stacksDelete stacksADestructiveIdempotent
Delete stacks
Delete multiple stacks by providing a list of stack IDs.
Immich operation: DELETE /stacks · tag: Stacks
Inputs: ids (required).
immich_delete_sync_ackDelete acknowledgementsCDestructiveIdempotent
Delete acknowledgements
Delete specific synchronization acknowledgments.
Immich operation: DELETE /sync/ack · tag: Sync
Inputs: types.
immich_delete_tagDelete a tagBDestructiveIdempotent
Delete a tag
Delete a specific tag by its ID.
Immich operation: DELETE /tags/{id} · tag: Tags
Inputs: id (required).
immich_delete_user_adminDelete a userCDestructiveIdempotent
Delete a user
Delete a user.
Immich operation: DELETE /admin/users/{id} · tag: Users (admin)
Inputs: id (required), force.
immich_delete_user_licenseDelete user product keyBDestructiveIdempotent
Delete user product key
Delete the registered product key for the current user.
Immich operation: DELETE /users/me/license · tag: Users
Inputs: no named parameters.
immich_delete_user_onboardingDelete user onboardingBDestructiveIdempotent
Delete user onboarding
Delete the onboarding status of the current user.
Immich operation: DELETE /users/me/onboarding · tag: Users
Inputs: no named parameters.
immich_delete_workflowDelete a workflowBDestructiveIdempotent
Delete a workflow
Delete a workflow by its ID.
Immich operation: DELETE /workflows/{id} · tag: Workflows
Inputs: id (required).
immich_detect_prior_installDetect existing installBRead-onlyIdempotent
Detect existing install
Collect integrity checks and other heuristics about local data.
Immich operation: GET /admin/maintenance/detect-install · tag: Maintenance (admin)
Inputs: no named parameters.
immich_download_archiveDownload asset archiveA
Download asset archive
Download a ZIP archive containing the specified assets. The assets must have been previously requested via the "getDownloadInfo" endpoint.
Immich operation: POST /download/archive · tag: Download
Inputs: assetIds (required), key, slug, edited, +1 more.
immich_download_assetDownload original assetBRead-onlyIdempotent
Download original asset
Downloads the original file of the specified asset.
Immich operation: GET /assets/{id}/original · tag: Assets
Inputs: id (required), key, slug, edited.
immich_download_asset_fileDownload an asset fileBRead-onlyIdempotent
Download an asset file
Serve the contents of a specific asset file.
Immich operation: GET /asset-files/{id}/download · tag: Asset files
Inputs: id (required).
immich_download_database_backupDownload database backupCRead-onlyIdempotent
Download database backup
Downloads the database backup file
Immich operation: GET /admin/database-backups/{filename} · tag: Database Backups (admin)
Inputs: filename (required).
immich_edit_assetApply edits to an existing assetBIdempotent
Apply edits to an existing asset
Apply a series of edit actions (crop, rotate, mirror) to the specified asset.
Immich operation: PUT /assets/{id}/edits · tag: Assets
Inputs: id (required), edits (required).
immich_empty_queueEmpty a queueBDestructiveIdempotent
Empty a queue
Removes all jobs from the specified queue.
Immich operation: DELETE /queues/{name}/jobs · tag: Queues
Inputs: name (required), failed.
immich_empty_trashEmpty trashB
Empty trash
Permanently delete all items in the trash.
Immich operation: POST /trash/empty · tag: Trash
Inputs: no named parameters.
immich_end_sessionEnd HLS streaming sessionBDestructiveIdempotent
End HLS streaming session
Releases server resources for the streaming session.
Immich operation: DELETE /assets/{id}/video/stream/{sessionId} · tag: Assets
Inputs: id (required), sessionId (required), key, slug.
immich_finish_o_authFinish OAuthA
Finish OAuth
Complete the OAuth authorization process by exchanging the authorization code for a session token.
Immich operation: POST /oauth/callback · tag: Authentication
Inputs: url (required), state, codeVerifier.
immich_get_about_infoGet server informationCRead-onlyIdempotent
Get server information
Retrieve a list of information about the server.
Immich operation: GET /server/about · tag: Server
Inputs: no named parameters.
immich_get_activitiesList all activitiesARead-onlyIdempotent
List all activities
Returns a list of activities for the selected asset or album. The activities are returned in sorted order, with the oldest activities appearing first.
Immich operation: GET /activities · tag: Activities
Inputs: albumId (required), type, level, userId, +1 more.
immich_get_activity_statisticsRetrieve activity statisticsARead-onlyIdempotent
Retrieve activity statistics
Returns the number of likes and comments for a given album or asset in an album.
Immich operation: GET /activities/statistics · tag: Activities
Inputs: albumId (required), assetId.
immich_get_admin_configGet the admin configurationCRead-onlyIdempotent
Get the admin configuration
Retrieve admin configuration.
Immich operation: GET /admin/config · tag: Config (admin)
Inputs: no named parameters.
immich_get_admin_config_defaultsGet the system configuration defaultsARead-onlyIdempotent
Get the system configuration defaults
Retrieve the default value of every system configuration property.
Immich operation: GET /admin/config/defaults · tag: Config (admin)
Inputs: no named parameters.
immich_get_admin_onboardingRetrieve admin onboardingBRead-onlyIdempotent
Retrieve admin onboarding
Retrieve the current admin onboarding status.
Immich operation: GET /system-metadata/admin-onboarding · tag: System metadata
Inputs: no named parameters.
immich_get_album_infoRetrieve an albumBRead-onlyIdempotent
Retrieve an album
Retrieve information about a specific album by its ID.
Immich operation: GET /albums/{id} · tag: Albums
Inputs: id (required), key, slug.
immich_get_album_map_markersRetrieve album map markersBRead-onlyIdempotent
Retrieve album map markers
Retrieve map marker information for a specific album by its ID.
Immich operation: GET /albums/{id}/map-markers · tag: Albums
Inputs: id (required), key, slug.
immich_get_album_statisticsRetrieve album statisticsBRead-onlyIdempotent
Retrieve album statistics
Returns statistics about the albums available to the authenticated user.
Immich operation: GET /albums/statistics · tag: Albums
Inputs: no named parameters.
immich_get_all_albumsList all albumsBRead-onlyIdempotent
List all albums
Retrieve a list of albums available to the authenticated user.
Immich operation: GET /albums · tag: Albums
Inputs: id, name, assetId, isOwned, +1 more.
immich_get_all_librariesRetrieve librariesBRead-onlyIdempotent
Retrieve libraries
Retrieve a list of external libraries.
Immich operation: GET /libraries · tag: Libraries
Inputs: no named parameters.
immich_get_all_peopleGet all peopleCRead-onlyIdempotent
Get all people
Retrieve a list of all people.
Immich operation: GET /people · tag: People
Inputs: page, size, withHidden, closestAssetId, +1 more.
immich_get_all_tagsRetrieve tagsARead-onlyIdempotent
Retrieve tags
Retrieve a list of all tags.
Immich operation: GET /tags · tag: Tags
Inputs: no named parameters.
immich_get_api_keyRetrieve an API keyARead-onlyIdempotent
Retrieve an API key
Retrieve an API key by its ID. The current user must own this API key.
Immich operation: GET /api-keys/{id} · tag: API keys
Inputs: id (required).
immich_get_api_keysList all API keysARead-onlyIdempotent
List all API keys
Retrieve all API keys of the current user.
Immich operation: GET /api-keys · tag: API keys
Inputs: no named parameters.
immich_get_apk_linksGet APK linksBRead-onlyIdempotent
Get APK links
Retrieve links to the APKs for the current server version.
Immich operation: GET /server/apk-links · tag: Server
Inputs: no named parameters.
immich_get_asset_duplicatesRetrieve duplicatesBRead-onlyIdempotent
Retrieve duplicates
Retrieve a list of duplicate assets available to the authenticated user.
Immich operation: GET /duplicates · tag: Duplicates
Inputs: no named parameters.
immich_get_asset_editsRetrieve edits for an existing assetBRead-onlyIdempotent
Retrieve edits for an existing asset
Retrieve a series of edit actions (crop, rotate, mirror) associated with the specified asset.
Immich operation: GET /assets/{id}/edits · tag: Assets
Inputs: id (required).
immich_get_asset_fileRetrieve an asset fileBRead-onlyIdempotent
Retrieve an asset file
Returns metadata about a specific asset file.
Immich operation: GET /asset-files/{id} · tag: Asset files
Inputs: id (required).
immich_get_asset_infoRetrieve an assetBRead-onlyIdempotent
Retrieve an asset
Retrieve detailed information about a specific asset.
Immich operation: GET /assets/{id} · tag: Assets
Inputs: id (required), key, slug.
immich_get_asset_metadataGet asset metadataARead-onlyIdempotent
Get asset metadata
Retrieve all metadata key-value pairs associated with the specified asset.
Immich operation: GET /assets/{id}/metadata · tag: Assets
Inputs: id (required).
immich_get_asset_metadata_by_keyRetrieve asset metadata by keyCRead-onlyIdempotent
Retrieve asset metadata by key
Retrieve the value of a specific metadata key associated with the specified asset.
Immich operation: GET /assets/{id}/metadata/{key} · tag: Assets
Inputs: id (required), key (required).
immich_get_asset_ocrRetrieve asset OCR dataBRead-onlyIdempotent
Retrieve asset OCR data
Retrieve all OCR (Optical Character Recognition) data associated with the specified asset.
Immich operation: GET /assets/{id}/ocr · tag: Assets
Inputs: id (required).
immich_get_assets_by_cityRetrieve assets by cityARead-onlyIdempotent
Retrieve assets by city
Retrieve a list of assets with each asset belonging to a different city. This endpoint is used on the places pages to show a single thumbnail for each city the user has assets in.
Immich operation: GET /search/cities · tag: Search
Inputs: no named parameters.
immich_get_assets_by_original_pathRetrieve assets by original pathCRead-onlyIdempotent
Retrieve assets by original path
Retrieve assets that are children of a specific folder.
Immich operation: GET /view/folder · tag: Views
Inputs: path (required).
immich_get_asset_statisticsGet asset statisticsBRead-onlyIdempotent
Get asset statistics
Retrieve various statistics about the assets owned by the authenticated user.
Immich operation: GET /assets/statistics · tag: Assets
Inputs: isTrashed, isFavorite, visibility.
immich_get_auth_statusRetrieve auth statusBRead-onlyIdempotent
Retrieve auth status
Get information about the current session, including whether the user has a password, and if the session can access locked assets.
Immich operation: GET /auth/status · tag: Authentication
Inputs: no named parameters.
immich_get_cluster_group_requestsRetrieve cluster group requestsARead-onlyIdempotent
Retrieve cluster group requests
Retrieve the pending requests for the current user to join a cluster group.
Immich operation: GET /cluster-groups/requests · tag: Cluster groups
Inputs: no named parameters.
immich_get_cluster_group_requests_for_groupRetrieve the requests sent by a cluster groupBRead-onlyIdempotent
Retrieve the requests sent by a cluster group
Retrieve the pending requests for other users to join the cluster group.
Immich operation: GET /cluster-groups/{id}/requests · tag: Cluster groups
Inputs: id (required).
immich_get_cluster_group_usersRetrieve the users of a cluster groupCRead-onlyIdempotent
Retrieve the users of a cluster group
Retrieve the users that are a member of the cluster group.
Immich operation: GET /cluster-groups/{id}/users · tag: Cluster groups
Inputs: id (required).
immich_get_configGet system configurationBRead-onlyIdempotent
Get system configuration
Retrieve the current system configuration.
Immich operation: GET /system-config · tag: System config
DEPRECATED — prefer the replacement operation if one exists.
Inputs: no named parameters.
immich_get_config_defaultsGet system configuration defaultsBRead-onlyIdempotent
Get system configuration defaults
Retrieve the default values for the system configuration.
Immich operation: GET /system-config/defaults · tag: System config
DEPRECATED — prefer the replacement operation if one exists.
Inputs: no named parameters.
immich_get_download_infoRetrieve download informationB
Retrieve download information
Retrieve information about how to request a download for the specified assets or album. The response includes groups of assets that can be downloaded together.
Immich operation: POST /download/info · tag: Download
Inputs: key, slug, userId, albumId, +2 more.
immich_get_explore_dataRetrieve explore dataBRead-onlyIdempotent
Retrieve explore data
Retrieve data for the explore section, such as popular people and places.
Immich operation: GET /search/explore · tag: Search
Inputs: no named parameters.
immich_get_facesRetrieve faces for assetBRead-onlyIdempotent
Retrieve faces for asset
Retrieve all faces belonging to an asset.
Immich operation: GET /faces · tag: Faces
Inputs: id (required).
immich_get_integrity_reportGet integrity report by typeBRead-onlyIdempotent
Get integrity report by type
Get all flagged items by integrity report type
Immich operation: GET /admin/integrity/report · tag: Maintenance (admin)
Inputs: type (required), limit, cursor.
immich_get_integrity_report_csvExport integrity report by type as CSVBRead-onlyIdempotent
Export integrity report by type as CSV
Get all integrity report entries for a given type as a CSV
Immich operation: GET /admin/integrity/report/{type}/csv · tag: Maintenance (admin)
Inputs: type (required).
immich_get_integrity_report_fileDownload flagged fileBRead-onlyIdempotent
Download flagged file
Download the untracked/broken file if one exists
Immich operation: GET /admin/integrity/report/{id}/file · tag: Maintenance (admin)
Inputs: id (required).
immich_get_integrity_report_summaryGet integrity report summaryBRead-onlyIdempotent
Get integrity report summary
Get a count of the items flagged in each integrity report
Immich operation: GET /admin/integrity/summary · tag: Maintenance (admin)
Inputs: no named parameters.
immich_get_libraryRetrieve a libraryBRead-onlyIdempotent
Retrieve a library
Retrieve an external library by its ID.
Immich operation: GET /libraries/{id} · tag: Libraries
Inputs: id (required).
immich_get_library_statisticsRetrieve library statisticsBRead-onlyIdempotent
Retrieve library statistics
Retrieve statistics for a specific external library, including number of videos, images, and storage usage.
Immich operation: GET /libraries/{id}/statistics · tag: Libraries
Inputs: id (required).
immich_get_main_playlistGet HLS main playlistBRead-onlyIdempotent
Get HLS main playlist
Returns an HLS main playlist with all available variants for the asset.
Immich operation: GET /assets/{id}/video/stream/main.m3u8 · tag: Assets
Inputs: id (required), key, slug.
immich_get_maintenance_statusGet maintenance mode statusARead-onlyIdempotent
Get maintenance mode status
Fetch information about the currently running maintenance action.
Immich operation: GET /admin/maintenance/status · tag: Maintenance (admin)
Inputs: no named parameters.
immich_get_map_markersRetrieve map markersBRead-onlyIdempotent
Retrieve map markers
Retrieve a list of latitude and longitude coordinates for every asset with location data.
Immich operation: GET /map/markers · tag: Map
Inputs: isArchived, isFavorite, withPartners, fileCreatedAfter, +2 more.
immich_get_media_playlistGet HLS media playlistBRead-onlyIdempotent
Get HLS media playlist
Returns an HLS media playlist for one variant of the streaming session.
Immich operation: GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8 · tag: Assets
Inputs: id (required), sessionId (required), variantIndex (required), key, +2 more.
immich_get_memoryRetrieve a memoryARead-onlyIdempotent
Retrieve a memory
Retrieve a specific memory by its ID.
Immich operation: GET /memories/{id} · tag: Memories
Inputs: id (required).
immich_get_my_api_keyRetrieve the current API keyBRead-onlyIdempotent
Retrieve the current API key
Retrieve the API key that is used to access this endpoint.
Immich operation: GET /api-keys/me · tag: API keys
Inputs: no named parameters.
immich_get_my_calendar_heatmapRetrieve calendar heatmap activityBRead-onlyIdempotent
Retrieve calendar heatmap activity
Retrieve activity counts for a specified period, in a calendar heatmap format.
Immich operation: GET /users/me/calendar-heatmap · tag: Users
Inputs: to, from, type.
immich_get_my_preferencesGet my preferencesBRead-onlyIdempotent
Get my preferences
Retrieve the preferences for the current user.
Immich operation: GET /users/me/preferences · tag: Users
Inputs: no named parameters.
immich_get_my_userGet current userBRead-onlyIdempotent
Get current user
Retrieve information about the user making the API request.
Immich operation: GET /users/me · tag: Users
Inputs: no named parameters.
immich_get_notificationGet a notificationARead-onlyIdempotent
Get a notification
Retrieve a specific notification identified by id.
Immich operation: GET /notifications/{id} · tag: Notifications
Inputs: id (required).
immich_get_notificationsRetrieve notificationsCRead-onlyIdempotent
Retrieve notifications
Retrieve a list of notifications.
Immich operation: GET /notifications · tag: Notifications
Inputs: id, type, level, unread.
immich_get_notification_template_adminRender email templateB
Render email template
Retrieve a preview of the provided email template.
Immich operation: POST /admin/notifications/templates/{name} · tag: Notifications (admin)
Inputs: name (required), template (required).
immich_get_partnersRetrieve partnersARead-onlyIdempotent
Retrieve partners
Retrieve a list of partners with whom assets are shared.
Immich operation: GET /partners · tag: Partners
Inputs: direction (required).
immich_get_personGet a personCRead-onlyIdempotent
Get a person
Retrieve a person by id.
Immich operation: GET /people/{id} · tag: People
Inputs: id (required).
immich_get_person_statisticsGet person statisticsBRead-onlyIdempotent
Get person statistics
Retrieve statistics about a specific person.
Immich operation: GET /people/{id}/statistics · tag: People
Inputs: id (required).
immich_get_person_thumbnailGet person thumbnailBRead-onlyIdempotent
Get person thumbnail
Retrieve the thumbnail file for a person.
Immich operation: GET /people/{id}/thumbnail · tag: People
Inputs: id (required).
immich_get_pluginRetrieve a pluginBRead-onlyIdempotent
Retrieve a plugin
Retrieve information about a specific plugin by its ID.
Immich operation: GET /plugins/{id} · tag: Plugins
Inputs: id (required).
immich_get_profile_imageRetrieve user profile imageBRead-onlyIdempotent
Retrieve user profile image
Retrieve the profile image file for a user.
Immich operation: GET /users/{id}/profile-image · tag: Users
Inputs: id (required).
immich_get_public_configGet the public configurationARead-onlyIdempotent
Get the public configuration
Retrieve the system configuration properties that are visible to everyone.
Immich operation: GET /public/config · tag: Config (public)
Inputs: no named parameters.
immich_get_public_config_defaultsGet the public configuration defaultsARead-onlyIdempotent
Get the public configuration defaults
Retrieve the default value of the configuration properties that are visible to everyone.
Immich operation: GET /public/config/defaults · tag: Config (public)
Inputs: no named parameters.
immich_get_queueRetrieve a queueBRead-onlyIdempotent
Retrieve a queue
Retrieves a specific queue by its name.
Immich operation: GET /queues/{name} · tag: Queues
Inputs: name (required).
immich_get_queue_jobsRetrieve queue jobsBRead-onlyIdempotent
Retrieve queue jobs
Retrieves a list of queue jobs from the specified queue.
Immich operation: GET /queues/{name}/jobs · tag: Queues
Inputs: name (required), status.
immich_get_queuesList all queuesBRead-onlyIdempotent
List all queues
Retrieves a list of queues.
Immich operation: GET /queues · tag: Queues
Inputs: no named parameters.
immich_get_queues_legacyRetrieve queue counts and statusARead-onlyIdempotent
Retrieve queue counts and status
Retrieve the counts of the current queue, as well as the current status.
Immich operation: GET /jobs · tag: Jobs
DEPRECATED — prefer the replacement operation if one exists.
Inputs: no named parameters.
immich_get_reverse_geocoding_stateRetrieve reverse geocoding stateBRead-onlyIdempotent
Retrieve reverse geocoding state
Retrieve the current state of the reverse geocoding import.
Immich operation: GET /system-metadata/reverse-geocoding-state · tag: System metadata
Inputs: no named parameters.
immich_get_search_suggestionsRetrieve search suggestionsARead-onlyIdempotent
Retrieve search suggestions
Retrieve search suggestions based on partial input. This endpoint is used for typeahead search features.
Immich operation: GET /search/suggestions · tag: Search
Inputs: type (required), make, model, state, +3 more.
immich_get_segmentGet HLS segment or init fileBRead-onlyIdempotent
Get HLS segment or init file
Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).
Immich operation: GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename} · tag: Assets
Inputs: id (required), filename (required), sessionId (required), variantIndex (required), +3 more.
immich_get_server_configGet configCRead-onlyIdempotent
Get config
Retrieve the current server configuration.
Immich operation: GET /server/config · tag: Server
DEPRECATED — prefer the replacement operation if one exists.
Inputs: no named parameters.
immich_get_server_featuresGet featuresBRead-onlyIdempotent
Get features
Retrieve available features supported by this server.
Immich operation: GET /server/features · tag: Server
DEPRECATED — prefer the replacement operation if one exists.
Inputs: no named parameters.
immich_get_server_licenseGet product keyBRead-onlyIdempotent
Get product key
Retrieve information about whether the server currently has a product key registered.
Immich operation: GET /server/license · tag: Server
Inputs: no named parameters.
immich_get_server_statisticsGet statisticsBRead-onlyIdempotent
Get statistics
Retrieve statistics about the entire Immich instance such as asset counts.
Immich operation: GET /server/statistics · tag: Server
Inputs: no named parameters.
immich_get_server_versionGet server versionBRead-onlyIdempotent
Get server version
Retrieve the current server version in semantic versioning (semver) format.
Immich operation: GET /server/version · tag: Server
Inputs: no named parameters.
immich_get_sessionsRetrieve sessionsBRead-onlyIdempotent
Retrieve sessions
Retrieve a list of sessions for the user.
Immich operation: GET /sessions · tag: Sessions
Inputs: no named parameters.
immich_get_stackRetrieve a stackBRead-onlyIdempotent
Retrieve a stack
Retrieve a specific stack by its ID.
Immich operation: GET /stacks/{id} · tag: Stacks
Inputs: id (required).
immich_get_storageGet storageARead-onlyIdempotent
Get storage
Retrieve the current storage utilization information of the server.
Immich operation: GET /server/storage · tag: Server
Inputs: no named parameters.
immich_get_storage_template_optionsGet storage template optionsBRead-onlyIdempotent
Get storage template options
Retrieve exemplary storage template options.
Immich operation: GET /system-config/storage-template-options · tag: System config
Inputs: no named parameters.
immich_get_supported_media_typesGet supported media typesBRead-onlyIdempotent
Get supported media types
Retrieve all media types supported by the server.
Immich operation: GET /server/media-types · tag: Server
Inputs: no named parameters.
immich_get_sync_ackRetrieve acknowledgementsBRead-onlyIdempotent
Retrieve acknowledgements
Retrieve the synchronization acknowledgments for the current session.
Immich operation: GET /sync/ack · tag: Sync
Inputs: no named parameters.
immich_get_sync_streamStream sync changesB
Stream sync changes
Retrieve a JSON lines streamed response of changes for synchronization. This endpoint is used by the mobile app to efficiently stay up to date with changes.
Immich operation: POST /sync/stream · tag: Sync
Inputs: types (required), reset.
immich_get_tag_by_idRetrieve a tagBRead-onlyIdempotent
Retrieve a tag
Retrieve a specific tag by its ID.
Immich operation: GET /tags/{id} · tag: Tags
Inputs: id (required).
immich_get_time_bucketGet time bucketBRead-onlyIdempotent
Get time bucket
Retrieve a string of all asset ids in a given time bucket.
Immich operation: GET /timeline/bucket · tag: Timeline
Inputs: timeBucket (required), key, bbox, slug, +12 more.
immich_get_time_bucketsGet time bucketsCRead-onlyIdempotent
Get time buckets
Retrieve a list of all minimal time buckets.
Immich operation: GET /timeline/buckets · tag: Timeline
Inputs: key, bbox, slug, order, +11 more.
immich_get_unique_original_pathsRetrieve unique pathsARead-onlyIdempotent
Retrieve unique paths
Retrieve a list of unique folder paths from asset original paths.
Immich operation: GET /view/folder/unique-paths · tag: Views
Inputs: no named parameters.
immich_get_userRetrieve a userCRead-onlyIdempotent
Retrieve a user
Retrieve a specific user by their ID.
Immich operation: GET /users/{id} · tag: Users
Inputs: id (required).
immich_get_user_adminRetrieve a userBRead-onlyIdempotent
Retrieve a user
Retrieve a specific user by their ID.
Immich operation: GET /admin/users/{id} · tag: Users (admin)
Inputs: id (required).
immich_get_user_calendar_heatmap_adminRetrieve calendar heatmap activityBRead-onlyIdempotent
Retrieve calendar heatmap activity
Retrieve activity counts for a specified period, in a calendar heatmap format.
Immich operation: GET /admin/users/{id}/calendar-heatmap · tag: Users (admin)
Inputs: id (required), to, from, type.
immich_get_user_configGet the configuration with user visibilityBRead-onlyIdempotent
Get the configuration with user visibility
Retrieve the system configuration properties that are visible to logged in users.
Immich operation: GET /config · tag: Config (user)
Inputs: no named parameters.
immich_get_user_config_defaultsGet the default configuration with user visibilityARead-onlyIdempotent
Get the default configuration with user visibility
Retrieve the default value of the configuration properties that are visible to logged in users.
Immich operation: GET /config/defaults · tag: Config (user)
Inputs: no named parameters.
immich_get_user_licenseRetrieve user product keyBRead-onlyIdempotent
Retrieve user product key
Retrieve information about whether the current user has a registered product key.
Immich operation: GET /users/me/license · tag: Users
Inputs: no named parameters.
immich_get_user_onboardingRetrieve user onboardingBRead-onlyIdempotent
Retrieve user onboarding
Retrieve the onboarding status of the current user.
Immich operation: GET /users/me/onboarding · tag: Users
Inputs: no named parameters.
immich_get_user_preferences_adminRetrieve user preferencesARead-onlyIdempotent
Retrieve user preferences
Retrieve the preferences of a specific user.
Immich operation: GET /admin/users/{id}/preferences · tag: Users (admin)
Inputs: id (required).
immich_get_user_sessions_adminRetrieve user sessionsBRead-onlyIdempotent
Retrieve user sessions
Retrieve all sessions for a specific user.
Immich operation: GET /admin/users/{id}/sessions · tag: Users (admin)
Inputs: id (required).
immich_get_user_statistics_adminRetrieve user statisticsBRead-onlyIdempotent
Retrieve user statistics
Retrieve asset statistics for a specific user.
Immich operation: GET /admin/users/{id}/statistics · tag: Users (admin)
Inputs: id (required), isTrashed, isFavorite, visibility.
immich_get_version_checkGet version check statusARead-onlyIdempotent
Get version check status
Retrieve information about the last time the version check ran.
Immich operation: GET /server/version-check · tag: Server
Inputs: no named parameters.
immich_get_version_check_stateRetrieve version check stateBRead-onlyIdempotent
Retrieve version check state
Retrieve the current state of the version check process.
Immich operation: GET /system-metadata/version-check-state · tag: System metadata
Inputs: no named parameters.
immich_get_version_historyGet version historyBRead-onlyIdempotent
Get version history
Retrieve a list of past versions the server has been on.
Immich operation: GET /server/version-history · tag: Server
Inputs: no named parameters.
immich_get_workflowRetrieve a workflowBRead-onlyIdempotent
Retrieve a workflow
Retrieve information about a specific workflow by its ID.
Immich operation: GET /workflows/{id} · tag: Workflows
Inputs: id (required).
immich_get_workflow_logsRetrieve workflow logsBRead-onlyIdempotent
Retrieve workflow logs
Retrieve logs of a workflows runs by ID
Immich operation: GET /workflows/{id}/logs · tag: Workflows
Inputs: id (required), limit, before, result.
immich_get_workflow_triggersList all workflow triggersBRead-onlyIdempotent
List all workflow triggers
Retrieve a list of all available workflow triggers.
Immich operation: GET /workflows/triggers · tag: Workflows
Inputs: no named parameters.
immich_leave_cluster_groupLeave a cluster groupB
Leave a cluster group
Move the current user into a new cluster group of their own.
Immich operation: POST /cluster-groups/{id}/leave · tag: Cluster groups
Inputs: id (required).
immich_link_o_auth_accountLink OAuth accountB
Link OAuth account
Link an OAuth account to the authenticated user.
Immich operation: POST /oauth/link · tag: Authentication
Inputs: url (required), state, codeVerifier.
immich_list_database_backupsList database backupsBRead-onlyIdempotent
List database backups
Get the list of the successful and failed backups
Immich operation: GET /admin/database-backups · tag: Database Backups (admin)
Inputs: no named parameters.
immich_lock_auth_sessionLock auth sessionB
Lock auth session
Remove elevated access to locked assets from the current session.
Immich operation: POST /auth/session/lock · tag: Authentication
Inputs: no named parameters.
immich_lock_sessionLock a sessionB
Lock a session
Lock a specific session by id.
Immich operation: POST /sessions/{id}/lock · tag: Sessions
Inputs: id (required).
immich_loginLoginB
Login
Login with username and password and receive a session token.
Immich operation: POST /auth/login · tag: Authentication
Inputs: email (required), password (required).
immich_logoutLogoutA
Logout
Logout the current user and invalidate the session token.
Immich operation: POST /auth/logout · tag: Authentication
Inputs: no named parameters.
immich_logout_o_authBackchannel OAuth logoutB
Backchannel OAuth logout
Logout the OAuth account and invalidate the session specified by the sid claim or all sessions if the sid claim is not present.
Immich operation: POST /oauth/backchannel-logout · tag: Authentication
Inputs: logout_token (required).
immich_maintenance_loginLog into maintenance modeA
Log into maintenance mode
Login with maintenance token or cookie to receive current information and perform further actions.
Immich operation: POST /admin/maintenance/login · tag: Maintenance (admin)
Inputs: token.
immich_memories_statisticsRetrieve memories statisticsBRead-onlyIdempotent
Retrieve memories statistics
Retrieve statistics about memories, such as total count and other relevant metrics.
Immich operation: GET /memories/statistics · tag: Memories
Inputs: id, for, page, size, +5 more.
immich_merge_peopleMerge peopleA
Merge people
Merge an ordered list of people together into a single person. The final name and birth date are always the first defined value, following the order. Also automatically merges people for other users in the cluster group, skipping people that would result in overriding a previously set name or birth date.
Immich operation: POST /people/merge · tag: People
Inputs: ids (required).
immich_merge_person_legacyMerge peopleA
Merge people
Merge a list of people into the person specified in the path parameter.
Immich operation: POST /people/{id}/merge · tag: People
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), ids (required).
immich_ping_serverPingCRead-onlyIdempotent
Ping
Pong
Immich operation: GET /server/ping · tag: Server
Inputs: no named parameters.
immich_play_asset_videoPlay asset videoBRead-onlyIdempotent
Play asset video
Streams the video file for the specified asset. This endpoint also supports byte range requests.
Immich operation: GET /assets/{id}/video/playback · tag: Assets
Inputs: id (required), key, slug.
immich_reassign_facesReassign facesBIdempotent
Reassign faces
Bulk reassign a list of faces to a different person.
Immich operation: PUT /people/{id}/reassign · tag: People
Inputs: id (required), data (required).
immich_reassign_faces_by_idRe-assign a face to another personBIdempotent
Re-assign a face to another person
Re-assign the face provided in the body to the person identified by the id in the path parameter.
Immich operation: PUT /faces/{id} · tag: Faces
Inputs: id (required), body (required).
immich_redirect_o_auth_to_mobileRedirect OAuth to mobileBRead-onlyIdempotent
Redirect OAuth to mobile
Requests to this URL are automatically forwarded to the mobile app, and is used in some cases for OAuth redirecting.
Immich operation: GET /oauth/mobile-redirect · tag: Authentication
Inputs: no named parameters.
immich_remove_asset_editsRemove edits from an existing assetADestructiveIdempotent
Remove edits from an existing asset
Removes all edit actions (crop, rotate, mirror) associated with the specified asset.
Immich operation: DELETE /assets/{id}/edits · tag: Assets
Inputs: id (required).
immich_remove_asset_from_albumRemove assets from an albumCDestructiveIdempotent
Remove assets from an album
Remove multiple assets from a specific album by its ID.
Immich operation: DELETE /albums/{id}/assets · tag: Albums
Inputs: id (required), ids (required).
immich_remove_asset_from_stackRemove an asset from a stackBDestructiveIdempotent
Remove an asset from a stack
Remove a specific asset from a stack by providing the stack ID and asset ID.
Immich operation: DELETE /stacks/{id}/assets/{assetId} · tag: Stacks
Inputs: id (required), assetId (required).
immich_remove_memory_assetsRemove assets from a memoryBDestructiveIdempotent
Remove assets from a memory
Remove a list of asset IDs from a specific memory.
Immich operation: DELETE /memories/{id}/assets · tag: Memories
Inputs: id (required), ids (required).
immich_remove_partnerRemove a partnerBDestructiveIdempotent
Remove a partner
Stop sharing assets with a partner.
Immich operation: DELETE /partners/{id} · tag: Partners
Inputs: id (required).
immich_remove_user_from_albumRemove user from albumBDestructiveIdempotent
Remove user from album
Remove a user from an album. Use an ID of "me" to leave a shared album.
Immich operation: DELETE /albums/{id}/user/{userId} · tag: Albums
Inputs: id (required), userId (required).
immich_reset_pin_codeReset pin codeADestructiveIdempotent
Reset pin code
Reset the pin code for the current user by providing the account password
Immich operation: DELETE /auth/pin-code · tag: Authentication
Inputs: pinCode, password.
immich_resolve_duplicatesResolve duplicate groupsB
Resolve duplicate groups
Resolve duplicate groups by synchronizing metadata across assets and deleting/trashing duplicates.
Immich operation: POST /duplicates/resolve · tag: Duplicates
Inputs: groups (required).
immich_restore_assetsRestore assetsA
Restore assets
Restore specific assets from the trash.
Immich operation: POST /trash/restore/assets · tag: Trash
Inputs: ids (required).
immich_restore_trashRestore trashB
Restore trash
Restore all items in the trash.
Immich operation: POST /trash/restore · tag: Trash
Inputs: no named parameters.
immich_restore_user_adminRestore a deleted userB
Restore a deleted user
Restore a previously deleted user.
Immich operation: POST /admin/users/{id}/restore · tag: Users (admin)
Inputs: id (required).
immich_reverse_geocodeReverse geocode coordinatesARead-onlyIdempotent
Reverse geocode coordinates
Retrieve location information (e.g., city, country) for given latitude and longitude coordinates.
Immich operation: GET /map/reverse-geocode · tag: Map
Inputs: lat (required), lon (required).
immich_rotate_api_keyRotate an API keyA
Rotate an API key
Generates a new secret for an API key, immediately invalidating the previous one. The current user must own this API key.
Immich operation: POST /api-keys/{id}/rotate · tag: API keys
Inputs: id (required).
immich_run_asset_jobsRun an asset jobC
Run an asset job
Run a specific job on a set of assets.
Immich operation: POST /assets/jobs · tag: Assets
Inputs: name (required), assetIds (required).
immich_run_queue_command_legacyRun jobsBIdempotent
Run jobs
Queue all assets for a specific job type. Defaults to only queueing assets that have not yet been processed, but the force command can be used to re-process all assets.
Immich operation: PUT /jobs/{name} · tag: Jobs
DEPRECATED — prefer the replacement operation if one exists.
Inputs: name (required), command (required), force.
immich_scan_libraryScan a libraryA
Scan a library
Queue a scan for the external library to find and import new assets.
Immich operation: POST /libraries/{id}/scan · tag: Libraries
Inputs: id (required).
immich_search_asset_filesSearch asset filesCRead-onlyIdempotent
Search asset files
Returns all matching asset files.
Immich operation: GET /asset-files · tag: Asset files
Inputs: assetId (required), type, isEdited, isProgressive, +1 more.
immich_search_assetsSearch assets by metadataC
Search assets by metadata
Search for assets based on various metadata criteria.
Immich operation: POST /search/metadata · tag: Search
Inputs: id, key, ocr, city, +43 more.
immich_search_asset_statisticsSearch asset statisticsC
Search asset statistics
Retrieve statistical data about assets based on search criteria, such as the total matching count.
Immich operation: POST /search/statistics · tag: Search
Inputs: ocr, city, make, type, +25 more.
immich_search_large_assetsSearch large assetsC
Search large assets
Search for assets that are considered large based on specified criteria.
Immich operation: POST /search/large-assets · tag: Search
DEPRECATED — prefer the replacement operation if one exists.
Inputs: ocr, city, make, size, +27 more.
immich_search_memoriesRetrieve memoriesBRead-onlyIdempotent
Retrieve memories
Retrieve a list of memories. Memories are sorted descending by creation date by default, although they can also be sorted in ascending order, or randomly.
Immich operation: GET /memories · tag: Memories
Inputs: id, for, page, size, +5 more.
immich_search_personSearch peopleCRead-onlyIdempotent
Search people
Search for people by name.
Immich operation: GET /search/person · tag: Search
Inputs: name (required), withHidden.
immich_search_placesSearch placesCRead-onlyIdempotent
Search places
Search for places by name.
Immich operation: GET /search/places · tag: Search
Inputs: name (required).
immich_search_plugin_methodsRetrieve plugin methodsCRead-onlyIdempotent
Retrieve plugin methods
Retrieve a list of plugin methods
Immich operation: GET /plugins/methods · tag: Plugins
Inputs: id, name, type, title, +5 more.
immich_search_pluginsList all pluginsBRead-onlyIdempotent
List all plugins
Retrieve a list of plugins available to the authenticated user.
Immich operation: GET /plugins · tag: Plugins
Inputs: id, name, title, enabled, +2 more.
immich_search_plugin_templatesRetrieve workflow templatesBRead-onlyIdempotent
Retrieve workflow templates
Retrieve workflow templates provided by installed plugins
Immich operation: GET /plugins/templates · tag: Plugins
Inputs: no named parameters.
immich_search_randomSearch random assetsB
Search random assets
Retrieve a random selection of assets based on the provided criteria.
Immich operation: POST /search/random · tag: Search
Inputs: ocr, city, make, size, +29 more.
immich_search_smartSmart asset searchC
Smart asset search
Perform a smart search for assets by using machine learning vectors to determine relevance.
Immich operation: POST /search/smart · tag: Search
Inputs: ocr, city, make, page, +31 more.
immich_search_stacksRetrieve stacksCRead-onlyIdempotent
Retrieve stacks
Retrieve a list of stacks.
Immich operation: GET /stacks · tag: Stacks
Inputs: primaryAssetId.
immich_search_usersGet all usersBRead-onlyIdempotent
Get all users
Retrieve a list of all users on the server.
Immich operation: GET /users · tag: Users
Inputs: no named parameters.
immich_search_users_adminSearch usersCRead-onlyIdempotent
Search users
Search for users.
Immich operation: GET /admin/users · tag: Users (admin)
Inputs: id, withDeleted.
immich_search_workflowsList all workflowsBRead-onlyIdempotent
List all workflows
Retrieve a list of workflows available to the authenticated user.
Immich operation: GET /workflows · tag: Workflows
Inputs: id, name, enabled, logging, +2 more.
immich_send_sync_ackAcknowledge changesB
Acknowledge changes
Send a list of synchronization acknowledgements to confirm that the latest changes have been received.
Immich operation: POST /sync/ack · tag: Sync
Inputs: acks (required).
immich_send_test_email_adminSend test emailA
Send test email
Send a test email using the provided SMTP configuration.
Immich operation: POST /admin/notifications/test-email · tag: Notifications (admin)
Inputs: from (required), enabled (required), replyTo (required), transport (required).
immich_set_maintenance_modeSet maintenance modeC
Set maintenance mode
Put Immich into or take it out of maintenance mode
Immich operation: POST /admin/maintenance · tag: Maintenance (admin)
Inputs: action (required), restoreBackupFilename.
immich_set_server_licenseSet server product keyBIdempotent
Set server product key
Validate and set the server product key if successful.
Immich operation: PUT /server/license · tag: Server
Inputs: licenseKey (required), activationKey (required).
immich_setup_pin_codeSetup pin codeB
Setup pin code
Setup a new pin code for the current user.
Immich operation: POST /auth/pin-code · tag: Authentication
Inputs: pinCode (required).
immich_set_user_licenseSet user product keyBIdempotent
Set user product key
Register a product key for the current user.
Immich operation: PUT /users/me/license · tag: Users
Inputs: licenseKey (required), activationKey (required).
immich_set_user_onboardingUpdate user onboardingBIdempotent
Update user onboarding
Update the onboarding status of the current user.
Immich operation: PUT /users/me/onboarding · tag: Users
Inputs: isOnboarded (required).
immich_sign_up_adminRegister adminB
Register admin
Create the first admin user in the system.
Immich operation: POST /auth/admin-sign-up · tag: Authentication
Inputs: name (required), email (required), password (required).
immich_start_database_restore_flowStart database backup restore flowA
Start database backup restore flow
Put Immich into maintenance mode to restore a backup (Immich must not be configured)
Immich operation: POST /admin/database-backups/start-restore · tag: Database Backups (admin)
Inputs: no named parameters.
immich_start_o_authStart OAuthC
Start OAuth
Initiate the OAuth authorization process.
Immich operation: POST /oauth/authorize · tag: Authentication
Inputs: redirectUri (required), state, codeChallenge.
immich_tag_assetsTag assetsBIdempotent
Tag assets
Add a tag to all the specified assets.
Immich operation: PUT /tags/{id}/assets · tag: Tags
Inputs: id (required), ids (required).
immich_unlink_all_o_auth_accounts_adminUnlink all OAuth accountsB
Unlink all OAuth accounts
Unlinks all OAuth accounts associated with user accounts in the system.
Immich operation: POST /admin/auth/unlink-all · tag: Authentication (admin)
Inputs: no named parameters.
immich_unlink_o_auth_accountUnlink OAuth accountA
Unlink OAuth account
Unlink the OAuth account from the authenticated user.
Immich operation: POST /oauth/unlink · tag: Authentication
Inputs: no named parameters.
immich_unlock_auth_sessionUnlock auth sessionA
Unlock auth session
Temporarily grant the session elevated access to locked assets by providing the correct PIN code.
Immich operation: POST /auth/session/unlock · tag: Authentication
Inputs: pinCode, password.
immich_untag_assetsUntag assetsBDestructiveIdempotent
Untag assets
Remove a tag from all the specified assets.
Immich operation: DELETE /tags/{id}/assets · tag: Tags
Inputs: id (required), ids (required).
immich_update_admin_configUpdate the system configurationCIdempotent
Update the system configuration
Update the system configuration with a new system configuration.
Immich operation: PUT /admin/config · tag: Config (admin)
Inputs: job (required), map (required), user (required), image (required), +18 more.
immich_update_admin_onboardingUpdate admin onboardingC
Update admin onboarding
Update the admin onboarding status.
Immich operation: POST /system-metadata/admin-onboarding · tag: System metadata
Inputs: isOnboarded (required).
immich_update_album_infoUpdate an albumA
Update an album
Update the information of a specific album by its ID. This endpoint can be used to update the album name, description, sort order, etc. However, it is not used to add or remove assets or users from the album.
Immich operation: PATCH /albums/{id} · tag: Albums
Inputs: id (required), order, albumName, description, +2 more.
immich_update_album_userUpdate user roleAIdempotent
Update user role
Change the role for a specific user in a specific album.
Immich operation: PUT /albums/{id}/user/{userId} · tag: Albums
Inputs: id (required), role (required), userId (required).
immich_update_api_keyUpdate an API keyAIdempotent
Update an API key
Updates the name and permissions of an API key by its ID. The current user must own this API key.
Immich operation: PUT /api-keys/{id} · tag: API keys
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, permissions.
immich_update_assetUpdate an assetBIdempotent
Update an asset
Update information of a specific asset.
Immich operation: PUT /assets/{id} · tag: Assets
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), rating, latitude, longitude, +5 more.
immich_update_asset_metadataUpdate asset metadataBIdempotent
Update asset metadata
Update or add metadata key-value pairs for the specified asset.
Immich operation: PUT /assets/{id}/metadata · tag: Assets
Inputs: id (required), items (required).
immich_update_assetsUpdate assetsBIdempotent
Update assets
Updates multiple assets at the same time.
Immich operation: PUT /assets · tag: Assets
DEPRECATED — prefer the replacement operation if one exists.
Inputs: ids (required), rating, latitude, timeZone, +7 more.
immich_update_bulk_asset_metadataUpsert asset metadataBIdempotent
Upsert asset metadata
Upsert metadata key-value pairs for multiple assets.
Immich operation: PUT /assets/metadata · tag: Assets
Inputs: items (required).
immich_update_configUpdate system configurationCIdempotent
Update system configuration
Update the system configuration with a new system configuration.
Immich operation: PUT /system-config · tag: System config
DEPRECATED — prefer the replacement operation if one exists.
Inputs: job (required), map (required), user (required), image (required), +18 more.
immich_update_libraryUpdate a libraryAIdempotent
Update a library
Update an existing external library.
Immich operation: PUT /libraries/{id} · tag: Libraries
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, importPaths, exclusionPatterns.
immich_update_memoryUpdate a memoryBIdempotent
Update a memory
Update an existing memory by its ID.
Immich operation: PUT /memories/{id} · tag: Memories
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), seenAt, isSaved, memoryAt.
immich_update_my_preferencesUpdate my preferencesBIdempotent
Update my preferences
Update the preferences of the current user.
Immich operation: PUT /users/me/preferences · tag: Users
DEPRECATED — prefer the replacement operation if one exists.
Inputs: cast, tags, albums, avatar, +9 more.
immich_update_my_userUpdate current userBIdempotent
Update current user
Update the current user making the API request.
Immich operation: PUT /users/me · tag: Users
DEPRECATED — prefer the replacement operation if one exists.
Inputs: name, email, password, avatarColor.
immich_update_notificationUpdate a notificationAIdempotent
Update a notification
Update a specific notification to set its read status.
Immich operation: PUT /notifications/{id} · tag: Notifications
Inputs: id (required), readAt.
immich_update_notificationsUpdate notificationsAIdempotent
Update notifications
Update a list of notifications. Allows to bulk-set the read status of notifications.
Immich operation: PUT /notifications · tag: Notifications
Inputs: ids (required), readAt.
immich_update_partnerUpdate a partnerAIdempotent
Update a partner
Specify whether a partner's assets should appear in the user's timeline.
Immich operation: PUT /partners/{id} · tag: Partners
Inputs: id (required), inTimeline (required).
immich_update_peopleUpdate peopleBIdempotent
Update people
Bulk update multiple people at once.
Immich operation: PUT /people · tag: People
Inputs: people (required).
immich_update_personUpdate personCIdempotent
Update person
Update an individual person.
Immich operation: PUT /people/{id} · tag: People
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, color, isHidden, +3 more.
immich_update_queueUpdate a queueBIdempotent
Update a queue
Change the paused status of a specific queue.
Immich operation: PUT /queues/{name} · tag: Queues
Inputs: name (required), isPaused.
immich_update_sessionUpdate a sessionBIdempotent
Update a session
Update a specific session identified by id.
Immich operation: PUT /sessions/{id} · tag: Sessions
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), isPendingSyncReset.
immich_update_stackUpdate a stackBIdempotent
Update a stack
Update an existing stack by its ID.
Immich operation: PUT /stacks/{id} · tag: Stacks
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), primaryAssetId.
immich_update_tagUpdate a tagBIdempotent
Update a tag
Update an existing tag identified by its ID.
Immich operation: PUT /tags/{id} · tag: Tags
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, color.
immich_update_user_adminUpdate a userBIdempotent
Update a user
Update an existing user.
Immich operation: PUT /admin/users/{id} · tag: Users (admin)
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, email, isAdmin, +6 more.
immich_update_user_preferences_adminUpdate user preferencesBIdempotent
Update user preferences
Update the preferences of a specific user.
Immich operation: PUT /admin/users/{id}/preferences · tag: Users (admin)
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), cast, tags, albums, +10 more.
immich_update_workflowUpdate a workflowBIdempotent
Update a workflow
Update the information of a specific workflow by its ID. This endpoint can be used to update the workflow name, description, trigger type, filters and actions order, etc.
Immich operation: PUT /workflows/{id} · tag: Workflows
DEPRECATED — prefer the replacement operation if one exists.
Inputs: id (required), name, steps, enabled, +3 more.
immich_upload_assetUpload assetC
Upload asset
Uploads a new asset to the server.
Immich operation: POST /assets · tag: Assets
Inputs: assetData (required), fileCreatedAt (required), fileModifiedAt (required), key, +9 more.
immich_upload_database_backupUpload database backupA
Upload database backup
Uploads .sql/.sql.gz file to restore backup from
Immich operation: POST /admin/database-backups/upload · tag: Database Backups (admin)
Inputs: file.
immich_upsert_tagsUpsert tagsCIdempotent
Upsert tags
Create or update multiple tags in a single request.
Immich operation: PUT /tags · tag: Tags
Inputs: tags (required).
immich_validateValidate library settingsC
Validate library settings
Validate the settings of an external library.
Immich operation: POST /libraries/{id}/validate · tag: Libraries
Inputs: id (required), importPaths, exclusionPatterns.
immich_validate_access_tokenValidate access tokenB
Validate access token
Validate the current authorization method is still valid.
Immich operation: POST /auth/validateToken · tag: Authentication
Inputs: no named parameters.
immich_view_assetView asset thumbnailBRead-onlyIdempotent
View asset thumbnail
Retrieve the thumbnail image for the specified asset. Viewing the fullsize thumbnail might redirect to downloadAsset, which requires a different permission.
Immich operation: GET /assets/{id}/thumbnail · tag: Assets
Inputs: id (required), key, size, slug, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 276 tools
With 276 tools there is heavy overlap: many near-identical config getters (get_config, get_admin_config, get_user_config, get_public_config, get_server_config plus their *_defaults variants), duplicate partner creators (create_partner vs create_partner_deprecated), and deprecated tools sitting alongside their replacements (update_tag/upsert_tags, update_asset/update_assets, get_user/get_user_admin). An agent will frequently struggle to pick the right tool. Some resource+action pairs are distinct, but the sheer volume of deprecated/duplicate variants muddies boundaries.
Names use a predictable immich_<verb>_<noun> snake_case pattern (immich_create_album, immich_get_asset_info, immich_delete_stack), which is highly consistent and readable. A few exceptions drop the noun (immich_login, immich_logout, immich_validate, immich_ping_server), but these are minor deviations within an otherwise uniform convention.
276 tools is an extreme count that far exceeds a manageable surface, reflecting a 1:1 mechanical mapping of the entire Immich REST API rather than a curated, agent-friendly set. This makes discovery, selection, and context management impractical.
The surface mirrors the full Immich API exhaustively — assets, albums, people, faces, tags, libraries, memories, queues, jobs, admin, auth, sync, workflows, and more — leaving essentially no CRUD or lifecycle gaps. Coverage is as complete as a tool set can be.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Browse, search, upload, tag, transfer, and delete images in your Raster libraries over MCP.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server for Immich self-hosted photo management that provides AI-accessible tools for browsing, searching, organizing, and managing photo libraries with duplicate detection and safe deletion workflows.431-
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to interact with an Immich photo management instance, providing access to users, assets, API keys, and partners through standardized resources and tools.1MIT
- AlicenseNot gradedqualityDmaintenanceAn OpenAPI 3.0-based MCP server that provides structured access to Immich 2.0 server functionality through tools, resources, and contextual capabilities.3MIT
- AlicenseAqualityCmaintenanceConnects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.587 npmMIT