Immich Photo Manager

List assets with simple filters (no search query needed). Use this to browse the library by status (favorites, archived, trashed) or type. For finding specific content, use search_metadata (structured) or search_smart (visual AI). Read-only. Args: is_favorite: true = only favorites, false = only non-favorites, omit = all. is_archived: true = only archived, false = only non-archived, omit = all. is_trashed: true = only trashed items; false/omit = active library (Immich never mixes both). asset_type: 'IMAGE' or 'VIDEO'. Omit for both. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50). Returns: JSON with total count, current page, and assets array with IDs, filenames, dates, and types.

List memories — Immich's "on this day" collections of photos from past years. Use this to build a 'tal día como hoy' story, album or PDF: each memory carries the year it looks back to and the assets Immich picked for it. Read-only. Args: for_date: ISO date — return the memories Immich shows on that day (e.g. today for the classic on-this-day feed). Omit for all memories. is_saved: If true, only memories the user saved; if false, only unsaved. size: Maximum memories to return (default 50). Returns: JSON with total and a memories array; each has id, type, memory_at, the year it remembers, is_saved, asset_count and a trimmed assets list (id, filename, date).

Who shares their library with this account, and who this account shares with. Partner sharing is Immich's family feature: each side keeps its own library but can see the other's. Read-only. Returns: JSON with shared_with_me and shared_by_me arrays (id, name, email, in_timeline).

List all recognized people (face clusters) in the library. Use this to browse who appears in the photo library or find a person's ID. For searching by name, use search_people instead. Read-only. Args: page: Page number, starting from 1 (default 1). size: Results per page (default 50). with_hidden: Include people marked as hidden (default false). Returns: JSON with total count, page, and people array (each with id, name, thumbnailPath, photoCount).

List all shared links (public gallery URLs). Use this to see what's currently shared publicly or to find a link ID for updates/deletion. Read-only. Returns: JSON with total count and links array (each with id, key, type, description, album info).

List every stack in the library. Use this to see what is already grouped before creating new stacks or to find a stack's id. Read-only. Args: primary_asset_id: Only the stack fronted by this asset. Returns: JSON with total and a stacks array (id, primary_asset_id, assets).

List all tags in the library. Use this to discover existing tags before creating new ones or to find a tag ID for tagging operations. Read-only. Returns: JSON with total count and tags array (each with id, name, color).

The users visible on this Immich server. Use this to find the id that create_partner needs, or to see who could be shared with. Read-only. Returns: JSON with total and a users array of {id, name, email}.

Merge multiple person clusters into one. Use this when the same real person has been split into multiple face clusters. DESTRUCTIVE and IRREVERSIBLE: merged persons are permanently deleted and all their faces transfer to the target. Without confirm=true nothing happens: the call returns who would be kept and who would disappear, so the user can check the names before the merge. Side effect: with confirm=true, permanently deletes the merged persons; without it the call only previews and changes nothing. Args: person_id: The target person UUID to keep (receives all merged faces). merge_ids: List of person UUIDs to absorb into the target. These persons are permanently deleted. confirm: Pass true only after the user has seen the preview and agreed. Returns: JSON with the preview (confirm_required, keep, merge, failed) or the merge result.

Check Immich server connectivity. Use this to verify the server is reachable before running other operations. Read-only. Returns: JSON with 'server' status ('pong' if healthy).

Reassign a detected face to a different person. Use this to correct face recognition mistakes (e.g. a face wrongly attributed to Person A should be Person B). Get face_id from get_asset_faces first. Side effect: permanently changes face-to-person mapping. Args: face_id: The face detection UUID (from get_asset_faces results). person_id: The correct person UUID to assign this face to. Returns: JSON with the updated face assignment.

