# Gumnut AI > Gumnut is an AI-powered, open alternative to Google and Apple Photos — and an open platform for building on your library through a REST API, native SDKs, a hosted MCP server, and Immich compatibility. - [Introduction](https://docs.gumnut.ai/guides/getting-started/introduction.md): Welcome to Gumnut - the open, agent-native platform for photo intelligence - [Quickstart](https://docs.gumnut.ai/guides/getting-started/quickstart.md): Get up and running with Gumnut in minutes - [Import from Google Photos or iCloud](https://docs.gumnut.ai/guides/getting-started/import-from-google-or-apple.md): Export your cloud photo library, upload it to Gumnut, and understand which metadata travels with it - [Libraries and sharing](https://docs.gumnut.ai/guides/product/libraries.md): Keep collections separate or work together on the same photos, albums, and people - [Uploads and processing](https://docs.gumnut.ai/guides/product/uploads.md): Add files, folders, or your phone's photos and understand what happens after upload - [Albums](https://docs.gumnut.ai/guides/product/albums.md): Organize photos and videos into collections without duplicating their files - [Searching and filtering](https://docs.gumnut.ai/guides/product/search-and-filtering.md): Find photos by content, people, dates, albums, location, and favorites - [Faces and people](https://docs.gumnut.ai/guides/product/people.md): Find people across your library and correct or add face assignments - [Map view](https://docs.gumnut.ai/guides/product/map.md): Explore where your photos were taken and combine location with other filters - [Stacks and bursts](https://docs.gumnut.ai/guides/product/stacks.md): Group related shots automatically or manually while keeping every photo - [Photo editing and versions](https://docs.gumnut.ai/guides/product/editing.md): Crop, rotate, and mirror photos while preserving the original upload - [AI assistants and integrations](https://docs.gumnut.ai/guides/product/ai-assistants.md): Let an assistant search, curate, inspect, and organize your photo library - [Duplicate Detection](https://docs.gumnut.ai/guides/product/duplicate-detection.md): Learn how Gumnut avoids storing exact duplicate photo and video uploads - [Authentication](https://docs.gumnut.ai/guides/authentication/overview.md): Choose the supported authentication method for Gumnut - [API Keys](https://docs.gumnut.ai/guides/authentication/api-keys.md): Create and manage API keys for authenticating with the Gumnut API - [OAuth](https://docs.gumnut.ai/guides/authentication/oauth.md): How user-facing integrations authenticate with Gumnut through Clerk - [API Overview](https://docs.gumnut.ai/guides/apis/overview.md): Get started with the Gumnut REST API — explore resources and make your first API calls - [Versioning and editing assets](https://docs.gumnut.ai/guides/apis/asset-versioning.md): Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API - [Named Creates and Retries](https://docs.gumnut.ai/guides/apis/named-creates.md): Safely retry album, person, and library creation when a request may have succeeded - [Library Sharing](https://docs.gumnut.ai/guides/apis/library-sharing.md): Library roles, invitation and membership contracts, and credential scope - [People and Faces](https://docs.gumnut.ai/guides/apis/faces-and-people.md): Use the Gumnut API to review face detections, add manual face boxes, and manage people assignments - [Requests & Responses](https://docs.gumnut.ai/guides/apis/requests-and-responses.md): Request format, response structure, and error handling for the Gumnut API - [Pagination & Filtering](https://docs.gumnut.ai/guides/apis/pagination-and-filtering.md): Paginate, filter, and sort results from the Gumnut API - [Syncing with Events](https://docs.gumnut.ai/guides/apis/syncing-with-events.md): Keep a local copy of a Gumnut library up to date by reading the events feed - [Rate Limiting](https://docs.gumnut.ai/guides/apis/rate-limiting.md): Understand and handle rate limits for the Gumnut API - [SDKs Overview](https://docs.gumnut.ai/guides/sdks/overview.md): Choose an official Gumnut SDK for Python or TypeScript - [TypeScript SDK](https://docs.gumnut.ai/guides/sdks/typescript.md): Use the official TypeScript and JavaScript SDK for the Gumnut API - [Python SDK](https://docs.gumnut.ai/guides/sdks/python.md): Use the official Python SDK for the Gumnut API - [MCP Overview](https://docs.gumnut.ai/guides/mcp/overview.md): Model Context Protocol server for AI-powered Gumnut integration - [MCP Setup](https://docs.gumnut.ai/guides/mcp/setup.md): Configure Gumnut MCP server in Claude Code, Cursor, ChatGPT, and Claude Web - [MCP Troubleshooting](https://docs.gumnut.ai/guides/mcp/troubleshooting.md): Troubleshooting common issues with the Gumnut MCP server - [Immich Overview](https://docs.gumnut.ai/guides/immich/overview.md): Use Immich apps and tools with Gumnut's AI-powered photo platform - [Immich Compatibility](https://docs.gumnut.ai/guides/immich/compatibility.md): Supported features, known differences, and how Gumnut compares to the official Immich server - [Faces and People](https://docs.gumnut.ai/guides/immich/faces-and-people.md): How Gumnut groups faces into People, and how that differs from Immich - [Immich Troubleshooting](https://docs.gumnut.ai/guides/immich/troubleshooting.md): Troubleshooting Gumnut-specific issues when using Immich apps - [Demos](https://docs.gumnut.ai/guides/demos/overview.md): Standalone reference integrations that consume the Gumnut Photos API - [Monthly progress](https://docs.gumnut.ai/changelog/overview.md): A high-level summary of what shipped in Gumnut each month - [Detailed changelog](https://docs.gumnut.ai/changelog/detailed.md): An itemized changelog of user- and developer-facing changes to Gumnut - [Generate OAuth authorization URL](https://docs.gumnut.ai/api-reference/oauth/generate-oauth-authorization-url.md): Generate OAuth authorization URL with state and nonce for CSRF and replay attack protection. State is stored with TTL for validation. - [Exchange OAuth code for JWT](https://docs.gumnut.ai/api-reference/oauth/exchange-oauth-code-for-jwt.md): Exchange OAuth authorization code for application JWT after validating state, nonce, and ID token signature. User is retrieved from or created in the database and details added to the JWT. First-time provisioning returns 401 if the Clerk identity was deleted, 409 if it conflicts with a retained acco… - [Get OAuth provider logout endpoint](https://docs.gumnut.ai/api-reference/oauth/get-oauth-provider-logout-endpoint.md): Returns the OAuth provider's logout endpoint URL from OIDC discovery. This can be used to redirect users to logout from the OAuth provider after logging out locally. - [List assets in a library](https://docs.gumnut.ai/api-reference/assets/list-assets-in-a-library.md): Returns a paginated list of assets ordered by local capture time (or trash time for trashed assets), newest first by default, optionally filtered by album, person, rating, media type, date range, geographic area, or asset ID. Use this tool for structured browsing and filtering — when the request can… - [Upload a new asset](https://docs.gumnut.ai/api-reference/assets/upload-a-new-asset.md): Uploads a new asset (image or video) and its metadata as multipart form data, returning the created asset with 201. Uploads are deduplicated per library by the file's SHA-256 checksum: re-uploading a file whose bytes already exist in the target library stores nothing and returns the existing asset w… - [Permanently delete assets](https://docs.gumnut.ai/api-reference/assets/permanently-delete-assets.md): Hard-deletes each specified asset — the database record, the stored file, and all associated data (faces, album links, etc.). **Irreversible.** Prefer `trash_assets` for the user's standard delete action so accidents can be recovered. - [Get asset counts](https://docs.gumnut.ai/api-reference/assets/get-asset-counts.md): Counts assets bucketed by time period — use this to summarize a library (or a filtered slice) without paging through the full timeline. Returns one row per bucket, newest-first by default or oldest-first when `order=asc`, with optional filtering by album, album membership, people, rating, media type… - [Cluster assets by map location](https://docs.gumnut.ai/api-reference/assets/cluster-assets-by-map-location.md): Clusters geotagged assets in a map viewport (bounding box) onto a grid of square cells and returns one entry per non-empty cell — its centroid, asset count, and a representative cover asset. Use this to render a clustered map or to count how many photos fall in each part of a viewport at a chosen zo… - [Check asset existence](https://docs.gumnut.ai/api-reference/assets/check-asset-existence.md): Checks which assets exist in the user's library based on checksums or device identifiers. Provide exactly one of: checksums, checksum_sha1s, or (deviceId AND deviceAssetIds). List parameters are limited to 5000 items. - [Move assets to trash](https://docs.gumnut.ai/api-reference/assets/move-assets-to-trash.md): Soft-deletes the given assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window. **Reversible** via `restore_assets` until purge. - [Restore assets from trash](https://docs.gumnut.ai/api-reference/assets/restore-assets-from-trash.md): Restores trashed assets so they reappear in default list/search results. Idempotent — assets that are already live are silently skipped. - [Move assets to another library](https://docs.gumnut.ai/api-reference/assets/move-assets-to-another-library.md): Moves the given assets from one library to another, keeping their IDs and stored files. The caller must own the source library and either own the destination library or be a collaborator on it. A scoped credential must cover both libraries and allow both `delete_permanently` and `write`. Moved asset… - [Empty trash](https://docs.gumnut.ai/api-reference/assets/empty-trash.md): Permanently deletes every trashed asset and its associated stored data from the caller's library. **Irreversible**. - [Get an asset](https://docs.gumnut.ai/api-reference/assets/get-an-asset.md): Fetches one asset and its associated metadata by ID. Use this when you already have a specific asset ID (e.g., from `list_assets`, `search_assets`, or `list_album_assets`) and need its full details. For bulk fetch of multiple known IDs, prefer `list_assets` with the `ids` parameter to avoid N round… - [Permanently delete an asset](https://docs.gumnut.ai/api-reference/assets/permanently-delete-an-asset.md): Deletes the asset entirely — the database record, the stored file, and all associated data (faces, album links, etc.). **Irreversible.** Prefer `trash_assets` for the user's standard delete action so accidents can be recovered. - [Update an asset](https://docs.gumnut.ai/api-reference/assets/update-an-asset.md): Edits the user-editable metadata for a single asset — description, rating, GPS coordinates, and original capture datetime. Rating accepts 0-5, where 0 explicitly marks the asset unrated; passing null clears the USER override. Only fields included in the request body are changed; others are left unto… - [Update metadata on multiple assets](https://docs.gumnut.ai/api-reference/assets/update-metadata-on-multiple-assets.md): Updates metadata on multiple assets in one transactional call. Each item carries the target asset id and the per-asset change — different fields can be changed on different assets in the same request. Atomic: any per-item validation failure or unknown / cross-user id rejects the whole batch and writ… - [List an asset's versions](https://docs.gumnut.ai/api-reference/assets/list-an-assets-versions.md): Returns every retained rendering of one asset, ordered by `position` ascending — the uploaded original first, the current rendering last. Not paginated. Each entry's `version_urls` follows the same `include` semantics as an asset's `asset_urls`: lean `thumbnail` by default, `include=variants` for th… - [Append an asset version](https://docs.gumnut.ai/api-reference/assets/append-an-asset-version.md): Uploads a fully rendered image — with all edits already applied to its pixels — above the original version. An append is accepted only while the original is current; replace the current derived version through its replacement endpoint instead. Exact duplicates store nothing. Metadata is copied from… - [Replace the current derived asset version](https://docs.gumnut.ai/api-reference/assets/replace-the-current-derived-asset-version.md): Uploads a fully rendered image and replaces the version named in the path. That version must still be the current non-original version; the server infers its parent. Exact duplicates store nothing. Metadata is copied from the original, so retained bytes may differ from uploaded bytes. - [Delete the asset's current derived version](https://docs.gumnut.ai/api-reference/assets/delete-the-assets-current-derived-version.md): Irreversibly deletes the current non-original version and restores its predecessor. The original returns 422; a buried version returns 409. - [Revert an asset to a retained version](https://docs.gumnut.ai/api-reference/assets/revert-an-asset-to-a-retained-version.md): Makes a retained version current and irreversibly deletes its descendants. Reverting to the current version is a no-op. - [List album-asset link records](https://docs.gumnut.ai/api-reference/album-assets/list-album-asset-link-records.md): Returns paginated *link* records (lightweight join rows between albums and assets) describing which assets are in which albums — each row contains `album_id` + `asset_id` + link timestamps, not the full asset or album metadata. Use this when you specifically need the junction records (for sync or ch… - [Get an album-asset link record](https://docs.gumnut.ai/api-reference/album-assets/get-an-album-asset-link-record.md): Fetches one album-asset link record by ID (the junction row between an album and an asset). Rarely needed directly; most callers want `get_asset` or `get_album` instead. - [List albums in a library](https://docs.gumnut.ai/api-reference/albums/list-albums-in-a-library.md): Returns a paginated list of albums ordered by creation time (newest first), optionally filtered by name, asset membership or ID. Use this to enumerate a user's albums or to find which albums contain a specific asset (via `asset_id`). - [Create an album](https://docs.gumnut.ai/api-reference/albums/create-an-album.md): Creates an empty album, or reuses a matching album without changing it. The API checks names within the library, ignoring case and surrounding whitespace. Returns 201 for a new record or 200 for an existing matching name. Only supplied create fields must match; omitted fields leave existing values i… - [Get an album](https://docs.gumnut.ai/api-reference/albums/get-an-album.md): Fetches one album's metadata by ID (name, description, cover, counts). Use when you already have an album ID. The JSON response is metadata only and does not include the album's assets — to get the asset IDs or data, use `list_album_assets` or `list_assets` with `album_id`. - [Delete an album](https://docs.gumnut.ai/api-reference/albums/delete-an-album.md): Deletes the album itself. Assets that were in the album remain in the library — only the album and its asset-links are removed. Use `trash_assets` to soft-delete the underlying assets, or `remove_assets_from_album` to detach specific assets from an album you want to keep. - [Update an album](https://docs.gumnut.ai/api-reference/albums/update-an-album.md): Updates album metadata (name, description, and/or cover). Changes overwrite current metadata; there is no automatic undo. Omitted fields and a null name are unchanged; a null description or cover clears that field. Does not delete the album or its assets. Renaming to another record's name in the sam… - [Add existing assets to an album](https://docs.gumnut.ai/api-reference/albums/add-existing-assets-to-an-album.md): Adds one or more existing assets to the specified album. Assets must already be in the same library as the album (this tool does not upload new assets). Assets already in the album are silently skipped and returned separately as `duplicate_assets`; missing or different-library IDs are skipped and re… - [Remove assets from an album](https://docs.gumnut.ai/api-reference/albums/remove-assets-from-an-album.md): Detaches one or more assets from the given album. The assets themselves remain in the library and in any other albums they belong to. Use `trash_assets` to soft-delete the asset entirely. To empty an album completely, call `list_album_assets` to get the links and then remove them, or delete the albu… - [Stream entity change events](https://docs.gumnut.ai/api-reference/events/stream-entity-change-events.md): Returns a paginated stream of change events (create/update/delete) for entities in the library. Each event is a lightweight record — `entity_type`, `entity_id`, `event_type`, and timestamps — pointing at a concrete entity that has changed. Follow up with `list_assets`, `get_album`, `get_person`, or… - [List library invitations](https://docs.gumnut.ai/api-reference/library-invitations/list-library-invitations.md): List invitation metadata across libraries owned by the caller, newest first. Secrets are never included. - [Create a library invitation](https://docs.gumnut.ai/api-reference/library-invitations/create-a-library-invitation.md): Issue an invitation for one library. An identical active policy returns the same link with 200; a new policy returns 201. A matching inactive invitation returns 409 without a link; retry with a new policy. Authentication provider outages return 503; retry sign-in later. - [Get a library invitation link](https://docs.gumnut.ai/api-reference/library-invitations/get-a-library-invitation-link.md): Return an active invitation's existing link without changing its policy or usage. Inactive invitations return 409 without a link; retrying unchanged cannot reactivate one. - [Disable a library invitation](https://docs.gumnut.ai/api-reference/library-invitations/disable-a-library-invitation.md): Prevent future admissions through this invitation without removing existing members. Repeating disablement returns the same inactive record. - [Preview a library invitation](https://docs.gumnut.ai/api-reference/library-invitations/preview-a-library-invitation.md): Return library attribution and the caller's current eligibility without admitting them or reserving a place. Invalid secrets and unavailable libraries return the same generic 404; retry with a valid, available invitation link. - [Join a library through an invitation](https://docs.gumnut.ai/api-reference/library-invitations/join-a-library-through-an-invitation.md): Admit the caller atomically or return their unchanged existing access. Retrying an uncertain join unchanged consumes no additional place. Invalid secrets or unavailable libraries return a generic 404; retry with a valid, available link. Expired, disabled, exhausted, or removal-cutoff invitations ret… - [List library members](https://docs.gumnut.ai/api-reference/libraries/list-library-members.md): List non-owner membership records for a library owned by the caller, newest first. Inactive records remain available through the state filter. - [Remove a library member](https://docs.gumnut.ai/api-reference/libraries/remove-a-library-member.md): End a non-owner membership while retaining its owner-removal cutoff. Repeating removal returns the same record without advancing the cutoff. The owner cannot be removed; retrying that request unchanged returns 409. - [Change a library member's role](https://docs.gumnut.ai/api-reference/libraries/change-a-library-members-role.md): Change an active non-owner member's role. Repeating the same role is unchanged. An inactive membership or attempt to change the owner returns 409; retrying unchanged will not clear it. - [Leave a library](https://docs.gumnut.ai/api-reference/libraries/leave-a-library.md): End the caller's own non-owner membership, even when library content is unavailable. Repeating departure returns the existing inactive state without changing an owner-removal cutoff. An owner cannot leave; retrying unchanged returns 409. - [List libraries](https://docs.gumnut.ai/api-reference/libraries/list-libraries.md): Returns owned and joined libraries accessible to the authenticated user (no pagination — users typically have one or a handful). Call this when another tool's `library_id` parameter is required but you don't yet know which libraries exist. A single-library user can usually omit `library_id` on other… - [Create a library](https://docs.gumnut.ai/api-reference/libraries/create-a-library.md): Creates an empty library, or reuses a matching live library without changing it. The API checks names within the owning user's account, including trashed libraries, ignoring case and surrounding whitespace. Returns 201 for a new record or 200 for an existing matching name. Only supplied create field… - [Get a library](https://docs.gumnut.ai/api-reference/libraries/get-a-library.md): Fetches one library's metadata by ID. Returns the library regardless of trash state for owners; members can only access live libraries. - [Expedite purge on a trashed library](https://docs.gumnut.ai/api-reference/libraries/expedite-purge-on-a-trashed-library.md): Expedites the background purge on a **trashed** library: the 90-day undo window is waived and the drain begins claiming this library on the next scheduled tick. Returns immediately; the drain proceeds asynchronously in bounded batches and does not block on completion. `restore_library` still works u… - [Update a library](https://docs.gumnut.ai/api-reference/libraries/update-a-library.md): Renames a library or changes its description. Non-null supplied values overwrite current metadata; there is no automatic undo. Omitted or null fields are unchanged. Library contents (assets, albums, people, faces) are not affected. Renaming to another record's name in the same owning user, including… - [Move a library to trash](https://docs.gumnut.ai/api-reference/libraries/move-a-library-to-trash.md): Moves the library and all its contents into the trash. The library becomes inaccessible by default and can be fully restored within 90 days by calling `restore_library`. After 90 days the library's assets are gradually purged in the background; until the library row itself is removed, restore still… - [Restore a library from trash](https://docs.gumnut.ai/api-reference/libraries/restore-a-library-from-trash.md): Restores a previously-trashed library so it reappears in default list/search results. Works as long as the library row still exists — once `get_library` returns 404 the row is gone and restore is no longer possible. If the background drain has already started purging assets, restore succeeds but rec… - [Search assets](https://docs.gumnut.ai/api-reference/search/search-assets.md): Searches for assets by content, ranked by relevance and optionally narrowed by structured filters. Use `list_assets` (GET /api/assets) to browse by structured filters without search text or an image. Use this tool when the user describes *what's in* the photos they want — subjects, scenes, places, a… - [Search assets](https://docs.gumnut.ai/api-reference/search/search-assets-1.md): Searches for assets by content, ranked by relevance and optionally narrowed by structured filters. Use `list_assets` (GET /api/assets) to browse by structured filters without search text or an image. An uploaded `image` finds visually similar photos; when `query` is also provided, both count toward… - [List face detections](https://docs.gumnut.ai/api-reference/faces/list-face-detections.md): Returns a paginated list of individual face detections (with bounding boxes), ordered by creation time (newest first), optionally filtered by asset, person, or ID. Each row is a single face in a single asset — a person with many photos will have many face rows. - [Create a face](https://docs.gumnut.ai/api-reference/faces/create-a-face.md): Adds a user-drawn face box to an asset, for a face the detector missed. To remove a face detection instead, use `delete_face`; to introduce a brand-new identity first, use `create_person`. - [Get a face detection](https://docs.gumnut.ai/api-reference/faces/get-a-face-detection.md): Fetches one face's details by ID (bounding box, assigned person, timestamps, thumbnail). Use when you already have a `face_id`. - [Delete a face detection](https://docs.gumnut.ai/api-reference/faces/delete-a-face-detection.md): Removes one face detection row; the underlying asset and the person this face was assigned to are both preserved. - [Update a face](https://docs.gumnut.ai/api-reference/faces/update-a-face.md): Assigns a face to a specific person, or detaches it from its current person (set `person_id` to null). Use this for 'this face is Alice' or to remove an assignment. Sending the current person ID confirms the assignment as manual without changing the person. - [Report friction using Gumnut](https://docs.gumnut.ai/api-reference/feedback/report-friction-using-gumnut.md): Help improve Gumnut by reporting friction you encounter while using it. Use this for blocked or failed tasks, missing capabilities, confusing behavior or results, workarounds, and improvement suggestions, even when the task ultimately succeeds. Feedback is optional. You may report your own sanitized… - [List people in a library](https://docs.gumnut.ai/api-reference/people/list-people-in-a-library.md): Returns a paginated list of person records, which may be named or unnamed and may have zero or more faces, ordered according to `sort` (newest first by default), optionally filtered by asset, album, name, or ID. - [Create a person](https://docs.gumnut.ai/api-reference/people/create-a-person.md): Creates a person record to group faces, or reuses a matching named person without changing it. Does not delete existing records or move faces. The API checks names within the library, including hidden people, ignoring case and surrounding whitespace. Returns 201 for a new record or 200 for an existi… - [Get a person](https://docs.gumnut.ai/api-reference/people/get-a-person.md): Fetches one person's metadata by ID (name, asset count, thumbnail, etc.). Use this when you already have a `person_id`. The JSON response is metadata only; to get the photos that contain this person, use `search_assets` with `person_ids` or `list_assets` with `person_ids`. - [Delete a person](https://docs.gumnut.ai/api-reference/people/delete-a-person.md): Deletes the person record; the faces that were attached to this person are not deleted — they become unassigned and will be re-clustered on the next clustering pass. - [Update a person](https://docs.gumnut.ai/api-reference/people/update-a-person.md): Updates a person's name, birth date, visibility, favorite status, or thumbnail. Supplied values overwrite current metadata; there is no automatic undo. Omitted fields are unchanged. Does not delete the person or face detections. Renaming to another record's name in the same library, including hidden… - [Update multiple people](https://docs.gumnut.ai/api-reference/people/update-multiple-people.md): Updates name, birth date, visibility, favorite status, or thumbnail on multiple people in one transactional call. Each item carries the target person id and the per-person change — different fields can be changed on different people in the same request. Atomic: a duplicate id, an unknown or inaccess… - [Merge people](https://docs.gumnut.ai/api-reference/people/merge-people.md): Merges one or more source people into the primary person identified by the URL. All faces from source people are reassigned to the primary person. Source people are permanently deleted (this cannot be undone). The primary person's centroid embedding is recalculated. - [List API keys](https://docs.gumnut.ai/api-reference/api-keys/list-api-keys.md): Retrieves a list of all API keys for the current user - [Create API key](https://docs.gumnut.ai/api-reference/api-keys/create-api-key.md): Creates a new API key for the current user - [Revoke API key](https://docs.gumnut.ai/api-reference/api-keys/revoke-api-key.md): Revokes an API key so it can no longer authenticate. The key remains visible as inactive. - [Update API key](https://docs.gumnut.ai/api-reference/api-keys/update-api-key.md): Updates the name of a specific API key - [Ping](https://docs.gumnut.ai/api-reference/server/ping.md): Unauthenticated health-check endpoint for uptime monitoring. Returns 'pong'. - [List stacks in a library](https://docs.gumnut.ai/api-reference/stacks/list-stacks-in-a-library.md): Returns a paginated list of stacks — assets grouped for collapsed display, whether detected automatically or grouped by the user — ordered by `id`: stable, but arbitrary rather than chronological. - [Manually stack assets](https://docs.gumnut.ai/api-reference/stacks/manually-stack-assets.md): Groups two or more existing assets into a new user-owned stack (`origin = user`) for collapsed display. A user-owned stack is never re-segmented by burst re-detection. - [Get a stack](https://docs.gumnut.ai/api-reference/stacks/get-a-stack.md): Fetches one stack's metadata by ID (pinned cover, live member count, provenance). The response is metadata only and does not include the stack's assets — to get its frames, use `list_assets` with `stack_id`. - [Delete a stack (ungroup its frames)](https://docs.gumnut.ai/api-reference/stacks/delete-a-stack-ungroup-its-frames.md): Dissolves the stack: the grouping is removed and every member frame returns to loose, individual display. The photos themselves are untouched — nothing is trashed or deleted from the library; like `remove_assets_from_album`, this only removes an organizational grouping. Use `trash_assets` to soft-de… - [Set a stack's cover](https://docs.gumnut.ai/api-reference/stacks/set-a-stacks-cover.md): Pins one of the stack's own live members as its cover (`primary_asset_id`). Setting a cover marks the stack as user-owned (`origin = user`), which freezes it — membership included — against burst re-detection, so neither the chosen cover nor the frame grouping is ever silently reverted by a later de… - [Add assets to a stack](https://docs.gumnut.ai/api-reference/stacks/add-assets-to-a-stack.md): Adds one or more existing assets to the stack. An asset already in another stack is reconciled exactly as `create_stack` does. Ids already in this stack are silently skipped. - [Remove assets from a stack](https://docs.gumnut.ai/api-reference/stacks/remove-assets-from-a-stack.md): Pulls one or more frames out of the stack. The assets themselves are untouched — they remain in the library (and in any albums) and simply appear as individual photos again. IDs that are not current members of the stack are silently ignored. - [Get task status](https://docs.gumnut.ai/api-reference/tasks/get-task-status.md): Get the status of a background task by its ID. - [Get asset tasks](https://docs.gumnut.ai/api-reference/tasks/get-asset-tasks.md): Get all background tasks for a specific asset. Results are ordered newest first. - [List tasks](https://docs.gumnut.ai/api-reference/tasks/list-tasks.md): List background tasks for the authenticated user with optional filtering. - [Get the current user](https://docs.gumnut.ai/api-reference/users/get-the-current-user.md): Returns the profile of the authenticated user (the caller). Use this at the start of a session to ground subsequent calls (e.g., to confirm the caller's identity before making destructive changes). This tool does not accept a user ID; it always returns the authenticated caller. - [Update the current user](https://docs.gumnut.ai/api-reference/users/update-the-current-user.md): Updates preferences on the authenticated user's own account. Only the fields included in the request body are changed. This endpoint does not accept a user ID; it always updates the authenticated caller. Returns 404, without changing anything, when `immich_library_id` names a library the caller cann… ## OpenAPI Specs - [openapi](https://api.gumnut.ai/openapi.json) ## Optional - [Gumnut Home](https://www.gumnut.ai) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.