immich-photo-manager

Args:
    album_id: Target album UUID.
    asset_ids: List of asset UUIDs to add to the album.

Returns: JSON with album_id, count added, and per-asset success/error details.

Args:
    asset_ids: The assets to clear.

Returns: JSON with success, how many assets were cleared, and a failed array
of {asset_id, error}. Success is true only when nothing failed.

Args:
    album_id: The album to comment on.
    comment: The comment text. Leave empty when sending a like.
    asset_id: Attach the comment/like to this asset instead of the album.
    like: True to send a like instead of a comment.

Returns: JSON with the created activity's id and type.

Args:
    name: Album display name (e.g. 'Roma, Italia', 'Birthday 2024').
    description: Optional album description text.
    asset_ids: Optional list of asset UUIDs to add immediately on creation.

Returns: JSON with the new album's id, name, and asset count.

Args:
    memory_at: ISO date the memory is shown on (usually today's month and day).
    year: The past year the memory looks back to (required by Immich).
    asset_ids: Assets to include. May be empty, but an empty memory shows nothing.

Returns: JSON with the created memory's id, type, memory_at, the year it
remembers, is_saved, asset_count and a trimmed assets list (id, filename, date).

Args:
    user_id: The user to share with.

Returns: JSON with the new partner entry.

Args:
    album_id: The album UUID to share publicly.
    allow_download: Allow visitors to download original files (default true).
    show_metadata: Show EXIF data to visitors (default true).
    description: Optional human-readable description for the link.

Returns: JSON with link id, key, album_id, and the full shareable URL.

Args:
    asset_ids: The assets to group, at least two. Order matters: the first is
        the cover.

Returns: JSON with the new stack's id, primary_asset_id and asset list.

Args:
    name: Tag display name (e.g. 'Vacation', 'Family', 'Work'). Must be unique.
    color: Optional hex color for the tag (e.g. '#FF5733').

Returns: JSON with the new tag's id, name, and color.

Args:
    activity_id: The activity to remove (from list_activities).

Returns: JSON confirming the deletion.

Args:
    album_id: The album's UUID to delete.

Returns: JSON with success, the deleted album's id and album_id.

Args:
    asset_ids: List of asset UUIDs to delete.
    force: false (default) = move to trash (recoverable). true = PERMANENTLY delete (no undo).

Returns: JSON with count deleted and whether force was used.

Args:
    memory_id: The memory to delete.

Returns: JSON confirming the deletion.

Args:
    link_id: The shared link's UUID to delete.

Returns: JSON with deleted confirmation and link_id.

Args:
    stack_id: The stack to dissolve.

Returns: JSON confirming the deletion.

Args:
    tag_id: The tag's UUID to delete.

Returns: JSON with success, the deleted tag's id and tag_id.

Args:
    output_path: Where to write the zip (an existing file is refused).
    album_id: Download the whole album.
    asset_ids: Or download just these assets.

Returns: JSON with path, bytes written and how many assets went in, or an error.

Returns: JSON with success confirmation.

Keep the selection coherent: one story per PDF. Never mix unrelated assets
(two videos about different things, photos from different events) just to
show more; if the user's material spans several stories, offer one PDF per
story instead.

Args:
    album_id: Album UUID, or asset_ids: explicit asset UUIDs (exactly one of the two).
    output_path: Where to write (default ~/Desktop/<title>.pdf). Existing files are never overwritten.
    title: Cover title (default: album name or "Immich export <date>").
    captions: {asset_id: text} written after looking at the images.
    layout: 'detail' (one asset per page with its data, default), 'grid' (six per page)
        or 'photobook' (one asset per page, image as large as it fits, caption under
        it; a video with several chosen frames unfolds into one full page per frame).
    frames_per_video: Frames per video, evenly spaced (0-120, default 4; 0 = poster only).
    frame_interval: One frame every N seconds instead of frames_per_video (same 120 cap).
    frame_times: {asset_id: [seconds, ...]} exact moments for specific videos, chosen
        after looking at their frames ("the representative frame"). Wins over
        frames_per_video/frame_interval for the listed videos; others keep the spread.
    frame_captions: {asset_id: [text, ...]} one caption per extracted frame, in frame
        order (photobook prints each on its frame's page; other layouts ignore them).
    image_size: 'original' (default): photos go in at the stored file's quality,
        re-encoded to at most 3000px (a format the server cannot decode, like
        some HEIC, falls back to preview with a note); 'preview' (1440px) or
        'thumbnail' for smaller files.
    frame_size: video frame size in the PDF: 'auto' (default, same as 'preview':
        quality is free inside the PDF) or 'thumbnail' for a smaller file.
    language: 'en' (default) or 'es' for the fixed labels on the pages (Index,
        Places, Camera, page numbers); captions stay in whatever language you wrote.
    map: Draw an OpenStreetMap map on the Places page when assets carry GPS
        (default True; tiles come from tile.openstreetmap.org, the only
        third-party call this server makes — pass map=False to skip it).
    cover, index, places: Include each front-matter page (all default True;
        turn them off for a print-ready photobook of bare pages).
    footer: 'full' (plugin name, server and page number, default), 'pages'
        (just the page number) or 'none'.
    header: Repeat the title at the top of every page except the cover
        (default False).
    videos_position: Where the video pages (frame strips or frame pages) go:
        'mixed' with the photos in the general order (default), 'first' or 'last'.
    order: 'auto' (albums read oldest to newest, like the frames inside a video;
        asset_ids keep the order you passed), 'oldest', 'newest' or 'given'.
    confirm: Only asked for when explicit asset_ids mix videos more than 90 days
        apart (different stories). Pass True only when the user themselves asked
        to mix them; exporting a whole album never needs it.
    limit: Max assets (1-500, default 100).
    return_base64: Also return the PDF bytes (skipped above 2 MB; every MB is
        roughly 350k tokens in the conversation).

Returns: JSON {path, pages, bytes, assets_included, assets_skipped:[{id, reason}], warnings:[...]}.

Args:
    album_id: The album's UUID (from list_albums or create_album).

Returns: JSON with album metadata, a flat list of all asset_ids, and an assets array
(id, filename, type, date, recognized people) so "who appears in this album / who
repeats" can be answered without further calls.

Args:
    album_id: The album's UUID.
    size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'.
    limit: Max thumbnails to return (1-50, default 20).

Returns: A list of image blocks suitable for visual display.

Args:
    album_id: The album's UUID.
    size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'.
    limit: Max thumbnails to return (1-50, default 20).

Returns: JSON with album info and thumbnails array (each with asset_id, base64 data, filename, date).

Args:
    asset_id: The asset's UUID.

Returns: JSON array of face detections (each with face_id, person_id, person_name, bounding box).

Args:
    asset_id: The asset's UUID.
    size: 'thumbnail' (250px, fast) or 'preview' (1440px, higher quality). Default: 'thumbnail'.

Returns: An image block (MCP ImageContent) for visual display.

Args:
    asset_id: The asset's UUID (from search results, album listings, or list_assets).
    with_notes: Also include the plugin's notes on the asset (past review
        verdicts and recorded actions, see get_asset_notes). One extra request.

Returns: JSON with EXIF data, GPS, dates, dimensions, file size, camera
make/model, and owner; plus a `notes` object (reviews and actions) when
with_notes is true.

Args:
    asset_id: The asset to read.

Returns: JSON with asset_id, reviews [{at, verdict, reason}] and
actions [{at, action, detail}].

Args:
    asset_ids: The candidates to check (an album's assets, a search result).

Returns: JSON with checked (how many were asked), annotated (one compact row
per asset that has notes — asset_id, last_verdict, last_reason, last_review_at,
and the reviews/actions counts) and a failed array of {asset_id, error} for the
assets that could not be read. Success is true only when nothing failed.

Args:
    asset_id: The asset's UUID.
    size: 'thumbnail' (250px, fast) or 'preview' (1440px, higher quality). Default: 'thumbnail'.

Returns: JSON with 'data' (base64 string) and 'type' (MIME type, e.g. 'image/jpeg').

Args:
    from_date: ISO date lower bound (e.g. '2026-01-01'). Omit for the server
        default on Immich 3.x; on 2.x an omitted bound means the last 365 days,
        because an open-ended range would walk every month of the library.
    to_date: ISO date upper bound. Omit for the server default.
    heatmap_type: 'Taken' (capture date, default) or 'Upload' (when it reached
        Immich; 3.x only).

Returns: JSON with source ('immich' or 'timeline'), total and a series of
{date, count} for the days that have activity, oldest first (a day missing
from the series had nothing).

Returns: JSON with server_version, immich_major, features (the server's own
flags: ocr, smartSearch, facialRecognition, map, trash...) and quirks (plain
sentences about version-specific behaviour the caller should know). When the
API key may not read the feature flags, features is empty and a note says so;
the version and the quirks still come back.

Returns: JSON with base_url and api_key_masked (first 8 + last 4 chars only).

Args:
    album_id: Size the whole album.
    asset_ids: Or size just these assets.

Returns: JSON with total_size_mb, asset_count and the number of archives
Immich would split the download into.

Args:
    album_id: Optional. Restrict to groups that touch this album; each group then also
        reports which of its assets are inside/outside the album.

Returns: JSON array of duplicate groups (each with duplicateId, assets array, and similarity scores).

The result also carries `options`: every choice export_pdf accepts, with its
default. When the user asked for a PDF without saying how they want it, show
them these choices and ask (layout, cover pages, which video moments, captions)
before exporting; when they did give specs, or just want "a PDF, defaults are
fine", export directly.

Args:
    album_id: Album UUID, or
    asset_ids: Explicit asset UUIDs (search results, a selection).
    limit: Max assets (1-500, default 100).

Returns: JSON {title, count, assets:[...], warnings:[...]} or {"error": ...}.

Args:
    asset_ids: List of asset UUIDs to fetch thumbnails for.
    size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'.
    limit: Max thumbnails to return (1-50, default 20). Only the first N IDs are fetched.

Returns: A list of image blocks suitable for visual display.

Args:
    file_created_after: ISO date lower bound (e.g. '2023-01-01').
    file_created_before: ISO date upper bound.
    is_favorite: If true, only return favorites.

Returns: JSON with total count and markers array (each with asset ID, lat, lon).

Args:
    person_id: The person's UUID (from list_people or search_people).

Returns: JSON with person details (id, name, birthDate, isHidden, photoCount, thumbnailPath).

Args:
    person_id: The person's UUID.

Returns: JSON with 'data' (base64 string of face crop) and 'type' (MIME type).

Returns: JSON with major, minor, and patch version numbers.

Args:
    link_id: The shared link's UUID (from list_shared_links).

Returns: JSON with link details, permissions, expiry date, and associated assets/album.

Args:
    stack_id: The stack to fetch.

Returns: JSON with id, primary_asset_id and the asset list.

Returns: JSON with total photo count, video count, and storage usage in bytes.

Args:
    tag_id: The tag's UUID (from list_tags).

Returns: JSON with tag id, name, color, and usage count.

Args:
    asset_ids: List of asset UUIDs to fetch thumbnails for.
    size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'.
    limit: Max thumbnails to return (1-50, default 20). Only the first N IDs are fetched.

Returns: JSON with thumbnails array (each with asset_id, base64 data, filename, date).

Args:
    time_bucket: The bucket key exactly as get_timeline_buckets returned it
        (e.g. '2026-03-01').
    album_id: Only assets in this album.
    person_id: Only assets showing this person.
    tag_id: Only assets carrying this tag.
    is_favorite: If true, only favorites.

Returns: JSON with an assets array; each row has asset_id, date, is_image,
is_favorite, duration, city and country.

Args:
    album_id: Only count assets in this album.
    person_id: Only count assets showing this person.
    tag_id: Only count assets carrying this tag.
    is_favorite: If true, only count favorites.
    order: 'desc' for newest month first (the default), 'asc' for oldest first.

Returns: JSON with total_buckets and a buckets array of {timeBucket, count},
newest month first unless order='asc'.

Args:
    asset_id: The video asset's UUID.
    count: Frames evenly spaced over the segment (default 6). Ignored when interval > 0.
    size: 'thumbnail' (250px, ~1.6k tokens per frame) or 'preview' (1440px, ~6.4k). Default 'thumbnail'.
    start: Segment start in seconds (default 0).
    end: Segment end in seconds (0 = to the end).
    interval: One frame every N seconds instead of count (1 = one per second, the maximum granularity).
    confirm: Required (true) when more than 12 frames would be produced; ask the user first.
    sheet: Pack the frames into contact sheets (30 per image, timestamps burned in):
        a long video becomes one or two images instead of dozens, so no
        confirmation is needed. Use it to skim, then cut the moments that matter.

Returns: JPEG image blocks in time order, or JSON (confirmation plan / error).

Args:
    asset_id: The video asset's UUID.
    count: Frames evenly spaced over the segment (default 6). Ignored when interval > 0.
    size: 'thumbnail' (250px, ~1.6k tokens per frame) or 'preview' (1440px, ~6.4k). Default 'thumbnail'.
    start: Segment start in seconds (default 0).
    end: Segment end in seconds (0 = to the end).
    interval: One frame every N seconds instead of count (1 = one per second, the maximum granularity).
    confirm: Required (true) when more than 12 frames would be produced; ask the user first.

Returns: JSON {asset_id, duration, backend, count, frames:[{timestamp, data, type}]},
a confirmation plan {confirm_required, frames_planned, estimated_tokens, ...}, or {"error": ...}.

Args:
    album_id: The album whose activity to read.
    asset_id: Only activity on this asset within the album.
    activity_type: 'comment' or 'like'. Omit for both.

Returns: JSON with total and an activities array (id, type, comment, asset_id,
user name, created_at).

Args:
    shared: true = only shared albums, false = only non-shared, omit = all albums.
    name_contains: Only albums whose name contains this text (case-insensitive). Omit for all.
    page: Page number, starting from 1 (default 1). Only used when size is given.
    size: Albums per page (1-500). Omit or 0 = every album in one response (the default).
    compact: true = only id, albumName and assetCount per album (smaller response).

Returns: JSON with total count (after the filter), the albums array (each with id, name,
description, assetCount, shared status), and page/size/pages when paging.

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.

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).

Returns: JSON with shared_with_me and shared_by_me arrays
(id, name, email, in_timeline).

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).

Returns: JSON with total count and links array (each with id, key, type, description, album info).

Args:
    primary_asset_id: Only the stack fronted by this asset.

Returns: JSON with total and a stacks array (id, primary_asset_id, assets).

Returns: JSON with total count and tags array (each with id, name, color).

Returns: JSON with total and a users array of {id, name, email}.

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.

Returns: JSON with 'server' status ('pong' if healthy).

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.

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.

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.

Args:
    user_id: The user to unshare with.

Returns: JSON confirming the removal.

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.

Args:
    asset_ids: List of asset UUIDs currently in trash to restore.

Returns: JSON with count of restored assets.

Returns: JSON with success confirmation.

Args:
    lat: Latitude in decimal degrees.
    lon: Longitude in decimal degrees.

Returns: JSON with total and a places array of {city, state, country} candidates.

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.

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.

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.

Returns: JSON with a cities array of {city, country, asset_id, date}.

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.

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.

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.

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.

Args:
    name: Place name to look for (e.g. 'Lisbon').

Returns: JSON with a places array of {name, admin1name, admin2name, latitude,
longitude}.

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.

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.

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}.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.