Remember something the plugin did to assets and why, for audit or undo: which album they went into and from what prompt, what date they had before a fix, why they were rotated. Side effect: writes the plugin's metadata key on each asset; other apps' keys are untouched. Args: asset_ids: The assets the action touched. action: Short verb-like label (e.g. 'added_to_album', 'date_fixed', 'rotated'). detail: Free text with the context worth keeping (album name, previous value, the user's request). Returns: JSON with success, the number of assets recorded, the action, and a failed array of {asset_id, error} for any asset that could not be written. Success is true only when nothing failed.

Remove assets from an album without deleting them. The photos remain in the library and other albums. Use this to un-curate mistakenly added assets. Side effect: modifies album membership. Args: album_id: Album UUID to remove assets from. asset_ids: List of asset UUIDs to remove from this album. Returns: JSON with album_id, count removed, and per-asset result details.

Stop sharing this account's library with a user. Their own photos are not touched. Side effect: revokes their access. Args: user_id: The user to unshare with. Returns: JSON confirming the removal.

Resolve duplicate groups by choosing which assets to keep and which to trash. Use this after reviewing results from get_duplicates. Trashed assets can still be recovered via restore_assets. Side effect: moves rejected duplicates to trash. Args: groups: List of dicts, each with: duplicateId (from get_duplicates), assetIds (UUIDs to KEEP), trashIds (UUIDs to TRASH). Returns: JSON with count of resolved groups.

Restore specific assets from trash back to the active library. Use this to selectively recover accidentally deleted photos. For restoring everything at once, use restore_trash instead. Side effect: moves specified assets out of trash. Args: asset_ids: List of asset UUIDs currently in trash to restore. Returns: JSON with count of restored assets.

Restore ALL trashed assets back to the library. Use this to undo an accidental bulk deletion. For restoring specific assets only, use restore_assets instead. Side effect: moves all trashed assets back to the active library. Returns: JSON with success confirmation.

Resolve GPS coordinates to a place name using Immich's own offline geodata. Use this to name the location of a marker from get_map_markers or of an asset's EXIF coordinates — no external service is contacted. Read-only. Args: lat: Latitude in decimal degrees. lon: Longitude in decimal degrees. Returns: JSON with total and a places array of {city, state, country} candidates.

Remove all non-destructive edits (rotation, crop, mirror) from assets, restoring original appearance. Use this to undo rotate_assets or any other display transforms. Provide EITHER asset_ids OR album_id. Side effect: deletes all edit records for the assets. Args: asset_ids: List of asset UUIDs to revert. Mutually exclusive with album_id. album_id: Revert all assets in this album. Mutually exclusive with asset_ids. Returns: JSON with reverted/failed counts.

Remember a review verdict on assets, with the reason, so a later session does not redo the analysis and the why survives. Use this after deciding what to do with a photo in a cleanup or duplicate pass — together with a tag when the user must see the state in Immich (tags are visible there, notes are not). Side effect: writes the plugin's metadata key on each asset; other apps' keys are untouched. Args: asset_ids: The assets the verdict applies to. verdict: One of 'keep', 'delete_candidate', 'duplicate_of', 'needs_check'. reason: Free text explaining the verdict (e.g. 'near-identical to IMG_6367, keep that one'). Short and concrete beats long. Returns: JSON with success, the number of assets reviewed, the verdict, and a failed array of {asset_id, error} for any asset that could not be written. Success is true only when nothing failed.

Apply a non-destructive clockwise rotation to one or more assets. Use this to fix orientation issues. The original file is never modified — rotation is a display transform only. Use revert_asset_edits to undo. Provide EITHER asset_ids OR album_id. Side effect: writes rotation edits to Immich; accumulates with existing rotation. Args: angle: Clockwise degrees, must be a multiple of 90 (90, 180, or 270). Default: 90. asset_ids: List of asset UUIDs to rotate. Mutually exclusive with album_id. album_id: Rotate all assets in this album. Mutually exclusive with asset_ids. Returns: JSON with rotated/failed counts and the applied angle.

Every city that appears in the library, one representative asset each. Unlike search_explore this has no minimum-asset threshold, so it is the reliable way to answer 'which places are in this library?'. Read-only. Returns: JSON with a cities array of {city, country, asset_id, date}.

Overview of what the library contains, grouped by explore field: one representative asset per city and per detected concept (Immich's Explore page). Use this to get oriented in an unknown library before searching for anything specific — it answers 'what is in here?' in one call. A city only appears once it holds at least 5 assets (Immich's own threshold), so small libraries can come back empty. Read-only. Returns: JSON with total (how many fields came back) and a fields array; each field has its name (e.g. 'exifInfo.city') and items pairing each value with one representative asset_id.

The biggest files in the library, largest first. Use this to find what is eating storage before a cleanup — videos and originals show up immediately. Read-only. Args: min_size_mb: Only assets at least this many megabytes (0 = no minimum). size: How many assets to return (1-200, default 20). asset_type: 'IMAGE' or 'VIDEO'. Omit for both. Returns: JSON with total and an assets array of {asset_id, filename, size_mb, date}, largest first.

Search assets by EXIF metadata fields. Use this when you know specific criteria like city, camera model, or date range. For natural language visual queries (e.g. 'sunset at the beach'), use search_smart instead. For browsing without criteria, use list_assets. Read-only. Args: city: City name from EXIF GPS reverse-geocoding (case-sensitive, e.g. 'Barcelona'). state: State or region name. country: Country name (e.g. 'Spain', 'Egypt'). make: Camera manufacturer (e.g. 'Apple', 'Canon', 'Sony'). model: Camera model string (e.g. 'iPhone 14 Pro', 'EOS R5'). taken_after: ISO date — return only assets captured after this date. taken_before: ISO date — return only assets captured before this date. is_favorite: If true, only return favorites. asset_type: 'IMAGE' or 'VIDEO'. Omit for both. ocr: Text recognized inside the image (tickets, signs, documents). Needs OCR enabled on the server — check with get_capabilities. person_ids: Only assets showing ALL of these people (ids from list_people). tag_ids: Only assets carrying these tags (ids from list_tags). album_ids: Only assets inside these albums. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50). Returns: JSON with total match count, current page, and assets array with IDs, filenames, and dates.

