Skip to main content
Glama

immich-mcp

English · Русский

License: MIT PRs welcome

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 streamable http (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/sdk at build time.

Related MCP server: Immich MCP Server

Requirements

  • Node.js 18+ (Node 20+ recommended for File support 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 build

Configuration

All configuration is via environment variables:

Variable

Required

Default

Description

IMMICH_BASE_URL

yes

—

Immich API base URL, e.g. http://localhost:2283/api. /api is appended automatically if missing.

IMMICH_API_KEY

one of

—

Immich API key.

IMMICH_ACCESS_TOKEN

one of

—

Bearer access token (used if no API key is set).

IMMICH_HEADERS

no

{}

Extra JSON headers sent with every request.

IMMICH_MCP_TRANSPORT

no

stdio

stdio, http or both.

IMMICH_MCP_HTTP_HOST

no

127.0.0.1

HTTP bind host (0.0.0.0 in Docker).

IMMICH_MCP_HTTP_PORT

no

3000

HTTP port.

IMMICH_MCP_HTTP_PATH

no

/mcp

HTTP endpoint path.

IMMICH_MCP_HTTP_AUTH_TOKEN

no

—

If set, HTTP requests must send Authorization: Bearer <token>.

IMMICH_MCP_DOWNLOAD_DIR

no

./downloads

Where downloaded/binary files are written.

IMMICH_MCP_MAX_RESULT_CHARS

no

200000

Truncate large tool results.

IMMICH_MCP_TAGS

no

—

Comma-separated group allow-list (e.g. Assets,Albums,Search).

IMMICH_MCP_EXCLUDE_TAGS

no

—

Comma-separated group deny-list.

IMMICH_MCP_TOOLS

no

—

Comma-separated tool allow-list.

IMMICH_MCP_EXCLUDE_TOOLS

no

—

Comma-separated tool deny-list.

IMMICH_MCP_READONLY

no

0

Set to 1 to expose only GET operations.

IMMICH_MCP_LOG_LEVEL

no

info

debug, info, warn, error (logs go to stderr).

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 state

Then 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 named immich, immich_search_assets is exposed as immich_immich_search_assets; under the default Code Mode you call it as tools.immich.immich_search_assets(...). Set "codemode": false to 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": true to 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 --build

docker-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 build

Published 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 group

Tool naming

Tools are named immich_<snake_case operationId>, e.g.:

Tool

Operation

immich_search_assets

POST /search/metadata — smart/metadata search

immich_get_all_albums

GET /albums

immich_create_album

POST /albums

immich_upload_asset

POST /assets — uploads a local file

immich_download_asset

GET /assets/{id}/original — saves the file locally

immich_delete_assets

DELETE /assets

immich_run_queue_command

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  Workflows

Run --list-groups for the exact, current list.

Resources

URI

Contents

immich://server/about

Version & build info

immich://server/version

Server version

immich://server/storage

Disk usage per storage location

immich://server/statistics

Aggregate statistics

immich://user/me

Authenticated user profile

immich://albums

All albums

immich://people

All people

immich://tags

All tags

immich://memories

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_TOOLS to hide destructive tools (e.g. Maintenance (admin), Database Backups (admin)).

  • Set IMMICH_MCP_READONLY=1 for a strictly read-only server.

  • When using HTTP, always set IMMICH_MCP_HTTP_AUTH_TOKEN and terminate TLS in front of it.

Updating

Update immich-mcp itself

git pull
npm install
npm run build

Then 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 test

What each step does:

  • npm run spec:fetch downloads spec/immich-openapi-specs.json and spec/sdk-client.d.ts for the installed @immich/sdk version (falling back to the range in package.json). Pass an explicit version if needed: node scripts/fetch-spec.mjs 3.3.0.

  • npm run generate rewrites src/generated/manifest.ts and 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/sdk and the downloaded spec.

  • npm test rebuilds first (via pretest) 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.txt

Docker

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 -d

Reconnect 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 list shows 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 emitting

How it works

  1. scripts/fetch-spec.mjs downloads immich-openapi-specs.json and the @immich/sdk fetch-client.d.ts for the installed SDK version (falling back to the range in package.json) into spec/.

  2. scripts/generate.mjs walks the spec and emits src/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.

  3. At runtime src/json-schema.ts converts the OpenAPI/JSON schemas into Zod, src/tools.ts builds the MCP input schemas, and src/invoke.ts maps validated arguments back onto the @immich/sdk function 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 to main and v* tags, builds and publishes a multi-architecture image (linux/amd64 and linux/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 optional immich_sdk_version input 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 test

Contributing

Contributions are welcome — this is a community, open-source project. See CONTRIBUTING.md for details.

  1. Fork the repository and create a feature branch.

  2. Make the change, keeping the docs in sync (see AGENTS.md).

  3. Run the checks:

    npm install
    npm run typecheck
    npm run build
    git diff --exit-code -- src/generated/manifest.ts
    npm test
  4. Open 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 tools
immich_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 albumB
Idempotent

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 albumsB
Idempotent

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 memoryB
Idempotent

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 usersB
Idempotent

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 assetsB
Idempotent

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 codeC
Idempotent

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 assetB
Idempotent

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 requestA
Idempotent

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 activityB
DestructiveIdempotent

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 albumA
DestructiveIdempotent

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 sessionsA
DestructiveIdempotent

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 keyA
DestructiveIdempotent

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 fileB
DestructiveIdempotent

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 keyB
DestructiveIdempotent

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 assetsC
DestructiveIdempotent

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 metadataA
DestructiveIdempotent

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 requestB
DestructiveIdempotent

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 backupB
DestructiveIdempotent

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 groupA
DestructiveIdempotent

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 duplicatesB
DestructiveIdempotent

Delete duplicates

Delete multiple duplicate assets specified by their IDs.

Immich operation: DELETE /duplicates · tag: Duplicates

Inputs: ids (required).

immich_delete_faceDelete a faceC
DestructiveIdempotent

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 itemA
DestructiveIdempotent

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 libraryB
DestructiveIdempotent

Delete a library

Delete an external library by its ID.

Immich operation: DELETE /libraries/{id} · tag: Libraries

Inputs: id (required).

immich_delete_memoryDelete a memoryA
DestructiveIdempotent

Delete a memory

Delete a specific memory by its ID.

Immich operation: DELETE /memories/{id} · tag: Memories

Inputs: id (required).

immich_delete_notificationDelete a notificationC
DestructiveIdempotent

Delete a notification

Delete a specific notification.

Immich operation: DELETE /notifications/{id} · tag: Notifications

Inputs: id (required).

immich_delete_notificationsDelete notificationsC
DestructiveIdempotent

Delete notifications

Delete a list of notifications at once.

Immich operation: DELETE /notifications · tag: Notifications

Inputs: ids (required).

immich_delete_peopleDelete peopleB
DestructiveIdempotent

Delete people

Bulk delete a list of people at once.

Immich operation: DELETE /people · tag: People

Inputs: ids (required).

immich_delete_personDelete personC
DestructiveIdempotent

Delete person

Delete an individual person.

Immich operation: DELETE /people/{id} · tag: People

Inputs: id (required).

immich_delete_profile_imageDelete user profile imageB
DestructiveIdempotent

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 keyA
DestructiveIdempotent

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 sessionA
DestructiveIdempotent

Delete a session

Delete a specific session by id.

Immich operation: DELETE /sessions/{id} · tag: Sessions

Inputs: id (required).

immich_delete_stackDelete a stackB
DestructiveIdempotent

Delete a stack

Delete a specific stack by its ID.

Immich operation: DELETE /stacks/{id} · tag: Stacks

Inputs: id (required).

immich_delete_stacksDelete stacksA
DestructiveIdempotent

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 acknowledgementsC
DestructiveIdempotent

Delete acknowledgements

Delete specific synchronization acknowledgments.

Immich operation: DELETE /sync/ack · tag: Sync

Inputs: types.

immich_delete_tagDelete a tagB
DestructiveIdempotent

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 userC
DestructiveIdempotent

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 keyB
DestructiveIdempotent

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 onboardingB
DestructiveIdempotent

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 workflowB
DestructiveIdempotent

Delete a workflow

Delete a workflow by its ID.

Immich operation: DELETE /workflows/{id} · tag: Workflows

Inputs: id (required).

immich_detect_prior_installDetect existing installB
Read-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 assetB
Read-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 fileB
Read-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 backupC
Read-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 assetB
Idempotent

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 queueB
DestructiveIdempotent

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 sessionB
DestructiveIdempotent

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 informationC
Read-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 activitiesA
Read-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 statisticsA
Read-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 configurationC
Read-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 defaultsA
Read-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 onboardingB
Read-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 albumB
Read-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 markersB
Read-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 statisticsB
Read-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 albumsB
Read-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 librariesB
Read-onlyIdempotent

Retrieve libraries

Retrieve a list of external libraries.

Immich operation: GET /libraries · tag: Libraries

Inputs: no named parameters.

immich_get_all_peopleGet all peopleC
Read-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 tagsA
Read-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 keyA
Read-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 keysA
Read-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_asset_duplicatesRetrieve duplicatesB
Read-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 assetB
Read-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 fileB
Read-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 assetB
Read-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 metadataA
Read-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 keyC
Read-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 dataB
Read-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 cityA
Read-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 pathC
Read-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 statisticsB
Read-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 statusB
Read-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 requestsA
Read-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 groupB
Read-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 groupC
Read-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 configurationB
Read-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 defaultsB
Read-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 dataB
Read-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 assetB
Read-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 typeB
Read-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 CSVB
Read-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 fileB
Read-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 summaryB
Read-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 libraryB
Read-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 statisticsB
Read-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 playlistB
Read-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 statusA
Read-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 markersB
Read-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 playlistB
Read-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 memoryA
Read-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 keyB
Read-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 activityB
Read-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 preferencesB
Read-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 userB
Read-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 notificationA
Read-onlyIdempotent

Get a notification

Retrieve a specific notification identified by id.

Immich operation: GET /notifications/{id} · tag: Notifications

Inputs: id (required).

immich_get_notificationsRetrieve notificationsC
Read-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 partnersA
Read-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 personC
Read-onlyIdempotent

Get a person

Retrieve a person by id.

Immich operation: GET /people/{id} · tag: People

Inputs: id (required).

immich_get_person_statisticsGet person statisticsB
Read-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 thumbnailB
Read-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 pluginB
Read-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 imageB
Read-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 configurationA
Read-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 defaultsA
Read-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 queueB
Read-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 jobsB
Read-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 queuesB
Read-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 statusA
Read-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 stateB
Read-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 suggestionsA
Read-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 fileB
Read-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 configC
Read-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 featuresB
Read-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 keyB
Read-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 statisticsB
Read-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 versionB
Read-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 sessionsB
Read-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 stackB
Read-onlyIdempotent

Retrieve a stack

Retrieve a specific stack by its ID.

Immich operation: GET /stacks/{id} · tag: Stacks

Inputs: id (required).

immich_get_storageGet storageA
Read-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 optionsB
Read-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 typesB
Read-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 acknowledgementsB
Read-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 tagB
Read-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 bucketB
Read-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 bucketsC
Read-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 pathsA
Read-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 userC
Read-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 userB
Read-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 activityB
Read-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 visibilityB
Read-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 visibilityA
Read-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 keyB
Read-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 onboardingB
Read-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 preferencesA
Read-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 sessionsB
Read-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 statisticsB
Read-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 statusA
Read-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 stateB
Read-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 historyB
Read-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 workflowB
Read-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_for_shareRetrieve a workflowC
Read-onlyIdempotent

Retrieve a workflow

Retrieve a workflow details without ids, default values, etc.

Immich operation: GET /workflows/{id}/share · tag: Workflows

Inputs: id (required).

immich_get_workflow_logsRetrieve workflow logsB
Read-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 triggersB
Read-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_list_database_backupsList database backupsB
Read-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 statisticsB
Read-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_serverPingC
Read-onlyIdempotent

Ping

Pong

Immich operation: GET /server/ping · tag: Server

Inputs: no named parameters.

immich_play_asset_videoPlay asset videoB
Read-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 facesB
Idempotent

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 personB
Idempotent

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 mobileB
Read-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 assetA
DestructiveIdempotent

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 albumC
DestructiveIdempotent

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 stackB
DestructiveIdempotent

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 memoryB
DestructiveIdempotent

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 partnerB
DestructiveIdempotent

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 albumB
DestructiveIdempotent

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 codeA
DestructiveIdempotent

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 coordinatesA
Read-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 jobsB
Idempotent

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 filesC
Read-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 memoriesB
Read-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 peopleC
Read-onlyIdempotent

Search people

Search for people by name.

Immich operation: GET /search/person · tag: Search

Inputs: name (required), withHidden.

immich_search_placesSearch placesC
Read-onlyIdempotent

Search places

Search for places by name.

Immich operation: GET /search/places · tag: Search

Inputs: name (required).

immich_search_plugin_methodsRetrieve plugin methodsC
Read-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 pluginsB
Read-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 templatesB
Read-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 stacksC
Read-onlyIdempotent

Retrieve stacks

Retrieve a list of stacks.

Immich operation: GET /stacks · tag: Stacks

Inputs: primaryAssetId.

immich_search_usersGet all usersB
Read-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 usersC
Read-onlyIdempotent

Search users

Search for users.

Immich operation: GET /admin/users · tag: Users (admin)

Inputs: id, withDeleted.

immich_search_workflowsList all workflowsB
Read-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 keyB
Idempotent

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 keyB
Idempotent

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 onboardingB
Idempotent

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 assetsB
Idempotent

Tag assets

Add a tag to all the specified assets.

Immich operation: PUT /tags/{id}/assets · tag: Tags

Inputs: id (required), ids (required).

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 assetsB
DestructiveIdempotent

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 configurationC
Idempotent

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 roleA
Idempotent

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 keyA
Idempotent

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 assetB
Idempotent

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 metadataB
Idempotent

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 assetsB
Idempotent

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 metadataB
Idempotent

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 configurationC
Idempotent

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 libraryA
Idempotent

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 memoryB
Idempotent

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 preferencesB
Idempotent

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 userB
Idempotent

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 notificationA
Idempotent

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 notificationsA
Idempotent

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 partnerA
Idempotent

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 peopleB
Idempotent

Update people

Bulk update multiple people at once.

Immich operation: PUT /people · tag: People

Inputs: people (required).

immich_update_personUpdate personC
Idempotent

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 queueB
Idempotent

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 sessionB
Idempotent

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 stackB
Idempotent

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 tagB
Idempotent

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 userB
Idempotent

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 preferencesB
Idempotent

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 workflowB
Idempotent

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 tagsC
Idempotent

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 thumbnailB
Read-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

    C2.9/5.0

    Scored across 276 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An 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.
      43
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An OpenAPI 3.0-based MCP server that provides structured access to Immich 2.0 server functionality through tools, resources, and contextual capabilities.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects 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.
      5
      87 npm
      MIT