# Gumnut AI

> Gumnut is an AI-powered, open alternative to Google and Apple Photos.  Curate and organize your photos with agentic AI. Transform your photos with simple text prompts.  Leverage the ecosystem of integrations to do anything you can imagine.

## Docs

- [Get album asset details](https://docs.gumnut.ai/api-reference/album-assets/get-album-asset-details.md): Retrieves details for a specific album-asset link.
- [List album assets](https://docs.gumnut.ai/api-reference/album-assets/list-album-assets.md): Retrieves a paginated list of album-asset links, ordered by creation time, descending. Can be filtered by album_id, asset_id, or specific album-asset IDs.
- [Add assets to album](https://docs.gumnut.ai/api-reference/albums/add-assets-to-album.md): Adds one or more existing assets to a specific album. Assets must be in the same library as the album. Duplicate assets are ignored.
- [Create a new album](https://docs.gumnut.ai/api-reference/albums/create-a-new-album.md): Creates a new, empty album with optional name and description in the specified library.
- [Delete album](https://docs.gumnut.ai/api-reference/albums/delete-album.md): Deletes a specific album. Note: This does not delete the assets within the album.
- [Get album details](https://docs.gumnut.ai/api-reference/albums/get-album-details.md): Retrieves details for a specific album.
- [List albums](https://docs.gumnut.ai/api-reference/albums/list-albums.md): Retrieves a paginated list of albums from the specified library, ordered by creation time, descending. Can be filtered by asset_id or specific album IDs.
- [Remove assets from album](https://docs.gumnut.ai/api-reference/albums/remove-assets-from-album.md): Removes one or more assets from a specific album. Note: This does not delete the assets themselves.
- [Update album details](https://docs.gumnut.ai/api-reference/albums/update-album-details.md): Updates the name and/or description of a specific album.
- [Create API key](https://docs.gumnut.ai/api-reference/api-keys/create-api-key.md): Creates a new API key for the current user
- [Delete API key](https://docs.gumnut.ai/api-reference/api-keys/delete-api-key.md): Deletes a specific API key
- [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
- [Update API key](https://docs.gumnut.ai/api-reference/api-keys/update-api-key.md): Updates the name of a specific API key
- [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.
- [Delete asset](https://docs.gumnut.ai/api-reference/assets/delete-asset.md): Deletes a specific asset and its associated data (including the file from storage).
- [Get asset counts](https://docs.gumnut.ai/api-reference/assets/get-asset-counts.md): Returns asset counts grouped by time period. Supports optional filtering by album, person, or date range. Results are ordered by time bucket descending.
- [Get asset metadata](https://docs.gumnut.ai/api-reference/assets/get-asset-metadata.md): Retrieves detailed metadata for a specific asset, including EXIF information, asset metrics, faces, and people.
- [List assets](https://docs.gumnut.ai/api-reference/assets/list-assets.md): Retrieves a paginated list of assets from the specified library, optionally filtered by album, person, or specific asset IDs. Asset data includes metrics, EXIF data, faces, and people. Assets are ordered by local creation time, descending.
- [Upload a new asset](https://docs.gumnut.ai/api-reference/assets/upload-a-new-asset.md): Uploads a new asset file (image or video) along with its metadata to the specified library. If no library_id is provided and the user only has one library, uses that library.  If the user has multiple libraries, library_id is required.
- [List entity change events](https://docs.gumnut.ai/api-reference/events/list-entity-change-events.md): Retrieves a list of entity change events for syncing.
- [Delete face](https://docs.gumnut.ai/api-reference/faces/delete-face.md): Deletes a specific face entry. This does not delete the associated asset or person.
- [Get face details](https://docs.gumnut.ai/api-reference/faces/get-face-details.md): Retrieves details for a specific face.
- [List faces](https://docs.gumnut.ai/api-reference/faces/list-faces.md): Retrieves a paginated list of faces, optionally filtered by asset, person, or specific face IDs, ordered by creation time, descending.
- [Update face details](https://docs.gumnut.ai/api-reference/faces/update-face-details.md): Updates the details of a specific face, currently only supporting associating/disassociating with a person.
- [Create a new library](https://docs.gumnut.ai/api-reference/libraries/create-a-new-library.md): Creates a new library for the authenticated user.
- [Delete library](https://docs.gumnut.ai/api-reference/libraries/delete-library.md): Deletes a library and all its associated data (assets, albums, people, faces). Cannot delete the user's only library.
- [Get library details](https://docs.gumnut.ai/api-reference/libraries/get-library-details.md): Returns details of a specific library owned by the authenticated user.
- [List user's libraries](https://docs.gumnut.ai/api-reference/libraries/list-users-libraries.md): Returns all libraries owned by the authenticated user.
- [Update library](https://docs.gumnut.ai/api-reference/libraries/update-library.md): Updates the name and/or description of a library owned by the authenticated user.
- [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.
- [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.
- [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.
- [Create a new person](https://docs.gumnut.ai/api-reference/people/create-a-new-person.md): Creates a new person entry.
- [Delete person](https://docs.gumnut.ai/api-reference/people/delete-person.md): Deletes a specific person. Orphaned faces will be re-clustered in the next clustering pass.
- [Get person details](https://docs.gumnut.ai/api-reference/people/get-person-details.md): Retrieves details for a specific person.
- [List people](https://docs.gumnut.ai/api-reference/people/list-people.md): Retrieves a paginated list of people, ordered by creation time, descending.
- [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 deleted. The primary person's centroid embedding is recalculated.
- [Update person details](https://docs.gumnut.ai/api-reference/people/update-person-details.md): Updates the details of a specific person.
- [Search assets](https://docs.gumnut.ai/api-reference/search/search-assets.md): Searches for assets using semantic similarity and/or metadata filters. Results include asset metadata, faces, and people. At least one search criterion must be provided.
- [Search assets](https://docs.gumnut.ai/api-reference/search/search-assets-1.md): Searches for assets using semantic similarity and/or metadata filters. Results include asset metadata, faces, and people. At least one search criterion must be provided. Can search by text query, uploaded image, or both combined.
- [Ping](https://docs.gumnut.ai/api-reference/server/ping.md): Unauthenticated health-check endpoint for uptime monitoring. Returns 'pong'.
- [Get Asset Tasks](https://docs.gumnut.ai/api-reference/tasks/get-asset-tasks.md): Get all background tasks for a specific asset.
- [Get Task Status](https://docs.gumnut.ai/api-reference/tasks/get-task-status.md): Get the status of a background task by its ID.
- [List Tasks](https://docs.gumnut.ai/api-reference/tasks/list-tasks.md): List background tasks with optional filtering.
- [Get current user](https://docs.gumnut.ai/api-reference/users/get-current-user.md): Returns information about the authenticated user making the request.
- [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
- [Pagination & Filtering](https://docs.gumnut.ai/guides/apis/pagination-and-filtering.md): Paginate, filter, and sort results from the Gumnut API
- [Rate Limiting](https://docs.gumnut.ai/guides/apis/rate-limiting.md): Understand and handle rate limits for the Gumnut API
- [Requests & Responses](https://docs.gumnut.ai/guides/apis/requests-and-responses.md): Request format, response structure, and error handling for the Gumnut API
- [Webhooks](https://docs.gumnut.ai/guides/apis/webhooks.md): Real-time event notifications for your Gumnut integration
- [API Keys](https://docs.gumnut.ai/guides/authentication/api-keys.md): Create and manage API keys for authenticating with the Gumnut API
- [OAuth 2.1](https://docs.gumnut.ai/guides/authentication/oauth.md): Authenticate with the Gumnut API using OAuth 2.1 for user-facing applications
- [Authentication](https://docs.gumnut.ai/guides/authentication/overview.md): Overview of authentication methods for the Gumnut API
- [Introduction](https://docs.gumnut.ai/guides/getting-started/introduction.md): Welcome to Gumnut - the platform for photo intelligence
- [Quickstart](https://docs.gumnut.ai/guides/getting-started/quickstart.md): Get up and running with Gumnut in minutes
- [Immich Compatibility](https://docs.gumnut.ai/guides/immich/compatibility.md): Supported features, known differences, and how Gumnut compares to the official Immich server
- [Immich Overview](https://docs.gumnut.ai/guides/immich/overview.md): Use Immich apps and tools with Gumnut's AI-powered photo platform
- [Immich Troubleshooting](https://docs.gumnut.ai/guides/immich/troubleshooting.md): Troubleshooting Gumnut-specific issues when using Immich apps
- [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
- [SDKs Overview](https://docs.gumnut.ai/guides/sdks/overview.md): Native SDKs for easy integration with Gumnut
- [Python SDK](https://docs.gumnut.ai/guides/sdks/python.md): Official Python SDK for the Gumnut API
- [TypeScript SDK](https://docs.gumnut.ai/guides/sdks/typescript.md): Official TypeScript/JavaScript SDK for the Gumnut API

## OpenAPI Specs

- [openapi](https://api.gumnut.ai/openapi.json)

## Optional

- [Gumnut Home](https://www.gumnut.ai)