Search for people by name (partial match). Use this when you know the person's name. For browsing all people, use list_people instead. Read-only. Args: name: Full or partial name to match (case-insensitive). with_hidden: Include hidden people in results (default false). Returns: JSON array of matching people with id, name, and photo count.

Look a place name up in Immich's built-in gazetteer (no assets involved). Use this to resolve a spelling or get coordinates for a place before a geographic search. Read-only. Args: name: Place name to look for (e.g. 'Lisbon'). Returns: JSON with a places array of {name, admin1name, admin2name, latitude, longitude}.

Random assets from the library, optionally filtered. Use this for sampling — a quick feel of what a filter matches, a surprise pick for a story, or spot checks over a big library. Read-only. Args: size: How many random assets to return (default 10, max 100). city: Only assets from this city. country: Only assets from this country. make: Only assets from this camera make. model: Only assets from this camera model. is_favorite: If true, only favorites. ocr: Only assets whose recognized text matches (needs OCR on the server). Returns: JSON with the matching assets array.

AI-powered visual search using CLIP embeddings. Use this when describing what a photo looks like in natural language (e.g. 'sunset at the beach', 'dog playing fetch'). For structured criteria (city, camera, date), use search_metadata instead. Requires Immich ML service with Smart Search enabled. Read-only. Args: query: Natural language description of the visual content to find. city: Optional city filter to narrow results geographically. state: Optional state/region filter. country: Optional country filter. taken_after: ISO date — only assets captured after this date. taken_before: ISO date — only assets captured before this date. ocr: Text recognized inside the image, combined with the visual query. Needs OCR enabled on the server — check with get_capabilities. person_ids: Only assets showing ALL of these people (ids from list_people). tag_ids: Only assets carrying these tags (ids from list_tags). album_ids: Only assets inside these albums. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50). Returns: JSON with total count, page, and assets ranked by visual similarity to the query.

Count how many assets match a filter WITHOUT fetching them. Use this instead of search_metadata whenever only the number matters ('how many photos from Spain?', 'how many did I take in 2019?') — it costs one integer instead of pages of assets. Read-only. Args: city: Count assets from this city. country: Count assets from this country. state: Count assets from this state/region. make: Count assets from this camera make. model: Count assets from this camera model. is_favorite: If true, count only favorites. ocr: Count assets whose recognized text matches (needs OCR on the server). created_after: ISO date lower bound on upload date (when it reached Immich). created_before: ISO date upper bound on upload date. taken_after: ISO date lower bound on capture date (when the photo was taken). taken_before: ISO date upper bound on capture date. Returns: JSON {total}.

Distinct values present in the library for one field — the exact spellings search_metadata expects. Use this before filtering by city or camera to avoid guessing (e.g. 'iPhone 14 Pro' vs 'iPhone14,3'). Read-only. Args: suggestion_type: One of 'country', 'state', 'city', 'camera-make', 'camera-model', 'camera-lens-model'. country: Narrow city/state suggestions to this country. state: Narrow city suggestions to this state. make: Narrow model suggestions to this camera make. model: Narrow lens suggestions to this camera model. Returns: JSON with total and a suggestions array of strings.

Apply a tag to multiple assets at once. Use this to bulk-categorize photos (e.g. tag all vacation photos). Side effect: adds tag association to assets. Args: tag_id: The tag UUID to apply (from list_tags or create_tag). asset_ids: List of asset UUIDs to tag. Must not be empty. Returns: JSON with tag_id, count tagged, and per-asset results.

Remove a tag from multiple assets. The tag itself remains; only the association is removed. Side effect: removes tag-to-asset links. Args: tag_id: The tag UUID to remove from assets. asset_ids: List of asset UUIDs to untag. Must not be empty. Returns: JSON with tag_id, count untagged, and per-asset results.

Update an album's name or description. Use this to rename or re-describe an existing album. Side effect: modifies album metadata in Immich. Args: album_id: The album's UUID. name: New album name. Leave empty to keep current name. description: New description. Leave empty to keep current description. Returns: JSON with the updated album object.

Update metadata fields on a specific asset. Use this to fix dates, correct GPS, add descriptions, or change favorite/rating status. Only provided fields are modified. Side effect: permanently changes asset metadata in Immich. Args: asset_id: The asset's UUID. date_time_original: ISO 8601 datetime (e.g. '2019-07-14T15:23:41.000Z'). latitude: GPS latitude, decimal degrees (-90.0 to 90.0). longitude: GPS longitude, decimal degrees (-180.0 to 180.0). description: Free-text description/caption for the asset. is_favorite: Set favorite status (true/false). rating: -1 to reject the photo, or 1 to 5 stars. A rating cannot be cleared from here, and 0 is not a rating Immich 3.x accepts. Returns: JSON with the updated asset object.

Update the same metadata fields on many assets in ONE call — the whole roll of a scanned album gets its real date, a trip's photos get their GPS, a selection becomes favorites. Same fields as update_asset_metadata; only the provided ones change. Side effect: permanently changes the metadata of every listed asset. Args: asset_ids: The assets to update. date_time_original: ISO 8601 datetime applied to all of them. latitude: GPS latitude, decimal degrees. longitude: GPS longitude, decimal degrees. description: Description/caption applied to all of them. is_favorite: Set favorite status on all of them. rating: -1 to reject them, or 1 to 5 stars. A rating cannot be cleared from here, and 0 is not a rating Immich 3.x accepts. Returns: JSON with success and the number of assets updated.

Update the Immich connection credentials. Use this when the API key has been rotated or the server URL changed. Validates credentials before applying. Side effect: persists new credentials to disk and hot-swaps the live connection. Args: base_url: Full Immich server URL including protocol (e.g. 'https://photos.example.com'). api_key: A valid Immich API key (generated in Immich > User Settings > API Keys). Returns: JSON with success status, photo/video counts confirming access, and persistence path.

Update a memory: save it for later, move its date, or mark it seen. Side effect: modifies the memory on the server. Args: memory_id: The memory to update. is_saved: True to save the memory, false to unsave it. memory_at: New ISO date to show the memory on. seen_at: ISO timestamp marking when the user viewed it. Returns: JSON with the updated memory.

Show or hide a partner's photos inside the main timeline (they stay reachable either way). Only works on a partner who shares their library with this account (someone in shared_with_me), because the flag controls how THEIR photos appear in THIS timeline. Side effect: updates the setting on the server. Args: user_id: The partner whose setting changes. in_timeline: True to mix their photos into the timeline, false to keep them separate. Returns: JSON with the updated partner entry.

Update a person's profile details. Use this to name unnamed faces, set birth dates, hide clutter faces, or change the representative thumbnail. Only provided fields are modified. Side effect: changes person metadata in Immich. Args: person_id: The person's UUID. name: Display name (e.g. 'John Smith'). Set to name unnamed face clusters. birth_date: ISO date (e.g. '1990-05-15'). is_hidden: Hide from the People view (useful for strangers/clutter). is_favorite: Mark as a favorite person. feature_face_asset_id: Asset UUID whose face crop becomes the person's thumbnail. color: Hex color label for UI grouping. Returns: JSON with the updated person object.

Update a shared link's permissions or expiry. Use this to tighten/loosen access or set an expiration date. Side effect: changes public link behavior immediately. Args: link_id: The shared link's UUID. allow_download: Allow visitors to download original files. show_metadata: Show EXIF data to visitors. allow_upload: Allow visitors to upload photos to the shared album. description: Link description. Empty string clears it. expiry_at: ISO 8601 expiry datetime. Empty string removes expiry (link never expires). Returns: JSON with the updated shared link object.

Change which asset fronts a stack (the one the library shows). Side effect: updates the stack on the server. Args: stack_id: The stack to update. primary_asset_id: The asset that should become the cover. It must already belong to the stack. Returns: JSON with the updated stack.

Update a tag's color. Side effect: changes apply to all assets using this tag. Immich's API cannot rename a tag (TagUpdateDto only carries `color`); to rename, create_tag with the new name, tag_assets, then delete_tag the old one. Args: tag_id: The tag's UUID. name: Not supported by Immich — passing it returns an error explaining the workaround. color: New hex color (e.g. '#FF5733'). Omit to keep current. Returns: JSON with the updated tag object.

Upload a local photo or video file to Immich. Use this to ingest new media into the library. Constraints: max 25MB, allowed types: jpg, jpeg, png, heic, mp4, mov, gif, webp. Symlinks are rejected for security. The original file is NOT modified or deleted. Side effect: creates a new asset in Immich. Args: file_path: Absolute path to the local file (e.g. '/tmp/photo.jpg'). Must exist. album_id: Optional album UUID to add the uploaded asset to immediately. Returns: JSON with new asset id, filename, size_mb, and album assignment status if applicable.