openapi: 3.0.0 paths: /activities: get: description: Returns a list of activities for the selected asset or album. The activities are returned in sorted order, with the oldest activities appearing first. operationId: getActivities parameters: - name: albumId required: true in: query description: Album ID schema: format: uuid type: string - name: assetId required: false in: query description: Asset ID (if activity is for an asset) schema: format: uuid type: string - name: level required: false in: query description: Filter by activity level schema: $ref: '#/components/schemas/ReactionLevel' - name: type required: false in: query description: Filter by activity type schema: $ref: '#/components/schemas/ReactionType' - name: userId required: false in: query description: Filter by user ID schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/ActivityResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all activities tags: - Activities x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: activity.read x-immich-state: Stable post: description: Create a like or a comment for an album, or an asset in an album. operationId: createActivity parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ActivityCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ActivityResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create an activity tags: - Activities x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: activity.create x-immich-state: Stable /activities/statistics: get: description: Returns the number of likes and comments for a given album or asset in an album. operationId: getActivityStatistics parameters: - name: albumId required: true in: query description: Album ID schema: format: uuid type: string - name: assetId required: false in: query description: Asset ID (if activity is for an asset) schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ActivityStatisticsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve activity statistics tags: - Activities x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: activity.statistics x-immich-state: Stable /activities/{id}: delete: description: Removes a like or comment from a given album or asset in an album. operationId: deleteActivity parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete an activity tags: - Activities x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: activity.delete x-immich-state: Stable /admin/auth/unlink-all: post: description: Unlinks all OAuth accounts associated with user accounts in the system. operationId: unlinkAllOAuthAccountsAdmin parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Unlink all OAuth accounts tags: - Authentication (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminAuth.unlinkAll x-immich-state: Stable /admin/database-backups: delete: description: Delete a backup by its filename operationId: deleteDatabaseBackup parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/DatabaseBackupDeleteDto' required: true responses: '200': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete database backup tags: - Database Backups (admin) x-immich-admin-only: true x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-permission: backup.delete x-immich-state: Alpha get: description: Get the list of the successful and failed backups operationId: listDatabaseBackups parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/DatabaseBackupListResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List database backups tags: - Database Backups (admin) x-immich-admin-only: true x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-permission: maintenance x-immich-state: Alpha /admin/database-backups/start-restore: post: description: Put Immich into maintenance mode to restore a backup (Immich must not be configured) operationId: startDatabaseRestoreFlow parameters: [] responses: '201': description: '' summary: Start database backup restore flow tags: - Database Backups (admin) x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-state: Alpha /admin/database-backups/upload: post: description: Uploads .sql/.sql.gz file to restore backup from operationId: uploadDatabaseBackup parameters: [] requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/DatabaseBackupUploadDto' description: Backup Upload required: true responses: '201': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Upload database backup tags: - Database Backups (admin) x-immich-admin-only: true x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-permission: backup.upload x-immich-state: Alpha /admin/database-backups/{filename}: get: description: Downloads the database backup file operationId: downloadDatabaseBackup parameters: - name: filename required: true in: path schema: format: string type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Download database backup tags: - Database Backups (admin) x-immich-admin-only: true x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-permission: backup.download x-immich-state: Alpha /admin/maintenance: post: description: Put Immich into or take it out of maintenance mode operationId: setMaintenanceMode parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SetMaintenanceModeDto' required: true responses: '201': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Set maintenance mode tags: - Maintenance (admin) x-immich-admin-only: true x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: maintenance x-immich-state: Alpha /admin/maintenance/detect-install: get: description: Collect integrity checks and other heuristics about local data. operationId: detectPriorInstall parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MaintenanceDetectInstallResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Detect existing install tags: - Maintenance (admin) x-immich-admin-only: true x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-permission: maintenance x-immich-state: Alpha /admin/maintenance/login: post: description: Login with maintenance token or cookie to receive current information and perform further actions. operationId: maintenanceLogin parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/MaintenanceLoginDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/MaintenanceAuthDto' description: '' summary: Log into maintenance mode tags: - Maintenance (admin) x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-state: Alpha /admin/maintenance/status: get: description: Fetch information about the currently running maintenance action. operationId: getMaintenanceStatus parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MaintenanceStatusResponseDto' description: '' summary: Get maintenance mode status tags: - Maintenance (admin) x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Alpha x-immich-state: Alpha /admin/notifications: post: description: Create a new notification for a specific user. operationId: createNotification parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/NotificationCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/NotificationDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a notification tags: - Notifications (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /admin/notifications/templates/{name}: post: description: Retrieve a preview of the provided email template. operationId: getNotificationTemplateAdmin parameters: - name: name required: true in: path schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/TemplateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TemplateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Render email template tags: - Notifications (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /admin/notifications/test-email: post: description: Send a test email using the provided SMTP configuration. operationId: sendTestEmailAdmin parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SystemConfigSmtpDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TestEmailResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Send test email tags: - Notifications (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /admin/users: get: description: Search for users. operationId: searchUsersAdmin parameters: - name: id required: false in: query description: User ID filter schema: format: uuid type: string - name: withDeleted required: false in: query description: Include deleted users schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/UserAdminResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search users tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.read x-immich-state: Stable post: description: Create a new user. operationId: createUserAdmin parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAdminCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a user tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.create x-immich-state: Stable /admin/users/{id}: delete: description: Delete a user. operationId: deleteUserAdmin parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAdminDeleteDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a user tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.delete x-immich-state: Stable get: description: Retrieve a specific user by their ID. operationId: getUserAdmin parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a user tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.read x-immich-state: Stable put: description: Update an existing user. operationId: updateUserAdmin parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAdminUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a user tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.update x-immich-state: Stable /admin/users/{id}/preferences: get: description: Retrieve the preferences of a specific user. operationId: getUserPreferencesAdmin parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserPreferencesResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user preferences tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.read x-immich-state: Stable put: description: Update the preferences of a specific user. operationId: updateUserPreferencesAdmin parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UserPreferencesUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserPreferencesResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update user preferences tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.update x-immich-state: Stable /admin/users/{id}/restore: post: description: Restore a previously deleted user. operationId: restoreUserAdmin parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Restore a deleted user tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.delete x-immich-state: Stable /admin/users/{id}/sessions: get: description: Retrieve all sessions for a specific user. operationId: getUserSessionsAdmin parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SessionResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user sessions tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminSession.read x-immich-state: Stable /admin/users/{id}/statistics: get: description: Retrieve asset statistics for a specific user. operationId: getUserStatisticsAdmin parameters: - name: id required: true in: path schema: format: uuid type: string - name: isFavorite required: false in: query description: Filter by favorite status schema: type: boolean - name: isTrashed required: false in: query description: Filter by trash status schema: type: boolean - name: visibility required: false in: query description: Filter by visibility schema: $ref: '#/components/schemas/AssetVisibility' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetStatsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user statistics tags: - Users (admin) x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: adminUser.read x-immich-state: Stable /albums: get: description: Retrieve a list of albums available to the authenticated user. operationId: getAllAlbums parameters: - name: assetId required: false in: query description: Filter albums containing this asset ID (ignores shared parameter) schema: format: uuid type: string - name: shared required: false in: query description: 'Filter by shared status: true = only shared, false = not shared, undefined = all owned albums' schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AlbumResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all albums tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.read x-immich-state: Stable post: description: Create a new album. The album can also be created with initial users and assets. operationId: createAlbum parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAlbumDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AlbumResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.create x-immich-state: Stable /albums/assets: put: description: Send a list of asset IDs and album IDs to add each asset to each album. operationId: addAssetsToAlbums parameters: - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AlbumsAddAssetsDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AlbumsAddAssetsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Add assets to albums tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumAsset.create x-immich-state: Stable /albums/statistics: get: description: Returns statistics about the albums available to the authenticated user. operationId: getAlbumStatistics parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AlbumStatisticsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve album statistics tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.statistics x-immich-state: Stable /albums/{id}: delete: description: Delete a specific album by its ID. Note the album is initially trashed and then immediately scheduled for deletion, but relies on a background job to complete the process. operationId: deleteAlbum parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.delete x-immich-state: Stable get: description: Retrieve information about a specific album by its ID. operationId: getAlbumInfo parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string - name: withoutAssets required: false in: query description: Exclude assets from response schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/AlbumResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.read x-immich-state: Stable patch: description: Update the information of a specific album by its ID. This endpoint can be used to update the album name, description, sort order, etc. However, it is not used to add or remove assets or users from the album. operationId: updateAlbumInfo parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAlbumDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AlbumResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: album.update x-immich-state: Stable /albums/{id}/assets: delete: description: Remove multiple assets from a specific album by its ID. operationId: removeAssetFromAlbum parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove assets from an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumAsset.delete x-immich-state: Stable put: description: Add multiple assets to a specific album by its ID. operationId: addAssetsToAlbum parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Add assets to an album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumAsset.create x-immich-state: Stable /albums/{id}/user/{userId}: delete: description: Remove a user from an album. Use an ID of "me" to leave a shared album. operationId: removeUserFromAlbum parameters: - name: id required: true in: path schema: format: uuid type: string - name: userId required: true in: path schema: type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove user from album tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumUser.delete x-immich-state: Stable put: description: Change the role for a specific user in a specific album. operationId: updateAlbumUser parameters: - name: id required: true in: path schema: format: uuid type: string - name: userId required: true in: path schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAlbumUserDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update user role tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumUser.update x-immich-state: Stable /albums/{id}/users: put: description: Share an album with multiple users. Each user can be given a specific role in the album. operationId: addUsersToAlbum parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AddUsersDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AlbumResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Share album with users tags: - Albums x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: albumUser.create x-immich-state: Stable /api-keys: get: description: Retrieve all API keys of the current user. operationId: getApiKeys parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/APIKeyResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all API keys tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: apiKey.read x-immich-state: Stable post: description: Creates a new API key. It will be limited to the permissions specified. operationId: createApiKey parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create an API key tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: apiKey.create x-immich-state: Stable /api-keys/me: get: description: Retrieve the API key that is used to access this endpoint. operationId: getMyApiKey parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKeyResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve the current API key tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /api-keys/{id}: delete: description: Deletes an API key identified by its ID. The current user must own this API key. operationId: deleteApiKey parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete an API key tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: apiKey.delete x-immich-state: Stable get: description: Retrieve an API key by its ID. The current user must own this API key. operationId: getApiKey parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKeyResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve an API key tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: apiKey.read x-immich-state: Stable put: description: Updates the name and permissions of an API key by its ID. The current user must own this API key. operationId: updateApiKey parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKeyUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKeyResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update an API key tags: - API keys x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: apiKey.update x-immich-state: Stable /assets: delete: description: Deletes multiple assets at the same time. operationId: deleteAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetBulkDeleteDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete assets tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.delete x-immich-state: Stable post: description: Uploads a new asset to the server. operationId: uploadAsset parameters: - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string - name: x-immich-checksum in: header description: sha1 checksum that can be used for duplicate detection before the file is uploaded required: false schema: type: string requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/AssetMediaCreateDto' description: Asset Upload Information required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetMediaResponseDto' description: Asset is a duplicate '201': content: application/json: schema: $ref: '#/components/schemas/AssetMediaResponseDto' description: Asset uploaded successfully security: - bearer: [] - cookie: [] - api_key: [] summary: Upload asset tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.upload x-immich-state: Stable put: description: Updates multiple assets at the same time. operationId: updateAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetBulkUpdateDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update assets tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.update x-immich-state: Stable /assets/bulk-upload-check: post: description: Determine which assets have already been uploaded to the server based on their SHA1 checksums. operationId: checkBulkUpload parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetBulkUploadCheckDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetBulkUploadCheckResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Check bulk upload tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.upload x-immich-state: Stable /assets/copy: put: description: Copy asset information like albums, tags, etc. from one asset to another. operationId: copyAsset parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetCopyDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Copy asset tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.copy x-immich-state: Stable /assets/device/{deviceId}: get: deprecated: true description: Get all asset of a device that are in the database, ID only. operationId: getAllUserAssetsByDeviceId parameters: - name: deviceId required: true in: path description: Device ID schema: type: string responses: '200': content: application/json: schema: items: type: string type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve assets by device ID tags: - Assets - Deprecated x-immich-history: - version: v1 state: Added - version: v2 state: Deprecated x-immich-state: Deprecated /assets/exist: post: description: Checks if multiple assets exist on the server and returns all existing - used by background backup operationId: checkExistingAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CheckExistingAssetsDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CheckExistingAssetsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Check existing assets tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.upload x-immich-state: Stable /assets/jobs: post: description: Run a specific job on a set of assets. operationId: runAssetJobs parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetJobsDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Run an asset job tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: job.create x-immich-state: Stable /assets/metadata: delete: description: Delete metadata key-value pairs for multiple assets. operationId: deleteBulkAssetMetadata parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetMetadataBulkDeleteDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete asset metadata tags: - Assets x-immich-history: - version: v1 state: Added - version: v2.5.0 state: Beta x-immich-permission: asset.update x-immich-state: Beta put: description: Upsert metadata key-value pairs for multiple assets. operationId: updateBulkAssetMetadata parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetMetadataBulkUpsertDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetMetadataBulkResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Upsert asset metadata tags: - Assets x-immich-history: - version: v1 state: Added - version: v2.5.0 state: Beta x-immich-permission: asset.update x-immich-state: Beta /assets/random: get: deprecated: true description: Retrieve a specified number of random assets for the authenticated user. operationId: getRandom parameters: - name: count required: false in: query description: Number of random assets to return schema: minimum: 1 type: number responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get random assets tags: - Assets - Deprecated x-immich-history: - version: v1 state: Added - version: v1 state: Deprecated replacementId: searchAssets x-immich-permission: asset.read x-immich-state: Deprecated /assets/statistics: get: description: Retrieve various statistics about the assets owned by the authenticated user. operationId: getAssetStatistics parameters: - name: isFavorite required: false in: query description: Filter by favorite status schema: type: boolean - name: isTrashed required: false in: query description: Filter by trash status schema: type: boolean - name: visibility required: false in: query description: Filter by visibility schema: $ref: '#/components/schemas/AssetVisibility' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetStatsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get asset statistics tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.statistics x-immich-state: Stable /assets/{id}: get: description: Retrieve detailed information about a specific asset. operationId: getAssetInfo parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve an asset tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable put: description: Update information of a specific asset. operationId: updateAsset parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAssetDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update an asset tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.update x-immich-state: Stable /assets/{id}/edits: delete: description: Removes all edit actions (crop, rotate, mirror) associated with the specified asset. operationId: removeAssetEdits parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove edits from an existing asset tags: - Assets x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Beta x-immich-permission: asset.edit.delete x-immich-state: Beta get: description: Retrieve a series of edit actions (crop, rotate, mirror) associated with the specified asset. operationId: getAssetEdits parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetEditsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve edits for an existing asset tags: - Assets x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Beta x-immich-permission: asset.edit.get x-immich-state: Beta put: description: Apply a series of edit actions (crop, rotate, mirror) to the specified asset. operationId: editAsset parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetEditsCreateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetEditsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Apply edits to an existing asset tags: - Assets x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Beta x-immich-permission: asset.edit.create x-immich-state: Beta /assets/{id}/metadata: get: description: Retrieve all metadata key-value pairs associated with the specified asset. operationId: getAssetMetadata parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetMetadataResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get asset metadata tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable put: description: Update or add metadata key-value pairs for the specified asset. operationId: updateAssetMetadata parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetMetadataUpsertDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetMetadataResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update asset metadata tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.update x-immich-state: Stable /assets/{id}/metadata/{key}: delete: description: Delete a specific metadata key-value pair associated with the specified asset. operationId: deleteAssetMetadata parameters: - name: id required: true in: path description: Asset ID schema: format: uuid type: string - name: key required: true in: path description: Metadata key schema: type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete asset metadata by key tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.update x-immich-state: Stable get: description: Retrieve the value of a specific metadata key associated with the specified asset. operationId: getAssetMetadataByKey parameters: - name: id required: true in: path description: Asset ID schema: format: uuid type: string - name: key required: true in: path description: Metadata key schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetMetadataResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve asset metadata by key tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /assets/{id}/ocr: get: description: Retrieve all OCR (Optical Character Recognition) data associated with the specified asset. operationId: getAssetOcr parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetOcrResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve asset OCR data tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /assets/{id}/original: get: description: Downloads the original file of the specified asset. operationId: downloadAsset parameters: - name: edited required: false in: query description: Return edited asset if available schema: default: false type: boolean - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Download original asset tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.download x-immich-state: Stable put: deprecated: true description: Replace the asset with new file, without changing its id. operationId: replaceAsset parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/AssetMediaReplaceDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetMediaResponseDto' description: Asset replaced successfully security: - bearer: [] - cookie: [] - api_key: [] summary: Replace asset tags: - Assets - Deprecated x-immich-history: - version: v1 state: Added - version: v1 state: Deprecated replacementId: copyAsset x-immich-permission: asset.replace x-immich-state: Deprecated /assets/{id}/thumbnail: get: description: Retrieve the thumbnail image for the specified asset. Viewing the fullsize thumbnail might redirect to downloadAsset, which requires a different permission. operationId: viewAsset parameters: - name: edited required: false in: query description: Return edited asset if available schema: default: false type: boolean - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: size required: false in: query description: Asset media size schema: $ref: '#/components/schemas/AssetMediaSize' - name: slug required: false in: query schema: type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: View asset thumbnail tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.view x-immich-state: Stable /assets/{id}/video/playback: get: description: Streams the video file for the specified asset. This endpoint also supports byte range requests. operationId: playAssetVideo parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Play asset video tags: - Assets x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.view x-immich-state: Stable /auth/admin-sign-up: post: description: Create the first admin user in the system. operationId: signUpAdmin parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SignUpDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' summary: Register admin tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/change-password: post: description: Change the password of the current user. operationId: changePassword parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ChangePasswordDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Change password tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: auth.changePassword x-immich-state: Stable /auth/login: post: description: Login with username and password and receive a session token. operationId: login parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/LoginCredentialDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/LoginResponseDto' description: '' summary: Login tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/logout: post: description: Logout the current user and invalidate the session token. operationId: logout parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/LogoutResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Logout tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/pin-code: delete: description: Reset the pin code for the current user by providing the account password operationId: resetPinCode parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PinCodeResetDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Reset pin code tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: pinCode.delete x-immich-state: Stable post: description: Setup a new pin code for the current user. operationId: setupPinCode parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PinCodeSetupDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Setup pin code tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: pinCode.create x-immich-state: Stable put: description: Change the pin code for the current user. operationId: changePinCode parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PinCodeChangeDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Change pin code tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: pinCode.update x-immich-state: Stable /auth/session/lock: post: description: Remove elevated access to locked assets from the current session. operationId: lockAuthSession parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Lock auth session tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/session/unlock: post: description: Temporarily grant the session elevated access to locked assets by providing the correct PIN code. operationId: unlockAuthSession parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionUnlockDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Unlock auth session tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/status: get: description: Get information about the current session, including whether the user has a password, and if the session can access locked assets. operationId: getAuthStatus parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AuthStatusResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve auth status tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /auth/validateToken: post: description: Validate the current authorization method is still valid. operationId: validateAccessToken parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ValidateAccessTokenResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Validate access token tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /download/archive: post: description: Download a ZIP archive containing the specified assets. The assets must have been previously requested via the "getDownloadInfo" endpoint. operationId: downloadArchive parameters: - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DownloadArchiveDto' required: true responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Download asset archive tags: - Download x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.download x-immich-state: Stable /download/info: post: description: Retrieve information about how to request a download for the specified assets or album. The response includes groups of assets that can be downloaded together. operationId: getDownloadInfo parameters: - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DownloadInfoDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/DownloadResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve download information tags: - Download x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.download x-immich-state: Stable /duplicates: delete: description: Delete multiple duplicate assets specified by their IDs. operationId: deleteDuplicates parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete duplicates tags: - Duplicates x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: duplicate.delete x-immich-state: Stable get: description: Retrieve a list of duplicate assets available to the authenticated user. operationId: getAssetDuplicates parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/DuplicateResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve duplicates tags: - Duplicates x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: duplicate.read x-immich-state: Stable /duplicates/resolve: post: description: Resolve duplicate groups by synchronizing metadata across assets and deleting/trashing duplicates. operationId: resolveDuplicates parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/DuplicateResolveDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Resolve duplicate groups tags: - Duplicates x-immich-history: - version: v3.0.0 state: Added - version: v3.0.0 state: Alpha x-immich-permission: duplicate.delete x-immich-state: Alpha /duplicates/{id}: delete: description: Delete a single duplicate asset specified by its ID. operationId: deleteDuplicate parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a duplicate tags: - Duplicates x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: duplicate.delete x-immich-state: Stable /faces: get: description: Retrieve all faces belonging to an asset. operationId: getFaces parameters: - name: id required: true in: query description: Face ID schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetFaceResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve faces for asset tags: - Faces x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: face.read x-immich-state: Stable post: description: Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face. operationId: createFace parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetFaceCreateDto' required: true responses: '201': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a face tags: - Faces x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: face.create x-immich-state: Stable /faces/{id}: delete: description: Delete a face identified by the id. Optionally can be force deleted. operationId: deleteFace parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetFaceDeleteDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a face tags: - Faces x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: face.delete x-immich-state: Stable put: description: Re-assign the face provided in the body to the person identified by the id in the path parameter. operationId: reassignFacesById parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/FaceDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PersonResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Re-assign a face to another person tags: - Faces x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: face.update x-immich-state: Stable /jobs: get: deprecated: true description: Retrieve the counts of the current queue, as well as the current status. operationId: getQueuesLegacy parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/QueuesResponseLegacyDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve queue counts and status tags: - Jobs - Deprecated x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable - version: v2.4.0 state: Deprecated x-immich-permission: job.read x-immich-state: Deprecated post: description: Run a specific job. Most jobs are queued automatically, but this endpoint allows for manual creation of a handful of jobs, including various cleanup tasks, as well as creating a new database backup. operationId: createJob parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/JobCreateDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a manual job tags: - Jobs x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: job.create x-immich-state: Stable /jobs/{name}: put: deprecated: true description: Queue all assets for a specific job type. Defaults to only queueing assets that have not yet been processed, but the force command can be used to re-process all assets. operationId: runQueueCommandLegacy parameters: - name: name required: true in: path description: Queue name schema: $ref: '#/components/schemas/QueueName' requestBody: content: application/json: schema: $ref: '#/components/schemas/QueueCommandDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QueueResponseLegacyDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Run jobs tags: - Jobs - Deprecated x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable - version: v2.4.0 state: Deprecated x-immich-permission: job.create x-immich-state: Deprecated /libraries: get: description: Retrieve a list of external libraries. operationId: getAllLibraries parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/LibraryResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve libraries tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.read x-immich-state: Stable post: description: Create a new external library. operationId: createLibrary parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateLibraryDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/LibraryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a library tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.create x-immich-state: Stable /libraries/{id}: delete: description: Delete an external library by its ID. operationId: deleteLibrary parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a library tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.delete x-immich-state: Stable get: description: Retrieve an external library by its ID. operationId: getLibrary parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/LibraryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a library tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.read x-immich-state: Stable put: description: Update an existing external library. operationId: updateLibrary parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateLibraryDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LibraryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a library tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.update x-immich-state: Stable /libraries/{id}/scan: post: description: Queue a scan for the external library to find and import new assets. operationId: scanLibrary parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Scan a library tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.update x-immich-state: Stable /libraries/{id}/statistics: get: description: Retrieve statistics for a specific external library, including number of videos, images, and storage usage. operationId: getLibraryStatistics parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/LibraryStatsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve library statistics tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: library.statistics x-immich-state: Stable /libraries/{id}/validate: post: description: Validate the settings of an external library. operationId: validate parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ValidateLibraryDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ValidateLibraryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Validate library settings tags: - Libraries x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /map/markers: get: description: Retrieve a list of latitude and longitude coordinates for every asset with location data. operationId: getMapMarkers parameters: - name: fileCreatedAfter required: false in: query description: Filter assets created after this date schema: format: date-time type: string - name: fileCreatedBefore required: false in: query description: Filter assets created before this date schema: format: date-time type: string - name: isArchived required: false in: query description: Filter by archived status schema: type: boolean - name: isFavorite required: false in: query description: Filter by favorite status schema: type: boolean - name: withPartners required: false in: query description: Include partner assets schema: type: boolean - name: withSharedAlbums required: false in: query description: Include shared album assets schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/MapMarkerResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve map markers tags: - Map x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: map.read x-immich-state: Stable /map/reverse-geocode: get: description: Retrieve location information (e.g., city, country) for given latitude and longitude coordinates. operationId: reverseGeocode parameters: - name: lat required: true in: query description: Latitude (-90 to 90) schema: format: double type: number - name: lon required: true in: query description: Longitude (-180 to 180) schema: format: double type: number responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/MapReverseGeocodeResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Reverse geocode coordinates tags: - Map x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: map.search x-immich-state: Stable /memories: get: description: Retrieve a list of memories. Memories are sorted descending by creation date by default, although they can also be sorted in ascending order, or randomly. operationId: searchMemories parameters: - name: for required: false in: query description: Filter by date schema: format: date-time type: string - name: isSaved required: false in: query description: Filter by saved status schema: type: boolean - name: isTrashed required: false in: query description: Include trashed memories schema: type: boolean - name: order required: false in: query description: Sort order schema: $ref: '#/components/schemas/MemorySearchOrder' - name: size required: false in: query description: Number of memories to return schema: minimum: 1 type: integer - name: type required: false in: query description: Memory type schema: $ref: '#/components/schemas/MemoryType' responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/MemoryResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve memories tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.read x-immich-state: Stable post: description: Create a new memory by providing a name, description, and a list of asset IDs to include in the memory. operationId: createMemory parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/MemoryCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/MemoryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.create x-immich-state: Stable /memories/statistics: get: description: Retrieve statistics about memories, such as total count and other relevant metrics. operationId: memoriesStatistics parameters: - name: for required: false in: query description: Filter by date schema: format: date-time type: string - name: isSaved required: false in: query description: Filter by saved status schema: type: boolean - name: isTrashed required: false in: query description: Include trashed memories schema: type: boolean - name: order required: false in: query description: Sort order schema: $ref: '#/components/schemas/MemorySearchOrder' - name: size required: false in: query description: Number of memories to return schema: minimum: 1 type: integer - name: type required: false in: query description: Memory type schema: $ref: '#/components/schemas/MemoryType' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemoryStatisticsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve memories statistics tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.statistics x-immich-state: Stable /memories/{id}: delete: description: Delete a specific memory by its ID. operationId: deleteMemory parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.delete x-immich-state: Stable get: description: Retrieve a specific memory by its ID. operationId: getMemory parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemoryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.read x-immich-state: Stable put: description: Update an existing memory by its ID. operationId: updateMemory parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/MemoryUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemoryResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memory.update x-immich-state: Stable /memories/{id}/assets: delete: description: Remove a list of asset IDs from a specific memory. operationId: removeMemoryAssets parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove assets from a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memoryAsset.delete x-immich-state: Stable put: description: Add a list of asset IDs to a specific memory. operationId: addMemoryAssets parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Add assets to a memory tags: - Memories x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: memoryAsset.create x-immich-state: Stable /notifications: delete: description: Delete a list of notifications at once. operationId: deleteNotifications parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/NotificationDeleteAllDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete notifications tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.delete x-immich-state: Stable get: description: Retrieve a list of notifications. operationId: getNotifications parameters: - name: id required: false in: query description: Filter by notification ID schema: format: uuid type: string - name: level required: false in: query description: Filter by notification level schema: $ref: '#/components/schemas/NotificationLevel' - name: type required: false in: query description: Filter by notification type schema: $ref: '#/components/schemas/NotificationType' - name: unread required: false in: query description: Filter by unread status schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/NotificationDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve notifications tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.read x-immich-state: Stable put: description: Update a list of notifications. Allows to bulk-set the read status of notifications. operationId: updateNotifications parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/NotificationUpdateAllDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update notifications tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.update x-immich-state: Stable /notifications/{id}: delete: description: Delete a specific notification. operationId: deleteNotification parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a notification tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.delete x-immich-state: Stable get: description: Retrieve a specific notification identified by id. operationId: getNotification parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/NotificationDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get a notification tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.read x-immich-state: Stable put: description: Update a specific notification to set its read status. operationId: updateNotification parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/NotificationUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/NotificationDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a notification tags: - Notifications x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: notification.update x-immich-state: Stable /oauth/authorize: post: description: Initiate the OAuth authorization process. operationId: startOAuth parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/OAuthConfigDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/OAuthAuthorizeResponseDto' description: '' summary: Start OAuth tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /oauth/callback: post: description: Complete the OAuth authorization process by exchanging the authorization code for a session token. operationId: finishOAuth parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/OAuthCallbackDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/LoginResponseDto' description: '' summary: Finish OAuth tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /oauth/link: post: description: Link an OAuth account to the authenticated user. operationId: linkOAuthAccount parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/OAuthCallbackDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Link OAuth account tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /oauth/mobile-redirect: get: description: Requests to this URL are automatically forwarded to the mobile app, and is used in some cases for OAuth redirecting. operationId: redirectOAuthToMobile parameters: [] responses: '200': description: '' summary: Redirect OAuth to mobile tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /oauth/unlink: post: description: Unlink the OAuth account from the authenticated user. operationId: unlinkOAuthAccount parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Unlink OAuth account tags: - Authentication x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /partners: get: description: Retrieve a list of partners with whom assets are shared. operationId: getPartners parameters: - name: direction required: true in: query description: Partner direction schema: $ref: '#/components/schemas/PartnerDirection' responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PartnerResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve partners tags: - Partners x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: partner.read x-immich-state: Stable post: description: Create a new partner to share assets with. operationId: createPartner parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PartnerResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a partner tags: - Partners x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: partner.create x-immich-state: Stable /partners/{id}: delete: description: Stop sharing assets with a partner. operationId: removePartner parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove a partner tags: - Partners x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: partner.delete x-immich-state: Stable post: deprecated: true description: Create a new partner to share assets with. operationId: createPartnerDeprecated parameters: - name: id required: true in: path schema: format: uuid type: string responses: '201': content: application/json: schema: $ref: '#/components/schemas/PartnerResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a partner tags: - Partners - Deprecated x-immich-history: - version: v1 state: Added - version: v1 state: Deprecated replacementId: createPartner x-immich-permission: partner.create x-immich-state: Deprecated put: description: Specify whether a partner's assets should appear in the user's timeline. operationId: updatePartner parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PartnerResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a partner tags: - Partners x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: partner.update x-immich-state: Stable /people: delete: description: Bulk delete a list of people at once. operationId: deletePeople parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete people tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.delete x-immich-state: Stable get: description: Retrieve a list of all people. operationId: getAllPeople parameters: - name: closestAssetId required: false in: query description: Closest asset ID for similarity search schema: format: uuid type: string - name: closestPersonId required: false in: query description: Closest person ID for similarity search schema: format: uuid type: string - name: page required: false in: query description: Page number for pagination schema: minimum: 1 default: 1 type: number - name: size required: false in: query description: Number of items per page schema: minimum: 1 maximum: 1000 default: 500 type: number - name: withHidden required: false in: query description: Include hidden people schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/PeopleResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get all people tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.read x-immich-state: Stable post: description: Create a new person that can have multiple faces assigned to them. operationId: createPerson parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PersonResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a person tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.create x-immich-state: Stable put: description: Bulk update multiple people at once. operationId: updatePeople parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PeopleUpdateDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update people tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.update x-immich-state: Stable /people/{id}: delete: description: Delete an individual person. operationId: deletePerson parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete person tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.delete x-immich-state: Stable get: description: Retrieve a person by id. operationId: getPerson parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PersonResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get a person tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.read x-immich-state: Stable put: description: Update an individual person. operationId: updatePerson parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PersonResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update person tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.update x-immich-state: Stable /people/{id}/merge: post: description: Merge a list of people into the person specified in the path parameter. operationId: mergePerson parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/MergePersonDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Merge people tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.merge x-immich-state: Stable /people/{id}/reassign: put: description: Bulk reassign a list of faces to a different person. operationId: reassignFaces parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetFaceUpdateDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PersonResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Reassign faces tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.reassign x-immich-state: Stable /people/{id}/statistics: get: description: Retrieve statistics about a specific person. operationId: getPersonStatistics parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PersonStatisticsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get person statistics tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.statistics x-immich-state: Stable /people/{id}/thumbnail: get: description: Retrieve the thumbnail file for a person. operationId: getPersonThumbnail parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get person thumbnail tags: - People x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.read x-immich-state: Stable /plugins: get: description: Retrieve a list of plugins available to the authenticated user. operationId: getPlugins parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PluginResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all plugins tags: - Plugins x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: plugin.read x-immich-state: Alpha /plugins/triggers: get: description: Retrieve a list of all available plugin triggers. operationId: getPluginTriggers parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PluginTriggerResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all plugin triggers tags: - Plugins x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: plugin.read x-immich-state: Alpha /plugins/{id}: get: description: Retrieve information about a specific plugin by its ID. operationId: getPlugin parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PluginResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a plugin tags: - Plugins x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: plugin.read x-immich-state: Alpha /queues: get: description: Retrieves a list of queues. operationId: getQueues parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/QueueResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all queues tags: - Queues x-immich-admin-only: true x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-permission: queue.read x-immich-state: Alpha /queues/{name}: get: description: Retrieves a specific queue by its name. operationId: getQueue parameters: - name: name required: true in: path description: Queue name schema: $ref: '#/components/schemas/QueueName' responses: '200': content: application/json: schema: $ref: '#/components/schemas/QueueResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a queue tags: - Queues x-immich-admin-only: true x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-permission: queue.read x-immich-state: Alpha put: description: Change the paused status of a specific queue. operationId: updateQueue parameters: - name: name required: true in: path description: Queue name schema: $ref: '#/components/schemas/QueueName' requestBody: content: application/json: schema: $ref: '#/components/schemas/QueueUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/QueueResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a queue tags: - Queues x-immich-admin-only: true x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-permission: queue.update x-immich-state: Alpha /queues/{name}/jobs: delete: description: Removes all jobs from the specified queue. operationId: emptyQueue parameters: - name: name required: true in: path description: Queue name schema: $ref: '#/components/schemas/QueueName' requestBody: content: application/json: schema: $ref: '#/components/schemas/QueueDeleteDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Empty a queue tags: - Queues x-immich-admin-only: true x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-permission: queueJob.delete x-immich-state: Alpha get: description: Retrieves a list of queue jobs from the specified queue. operationId: getQueueJobs parameters: - name: name required: true in: path description: Queue name schema: $ref: '#/components/schemas/QueueName' - name: status required: false in: query description: Filter jobs by status schema: type: array items: $ref: '#/components/schemas/QueueJobStatus' responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/QueueJobResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve queue jobs tags: - Queues x-immich-admin-only: true x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-permission: queueJob.read x-immich-state: Alpha /search/cities: get: description: Retrieve a list of assets with each asset belonging to a different city. This endpoint is used on the places pages to show a single thumbnail for each city the user has assets in. operationId: getAssetsByCity parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve assets by city tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/explore: get: description: Retrieve data for the explore section, such as popular people and places. operationId: getExploreData parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SearchExploreResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve explore data tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/large-assets: post: description: Search for assets that are considered large based on specified criteria. operationId: searchLargeAssets parameters: - name: albumIds required: false in: query description: Filter by album IDs schema: type: array items: type: string format: uuid - name: city required: false in: query description: Filter by city name schema: nullable: true type: string - name: country required: false in: query description: Filter by country name schema: nullable: true type: string - name: createdAfter required: false in: query description: Filter by creation date (after) schema: format: date-time type: string - name: createdBefore required: false in: query description: Filter by creation date (before) schema: format: date-time type: string - name: deviceId required: false in: query description: Device ID to filter by schema: type: string - name: isEncoded required: false in: query description: Filter by encoded status schema: type: boolean - name: isFavorite required: false in: query description: Filter by favorite status schema: type: boolean - name: isMotion required: false in: query description: Filter by motion photo status schema: type: boolean - name: isNotInAlbum required: false in: query description: Filter assets not in any album schema: type: boolean - name: isOffline required: false in: query description: Filter by offline status schema: type: boolean - name: lensModel required: false in: query description: Filter by lens model schema: nullable: true type: string - name: libraryId required: false in: query description: Library ID to filter by schema: format: uuid nullable: true type: string - name: make required: false in: query description: Filter by camera make schema: type: string - name: minFileSize required: false in: query description: Minimum file size in bytes schema: minimum: 0 type: integer - name: model required: false in: query description: Filter by camera model schema: nullable: true type: string - name: ocr required: false in: query description: Filter by OCR text content schema: type: string - name: personIds required: false in: query description: Filter by person IDs schema: type: array items: type: string format: uuid - name: rating required: false in: query description: Filter by rating [1-5], or null for unrated x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable schema: minimum: -1 maximum: 5 nullable: true type: number - name: size required: false in: query description: Number of results to return schema: minimum: 1 maximum: 1000 type: number - name: state required: false in: query description: Filter by state/province name schema: nullable: true type: string - name: tagIds required: false in: query description: Filter by tag IDs schema: nullable: true type: array items: type: string format: uuid - name: takenAfter required: false in: query description: Filter by taken date (after) schema: format: date-time type: string - name: takenBefore required: false in: query description: Filter by taken date (before) schema: format: date-time type: string - name: trashedAfter required: false in: query description: Filter by trash date (after) schema: format: date-time type: string - name: trashedBefore required: false in: query description: Filter by trash date (before) schema: format: date-time type: string - name: type required: false in: query description: Asset type filter schema: $ref: '#/components/schemas/AssetTypeEnum' - name: updatedAfter required: false in: query description: Filter by update date (after) schema: format: date-time type: string - name: updatedBefore required: false in: query description: Filter by update date (before) schema: format: date-time type: string - name: visibility required: false in: query description: Filter by visibility schema: $ref: '#/components/schemas/AssetVisibility' - name: withDeleted required: false in: query description: Include deleted assets schema: type: boolean - name: withExif required: false in: query description: Include EXIF data in response schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search large assets tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/metadata: post: description: Search for assets based on various metadata criteria. operationId: searchAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/MetadataSearchDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search assets by metadata tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/person: get: description: Search for people by name. operationId: searchPerson parameters: - name: name required: true in: query description: Person name to search for schema: type: string - name: withHidden required: false in: query description: Include hidden people schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PersonResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search people tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: person.read x-immich-state: Stable /search/places: get: description: Search for places by name. operationId: searchPlaces parameters: - name: name required: true in: query description: Place name to search for schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/PlacesResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search places tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/random: post: description: Retrieve a random selection of assets based on the provided criteria. operationId: searchRandom parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/RandomSearchDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search random assets tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/smart: post: description: Perform a smart search for assets by using machine learning vectors to determine relevance. operationId: searchSmart parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SmartSearchDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Smart asset search tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /search/statistics: post: description: Retrieve statistical data about assets based on search criteria, such as the total matching count. operationId: searchAssetStatistics parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/StatisticsSearchDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchStatisticsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Search asset statistics tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.statistics x-immich-state: Stable /search/suggestions: get: description: Retrieve search suggestions based on partial input. This endpoint is used for typeahead search features. operationId: getSearchSuggestions parameters: - name: country required: false in: query description: Filter by country schema: type: string - name: includeNull required: false in: query description: Include null values in suggestions x-immich-history: - version: v1.111.0 state: Added - version: v2 state: Stable x-immich-state: Stable schema: type: boolean - name: lensModel required: false in: query description: Filter by lens model schema: type: string - name: make required: false in: query description: Filter by camera make schema: type: string - name: model required: false in: query description: Filter by camera model schema: type: string - name: state required: false in: query description: Filter by state/province schema: type: string - name: type required: true in: query description: Suggestion type schema: $ref: '#/components/schemas/SearchSuggestionType' responses: '200': content: application/json: schema: items: type: string type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve search suggestions tags: - Search x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.read x-immich-state: Stable /server/about: get: description: Retrieve a list of information about the server. operationId: getAboutInfo parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerAboutResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get server information tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: server.about x-immich-state: Stable /server/apk-links: get: description: Retrieve links to the APKs for the current server version. operationId: getApkLinks parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerApkLinksDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get APK links tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: server.apkLinks x-immich-state: Stable /server/config: get: description: Retrieve the current server configuration. operationId: getServerConfig parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerConfigDto' description: '' summary: Get config tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/features: get: description: Retrieve available features supported by this server. operationId: getServerFeatures parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerFeaturesDto' description: '' summary: Get features tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/license: delete: description: Delete the currently set server product key. operationId: deleteServerLicense parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete server product key tags: - Server x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: serverLicense.delete x-immich-state: Stable get: description: Retrieve information about whether the server currently has a product key registered. operationId: getServerLicense parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/LicenseResponseDto' description: '' '404': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get product key tags: - Server x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: serverLicense.read x-immich-state: Stable put: description: Validate and set the server product key if successful. operationId: setServerLicense parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/LicenseKeyDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LicenseResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Set server product key tags: - Server x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: serverLicense.update x-immich-state: Stable /server/media-types: get: description: Retrieve all media types supported by the server. operationId: getSupportedMediaTypes parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerMediaTypesResponseDto' description: '' summary: Get supported media types tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/ping: get: description: Pong operationId: pingServer parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerPingResponse' description: '' summary: Ping tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/statistics: get: description: Retrieve statistics about the entire Immich instance such as asset counts. operationId: getServerStatistics parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerStatsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get statistics tags: - Server x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: server.statistics x-immich-state: Stable /server/storage: get: description: Retrieve the current storage utilization information of the server. operationId: getStorage parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerStorageResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get storage tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: server.storage x-immich-state: Stable /server/theme: get: description: Retrieve the custom CSS, if existent. operationId: getTheme parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerThemeDto' description: '' summary: Get theme tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/version: get: description: Retrieve the current server version in semantic versioning (semver) format. operationId: getServerVersion parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServerVersionResponseDto' description: '' summary: Get server version tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /server/version-check: get: description: Retrieve information about the last time the version check ran. operationId: getVersionCheck parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionCheckStateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get version check status tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: server.versionCheck x-immich-state: Stable /server/version-history: get: description: Retrieve a list of past versions the server has been on. operationId: getVersionHistory parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/ServerVersionHistoryResponseDto' type: array description: '' summary: Get version history tags: - Server x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /sessions: delete: description: Delete all sessions for the user. This will not delete the current session. operationId: deleteAllSessions parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete all sessions tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.delete x-immich-state: Stable get: description: Retrieve a list of sessions for the user. operationId: getSessions parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SessionResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve sessions tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.read x-immich-state: Stable post: description: Create a session as a child to the current session. This endpoint is used for casting. operationId: createSession parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SessionCreateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a session tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.create x-immich-state: Stable /sessions/{id}: delete: description: Delete a specific session by id. operationId: deleteSession parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a session tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.delete x-immich-state: Stable put: description: Update a specific session identified by id. operationId: updateSession parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SessionResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a session tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.update x-immich-state: Stable /sessions/{id}/lock: post: description: Lock a specific session by id. operationId: lockSession parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Lock a session tags: - Sessions x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: session.lock x-immich-state: Stable /shared-links: get: description: Retrieve a list of all shared links. operationId: getAllSharedLinks parameters: - name: albumId required: false in: query description: Filter by album ID schema: format: uuid type: string - name: id required: false in: query description: Filter by shared link ID x-immich-history: - version: v2.5.0 state: Added schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SharedLinkResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve all shared links tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.read x-immich-state: Stable post: description: Create a new shared link. operationId: createSharedLink parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SharedLinkCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SharedLinkResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.create x-immich-state: Stable /shared-links/login: post: description: Login to a password protected shared link operationId: sharedLinkLogin parameters: - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SharedLinkLoginDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SharedLinkResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Shared link login tags: - Shared links x-immich-history: - version: v2.6.0 state: Added - version: v2.6.0 state: Beta x-immich-state: Beta /shared-links/me: get: description: Retrieve the current shared link associated with authentication method. operationId: getMySharedLink parameters: - name: key required: false in: query schema: type: string - name: password required: false in: query description: Link password schema: example: password type: string - name: slug required: false in: query schema: type: string - name: token required: false in: query description: Access token schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SharedLinkResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve current shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /shared-links/{id}: delete: description: Delete a specific shared link by its ID. operationId: removeSharedLink parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.delete x-immich-state: Stable get: description: Retrieve a specific shared link by its ID. operationId: getSharedLinkById parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/SharedLinkResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.read x-immich-state: Stable patch: description: Update an existing shared link by its ID. operationId: updateSharedLink parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SharedLinkEditDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SharedLinkResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.update x-immich-state: Stable /shared-links/{id}/assets: delete: description: Remove assets from a specific shared link by its ID. This endpoint is only relevant for shared link of type individual. operationId: removeSharedLinkAssets parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetIdsResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove assets from a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sharedLink.update x-immich-state: Stable put: description: Add assets to a specific shared link by its ID. This endpoint is only relevant for shared link of type individual. operationId: addSharedLinkAssets parameters: - name: id required: true in: path schema: format: uuid type: string - name: key required: false in: query schema: type: string - name: slug required: false in: query schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetIdsResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Add assets to a shared link tags: - Shared links x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-state: Stable /stacks: delete: description: Delete multiple stacks by providing a list of stack IDs. operationId: deleteStacks parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete stacks tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.delete x-immich-state: Stable get: description: Retrieve a list of stacks. operationId: searchStacks parameters: - name: primaryAssetId required: false in: query description: Filter by primary asset ID schema: format: uuid type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/StackResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve stacks tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.read x-immich-state: Stable post: description: Create a new stack by providing a name and a list of asset IDs to include in the stack. If any of the provided asset IDs are primary assets of an existing stack, the existing stack will be merged into the newly created stack. operationId: createStack parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/StackCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/StackResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a stack tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.create x-immich-state: Stable /stacks/{id}: delete: description: Delete a specific stack by its ID. operationId: deleteStack parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a stack tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.delete x-immich-state: Stable get: description: Retrieve a specific stack by its ID. operationId: getStack parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/StackResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a stack tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.read x-immich-state: Stable put: description: Update an existing stack by its ID. operationId: updateStack parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/StackUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/StackResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a stack tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.update x-immich-state: Stable /stacks/{id}/assets/{assetId}: delete: description: Remove a specific asset from a stack by providing the stack ID and asset ID. operationId: removeAssetFromStack parameters: - name: assetId required: true in: path schema: format: uuid type: string - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Remove an asset from a stack tags: - Stacks x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: stack.update x-immich-state: Stable /sync/ack: delete: description: Delete specific synchronization acknowledgments. operationId: deleteSyncAck parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncAckDeleteDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete acknowledgements tags: - Sync x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: syncCheckpoint.delete x-immich-state: Stable get: description: Retrieve the synchronization acknowledgments for the current session. operationId: getSyncAck parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SyncAckDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve acknowledgements tags: - Sync x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: syncCheckpoint.read x-immich-state: Stable post: description: Send a list of synchronization acknowledgements to confirm that the latest changes have been received. operationId: sendSyncAck parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncAckSetDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Acknowledge changes tags: - Sync x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: syncCheckpoint.update x-immich-state: Stable /sync/delta-sync: post: deprecated: true description: Retrieve changed assets since the last sync for the authenticated user. operationId: getDeltaSync parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetDeltaSyncDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssetDeltaSyncResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get delta sync for user tags: - Sync - Deprecated x-immich-history: - version: v1 state: Added - version: v2 state: Deprecated x-immich-state: Deprecated /sync/full-sync: post: deprecated: true description: Retrieve all assets for a full synchronization for the authenticated user. operationId: getFullSyncForUser parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AssetFullSyncDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get full sync for user tags: - Sync - Deprecated x-immich-history: - version: v1 state: Added - version: v2 state: Deprecated x-immich-state: Deprecated /sync/stream: post: description: Retrieve a JSON lines streamed response of changes for synchronization. This endpoint is used by the mobile app to efficiently stay up to date with changes. operationId: getSyncStream parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncStreamDto' required: true responses: '200': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Stream sync changes tags: - Sync x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: sync.stream x-immich-state: Stable /system-config: get: description: Retrieve the current system configuration. operationId: getConfig parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemConfigDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get system configuration tags: - System config x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemConfig.read x-immich-state: Stable put: description: Update the system configuration with a new system configuration. operationId: updateConfig parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SystemConfigDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemConfigDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update system configuration tags: - System config x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemConfig.update x-immich-state: Stable /system-config/defaults: get: description: Retrieve the default values for the system configuration. operationId: getConfigDefaults parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemConfigDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get system configuration defaults tags: - System config x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemConfig.read x-immich-state: Stable /system-config/storage-template-options: get: description: Retrieve exemplary storage template options. operationId: getStorageTemplateOptions parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemConfigTemplateStorageOptionDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get storage template options tags: - System config x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemConfig.read x-immich-state: Stable /system-metadata/admin-onboarding: get: description: Retrieve the current admin onboarding status. operationId: getAdminOnboarding parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AdminOnboardingUpdateDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve admin onboarding tags: - System metadata x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemMetadata.read x-immich-state: Stable post: description: Update the admin onboarding status. operationId: updateAdminOnboarding parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AdminOnboardingUpdateDto' required: true responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update admin onboarding tags: - System metadata x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemMetadata.update x-immich-state: Stable /system-metadata/reverse-geocoding-state: get: description: Retrieve the current state of the reverse geocoding import. operationId: getReverseGeocodingState parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ReverseGeocodingStateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve reverse geocoding state tags: - System metadata x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemMetadata.read x-immich-state: Stable /system-metadata/version-check-state: get: description: Retrieve the current state of the version check process. operationId: getVersionCheckState parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionCheckStateResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve version check state tags: - System metadata x-immich-admin-only: true x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: systemMetadata.read x-immich-state: Stable /tags: get: description: Retrieve a list of all tags. operationId: getAllTags parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/TagResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve tags tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.read x-immich-state: Stable post: description: Create a new tag by providing a name and optional color. operationId: createTag parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TagCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/TagResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a tag tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.create x-immich-state: Stable put: description: Create or update multiple tags in a single request. operationId: upsertTags parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TagUpsertDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/TagResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Upsert tags tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.create x-immich-state: Stable /tags/assets: put: description: Add multiple tags to multiple assets in a single request. operationId: bulkTagAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TagBulkAssetsDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TagBulkAssetsResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Tag assets tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.asset x-immich-state: Stable /tags/{id}: delete: description: Delete a specific tag by its ID. operationId: deleteTag parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a tag tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.delete x-immich-state: Stable get: description: Retrieve a specific tag by its ID. operationId: getTagById parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/TagResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a tag tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.read x-immich-state: Stable put: description: Update an existing tag identified by its ID. operationId: updateTag parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/TagUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TagResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a tag tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.update x-immich-state: Stable /tags/{id}/assets: delete: description: Remove a tag from all the specified assets. operationId: untagAssets parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Untag assets tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.asset x-immich-state: Stable put: description: Add a tag to all the specified assets. operationId: tagAssets parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BulkIdResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Tag assets tags: - Tags x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: tag.asset x-immich-state: Stable /timeline/bucket: get: description: Retrieve a string of all asset ids in a given time bucket. operationId: getTimeBucket parameters: - name: albumId required: false in: query description: Filter assets belonging to a specific album schema: format: uuid type: string - name: bbox required: false in: query description: Bounding box coordinates as west,south,east,north (WGS84) schema: example: 11.075683,49.416711,11.117589,49.454875 type: string - name: isFavorite required: false in: query description: Filter by favorite status (true for favorites only, false for non-favorites only) schema: type: boolean - name: isTrashed required: false in: query description: Filter by trash status (true for trashed assets only, false for non-trashed only) schema: type: boolean - name: key required: false in: query schema: type: string - name: order required: false in: query description: Sort order for assets within time buckets (ASC for oldest first, DESC for newest first) schema: $ref: '#/components/schemas/AssetOrder' - name: personId required: false in: query description: Filter assets containing a specific person (face recognition) schema: format: uuid type: string - name: slug required: false in: query schema: type: string - name: tagId required: false in: query description: Filter assets with a specific tag schema: format: uuid type: string - name: timeBucket required: true in: query description: Time bucket identifier in YYYY-MM-DD format (e.g., "2024-01-01" for January 2024) schema: example: 2024-01-01 type: string - name: userId required: false in: query description: Filter assets by specific user ID schema: format: uuid type: string - name: visibility required: false in: query description: Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED) schema: $ref: '#/components/schemas/AssetVisibility' - name: withCoordinates required: false in: query description: Include location data in the response schema: type: boolean - name: withPartners required: false in: query description: Include assets shared by partners schema: type: boolean - name: withStacked required: false in: query description: Include stacked assets in the response. When true, only primary assets from stacks are returned. schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/TimeBucketAssetResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get time bucket tags: - Timeline x-immich-history: - version: v1 state: Added - version: v1 state: Internal x-immich-permission: asset.read x-immich-state: Internal /timeline/buckets: get: description: Retrieve a list of all minimal time buckets. operationId: getTimeBuckets parameters: - name: albumId required: false in: query description: Filter assets belonging to a specific album schema: format: uuid type: string - name: bbox required: false in: query description: Bounding box coordinates as west,south,east,north (WGS84) schema: example: 11.075683,49.416711,11.117589,49.454875 type: string - name: isFavorite required: false in: query description: Filter by favorite status (true for favorites only, false for non-favorites only) schema: type: boolean - name: isTrashed required: false in: query description: Filter by trash status (true for trashed assets only, false for non-trashed only) schema: type: boolean - name: key required: false in: query schema: type: string - name: order required: false in: query description: Sort order for assets within time buckets (ASC for oldest first, DESC for newest first) schema: $ref: '#/components/schemas/AssetOrder' - name: personId required: false in: query description: Filter assets containing a specific person (face recognition) schema: format: uuid type: string - name: slug required: false in: query schema: type: string - name: tagId required: false in: query description: Filter assets with a specific tag schema: format: uuid type: string - name: userId required: false in: query description: Filter assets by specific user ID schema: format: uuid type: string - name: visibility required: false in: query description: Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED) schema: $ref: '#/components/schemas/AssetVisibility' - name: withCoordinates required: false in: query description: Include location data in the response schema: type: boolean - name: withPartners required: false in: query description: Include assets shared by partners schema: type: boolean - name: withStacked required: false in: query description: Include stacked assets in the response. When true, only primary assets from stacks are returned. schema: type: boolean responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/TimeBucketsResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get time buckets tags: - Timeline x-immich-history: - version: v1 state: Added - version: v1 state: Internal x-immich-permission: asset.read x-immich-state: Internal /trash/empty: post: description: Permanently delete all items in the trash. operationId: emptyTrash parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/TrashResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Empty trash tags: - Trash x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.delete x-immich-state: Stable /trash/restore: post: description: Restore all items in the trash. operationId: restoreTrash parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/TrashResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Restore trash tags: - Trash x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.delete x-immich-state: Stable /trash/restore/assets: post: description: Restore specific assets from the trash. operationId: restoreAssets parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkIdsDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TrashResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Restore assets tags: - Trash x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: asset.delete x-immich-state: Stable /users: get: description: Retrieve a list of all users on the server. operationId: searchUsers parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/UserResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get all users tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: user.read x-immich-state: Stable /users/me: get: description: Retrieve information about the user making the API request. operationId: getMyUser parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get current user tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: user.read x-immich-state: Stable put: description: Update the current user making teh API request. operationId: updateMyUser parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UserUpdateMeDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserAdminResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update current user tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: user.update x-immich-state: Stable /users/me/license: delete: description: Delete the registered product key for the current user. operationId: deleteUserLicense parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete user product key tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userLicense.delete x-immich-state: Stable get: description: Retrieve information about whether the current user has a registered product key. operationId: getUserLicense parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/LicenseResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user product key tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userLicense.read x-immich-state: Stable put: description: Register a product key for the current user. operationId: setUserLicense parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/LicenseKeyDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LicenseResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Set user product key tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userLicense.update x-immich-state: Stable /users/me/onboarding: delete: description: Delete the onboarding status of the current user. operationId: deleteUserOnboarding parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete user onboarding tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userOnboarding.delete x-immich-state: Stable get: description: Retrieve the onboarding status of the current user. operationId: getUserOnboarding parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/OnboardingResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user onboarding tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userOnboarding.read x-immich-state: Stable put: description: Update the onboarding status of the current user. operationId: setUserOnboarding parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/OnboardingDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/OnboardingResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update user onboarding tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userOnboarding.update x-immich-state: Stable /users/me/preferences: get: description: Retrieve the preferences for the current user. operationId: getMyPreferences parameters: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserPreferencesResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Get my preferences tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userPreference.read x-immich-state: Stable put: description: Update the preferences of the current user. operationId: updateMyPreferences parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UserPreferencesUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserPreferencesResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update my preferences tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userPreference.update x-immich-state: Stable /users/profile-image: delete: description: Delete the profile image of the current user. operationId: deleteProfileImage parameters: [] responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete user profile image tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userProfileImage.delete x-immich-state: Stable post: description: Upload and set a new profile image for the current user. operationId: createProfileImage parameters: [] requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/CreateProfileImageDto' description: A new avatar for the user required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateProfileImageResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create user profile image tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userProfileImage.update x-immich-state: Stable /users/{id}: get: description: Retrieve a specific user by their ID. operationId: getUser parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a user tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: user.read x-immich-state: Stable /users/{id}/profile-image: get: description: Retrieve the profile image file for a user. operationId: getProfileImage parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/octet-stream: schema: format: binary type: string description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve user profile image tags: - Users x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: userProfileImage.read x-immich-state: Stable /view/folder: get: description: Retrieve assets that are children of a specific folder. operationId: getAssetsByOriginalPath parameters: - name: path required: true in: query schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AssetResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve assets by original path tags: - Views x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: folder.read x-immich-state: Stable /view/folder/unique-paths: get: description: Retrieve a list of unique folder paths from asset original paths. operationId: getUniqueOriginalPaths parameters: [] responses: '200': content: application/json: schema: items: type: string type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve unique paths tags: - Views x-immich-history: - version: v1 state: Added - version: v1 state: Beta - version: v2 state: Stable x-immich-permission: folder.read x-immich-state: Stable /workflows: get: description: Retrieve a list of workflows available to the authenticated user. operationId: getWorkflows parameters: [] responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/WorkflowResponseDto' type: array description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: List all workflows tags: - Workflows x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: workflow.read x-immich-state: Alpha post: description: Create a new workflow, the workflow can also be created with empty filters and actions. operationId: createWorkflow parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/WorkflowResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Create a workflow tags: - Workflows x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: workflow.create x-immich-state: Alpha /workflows/{id}: delete: description: Delete a workflow by its ID. operationId: deleteWorkflow parameters: - name: id required: true in: path schema: format: uuid type: string responses: '204': description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Delete a workflow tags: - Workflows x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: workflow.delete x-immich-state: Alpha get: description: Retrieve information about a specific workflow by its ID. operationId: getWorkflow parameters: - name: id required: true in: path schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkflowResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Retrieve a workflow tags: - Workflows x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: workflow.read x-immich-state: Alpha put: description: Update the information of a specific workflow by its ID. This endpoint can be used to update the workflow name, description, trigger type, filters and actions order, etc. operationId: updateWorkflow parameters: - name: id required: true in: path schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkflowUpdateDto' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkflowResponseDto' description: '' security: - bearer: [] - cookie: [] - api_key: [] summary: Update a workflow tags: - Workflows x-immich-history: - version: v2.3.0 state: Added - version: v2.3.0 state: Alpha x-immich-permission: workflow.update x-immich-state: Alpha info: title: Immich description: Immich API version: 2.7.4 contact: {} tags: - name: Activities description: An activity is a like or a comment made by a user on an asset or album. - name: Albums description: An album is a collection of assets that can be shared with other users or via shared links. - name: API keys description: An api key can be used to programmatically access the Immich API. - name: Assets description: An asset is an image or video that has been uploaded to Immich. - name: Authentication description: Endpoints related to user authentication, including OAuth. - name: Authentication (admin) description: Administrative endpoints related to authentication. - name: Database Backups (admin) description: Manage backups of the Immich database. - name: Deprecated description: Deprecated endpoints that are planned for removal in the next major release. - name: Download description: Endpoints for downloading assets or collections of assets. - name: Duplicates description: Endpoints for managing and identifying duplicate assets. - name: Faces description: A face is a detected human face within an asset, which can be associated with a person. Faces are normally detected via machine learning, but can also be created via manually. - name: Jobs description: Queues and background jobs are used for processing tasks asynchronously. Queues can be paused and resumed as needed. - name: Libraries description: An external library is made up of input file paths or expressions that are scanned for asset files. Discovered files are automatically imported. Assets much be unique within a library, but can be duplicated across libraries. Each user has a default upload library, and can have one or more external libraries. - name: Maintenance (admin) description: Maintenance mode allows you to put Immich in a read-only state to perform various operations. - name: Map description: Map endpoints include supplemental functionality related to geolocation, such as reverse geocoding and retrieving map markers for assets with geolocation data. - name: Memories description: A memory is a specialized collection of assets with dedicated viewing implementations in the web and mobile clients. A memory includes fields related to visibility and are automatically generated per user via a background job. - name: Notifications description: A notification is a specialized message sent to users to inform them of important events. Currently, these notifications are only shown in the Immich web application. - name: Notifications (admin) description: Notification administrative endpoints. - name: Partners description: A partner is a link with another user that allows sharing of assets between two users. - name: People description: A person is a collection of faces, which can be favorited and named. A person can also be merged into another person. People are automatically created via the face recognition job. - name: Plugins description: A plugin is an installed module that makes filters and actions available for the workflow feature. - name: Queues description: Queues and background jobs are used for processing tasks asynchronously. Queues can be paused and resumed as needed. - name: Search description: Endpoints related to searching assets via text, smart search, optical character recognition (OCR), and other filters like person, album, and other metadata. Search endpoints usually support pagination and sorting. - name: Server description: Information about the current server deployment, including version and build information, available features, supported media types, and more. - name: Sessions description: A session represents an authenticated login session for a user. Sessions also appear in the web application as "Authorized devices". - name: Shared links description: A shared link is a public url that provides access to a specific album, asset, or collection of assets. A shared link can be protected with a password, include a specific slug, allow or disallow downloads, and optionally include an expiration date. - name: Stacks description: A stack is a group of related assets. One asset is the "primary" asset, and the rest are "child" assets. On the main timeline, stack parents are included by default, while child assets are hidden. - name: Sync description: A collection of endpoints for the new mobile synchronization implementation. - name: System config description: Endpoints to view, modify, and validate the system configuration settings. - name: System metadata description: Endpoints to view, modify, and validate the system metadata, which includes information about things like admin onboarding status. - name: Tags description: A tag is a user-defined label that can be applied to assets for organizational purposes. Tags can also be hierarchical, allowing for parent-child relationships between tags. - name: Timeline description: Specialized endpoints related to the timeline implementation used in the web application. External applications or tools should not use or rely on these endpoints, as they are subject to change without notice. - name: Trash description: Endpoints for managing the trash can, which includes assets that have been discarded. Items in the trash are automatically deleted after a configured amount of time. - name: Users (admin) description: Administrative endpoints for managing users, including creating, updating, deleting, and restoring users. Also includes endpoints for resetting passwords and PIN codes. - name: Users description: Endpoints for viewing and updating the current users, including product key information, profile picture data, onboarding progress, and more. - name: Views description: Endpoints for specialized views, such as the folder view. - name: Workflows description: A workflow is a set of actions that run whenever a triggering event occurs. Workflows also can include filters to further limit execution. servers: - url: /api components: securitySchemes: bearer: scheme: Bearer bearerFormat: JWT type: http in: header cookie: type: apiKey in: cookie name: immich_access_token api_key: type: apiKey in: header name: x-api-key schemas: APIKeyCreateDto: properties: name: description: API key name type: string permissions: description: List of permissions items: $ref: '#/components/schemas/Permission' minItems: 1 type: array required: - permissions type: object APIKeyCreateResponseDto: properties: apiKey: $ref: '#/components/schemas/APIKeyResponseDto' secret: description: API key secret (only shown once) type: string required: - apiKey - secret type: object APIKeyResponseDto: properties: createdAt: description: Creation date format: date-time type: string id: description: API key ID type: string name: description: API key name type: string permissions: description: List of permissions items: $ref: '#/components/schemas/Permission' type: array updatedAt: description: Last update date format: date-time type: string required: - createdAt - id - name - permissions - updatedAt type: object APIKeyUpdateDto: properties: name: description: API key name type: string permissions: description: List of permissions items: $ref: '#/components/schemas/Permission' minItems: 1 type: array type: object ActivityCreateDto: properties: albumId: description: Album ID format: uuid type: string assetId: description: Asset ID (if activity is for an asset) format: uuid type: string comment: description: Comment text (required if type is comment) type: string type: allOf: - $ref: '#/components/schemas/ReactionType' description: Activity type (like or comment) required: - albumId - type type: object ActivityResponseDto: properties: assetId: description: Asset ID (if activity is for an asset) nullable: true type: string comment: description: Comment text (for comment activities) nullable: true type: string createdAt: description: Creation date format: date-time type: string id: description: Activity ID type: string type: allOf: - $ref: '#/components/schemas/ReactionType' description: Activity type user: $ref: '#/components/schemas/UserResponseDto' required: - assetId - createdAt - id - type - user type: object ActivityStatisticsResponseDto: properties: comments: description: Number of comments type: integer likes: description: Number of likes type: integer required: - comments - likes type: object AddUsersDto: properties: albumUsers: description: Album users to add items: $ref: '#/components/schemas/AlbumUserAddDto' minItems: 1 type: array required: - albumUsers type: object AdminOnboardingUpdateDto: properties: isOnboarded: description: Is admin onboarded type: boolean required: - isOnboarded type: object AlbumResponseDto: properties: albumName: description: Album name type: string albumThumbnailAssetId: description: Thumbnail asset ID nullable: true type: string albumUsers: items: $ref: '#/components/schemas/AlbumUserResponseDto' type: array assetCount: description: Number of assets type: integer assets: items: $ref: '#/components/schemas/AssetResponseDto' type: array contributorCounts: items: $ref: '#/components/schemas/ContributorCountResponseDto' type: array createdAt: description: Creation date format: date-time type: string description: description: Album description type: string endDate: description: End date (latest asset) format: date-time type: string hasSharedLink: description: Has shared link type: boolean id: description: Album ID type: string isActivityEnabled: description: Activity feed enabled type: boolean lastModifiedAssetTimestamp: description: Last modified asset timestamp format: date-time type: string order: allOf: - $ref: '#/components/schemas/AssetOrder' description: Asset sort order owner: $ref: '#/components/schemas/UserResponseDto' ownerId: description: Owner user ID type: string shared: description: Is shared album type: boolean startDate: description: Start date (earliest asset) format: date-time type: string updatedAt: description: Last update date format: date-time type: string required: - albumName - albumThumbnailAssetId - albumUsers - assetCount - assets - createdAt - description - hasSharedLink - id - isActivityEnabled - owner - ownerId - shared - updatedAt type: object AlbumStatisticsResponseDto: properties: notShared: description: Number of non-shared albums type: integer owned: description: Number of owned albums type: integer shared: description: Number of shared albums type: integer required: - notShared - owned - shared type: object AlbumUserAddDto: properties: role: allOf: - $ref: '#/components/schemas/AlbumUserRole' default: editor description: Album user role userId: description: User ID format: uuid type: string required: - userId type: object AlbumUserCreateDto: properties: role: allOf: - $ref: '#/components/schemas/AlbumUserRole' description: Album user role userId: description: User ID format: uuid type: string required: - role - userId type: object AlbumUserResponseDto: properties: role: allOf: - $ref: '#/components/schemas/AlbumUserRole' description: Album user role user: $ref: '#/components/schemas/UserResponseDto' required: - role - user type: object AlbumUserRole: description: Album user role enum: - editor - viewer type: string AlbumsAddAssetsDto: properties: albumIds: description: Album IDs items: format: uuid type: string type: array assetIds: description: Asset IDs items: format: uuid type: string type: array required: - albumIds - assetIds type: object AlbumsAddAssetsResponseDto: properties: error: allOf: - $ref: '#/components/schemas/BulkIdErrorReason' description: Error reason success: description: Operation success type: boolean required: - success type: object AlbumsResponse: properties: defaultAssetOrder: allOf: - $ref: '#/components/schemas/AssetOrder' default: desc description: Default asset order for albums required: - defaultAssetOrder type: object AlbumsUpdate: description: Album preferences properties: defaultAssetOrder: allOf: - $ref: '#/components/schemas/AssetOrder' description: Default asset order for albums type: object AssetBulkDeleteDto: properties: force: description: Force delete even if in use type: boolean ids: description: IDs to process items: format: uuid type: string type: array required: - ids type: object AssetBulkUpdateDto: properties: dateTimeOriginal: description: Original date and time type: string dateTimeRelative: description: Relative time offset in seconds type: number description: description: Asset description type: string duplicateId: description: Duplicate ID nullable: true type: string ids: description: Asset IDs to update items: format: uuid type: string type: array isFavorite: description: Mark as favorite type: boolean latitude: description: Latitude coordinate type: number longitude: description: Longitude coordinate type: number rating: description: Rating in range [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable timeZone: description: Time zone (IANA timezone) type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Asset visibility required: - ids type: object AssetBulkUploadCheckDto: properties: assets: description: Assets to check items: $ref: '#/components/schemas/AssetBulkUploadCheckItem' type: array required: - assets type: object AssetBulkUploadCheckItem: properties: checksum: description: Base64 or hex encoded SHA1 hash type: string id: description: Asset ID type: string required: - checksum - id type: object AssetBulkUploadCheckResponseDto: properties: results: description: Upload check results items: $ref: '#/components/schemas/AssetBulkUploadCheckResult' type: array required: - results type: object AssetBulkUploadCheckResult: properties: action: description: Upload action enum: - accept - reject type: string assetId: description: Existing asset ID if duplicate type: string id: description: Asset ID type: string isTrashed: description: Whether existing asset is trashed type: boolean reason: description: Rejection reason if rejected enum: - duplicate - unsupported-format type: string required: - action - id type: object AssetCopyDto: properties: albums: default: true description: Copy album associations type: boolean favorite: default: true description: Copy favorite status type: boolean sharedLinks: default: true description: Copy shared links type: boolean sidecar: default: true description: Copy sidecar file type: boolean sourceId: description: Source asset ID format: uuid type: string stack: default: true description: Copy stack association type: boolean targetId: description: Target asset ID format: uuid type: string required: - sourceId - targetId type: object AssetDeltaSyncDto: properties: updatedAfter: description: Sync assets updated after this date format: date-time type: string userIds: description: User IDs to sync items: format: uuid type: string type: array required: - updatedAfter - userIds type: object AssetDeltaSyncResponseDto: properties: deleted: description: Deleted asset IDs items: type: string type: array needsFullSync: description: Whether full sync is needed type: boolean upserted: description: Upserted assets items: $ref: '#/components/schemas/AssetResponseDto' type: array required: - deleted - needsFullSync - upserted type: object AssetEditAction: description: Type of edit action to perform enum: - crop - rotate - mirror type: string AssetEditActionItemDto: properties: action: allOf: - $ref: '#/components/schemas/AssetEditAction' description: Type of edit action to perform parameters: anyOf: - $ref: '#/components/schemas/CropParameters' - $ref: '#/components/schemas/RotateParameters' - $ref: '#/components/schemas/MirrorParameters' description: List of edit actions to apply (crop, rotate, or mirror) required: - action - parameters type: object AssetEditActionItemResponseDto: properties: action: allOf: - $ref: '#/components/schemas/AssetEditAction' description: Type of edit action to perform id: format: uuid type: string parameters: anyOf: - $ref: '#/components/schemas/CropParameters' - $ref: '#/components/schemas/RotateParameters' - $ref: '#/components/schemas/MirrorParameters' description: List of edit actions to apply (crop, rotate, or mirror) required: - action - id - parameters type: object AssetEditsCreateDto: properties: edits: description: List of edit actions to apply (crop, rotate, or mirror) items: $ref: '#/components/schemas/AssetEditActionItemDto' minItems: 1 type: array required: - edits type: object AssetEditsResponseDto: properties: assetId: description: Asset ID these edits belong to format: uuid type: string edits: description: List of edit actions applied to the asset items: $ref: '#/components/schemas/AssetEditActionItemResponseDto' type: array required: - assetId - edits type: object AssetFaceCreateDto: properties: assetId: description: Asset ID format: uuid type: string height: description: Face bounding box height type: integer imageHeight: description: Image height in pixels type: integer imageWidth: description: Image width in pixels type: integer personId: description: Person ID format: uuid type: string width: description: Face bounding box width type: integer x: description: Face bounding box X coordinate type: integer y: description: Face bounding box Y coordinate type: integer required: - assetId - height - imageHeight - imageWidth - personId - width - x - y type: object AssetFaceDeleteDto: properties: force: description: Force delete even if person has other faces type: boolean required: - force type: object AssetFaceResponseDto: properties: boundingBoxX1: description: Bounding box X1 coordinate type: integer boundingBoxX2: description: Bounding box X2 coordinate type: integer boundingBoxY1: description: Bounding box Y1 coordinate type: integer boundingBoxY2: description: Bounding box Y2 coordinate type: integer id: description: Face ID format: uuid type: string imageHeight: description: Image height in pixels type: integer imageWidth: description: Image width in pixels type: integer person: allOf: - $ref: '#/components/schemas/PersonResponseDto' description: Person associated with face nullable: true sourceType: allOf: - $ref: '#/components/schemas/SourceType' description: Face detection source type required: - boundingBoxX1 - boundingBoxX2 - boundingBoxY1 - boundingBoxY2 - id - imageHeight - imageWidth - person type: object AssetFaceUpdateDto: properties: data: description: Face update items items: $ref: '#/components/schemas/AssetFaceUpdateItem' type: array required: - data type: object AssetFaceUpdateItem: properties: assetId: description: Asset ID format: uuid type: string personId: description: Person ID format: uuid type: string required: - assetId - personId type: object AssetFaceWithoutPersonResponseDto: properties: boundingBoxX1: description: Bounding box X1 coordinate type: integer boundingBoxX2: description: Bounding box X2 coordinate type: integer boundingBoxY1: description: Bounding box Y1 coordinate type: integer boundingBoxY2: description: Bounding box Y2 coordinate type: integer id: description: Face ID format: uuid type: string imageHeight: description: Image height in pixels type: integer imageWidth: description: Image width in pixels type: integer sourceType: allOf: - $ref: '#/components/schemas/SourceType' description: Face detection source type required: - boundingBoxX1 - boundingBoxX2 - boundingBoxY1 - boundingBoxY2 - id - imageHeight - imageWidth type: object AssetFullSyncDto: properties: lastId: description: Last asset ID (pagination) format: uuid type: string limit: description: Maximum number of assets to return minimum: 1 type: integer updatedUntil: description: Sync assets updated until this date format: date-time type: string userId: description: Filter by user ID format: uuid type: string required: - limit - updatedUntil type: object AssetIdsDto: properties: assetIds: description: Asset IDs items: format: uuid type: string type: array required: - assetIds type: object AssetIdsResponseDto: properties: assetId: description: Asset ID type: string error: description: Error reason if failed enum: - duplicate - no_permission - not_found type: string success: description: Whether operation succeeded type: boolean required: - assetId - success type: object AssetJobName: description: Job name enum: - refresh-faces - refresh-metadata - regenerate-thumbnail - transcode-video type: string AssetJobsDto: properties: assetIds: description: Asset IDs items: format: uuid type: string type: array name: allOf: - $ref: '#/components/schemas/AssetJobName' description: Job name required: - assetIds - name type: object AssetMediaCreateDto: properties: assetData: description: Asset file data format: binary type: string deviceAssetId: description: Device asset ID type: string deviceId: description: Device ID type: string duration: description: Duration (for videos) type: string fileCreatedAt: description: File creation date format: date-time type: string fileModifiedAt: description: File modification date format: date-time type: string filename: description: Filename type: string isFavorite: description: Mark as favorite type: boolean livePhotoVideoId: description: Live photo video ID format: uuid type: string metadata: description: Asset metadata items items: $ref: '#/components/schemas/AssetMetadataUpsertItemDto' type: array sidecarData: description: Sidecar file data format: binary type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Asset visibility required: - assetData - deviceAssetId - deviceId - fileCreatedAt - fileModifiedAt type: object AssetMediaReplaceDto: properties: assetData: description: Asset file data format: binary type: string deviceAssetId: description: Device asset ID type: string deviceId: description: Device ID type: string duration: description: Duration (for videos) type: string fileCreatedAt: description: File creation date format: date-time type: string fileModifiedAt: description: File modification date format: date-time type: string filename: description: Filename type: string required: - assetData - deviceAssetId - deviceId - fileCreatedAt - fileModifiedAt type: object AssetMediaResponseDto: properties: id: description: Asset media ID type: string status: allOf: - $ref: '#/components/schemas/AssetMediaStatus' description: Upload status required: - id - status type: object AssetMediaSize: enum: - original - fullsize - preview - thumbnail type: string AssetMediaStatus: description: Upload status enum: - created - replaced - duplicate type: string AssetMetadataBulkDeleteDto: properties: items: description: Metadata items to delete items: $ref: '#/components/schemas/AssetMetadataBulkDeleteItemDto' type: array required: - items type: object AssetMetadataBulkDeleteItemDto: properties: assetId: description: Asset ID format: uuid type: string key: description: Metadata key type: string required: - assetId - key type: object AssetMetadataBulkResponseDto: properties: assetId: description: Asset ID type: string key: description: Metadata key type: string updatedAt: description: Last update date format: date-time type: string value: description: Metadata value (object) type: object required: - assetId - key - updatedAt - value type: object AssetMetadataBulkUpsertDto: properties: items: description: Metadata items to upsert items: $ref: '#/components/schemas/AssetMetadataBulkUpsertItemDto' type: array required: - items type: object AssetMetadataBulkUpsertItemDto: properties: assetId: description: Asset ID format: uuid type: string key: description: Metadata key type: string value: description: Metadata value (object) type: object required: - assetId - key - value type: object AssetMetadataResponseDto: properties: key: description: Metadata key type: string updatedAt: description: Last update date format: date-time type: string value: description: Metadata value (object) type: object required: - key - updatedAt - value type: object AssetMetadataUpsertDto: properties: items: description: Metadata items to upsert items: $ref: '#/components/schemas/AssetMetadataUpsertItemDto' type: array required: - items type: object AssetMetadataUpsertItemDto: properties: key: description: Metadata key type: string value: description: Metadata value (object) type: object required: - key - value type: object AssetOcrResponseDto: properties: assetId: format: uuid type: string boxScore: description: Confidence score for text detection box format: double type: number id: format: uuid type: string text: description: Recognized text type: string textScore: description: Confidence score for text recognition format: double type: number x1: description: Normalized x coordinate of box corner 1 (0-1) format: double type: number x2: description: Normalized x coordinate of box corner 2 (0-1) format: double type: number x3: description: Normalized x coordinate of box corner 3 (0-1) format: double type: number x4: description: Normalized x coordinate of box corner 4 (0-1) format: double type: number y1: description: Normalized y coordinate of box corner 1 (0-1) format: double type: number y2: description: Normalized y coordinate of box corner 2 (0-1) format: double type: number y3: description: Normalized y coordinate of box corner 3 (0-1) format: double type: number y4: description: Normalized y coordinate of box corner 4 (0-1) format: double type: number required: - assetId - boxScore - id - text - textScore - x1 - x2 - x3 - x4 - y1 - y2 - y3 - y4 type: object AssetOrder: description: Asset sort order enum: - asc - desc type: string AssetResponseDto: properties: checksum: description: Base64 encoded SHA1 hash type: string createdAt: description: The UTC timestamp when the asset was originally uploaded to Immich. example: 2024-01-15T20:30:00.000Z format: date-time type: string deviceAssetId: description: Device asset ID type: string deviceId: description: Device ID type: string duplicateId: description: Duplicate group ID nullable: true type: string duration: description: Video duration (for videos) type: string exifInfo: $ref: '#/components/schemas/ExifResponseDto' fileCreatedAt: description: The actual UTC timestamp when the file was created/captured, preserving timezone information. This is the authoritative timestamp for chronological sorting within timeline groups. Combined with timezone data, this can be used to determine the exact moment the photo was taken. example: 2024-01-15T19:30:00.000Z format: date-time type: string fileModifiedAt: description: The UTC timestamp when the file was last modified on the filesystem. This reflects the last time the physical file was changed, which may be different from when the photo was originally taken. example: 2024-01-16T10:15:00.000Z format: date-time type: string hasMetadata: description: Whether asset has metadata type: boolean height: description: Asset height nullable: true type: number id: description: Asset ID type: string isArchived: description: Is archived type: boolean isEdited: description: Is edited type: boolean x-immich-history: - version: v2.5.0 state: Added - version: v2.5.0 state: Beta x-immich-state: Beta isFavorite: description: Is favorite type: boolean isOffline: description: Is offline type: boolean isTrashed: description: Is trashed type: boolean libraryId: deprecated: true description: Library ID format: uuid nullable: true type: string x-immich-history: - version: v1 state: Added - version: v1 state: Deprecated x-immich-state: Deprecated livePhotoVideoId: description: Live photo video ID nullable: true type: string localDateTime: description: The local date and time when the photo/video was taken, derived from EXIF metadata. This represents the photographer's local time regardless of timezone, stored as a timezone-agnostic timestamp. Used for timeline grouping by "local" days and months. example: 2024-01-15T14:30:00.000Z format: date-time type: string originalFileName: description: Original file name type: string originalMimeType: description: Original MIME type type: string originalPath: description: Original file path type: string owner: $ref: '#/components/schemas/UserResponseDto' ownerId: description: Owner user ID type: string people: items: $ref: '#/components/schemas/PersonWithFacesResponseDto' type: array resized: deprecated: true description: Is resized type: boolean x-immich-history: - version: v1 state: Added - version: v1.113.0 state: Deprecated x-immich-state: Deprecated stack: allOf: - $ref: '#/components/schemas/AssetStackResponseDto' nullable: true tags: items: $ref: '#/components/schemas/TagResponseDto' type: array thumbhash: description: Thumbhash for thumbnail generation (base64) also used as the c query param for thumbnail cache busting. nullable: true type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type unassignedFaces: items: $ref: '#/components/schemas/AssetFaceWithoutPersonResponseDto' type: array updatedAt: description: The UTC timestamp when the asset record was last updated in the database. This is automatically maintained by the database and reflects when any field in the asset was last modified. example: 2024-01-16T12:45:30.000Z format: date-time type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Asset visibility width: description: Asset width nullable: true type: number required: - checksum - createdAt - deviceAssetId - deviceId - duration - fileCreatedAt - fileModifiedAt - hasMetadata - height - id - isArchived - isEdited - isFavorite - isOffline - isTrashed - localDateTime - originalFileName - originalPath - ownerId - thumbhash - type - updatedAt - visibility - width type: object AssetStackResponseDto: properties: assetCount: description: Number of assets in stack type: integer id: description: Stack ID type: string primaryAssetId: description: Primary asset ID type: string required: - assetCount - id - primaryAssetId type: object AssetStatsResponseDto: properties: images: description: Number of images type: integer total: description: Total number of assets type: integer videos: description: Number of videos type: integer required: - images - total - videos type: object AssetTypeEnum: description: Asset type enum: - IMAGE - VIDEO - AUDIO - OTHER type: string AssetVisibility: description: Asset visibility enum: - archive - timeline - hidden - locked type: string AudioCodec: description: Target audio codec enum: - mp3 - aac - libopus - opus - pcm_s16le type: string AuthStatusResponseDto: properties: expiresAt: description: Session expiration date type: string isElevated: description: Is elevated session type: boolean password: description: Has password set type: boolean pinCode: description: Has PIN code set type: boolean pinExpiresAt: description: PIN expiration date type: string required: - isElevated - password - pinCode type: object AvatarUpdate: properties: color: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color type: object BulkIdErrorReason: description: Error reason enum: - duplicate - no_permission - not_found - unknown - validation type: string BulkIdResponseDto: properties: error: description: Error reason if failed enum: - duplicate - no_permission - not_found - unknown - validation type: string errorMessage: type: string id: description: ID type: string success: description: Whether operation succeeded type: boolean required: - id - success type: object BulkIdsDto: properties: ids: description: IDs to process items: format: uuid type: string type: array required: - ids type: object CLIPConfig: properties: enabled: description: Whether the task is enabled type: boolean modelName: description: Name of the model to use type: string required: - enabled - modelName type: object CQMode: description: CQ mode enum: - auto - cqp - icq type: string CastResponse: properties: gCastEnabled: default: false description: Whether Google Cast is enabled type: boolean required: - gCastEnabled type: object CastUpdate: properties: gCastEnabled: description: Whether Google Cast is enabled type: boolean type: object ChangePasswordDto: properties: invalidateSessions: default: false description: Invalidate all other sessions type: boolean newPassword: description: New password (min 8 characters) example: password minLength: 8 type: string password: description: Current password example: password type: string required: - newPassword - password type: object CheckExistingAssetsDto: properties: deviceAssetIds: description: Device asset IDs to check items: type: string minItems: 1 type: array deviceId: description: Device ID type: string required: - deviceAssetIds - deviceId type: object CheckExistingAssetsResponseDto: properties: existingIds: description: Existing asset IDs items: type: string type: array required: - existingIds type: object Colorspace: description: Colorspace enum: - srgb - p3 type: string ContributorCountResponseDto: properties: assetCount: description: Number of assets contributed type: integer userId: description: User ID type: string required: - assetCount - userId type: object CreateAlbumDto: properties: albumName: description: Album name type: string albumUsers: description: Album users items: $ref: '#/components/schemas/AlbumUserCreateDto' type: array assetIds: description: Initial asset IDs items: format: uuid type: string type: array description: description: Album description type: string required: - albumName type: object CreateLibraryDto: properties: exclusionPatterns: description: Exclusion patterns (max 128) items: type: string maxItems: 128 type: array uniqueItems: true importPaths: description: Import paths (max 128) items: type: string maxItems: 128 type: array uniqueItems: true name: description: Library name type: string ownerId: description: Owner user ID format: uuid type: string required: - ownerId type: object CreateProfileImageDto: properties: file: description: Profile image file format: binary type: string required: - file type: object CreateProfileImageResponseDto: properties: profileChangedAt: description: Profile image change date format: date-time type: string profileImagePath: description: Profile image file path type: string userId: description: User ID type: string required: - profileChangedAt - profileImagePath - userId type: object CropParameters: properties: height: description: Height of the crop minimum: 1 type: number width: description: Width of the crop minimum: 1 type: number x: description: Top-Left X coordinate of crop minimum: 0 type: number y: description: Top-Left Y coordinate of crop minimum: 0 type: number required: - height - width - x - y type: object DatabaseBackupConfig: properties: cronExpression: description: Cron expression type: string enabled: description: Enabled type: boolean keepLastAmount: description: Keep last amount minimum: 1 type: number required: - cronExpression - enabled - keepLastAmount type: object DatabaseBackupDeleteDto: properties: backups: items: type: string type: array required: - backups type: object DatabaseBackupDto: properties: filename: type: string filesize: type: number timezone: type: string required: - filename - filesize - timezone type: object DatabaseBackupListResponseDto: properties: backups: items: $ref: '#/components/schemas/DatabaseBackupDto' type: array required: - backups type: object DatabaseBackupUploadDto: properties: file: format: binary type: string type: object DownloadArchiveDto: properties: assetIds: description: Asset IDs items: format: uuid type: string type: array edited: description: Download edited asset if available type: boolean required: - assetIds type: object DownloadArchiveInfo: properties: assetIds: description: Asset IDs in this archive items: type: string type: array size: description: Archive size in bytes type: integer required: - assetIds - size type: object DownloadInfoDto: properties: albumId: description: Album ID to download format: uuid type: string archiveSize: description: Archive size limit in bytes minimum: 1 type: integer assetIds: description: Asset IDs to download items: format: uuid type: string type: array userId: description: User ID to download assets from format: uuid type: string type: object DownloadResponse: properties: archiveSize: description: Maximum archive size in bytes type: integer includeEmbeddedVideos: default: false description: Whether to include embedded videos in downloads type: boolean required: - archiveSize - includeEmbeddedVideos type: object DownloadResponseDto: properties: archives: description: Archive information items: $ref: '#/components/schemas/DownloadArchiveInfo' type: array totalSize: description: Total size in bytes type: integer required: - archives - totalSize type: object DownloadUpdate: properties: archiveSize: description: Maximum archive size in bytes minimum: 1 type: integer includeEmbeddedVideos: description: Whether to include embedded videos in downloads type: boolean type: object DuplicateDetectionConfig: properties: enabled: description: Whether the task is enabled type: boolean maxDistance: description: Maximum distance threshold for duplicate detection format: double maximum: 0.1 minimum: 0.001 type: number required: - enabled - maxDistance type: object DuplicateResolveDto: properties: groups: description: List of duplicate groups to resolve items: $ref: '#/components/schemas/DuplicateResolveGroupDto' minItems: 1 type: array required: - groups type: object DuplicateResolveGroupDto: properties: duplicateId: format: uuid type: string keepAssetIds: description: Asset IDs to keep items: format: uuid type: string type: array trashAssetIds: description: Asset IDs to trash or delete items: format: uuid type: string type: array required: - duplicateId - keepAssetIds - trashAssetIds type: object DuplicateResponseDto: properties: assets: description: Duplicate assets items: $ref: '#/components/schemas/AssetResponseDto' type: array duplicateId: description: Duplicate group ID type: string suggestedKeepAssetIds: description: Suggested asset IDs to keep based on file size and EXIF data items: format: uuid type: string type: array required: - assets - duplicateId - suggestedKeepAssetIds type: object EmailNotificationsResponse: properties: albumInvite: description: Whether to receive email notifications for album invites type: boolean albumUpdate: description: Whether to receive email notifications for album updates type: boolean enabled: description: Whether email notifications are enabled type: boolean required: - albumInvite - albumUpdate - enabled type: object EmailNotificationsUpdate: properties: albumInvite: description: Whether to receive email notifications for album invites type: boolean albumUpdate: description: Whether to receive email notifications for album updates type: boolean enabled: description: Whether email notifications are enabled type: boolean type: object ExifResponseDto: properties: city: default: null description: City name nullable: true type: string country: default: null description: Country name nullable: true type: string dateTimeOriginal: default: null description: Original date/time format: date-time nullable: true type: string description: default: null description: Image description nullable: true type: string exifImageHeight: default: null description: Image height in pixels nullable: true type: number exifImageWidth: default: null description: Image width in pixels nullable: true type: number exposureTime: default: null description: Exposure time nullable: true type: string fNumber: default: null description: F-number (aperture) nullable: true type: number fileSizeInByte: default: null description: File size in bytes format: int64 nullable: true type: integer focalLength: default: null description: Focal length in mm nullable: true type: number iso: default: null description: ISO sensitivity nullable: true type: number latitude: default: null description: GPS latitude nullable: true type: number lensModel: default: null description: Lens model nullable: true type: string longitude: default: null description: GPS longitude nullable: true type: number make: default: null description: Camera make nullable: true type: string model: default: null description: Camera model nullable: true type: string modifyDate: default: null description: Modification date/time format: date-time nullable: true type: string orientation: default: null description: Image orientation nullable: true type: string projectionType: default: null description: Projection type nullable: true type: string rating: default: null description: Rating nullable: true type: number state: default: null description: State/province name nullable: true type: string timeZone: default: null description: Time zone nullable: true type: string type: object FaceDto: properties: id: description: Face ID format: uuid type: string required: - id type: object FacialRecognitionConfig: properties: enabled: description: Whether the task is enabled type: boolean maxDistance: description: Maximum distance threshold for face recognition format: double maximum: 2 minimum: 0.1 type: number minFaces: description: Minimum number of faces required for recognition minimum: 1 type: integer minScore: description: Minimum confidence score for face detection format: double maximum: 1 minimum: 0.1 type: number modelName: description: Name of the model to use type: string required: - enabled - maxDistance - minFaces - minScore - modelName type: object FoldersResponse: properties: enabled: default: false description: Whether folders are enabled type: boolean sidebarWeb: default: false description: Whether folders appear in web sidebar type: boolean required: - enabled - sidebarWeb type: object FoldersUpdate: properties: enabled: description: Whether folders are enabled type: boolean sidebarWeb: description: Whether folders appear in web sidebar type: boolean type: object ImageFormat: description: Image format enum: - jpeg - webp type: string JobCreateDto: properties: name: allOf: - $ref: '#/components/schemas/ManualJobName' description: Job name required: - name type: object JobName: description: Job name enum: - AssetDelete - AssetDeleteCheck - AssetDetectFacesQueueAll - AssetDetectFaces - AssetDetectDuplicatesQueueAll - AssetDetectDuplicates - AssetEditThumbnailGeneration - AssetEncodeVideoQueueAll - AssetEncodeVideo - AssetEmptyTrash - AssetExtractMetadataQueueAll - AssetExtractMetadata - AssetFileMigration - AssetGenerateThumbnailsQueueAll - AssetGenerateThumbnails - AuditLogCleanup - AuditTableCleanup - DatabaseBackup - FacialRecognitionQueueAll - FacialRecognition - FileDelete - FileMigrationQueueAll - LibraryDeleteCheck - LibraryDelete - LibraryRemoveAsset - LibraryScanAssetsQueueAll - LibrarySyncAssets - LibrarySyncFilesQueueAll - LibrarySyncFiles - LibraryScanQueueAll - MemoryCleanup - MemoryGenerate - NotificationsCleanup - NotifyUserSignup - NotifyAlbumInvite - NotifyAlbumUpdate - UserDelete - UserDeleteCheck - UserSyncUsage - PersonCleanup - PersonFileMigration - PersonGenerateThumbnail - SessionCleanup - SendMail - SidecarQueueAll - SidecarCheck - SidecarWrite - SmartSearchQueueAll - SmartSearch - StorageTemplateMigration - StorageTemplateMigrationSingle - TagCleanup - VersionCheck - OcrQueueAll - Ocr - WorkflowRun type: string JobSettingsDto: properties: concurrency: description: Concurrency minimum: 1 type: integer required: - concurrency type: object LibraryResponseDto: properties: assetCount: description: Number of assets type: integer createdAt: description: Creation date format: date-time type: string exclusionPatterns: description: Exclusion patterns items: type: string type: array id: description: Library ID type: string importPaths: description: Import paths items: type: string type: array name: description: Library name type: string ownerId: description: Owner user ID type: string refreshedAt: description: Last refresh date format: date-time nullable: true type: string updatedAt: description: Last update date format: date-time type: string required: - assetCount - createdAt - exclusionPatterns - id - importPaths - name - ownerId - refreshedAt - updatedAt type: object LibraryStatsResponseDto: properties: photos: default: 0 description: Number of photos type: integer total: default: 0 description: Total number of assets type: integer usage: default: 0 description: Storage usage in bytes format: int64 type: integer videos: default: 0 description: Number of videos type: integer required: - photos - total - usage - videos type: object LicenseKeyDto: properties: activationKey: description: Activation key type: string licenseKey: description: 'License key (format: IM(SV|CL)(-XXXX){8})' pattern: /IM(SV|CL)(-[\dA-Za-z]{4}){8}/ type: string required: - activationKey - licenseKey type: object LicenseResponseDto: properties: activatedAt: description: Activation date format: date-time type: string activationKey: description: Activation key type: string licenseKey: description: 'License key (format: IM(SV|CL)(-XXXX){8})' pattern: /IM(SV|CL)(-[\dA-Za-z]{4}){8}/ type: string required: - activatedAt - activationKey - licenseKey type: object LogLevel: enum: - verbose - debug - log - warn - error - fatal type: string LoginCredentialDto: properties: email: description: User email example: testuser@email.com format: email type: string password: description: User password example: password type: string required: - email - password type: object LoginResponseDto: properties: accessToken: description: Access token type: string isAdmin: description: Is admin user type: boolean isOnboarded: description: Is onboarded type: boolean name: description: User name type: string profileImagePath: description: Profile image path type: string shouldChangePassword: description: Should change password type: boolean userEmail: description: User email type: string userId: description: User ID type: string required: - accessToken - isAdmin - isOnboarded - name - profileImagePath - shouldChangePassword - userEmail - userId type: object LogoutResponseDto: properties: redirectUri: description: Redirect URI type: string successful: description: Logout successful type: boolean required: - redirectUri - successful type: object MachineLearningAvailabilityChecksDto: properties: enabled: description: Enabled type: boolean interval: type: number timeout: type: number required: - enabled - interval - timeout type: object MaintenanceAction: description: Maintenance action enum: - start - end - select_database_restore - restore_database type: string MaintenanceAuthDto: properties: username: description: Maintenance username type: string required: - username type: object MaintenanceDetectInstallResponseDto: properties: storage: items: $ref: '#/components/schemas/MaintenanceDetectInstallStorageFolderDto' type: array required: - storage type: object MaintenanceDetectInstallStorageFolderDto: properties: files: description: Number of files in the folder type: number folder: allOf: - $ref: '#/components/schemas/StorageFolder' description: Storage folder readable: description: Whether the folder is readable type: boolean writable: description: Whether the folder is writable type: boolean required: - files - folder - readable - writable type: object MaintenanceLoginDto: properties: token: description: Maintenance token type: string type: object MaintenanceStatusResponseDto: properties: action: allOf: - $ref: '#/components/schemas/MaintenanceAction' description: Maintenance action active: type: boolean error: type: string progress: type: number task: type: string required: - action - active type: object ManualJobName: description: Job name enum: - person-cleanup - tag-cleanup - user-cleanup - memory-cleanup - memory-create - backup-database type: string MapMarkerResponseDto: properties: city: description: City name nullable: true type: string country: description: Country name nullable: true type: string id: description: Asset ID type: string lat: description: Latitude format: double type: number lon: description: Longitude format: double type: number state: description: State/Province name nullable: true type: string required: - city - country - id - lat - lon - state type: object MapReverseGeocodeResponseDto: properties: city: description: City name nullable: true type: string country: description: Country name nullable: true type: string state: description: State/Province name nullable: true type: string required: - city - country - state type: object MemoriesResponse: properties: duration: default: 5 description: Memory duration in seconds type: integer enabled: default: true description: Whether memories are enabled type: boolean required: - duration - enabled type: object MemoriesUpdate: properties: duration: description: Memory duration in seconds minimum: 1 type: integer enabled: description: Whether memories are enabled type: boolean type: object MemoryCreateDto: properties: assetIds: description: Asset IDs to associate with memory items: format: uuid type: string type: array data: $ref: '#/components/schemas/OnThisDayDto' hideAt: description: Date when memory should be hidden format: date-time type: string x-immich-history: - version: v2.6.0 state: Added - version: v2.6.0 state: Stable x-immich-state: Stable isSaved: description: Is memory saved type: boolean memoryAt: description: Memory date format: date-time type: string seenAt: description: Date when memory was seen format: date-time type: string showAt: description: Date when memory should be shown format: date-time type: string x-immich-history: - version: v2.6.0 state: Added - version: v2.6.0 state: Stable x-immich-state: Stable type: allOf: - $ref: '#/components/schemas/MemoryType' description: Memory type required: - data - memoryAt - type type: object MemoryResponseDto: properties: assets: items: $ref: '#/components/schemas/AssetResponseDto' type: array createdAt: description: Creation date format: date-time type: string data: $ref: '#/components/schemas/OnThisDayDto' deletedAt: description: Deletion date format: date-time type: string hideAt: description: Date when memory should be hidden format: date-time type: string id: description: Memory ID type: string isSaved: description: Is memory saved type: boolean memoryAt: description: Memory date format: date-time type: string ownerId: description: Owner user ID type: string seenAt: description: Date when memory was seen format: date-time type: string showAt: description: Date when memory should be shown format: date-time type: string type: allOf: - $ref: '#/components/schemas/MemoryType' description: Memory type updatedAt: description: Last update date format: date-time type: string required: - assets - createdAt - data - id - isSaved - memoryAt - ownerId - type - updatedAt type: object MemorySearchOrder: enum: - asc - desc - random type: string MemoryStatisticsResponseDto: properties: total: description: Total number of memories type: integer required: - total type: object MemoryType: enum: - on_this_day type: string MemoryUpdateDto: properties: isSaved: description: Is memory saved type: boolean memoryAt: description: Memory date format: date-time type: string seenAt: description: Date when memory was seen format: date-time type: string type: object MergePersonDto: properties: ids: description: Person IDs to merge items: format: uuid type: string type: array required: - ids type: object MetadataSearchDto: properties: albumIds: description: Filter by album IDs items: format: uuid type: string type: array checksum: description: Filter by file checksum type: string city: description: Filter by city name nullable: true type: string country: description: Filter by country name nullable: true type: string createdAfter: description: Filter by creation date (after) format: date-time type: string createdBefore: description: Filter by creation date (before) format: date-time type: string description: description: Filter by description text type: string deviceAssetId: description: Filter by device asset ID type: string deviceId: description: Device ID to filter by type: string encodedVideoPath: description: Filter by encoded video file path type: string id: description: Filter by asset ID format: uuid type: string isEncoded: description: Filter by encoded status type: boolean isFavorite: description: Filter by favorite status type: boolean isMotion: description: Filter by motion photo status type: boolean isNotInAlbum: description: Filter assets not in any album type: boolean isOffline: description: Filter by offline status type: boolean lensModel: description: Filter by lens model nullable: true type: string libraryId: description: Library ID to filter by format: uuid nullable: true type: string make: description: Filter by camera make type: string model: description: Filter by camera model nullable: true type: string ocr: description: Filter by OCR text content type: string order: allOf: - $ref: '#/components/schemas/AssetOrder' default: desc description: Sort order originalFileName: description: Filter by original file name type: string originalPath: description: Filter by original file path type: string page: description: Page number minimum: 1 type: number personIds: description: Filter by person IDs items: format: uuid type: string type: array previewPath: description: Filter by preview file path type: string rating: description: Filter by rating [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable size: description: Number of results to return maximum: 1000 minimum: 1 type: number state: description: Filter by state/province name nullable: true type: string tagIds: description: Filter by tag IDs items: format: uuid type: string nullable: true type: array takenAfter: description: Filter by taken date (after) format: date-time type: string takenBefore: description: Filter by taken date (before) format: date-time type: string thumbnailPath: description: Filter by thumbnail file path type: string trashedAfter: description: Filter by trash date (after) format: date-time type: string trashedBefore: description: Filter by trash date (before) format: date-time type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type filter updatedAfter: description: Filter by update date (after) format: date-time type: string updatedBefore: description: Filter by update date (before) format: date-time type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Filter by visibility withDeleted: description: Include deleted assets type: boolean withExif: description: Include EXIF data in response type: boolean withPeople: description: Include people data in response type: boolean withStacked: description: Include stacked assets type: boolean type: object MirrorAxis: description: Axis to mirror along enum: - horizontal - vertical type: string MirrorParameters: properties: axis: allOf: - $ref: '#/components/schemas/MirrorAxis' description: Axis to mirror along required: - axis type: object NotificationCreateDto: properties: data: description: Additional notification data type: object description: description: Notification description nullable: true type: string level: allOf: - $ref: '#/components/schemas/NotificationLevel' description: Notification level readAt: description: Date when notification was read format: date-time nullable: true type: string title: description: Notification title type: string type: allOf: - $ref: '#/components/schemas/NotificationType' description: Notification type userId: description: User ID to send notification to format: uuid type: string required: - title - userId type: object NotificationDeleteAllDto: properties: ids: description: Notification IDs to delete items: format: uuid type: string minItems: 1 type: array required: - ids type: object NotificationDto: properties: createdAt: description: Creation date format: date-time type: string data: description: Additional notification data type: object description: description: Notification description type: string id: description: Notification ID type: string level: allOf: - $ref: '#/components/schemas/NotificationLevel' description: Notification level readAt: description: Date when notification was read format: date-time type: string title: description: Notification title type: string type: allOf: - $ref: '#/components/schemas/NotificationType' description: Notification type required: - createdAt - id - level - title - type type: object NotificationLevel: enum: - success - error - warning - info type: string NotificationType: enum: - JobFailed - BackupFailed - SystemMessage - AlbumInvite - AlbumUpdate - Custom type: string NotificationUpdateAllDto: properties: ids: description: Notification IDs to update items: format: uuid type: string minItems: 1 type: array readAt: description: Date when notifications were read format: date-time nullable: true type: string required: - ids type: object NotificationUpdateDto: properties: readAt: description: Date when notification was read format: date-time nullable: true type: string type: object OAuthAuthorizeResponseDto: properties: url: description: OAuth authorization URL type: string required: - url type: object OAuthCallbackDto: properties: codeVerifier: description: OAuth code verifier (PKCE) type: string state: description: OAuth state parameter type: string url: description: OAuth callback URL type: string required: - url type: object OAuthConfigDto: properties: codeChallenge: description: OAuth code challenge (PKCE) type: string redirectUri: description: OAuth redirect URI type: string state: description: OAuth state parameter type: string required: - redirectUri type: object OAuthTokenEndpointAuthMethod: description: Token endpoint auth method enum: - client_secret_post - client_secret_basic type: string OcrConfig: properties: enabled: description: Whether the task is enabled type: boolean maxResolution: description: Maximum resolution for OCR processing minimum: 1 type: integer minDetectionScore: description: Minimum confidence score for text detection format: double maximum: 1 minimum: 0.1 type: number minRecognitionScore: description: Minimum confidence score for text recognition format: double maximum: 1 minimum: 0.1 type: number modelName: description: Name of the model to use type: string required: - enabled - maxResolution - minDetectionScore - minRecognitionScore - modelName type: object OnThisDayDto: properties: year: description: Year for on this day memory minimum: 1 type: number required: - year type: object OnboardingDto: properties: isOnboarded: description: Is user onboarded type: boolean required: - isOnboarded type: object OnboardingResponseDto: properties: isOnboarded: description: Is user onboarded type: boolean required: - isOnboarded type: object PartnerCreateDto: properties: sharedWithId: description: User ID to share with format: uuid type: string required: - sharedWithId type: object PartnerDirection: enum: - shared-by - shared-with type: string PartnerResponseDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color email: description: User email type: string id: description: User ID type: string inTimeline: description: Show in timeline type: boolean name: description: User name type: string profileChangedAt: description: Profile change date format: date-time type: string profileImagePath: description: Profile image path type: string required: - avatarColor - email - id - name - profileChangedAt - profileImagePath type: object PartnerUpdateDto: properties: inTimeline: description: Show partner assets in timeline type: boolean required: - inTimeline type: object PeopleResponse: properties: enabled: default: true description: Whether people are enabled type: boolean sidebarWeb: default: false description: Whether people appear in web sidebar type: boolean required: - enabled - sidebarWeb type: object PeopleResponseDto: properties: hasNextPage: description: Whether there are more pages type: boolean x-immich-history: - version: v1.110.0 state: Added - version: v2 state: Stable x-immich-state: Stable hidden: description: Number of hidden people type: integer people: description: List of people items: $ref: '#/components/schemas/PersonResponseDto' type: array total: description: Total number of people type: integer required: - hidden - people - total type: object PeopleUpdate: properties: enabled: description: Whether people are enabled type: boolean sidebarWeb: description: Whether people appear in web sidebar type: boolean type: object PeopleUpdateDto: properties: people: description: People to update items: $ref: '#/components/schemas/PeopleUpdateItem' type: array required: - people type: object PeopleUpdateItem: properties: birthDate: description: Person date of birth format: date nullable: true type: string color: description: Person color (hex) nullable: true type: string featureFaceAssetId: description: Asset ID used for feature face thumbnail format: uuid type: string id: description: Person ID type: string isFavorite: description: Mark as favorite type: boolean isHidden: description: Person visibility (hidden) type: boolean name: description: Person name type: string required: - id type: object Permission: description: List of permissions enum: - all - activity.create - activity.read - activity.update - activity.delete - activity.statistics - apiKey.create - apiKey.read - apiKey.update - apiKey.delete - asset.read - asset.update - asset.delete - asset.statistics - asset.share - asset.view - asset.download - asset.upload - asset.replace - asset.copy - asset.derive - asset.edit.get - asset.edit.create - asset.edit.delete - album.create - album.read - album.update - album.delete - album.statistics - album.share - album.download - albumAsset.create - albumAsset.delete - albumUser.create - albumUser.update - albumUser.delete - auth.changePassword - authDevice.delete - archive.read - backup.list - backup.download - backup.upload - backup.delete - duplicate.read - duplicate.delete - face.create - face.read - face.update - face.delete - folder.read - job.create - job.read - library.create - library.read - library.update - library.delete - library.statistics - timeline.read - timeline.download - maintenance - map.read - map.search - memory.create - memory.read - memory.update - memory.delete - memory.statistics - memoryAsset.create - memoryAsset.delete - notification.create - notification.read - notification.update - notification.delete - partner.create - partner.read - partner.update - partner.delete - person.create - person.read - person.update - person.delete - person.statistics - person.merge - person.reassign - pinCode.create - pinCode.update - pinCode.delete - plugin.create - plugin.read - plugin.update - plugin.delete - server.about - server.apkLinks - server.storage - server.statistics - server.versionCheck - serverLicense.read - serverLicense.update - serverLicense.delete - session.create - session.read - session.update - session.delete - session.lock - sharedLink.create - sharedLink.read - sharedLink.update - sharedLink.delete - stack.create - stack.read - stack.update - stack.delete - sync.stream - syncCheckpoint.read - syncCheckpoint.update - syncCheckpoint.delete - systemConfig.read - systemConfig.update - systemMetadata.read - systemMetadata.update - tag.create - tag.read - tag.update - tag.delete - tag.asset - user.read - user.update - userLicense.create - userLicense.read - userLicense.update - userLicense.delete - userOnboarding.read - userOnboarding.update - userOnboarding.delete - userPreference.read - userPreference.update - userProfileImage.create - userProfileImage.read - userProfileImage.update - userProfileImage.delete - queue.read - queue.update - queueJob.create - queueJob.read - queueJob.update - queueJob.delete - workflow.create - workflow.read - workflow.update - workflow.delete - adminUser.create - adminUser.read - adminUser.update - adminUser.delete - adminSession.read - adminAuth.unlinkAll type: string PersonCreateDto: properties: birthDate: description: Person date of birth format: date nullable: true type: string color: description: Person color (hex) nullable: true type: string isFavorite: description: Mark as favorite type: boolean isHidden: description: Person visibility (hidden) type: boolean name: description: Person name type: string type: object PersonResponseDto: properties: birthDate: description: Person date of birth format: date nullable: true type: string color: description: Person color (hex) type: string x-immich-history: - version: v1.126.0 state: Added - version: v2 state: Stable x-immich-state: Stable id: description: Person ID type: string isFavorite: description: Is favorite type: boolean x-immich-history: - version: v1.126.0 state: Added - version: v2 state: Stable x-immich-state: Stable isHidden: description: Is hidden type: boolean name: description: Person name type: string thumbnailPath: description: Thumbnail path type: string updatedAt: description: Last update date format: date-time type: string x-immich-history: - version: v1.107.0 state: Added - version: v2 state: Stable x-immich-state: Stable required: - birthDate - id - isHidden - name - thumbnailPath type: object PersonStatisticsResponseDto: properties: assets: description: Number of assets type: integer required: - assets type: object PersonUpdateDto: properties: birthDate: description: Person date of birth format: date nullable: true type: string color: description: Person color (hex) nullable: true type: string featureFaceAssetId: description: Asset ID used for feature face thumbnail format: uuid type: string isFavorite: description: Mark as favorite type: boolean isHidden: description: Person visibility (hidden) type: boolean name: description: Person name type: string type: object PersonWithFacesResponseDto: properties: birthDate: description: Person date of birth format: date nullable: true type: string color: description: Person color (hex) type: string x-immich-history: - version: v1.126.0 state: Added - version: v2 state: Stable x-immich-state: Stable faces: description: Face detections items: $ref: '#/components/schemas/AssetFaceWithoutPersonResponseDto' type: array id: description: Person ID type: string isFavorite: description: Is favorite type: boolean x-immich-history: - version: v1.126.0 state: Added - version: v2 state: Stable x-immich-state: Stable isHidden: description: Is hidden type: boolean name: description: Person name type: string thumbnailPath: description: Thumbnail path type: string updatedAt: description: Last update date format: date-time type: string x-immich-history: - version: v1.107.0 state: Added - version: v2 state: Stable x-immich-state: Stable required: - birthDate - faces - id - isHidden - name - thumbnailPath type: object PinCodeChangeDto: properties: newPinCode: description: New PIN code (4-6 digits) example: '123456' type: string password: description: User password (required if PIN code is not provided) type: string pinCode: description: New PIN code (4-6 digits) example: '123456' type: string required: - newPinCode type: object PinCodeResetDto: properties: password: description: User password (required if PIN code is not provided) type: string pinCode: description: New PIN code (4-6 digits) example: '123456' type: string type: object PinCodeSetupDto: properties: pinCode: description: PIN code (4-6 digits) example: '123456' type: string required: - pinCode type: object PlacesResponseDto: properties: admin1name: description: Administrative level 1 name (state/province) type: string admin2name: description: Administrative level 2 name (county/district) type: string latitude: description: Latitude coordinate type: number longitude: description: Longitude coordinate type: number name: description: Place name type: string required: - latitude - longitude - name type: object PluginActionResponseDto: properties: description: description: Action description type: string id: description: Action ID type: string methodName: description: Method name type: string pluginId: description: Plugin ID type: string schema: description: Action schema nullable: true type: object supportedContexts: description: Supported contexts items: $ref: '#/components/schemas/PluginContextType' type: array title: description: Action title type: string required: - description - id - methodName - pluginId - schema - supportedContexts - title type: object PluginContextType: description: Context type enum: - asset - album - person type: string PluginFilterResponseDto: properties: description: description: Filter description type: string id: description: Filter ID type: string methodName: description: Method name type: string pluginId: description: Plugin ID type: string schema: description: Filter schema nullable: true type: object supportedContexts: description: Supported contexts items: $ref: '#/components/schemas/PluginContextType' type: array title: description: Filter title type: string required: - description - id - methodName - pluginId - schema - supportedContexts - title type: object PluginResponseDto: properties: actions: description: Plugin actions items: $ref: '#/components/schemas/PluginActionResponseDto' type: array author: description: Plugin author type: string createdAt: description: Creation date type: string description: description: Plugin description type: string filters: description: Plugin filters items: $ref: '#/components/schemas/PluginFilterResponseDto' type: array id: description: Plugin ID type: string name: description: Plugin name type: string title: description: Plugin title type: string updatedAt: description: Last update date type: string version: description: Plugin version type: string required: - actions - author - createdAt - description - filters - id - name - title - updatedAt - version type: object PluginTriggerResponseDto: properties: contextType: allOf: - $ref: '#/components/schemas/PluginContextType' description: Context type type: allOf: - $ref: '#/components/schemas/PluginTriggerType' description: Trigger type required: - contextType - type type: object PluginTriggerType: description: Trigger type enum: - AssetCreate - PersonRecognized type: string PurchaseResponse: properties: hideBuyButtonUntil: description: Date until which to hide buy button type: string showSupportBadge: description: Whether to show support badge type: boolean required: - hideBuyButtonUntil - showSupportBadge type: object PurchaseUpdate: properties: hideBuyButtonUntil: description: Date until which to hide buy button type: string showSupportBadge: description: Whether to show support badge type: boolean type: object QueueCommand: description: Queue command to execute enum: - start - pause - resume - empty - clear-failed type: string QueueCommandDto: properties: command: allOf: - $ref: '#/components/schemas/QueueCommand' description: Queue command to execute force: description: Force the command execution (if applicable) type: boolean required: - command type: object QueueDeleteDto: properties: failed: description: If true, will also remove failed jobs from the queue. type: boolean x-immich-history: - version: v2.4.0 state: Added - version: v2.4.0 state: Alpha x-immich-state: Alpha type: object QueueJobResponseDto: properties: data: description: Job data payload type: object id: description: Job ID type: string name: allOf: - $ref: '#/components/schemas/JobName' description: Job name timestamp: description: Job creation timestamp type: integer required: - data - name - timestamp type: object QueueJobStatus: enum: - active - failed - completed - delayed - waiting - paused type: string QueueName: enum: - thumbnailGeneration - metadataExtraction - videoConversion - faceDetection - facialRecognition - smartSearch - duplicateDetection - backgroundTask - storageTemplateMigration - migration - search - sidecar - library - notifications - backupDatabase - ocr - workflow - editor type: string QueueResponseDto: properties: isPaused: description: Whether the queue is paused type: boolean name: allOf: - $ref: '#/components/schemas/QueueName' description: Queue name statistics: $ref: '#/components/schemas/QueueStatisticsDto' required: - isPaused - name - statistics type: object QueueResponseLegacyDto: properties: jobCounts: $ref: '#/components/schemas/QueueStatisticsDto' queueStatus: $ref: '#/components/schemas/QueueStatusLegacyDto' required: - jobCounts - queueStatus type: object QueueStatisticsDto: properties: active: description: Number of active jobs type: integer completed: description: Number of completed jobs type: integer delayed: description: Number of delayed jobs type: integer failed: description: Number of failed jobs type: integer paused: description: Number of paused jobs type: integer waiting: description: Number of waiting jobs type: integer required: - active - completed - delayed - failed - paused - waiting type: object QueueStatusLegacyDto: properties: isActive: description: Whether the queue is currently active (has running jobs) type: boolean isPaused: description: Whether the queue is paused type: boolean required: - isActive - isPaused type: object QueueUpdateDto: properties: isPaused: description: Whether to pause the queue type: boolean type: object QueuesResponseLegacyDto: properties: backgroundTask: $ref: '#/components/schemas/QueueResponseLegacyDto' backupDatabase: $ref: '#/components/schemas/QueueResponseLegacyDto' duplicateDetection: $ref: '#/components/schemas/QueueResponseLegacyDto' editor: $ref: '#/components/schemas/QueueResponseLegacyDto' faceDetection: $ref: '#/components/schemas/QueueResponseLegacyDto' facialRecognition: $ref: '#/components/schemas/QueueResponseLegacyDto' library: $ref: '#/components/schemas/QueueResponseLegacyDto' metadataExtraction: $ref: '#/components/schemas/QueueResponseLegacyDto' migration: $ref: '#/components/schemas/QueueResponseLegacyDto' notifications: $ref: '#/components/schemas/QueueResponseLegacyDto' ocr: $ref: '#/components/schemas/QueueResponseLegacyDto' search: $ref: '#/components/schemas/QueueResponseLegacyDto' sidecar: $ref: '#/components/schemas/QueueResponseLegacyDto' smartSearch: $ref: '#/components/schemas/QueueResponseLegacyDto' storageTemplateMigration: $ref: '#/components/schemas/QueueResponseLegacyDto' thumbnailGeneration: $ref: '#/components/schemas/QueueResponseLegacyDto' videoConversion: $ref: '#/components/schemas/QueueResponseLegacyDto' workflow: $ref: '#/components/schemas/QueueResponseLegacyDto' required: - backgroundTask - backupDatabase - duplicateDetection - editor - faceDetection - facialRecognition - library - metadataExtraction - migration - notifications - ocr - search - sidecar - smartSearch - storageTemplateMigration - thumbnailGeneration - videoConversion - workflow type: object RandomSearchDto: properties: albumIds: description: Filter by album IDs items: format: uuid type: string type: array city: description: Filter by city name nullable: true type: string country: description: Filter by country name nullable: true type: string createdAfter: description: Filter by creation date (after) format: date-time type: string createdBefore: description: Filter by creation date (before) format: date-time type: string deviceId: description: Device ID to filter by type: string isEncoded: description: Filter by encoded status type: boolean isFavorite: description: Filter by favorite status type: boolean isMotion: description: Filter by motion photo status type: boolean isNotInAlbum: description: Filter assets not in any album type: boolean isOffline: description: Filter by offline status type: boolean lensModel: description: Filter by lens model nullable: true type: string libraryId: description: Library ID to filter by format: uuid nullable: true type: string make: description: Filter by camera make type: string model: description: Filter by camera model nullable: true type: string ocr: description: Filter by OCR text content type: string personIds: description: Filter by person IDs items: format: uuid type: string type: array rating: description: Filter by rating [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable size: description: Number of results to return maximum: 1000 minimum: 1 type: number state: description: Filter by state/province name nullable: true type: string tagIds: description: Filter by tag IDs items: format: uuid type: string nullable: true type: array takenAfter: description: Filter by taken date (after) format: date-time type: string takenBefore: description: Filter by taken date (before) format: date-time type: string trashedAfter: description: Filter by trash date (after) format: date-time type: string trashedBefore: description: Filter by trash date (before) format: date-time type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type filter updatedAfter: description: Filter by update date (after) format: date-time type: string updatedBefore: description: Filter by update date (before) format: date-time type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Filter by visibility withDeleted: description: Include deleted assets type: boolean withExif: description: Include EXIF data in response type: boolean withPeople: description: Include people data in response type: boolean withStacked: description: Include stacked assets type: boolean type: object RatingsResponse: properties: enabled: default: false description: Whether ratings are enabled type: boolean required: - enabled type: object RatingsUpdate: properties: enabled: description: Whether ratings are enabled type: boolean type: object ReactionLevel: enum: - album - asset type: string ReactionType: enum: - comment - like type: string ReverseGeocodingStateResponseDto: properties: lastImportFileName: description: Last import file name nullable: true type: string lastUpdate: description: Last update timestamp nullable: true type: string required: - lastImportFileName - lastUpdate type: object RotateParameters: properties: angle: description: Rotation angle in degrees type: number required: - angle type: object SearchAlbumResponseDto: properties: count: description: Number of albums in this page type: integer facets: items: $ref: '#/components/schemas/SearchFacetResponseDto' type: array items: items: $ref: '#/components/schemas/AlbumResponseDto' type: array total: description: Total number of matching albums type: integer required: - count - facets - items - total type: object SearchAssetResponseDto: properties: count: description: Number of assets in this page type: integer facets: items: $ref: '#/components/schemas/SearchFacetResponseDto' type: array items: items: $ref: '#/components/schemas/AssetResponseDto' type: array nextPage: description: Next page token nullable: true type: string total: description: Total number of matching assets type: integer required: - count - facets - items - nextPage - total type: object SearchExploreItem: properties: data: $ref: '#/components/schemas/AssetResponseDto' value: description: Explore value type: string required: - data - value type: object SearchExploreResponseDto: properties: fieldName: description: Explore field name type: string items: items: $ref: '#/components/schemas/SearchExploreItem' type: array required: - fieldName - items type: object SearchFacetCountResponseDto: properties: count: description: Number of assets with this facet value type: integer value: description: Facet value type: string required: - count - value type: object SearchFacetResponseDto: properties: counts: description: Facet counts items: $ref: '#/components/schemas/SearchFacetCountResponseDto' type: array fieldName: description: Facet field name type: string required: - counts - fieldName type: object SearchResponseDto: properties: albums: $ref: '#/components/schemas/SearchAlbumResponseDto' assets: $ref: '#/components/schemas/SearchAssetResponseDto' required: - albums - assets type: object SearchStatisticsResponseDto: properties: total: description: Total number of matching assets type: integer required: - total type: object SearchSuggestionType: enum: - country - state - city - camera-make - camera-model - camera-lens-model type: string ServerAboutResponseDto: properties: build: description: Build identifier type: string buildImage: description: Build image name type: string buildImageUrl: description: Build image URL type: string buildUrl: description: Build URL type: string exiftool: description: ExifTool version type: string ffmpeg: description: FFmpeg version type: string imagemagick: description: ImageMagick version type: string libvips: description: libvips version type: string licensed: description: Whether the server is licensed type: boolean nodejs: description: Node.js version type: string repository: description: Repository name type: string repositoryUrl: description: Repository URL type: string sourceCommit: description: Source commit hash type: string sourceRef: description: Source reference (branch/tag) type: string sourceUrl: description: Source URL type: string thirdPartyBugFeatureUrl: description: Third-party bug/feature URL type: string thirdPartyDocumentationUrl: description: Third-party documentation URL type: string thirdPartySourceUrl: description: Third-party source URL type: string thirdPartySupportUrl: description: Third-party support URL type: string version: description: Server version type: string versionUrl: description: URL to version information type: string required: - licensed - version - versionUrl type: object ServerApkLinksDto: properties: arm64v8a: description: APK download link for ARM64 v8a architecture type: string armeabiv7a: description: APK download link for ARM EABI v7a architecture type: string universal: description: APK download link for universal architecture type: string x86_64: description: APK download link for x86_64 architecture type: string required: - arm64v8a - armeabiv7a - universal - x86_64 type: object ServerConfigDto: properties: externalDomain: description: External domain URL type: string isInitialized: description: Whether the server has been initialized type: boolean isOnboarded: description: Whether the admin has completed onboarding type: boolean loginPageMessage: description: Login page message type: string maintenanceMode: description: Whether maintenance mode is active type: boolean mapDarkStyleUrl: description: Map dark style URL type: string mapLightStyleUrl: description: Map light style URL type: string oauthButtonText: description: OAuth button text type: string publicUsers: description: Whether public user registration is enabled type: boolean trashDays: description: Number of days before trashed assets are permanently deleted type: integer userDeleteDelay: description: Delay in days before deleted users are permanently removed type: integer required: - externalDomain - isInitialized - isOnboarded - loginPageMessage - maintenanceMode - mapDarkStyleUrl - mapLightStyleUrl - oauthButtonText - publicUsers - trashDays - userDeleteDelay type: object ServerFeaturesDto: properties: configFile: description: Whether config file is available type: boolean duplicateDetection: description: Whether duplicate detection is enabled type: boolean email: description: Whether email notifications are enabled type: boolean facialRecognition: description: Whether facial recognition is enabled type: boolean importFaces: description: Whether face import is enabled type: boolean map: description: Whether map feature is enabled type: boolean oauth: description: Whether OAuth is enabled type: boolean oauthAutoLaunch: description: Whether OAuth auto-launch is enabled type: boolean ocr: description: Whether OCR is enabled type: boolean passwordLogin: description: Whether password login is enabled type: boolean reverseGeocoding: description: Whether reverse geocoding is enabled type: boolean search: description: Whether search is enabled type: boolean sidecar: description: Whether sidecar files are supported type: boolean smartSearch: description: Whether smart search is enabled type: boolean trash: description: Whether trash feature is enabled type: boolean required: - configFile - duplicateDetection - email - facialRecognition - importFaces - map - oauth - oauthAutoLaunch - ocr - passwordLogin - reverseGeocoding - search - sidecar - smartSearch - trash type: object ServerMediaTypesResponseDto: properties: image: description: Supported image MIME types items: type: string type: array sidecar: description: Supported sidecar MIME types items: type: string type: array video: description: Supported video MIME types items: type: string type: array required: - image - sidecar - video type: object ServerPingResponse: properties: res: example: pong readOnly: true type: string required: - res type: object ServerStatsResponseDto: properties: photos: default: 0 description: Total number of photos type: integer usage: default: 0 description: Total storage usage in bytes format: int64 type: integer usageByUser: default: [] example: - photos: 1 videos: 1 diskUsageRaw: 2 usagePhotos: 1 usageVideos: 1 items: $ref: '#/components/schemas/UsageByUserDto' title: Array of usage for each user type: array usagePhotos: default: 0 description: Storage usage for photos in bytes format: int64 type: integer usageVideos: default: 0 description: Storage usage for videos in bytes format: int64 type: integer videos: default: 0 description: Total number of videos type: integer required: - photos - usage - usageByUser - usagePhotos - usageVideos - videos type: object ServerStorageResponseDto: properties: diskAvailable: description: Available disk space (human-readable format) type: string diskAvailableRaw: description: Available disk space in bytes format: int64 type: integer diskSize: description: Total disk size (human-readable format) type: string diskSizeRaw: description: Total disk size in bytes format: int64 type: integer diskUsagePercentage: description: Disk usage percentage (0-100) format: double type: number diskUse: description: Used disk space (human-readable format) type: string diskUseRaw: description: Used disk space in bytes format: int64 type: integer required: - diskAvailable - diskAvailableRaw - diskSize - diskSizeRaw - diskUsagePercentage - diskUse - diskUseRaw type: object ServerThemeDto: properties: customCss: description: Custom CSS for theming type: string required: - customCss type: object ServerVersionHistoryResponseDto: properties: createdAt: description: When this version was first seen format: date-time type: string id: description: Version history entry ID type: string version: description: Version string type: string required: - createdAt - id - version type: object ServerVersionResponseDto: properties: major: description: Major version number type: integer minor: description: Minor version number type: integer patch: description: Patch version number type: integer required: - major - minor - patch type: object SessionCreateDto: properties: deviceOS: description: Device OS type: string deviceType: description: Device type type: string duration: description: Session duration in seconds minimum: 1 type: number type: object SessionCreateResponseDto: properties: appVersion: description: App version nullable: true type: string createdAt: description: Creation date type: string current: description: Is current session type: boolean deviceOS: description: Device OS type: string deviceType: description: Device type type: string expiresAt: description: Expiration date type: string id: description: Session ID type: string isPendingSyncReset: description: Is pending sync reset type: boolean token: description: Session token type: string updatedAt: description: Last update date type: string required: - appVersion - createdAt - current - deviceOS - deviceType - id - isPendingSyncReset - token - updatedAt type: object SessionResponseDto: properties: appVersion: description: App version nullable: true type: string createdAt: description: Creation date type: string current: description: Is current session type: boolean deviceOS: description: Device OS type: string deviceType: description: Device type type: string expiresAt: description: Expiration date type: string id: description: Session ID type: string isPendingSyncReset: description: Is pending sync reset type: boolean updatedAt: description: Last update date type: string required: - appVersion - createdAt - current - deviceOS - deviceType - id - isPendingSyncReset - updatedAt type: object SessionUnlockDto: properties: password: description: User password (required if PIN code is not provided) type: string pinCode: description: New PIN code (4-6 digits) example: '123456' type: string type: object SessionUpdateDto: properties: isPendingSyncReset: description: Reset pending sync state type: boolean type: object SetMaintenanceModeDto: properties: action: allOf: - $ref: '#/components/schemas/MaintenanceAction' description: Maintenance action restoreBackupFilename: description: Restore backup filename type: string required: - action type: object SharedLinkCreateDto: properties: albumId: description: Album ID (for album sharing) format: uuid type: string allowDownload: default: true description: Allow downloads type: boolean allowUpload: description: Allow uploads type: boolean assetIds: description: Asset IDs (for individual assets) items: format: uuid type: string type: array description: description: Link description nullable: true type: string expiresAt: default: null description: Expiration date format: date-time nullable: true type: string password: description: Link password nullable: true type: string showMetadata: default: true description: Show metadata type: boolean slug: description: Custom URL slug nullable: true type: string type: allOf: - $ref: '#/components/schemas/SharedLinkType' description: Shared link type required: - type type: object SharedLinkEditDto: properties: allowDownload: description: Allow downloads type: boolean allowUpload: description: Allow uploads type: boolean changeExpiryTime: description: Whether to change the expiry time. Few clients cannot send null to set the expiryTime to never. Setting this flag and not sending expiryAt is considered as null instead. Clients that can send null values can ignore this. type: boolean description: description: Link description nullable: true type: string expiresAt: description: Expiration date format: date-time nullable: true type: string password: description: Link password nullable: true type: string showMetadata: description: Show metadata type: boolean slug: description: Custom URL slug nullable: true type: string type: object SharedLinkLoginDto: properties: password: description: Shared link password example: password type: string required: - password type: object SharedLinkResponseDto: properties: album: $ref: '#/components/schemas/AlbumResponseDto' allowDownload: description: Allow downloads type: boolean allowUpload: description: Allow uploads type: boolean assets: items: $ref: '#/components/schemas/AssetResponseDto' type: array createdAt: description: Creation date format: date-time type: string description: description: Link description nullable: true type: string expiresAt: description: Expiration date format: date-time nullable: true type: string id: description: Shared link ID type: string key: description: Encryption key (base64url) type: string password: description: Has password nullable: true type: string showMetadata: description: Show metadata type: boolean slug: description: Custom URL slug nullable: true type: string token: deprecated: true description: Access token nullable: true type: string x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Deprecated x-immich-state: Deprecated type: allOf: - $ref: '#/components/schemas/SharedLinkType' description: Shared link type userId: description: Owner user ID type: string required: - allowDownload - allowUpload - assets - createdAt - description - expiresAt - id - key - password - showMetadata - slug - type - userId type: object SharedLinkType: description: Shared link type enum: - ALBUM - INDIVIDUAL type: string SharedLinksResponse: properties: enabled: default: true description: Whether shared links are enabled type: boolean sidebarWeb: default: false description: Whether shared links appear in web sidebar type: boolean required: - enabled - sidebarWeb type: object SharedLinksUpdate: properties: enabled: description: Whether shared links are enabled type: boolean sidebarWeb: description: Whether shared links appear in web sidebar type: boolean type: object SignUpDto: properties: email: description: User email example: testuser@email.com format: email type: string name: description: User name example: Admin type: string password: description: User password example: password type: string required: - email - name - password type: object SmartSearchDto: properties: albumIds: description: Filter by album IDs items: format: uuid type: string type: array city: description: Filter by city name nullable: true type: string country: description: Filter by country name nullable: true type: string createdAfter: description: Filter by creation date (after) format: date-time type: string createdBefore: description: Filter by creation date (before) format: date-time type: string deviceId: description: Device ID to filter by type: string isEncoded: description: Filter by encoded status type: boolean isFavorite: description: Filter by favorite status type: boolean isMotion: description: Filter by motion photo status type: boolean isNotInAlbum: description: Filter assets not in any album type: boolean isOffline: description: Filter by offline status type: boolean language: description: Search language code type: string lensModel: description: Filter by lens model nullable: true type: string libraryId: description: Library ID to filter by format: uuid nullable: true type: string make: description: Filter by camera make type: string model: description: Filter by camera model nullable: true type: string ocr: description: Filter by OCR text content type: string page: description: Page number minimum: 1 type: number personIds: description: Filter by person IDs items: format: uuid type: string type: array query: description: Natural language search query type: string queryAssetId: description: Asset ID to use as search reference format: uuid type: string rating: description: Filter by rating [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable size: description: Number of results to return maximum: 1000 minimum: 1 type: number state: description: Filter by state/province name nullable: true type: string tagIds: description: Filter by tag IDs items: format: uuid type: string nullable: true type: array takenAfter: description: Filter by taken date (after) format: date-time type: string takenBefore: description: Filter by taken date (before) format: date-time type: string trashedAfter: description: Filter by trash date (after) format: date-time type: string trashedBefore: description: Filter by trash date (before) format: date-time type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type filter updatedAfter: description: Filter by update date (after) format: date-time type: string updatedBefore: description: Filter by update date (before) format: date-time type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Filter by visibility withDeleted: description: Include deleted assets type: boolean withExif: description: Include EXIF data in response type: boolean type: object SourceType: description: Face detection source type enum: - machine-learning - exif - manual type: string StackCreateDto: properties: assetIds: description: Asset IDs (first becomes primary, min 2) items: format: uuid type: string minItems: 2 type: array required: - assetIds type: object StackResponseDto: properties: assets: description: Stack assets items: $ref: '#/components/schemas/AssetResponseDto' type: array id: description: Stack ID type: string primaryAssetId: description: Primary asset ID type: string required: - assets - id - primaryAssetId type: object StackUpdateDto: properties: primaryAssetId: description: Primary asset ID format: uuid type: string type: object StatisticsSearchDto: properties: albumIds: description: Filter by album IDs items: format: uuid type: string type: array city: description: Filter by city name nullable: true type: string country: description: Filter by country name nullable: true type: string createdAfter: description: Filter by creation date (after) format: date-time type: string createdBefore: description: Filter by creation date (before) format: date-time type: string description: description: Filter by description text type: string deviceId: description: Device ID to filter by type: string isEncoded: description: Filter by encoded status type: boolean isFavorite: description: Filter by favorite status type: boolean isMotion: description: Filter by motion photo status type: boolean isNotInAlbum: description: Filter assets not in any album type: boolean isOffline: description: Filter by offline status type: boolean lensModel: description: Filter by lens model nullable: true type: string libraryId: description: Library ID to filter by format: uuid nullable: true type: string make: description: Filter by camera make type: string model: description: Filter by camera model nullable: true type: string ocr: description: Filter by OCR text content type: string personIds: description: Filter by person IDs items: format: uuid type: string type: array rating: description: Filter by rating [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable state: description: Filter by state/province name nullable: true type: string tagIds: description: Filter by tag IDs items: format: uuid type: string nullable: true type: array takenAfter: description: Filter by taken date (after) format: date-time type: string takenBefore: description: Filter by taken date (before) format: date-time type: string trashedAfter: description: Filter by trash date (after) format: date-time type: string trashedBefore: description: Filter by trash date (before) format: date-time type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type filter updatedAfter: description: Filter by update date (after) format: date-time type: string updatedBefore: description: Filter by update date (before) format: date-time type: string visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Filter by visibility type: object StorageFolder: description: Storage folder enum: - encoded-video - library - upload - profile - thumbs - backups type: string SyncAckDeleteDto: properties: types: description: Sync entity types to delete acks for items: $ref: '#/components/schemas/SyncEntityType' type: array type: object SyncAckDto: properties: ack: description: Acknowledgment ID type: string type: allOf: - $ref: '#/components/schemas/SyncEntityType' description: Sync entity type required: - ack - type type: object SyncAckSetDto: properties: acks: description: Acknowledgment IDs (max 1000) items: type: string maxItems: 1000 type: array required: - acks type: object SyncAckV1: properties: {} type: object SyncAlbumDeleteV1: properties: albumId: description: Album ID type: string required: - albumId type: object SyncAlbumToAssetDeleteV1: properties: albumId: description: Album ID type: string assetId: description: Asset ID type: string required: - albumId - assetId type: object SyncAlbumToAssetV1: properties: albumId: description: Album ID type: string assetId: description: Asset ID type: string required: - albumId - assetId type: object SyncAlbumUserDeleteV1: properties: albumId: description: Album ID type: string userId: description: User ID type: string required: - albumId - userId type: object SyncAlbumUserV1: properties: albumId: description: Album ID type: string role: allOf: - $ref: '#/components/schemas/AlbumUserRole' description: Album user role userId: description: User ID type: string required: - albumId - role - userId type: object SyncAlbumV1: properties: createdAt: description: Created at format: date-time type: string description: description: Album description type: string id: description: Album ID type: string isActivityEnabled: description: Is activity enabled type: boolean name: description: Album name type: string order: allOf: - $ref: '#/components/schemas/AssetOrder' ownerId: description: Owner ID type: string thumbnailAssetId: description: Thumbnail asset ID nullable: true type: string updatedAt: description: Updated at format: date-time type: string required: - createdAt - description - id - isActivityEnabled - name - order - ownerId - thumbnailAssetId - updatedAt type: object SyncAssetDeleteV1: properties: assetId: description: Asset ID type: string required: - assetId type: object SyncAssetEditDeleteV1: properties: editId: type: string required: - editId type: object SyncAssetEditV1: properties: action: allOf: - $ref: '#/components/schemas/AssetEditAction' assetId: type: string id: type: string parameters: type: object sequence: type: integer required: - action - assetId - id - parameters - sequence type: object SyncAssetExifV1: properties: assetId: description: Asset ID type: string city: description: City nullable: true type: string country: description: Country nullable: true type: string dateTimeOriginal: description: Date time original format: date-time nullable: true type: string description: description: Description nullable: true type: string exifImageHeight: description: Exif image height nullable: true type: integer exifImageWidth: description: Exif image width nullable: true type: integer exposureTime: description: Exposure time nullable: true type: string fNumber: description: F number format: double nullable: true type: number fileSizeInByte: description: File size in byte nullable: true type: integer focalLength: description: Focal length format: double nullable: true type: number fps: description: FPS format: double nullable: true type: number iso: description: ISO nullable: true type: integer latitude: description: Latitude format: double nullable: true type: number lensModel: description: Lens model nullable: true type: string longitude: description: Longitude format: double nullable: true type: number make: description: Make nullable: true type: string model: description: Model nullable: true type: string modifyDate: description: Modify date format: date-time nullable: true type: string orientation: description: Orientation nullable: true type: string profileDescription: description: Profile description nullable: true type: string projectionType: description: Projection type nullable: true type: string rating: description: Rating nullable: true type: integer state: description: State nullable: true type: string timeZone: description: Time zone nullable: true type: string required: - assetId - city - country - dateTimeOriginal - description - exifImageHeight - exifImageWidth - exposureTime - fNumber - fileSizeInByte - focalLength - fps - iso - latitude - lensModel - longitude - make - model - modifyDate - orientation - profileDescription - projectionType - rating - state - timeZone type: object SyncAssetFaceDeleteV1: properties: assetFaceId: description: Asset face ID type: string required: - assetFaceId type: object SyncAssetFaceV1: properties: assetId: description: Asset ID type: string boundingBoxX1: type: integer boundingBoxX2: type: integer boundingBoxY1: type: integer boundingBoxY2: type: integer id: description: Asset face ID type: string imageHeight: type: integer imageWidth: type: integer personId: description: Person ID nullable: true type: string sourceType: description: Source type type: string required: - assetId - boundingBoxX1 - boundingBoxX2 - boundingBoxY1 - boundingBoxY2 - id - imageHeight - imageWidth - personId - sourceType type: object SyncAssetFaceV2: properties: assetId: description: Asset ID type: string boundingBoxX1: type: integer boundingBoxX2: type: integer boundingBoxY1: type: integer boundingBoxY2: type: integer deletedAt: description: Face deleted at format: date-time nullable: true type: string id: description: Asset face ID type: string imageHeight: type: integer imageWidth: type: integer isVisible: description: Is the face visible in the asset type: boolean personId: description: Person ID nullable: true type: string sourceType: description: Source type type: string required: - assetId - boundingBoxX1 - boundingBoxX2 - boundingBoxY1 - boundingBoxY2 - deletedAt - id - imageHeight - imageWidth - isVisible - personId - sourceType type: object SyncAssetMetadataDeleteV1: properties: assetId: description: Asset ID type: string key: description: Key type: string required: - assetId - key type: object SyncAssetMetadataV1: properties: assetId: description: Asset ID type: string key: description: Key type: string value: description: Value type: object required: - assetId - key - value type: object SyncAssetV1: properties: checksum: description: Checksum type: string deletedAt: description: Deleted at format: date-time nullable: true type: string duration: description: Duration nullable: true type: string fileCreatedAt: description: File created at format: date-time nullable: true type: string fileModifiedAt: description: File modified at format: date-time nullable: true type: string height: description: Asset height nullable: true type: integer id: description: Asset ID type: string isEdited: description: Is edited type: boolean isFavorite: description: Is favorite type: boolean libraryId: description: Library ID nullable: true type: string livePhotoVideoId: description: Live photo video ID nullable: true type: string localDateTime: description: Local date time format: date-time nullable: true type: string originalFileName: description: Original file name type: string ownerId: description: Owner ID type: string stackId: description: Stack ID nullable: true type: string thumbhash: description: Thumbhash nullable: true type: string type: allOf: - $ref: '#/components/schemas/AssetTypeEnum' description: Asset type visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Asset visibility width: description: Asset width nullable: true type: integer required: - checksum - deletedAt - duration - fileCreatedAt - fileModifiedAt - height - id - isEdited - isFavorite - libraryId - livePhotoVideoId - localDateTime - originalFileName - ownerId - stackId - thumbhash - type - visibility - width type: object SyncAuthUserV1: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: User avatar color nullable: true deletedAt: description: User deleted at format: date-time nullable: true type: string email: description: User email type: string hasProfileImage: description: User has profile image type: boolean id: description: User ID type: string isAdmin: description: User is admin type: boolean name: description: User name type: string oauthId: description: User OAuth ID type: string pinCode: description: User pin code nullable: true type: string profileChangedAt: description: User profile changed at format: date-time type: string quotaSizeInBytes: nullable: true type: integer quotaUsageInBytes: type: integer storageLabel: description: User storage label nullable: true type: string required: - avatarColor - deletedAt - email - hasProfileImage - id - isAdmin - name - oauthId - pinCode - profileChangedAt - quotaSizeInBytes - quotaUsageInBytes - storageLabel type: object SyncCompleteV1: properties: {} type: object SyncEntityType: description: Sync entity type enum: - AuthUserV1 - UserV1 - UserDeleteV1 - AssetV1 - AssetDeleteV1 - AssetExifV1 - AssetEditV1 - AssetEditDeleteV1 - AssetMetadataV1 - AssetMetadataDeleteV1 - PartnerV1 - PartnerDeleteV1 - PartnerAssetV1 - PartnerAssetBackfillV1 - PartnerAssetDeleteV1 - PartnerAssetExifV1 - PartnerAssetExifBackfillV1 - PartnerStackBackfillV1 - PartnerStackDeleteV1 - PartnerStackV1 - AlbumV1 - AlbumDeleteV1 - AlbumUserV1 - AlbumUserBackfillV1 - AlbumUserDeleteV1 - AlbumAssetCreateV1 - AlbumAssetUpdateV1 - AlbumAssetBackfillV1 - AlbumAssetExifCreateV1 - AlbumAssetExifUpdateV1 - AlbumAssetExifBackfillV1 - AlbumToAssetV1 - AlbumToAssetDeleteV1 - AlbumToAssetBackfillV1 - MemoryV1 - MemoryDeleteV1 - MemoryToAssetV1 - MemoryToAssetDeleteV1 - StackV1 - StackDeleteV1 - PersonV1 - PersonDeleteV1 - AssetFaceV1 - AssetFaceV2 - AssetFaceDeleteV1 - UserMetadataV1 - UserMetadataDeleteV1 - SyncAckV1 - SyncResetV1 - SyncCompleteV1 type: string SyncMemoryAssetDeleteV1: properties: assetId: description: Asset ID type: string memoryId: description: Memory ID type: string required: - assetId - memoryId type: object SyncMemoryAssetV1: properties: assetId: description: Asset ID type: string memoryId: description: Memory ID type: string required: - assetId - memoryId type: object SyncMemoryDeleteV1: properties: memoryId: description: Memory ID type: string required: - memoryId type: object SyncMemoryV1: properties: createdAt: description: Created at format: date-time type: string data: description: Data type: object deletedAt: description: Deleted at format: date-time nullable: true type: string hideAt: description: Hide at format: date-time nullable: true type: string id: description: Memory ID type: string isSaved: description: Is saved type: boolean memoryAt: description: Memory at format: date-time type: string ownerId: description: Owner ID type: string seenAt: description: Seen at format: date-time nullable: true type: string showAt: description: Show at format: date-time nullable: true type: string type: allOf: - $ref: '#/components/schemas/MemoryType' description: Memory type updatedAt: description: Updated at format: date-time type: string required: - createdAt - data - deletedAt - hideAt - id - isSaved - memoryAt - ownerId - seenAt - showAt - type - updatedAt type: object SyncPartnerDeleteV1: properties: sharedById: description: Shared by ID type: string sharedWithId: description: Shared with ID type: string required: - sharedById - sharedWithId type: object SyncPartnerV1: properties: inTimeline: description: In timeline type: boolean sharedById: description: Shared by ID type: string sharedWithId: description: Shared with ID type: string required: - inTimeline - sharedById - sharedWithId type: object SyncPersonDeleteV1: properties: personId: description: Person ID type: string required: - personId type: object SyncPersonV1: properties: birthDate: description: Birth date format: date-time nullable: true type: string color: description: Color nullable: true type: string createdAt: description: Created at format: date-time type: string faceAssetId: description: Face asset ID nullable: true type: string id: description: Person ID type: string isFavorite: description: Is favorite type: boolean isHidden: description: Is hidden type: boolean name: description: Person name type: string ownerId: description: Owner ID type: string updatedAt: description: Updated at format: date-time type: string required: - birthDate - color - createdAt - faceAssetId - id - isFavorite - isHidden - name - ownerId - updatedAt type: object SyncRequestType: description: Sync request types enum: - AlbumsV1 - AlbumUsersV1 - AlbumToAssetsV1 - AlbumAssetsV1 - AlbumAssetExifsV1 - AssetsV1 - AssetExifsV1 - AssetEditsV1 - AssetMetadataV1 - AuthUsersV1 - MemoriesV1 - MemoryToAssetsV1 - PartnersV1 - PartnerAssetsV1 - PartnerAssetExifsV1 - PartnerStacksV1 - StacksV1 - UsersV1 - PeopleV1 - AssetFacesV1 - AssetFacesV2 - UserMetadataV1 type: string SyncResetV1: properties: {} type: object SyncStackDeleteV1: properties: stackId: description: Stack ID type: string required: - stackId type: object SyncStackV1: properties: createdAt: description: Created at format: date-time type: string id: description: Stack ID type: string ownerId: description: Owner ID type: string primaryAssetId: description: Primary asset ID type: string updatedAt: description: Updated at format: date-time type: string required: - createdAt - id - ownerId - primaryAssetId - updatedAt type: object SyncStreamDto: properties: reset: description: Reset sync state type: boolean types: description: Sync request types items: $ref: '#/components/schemas/SyncRequestType' type: array required: - types type: object SyncUserDeleteV1: properties: userId: description: User ID type: string required: - userId type: object SyncUserMetadataDeleteV1: properties: key: allOf: - $ref: '#/components/schemas/UserMetadataKey' description: User metadata key userId: description: User ID type: string required: - key - userId type: object SyncUserMetadataV1: properties: key: allOf: - $ref: '#/components/schemas/UserMetadataKey' description: User metadata key userId: description: User ID type: string value: description: User metadata value type: object required: - key - userId - value type: object SyncUserV1: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: User avatar color nullable: true deletedAt: description: User deleted at format: date-time nullable: true type: string email: description: User email type: string hasProfileImage: description: User has profile image type: boolean id: description: User ID type: string name: description: User name type: string profileChangedAt: description: User profile changed at format: date-time type: string required: - avatarColor - deletedAt - email - hasProfileImage - id - name - profileChangedAt type: object SystemConfigBackupsDto: properties: database: $ref: '#/components/schemas/DatabaseBackupConfig' required: - database type: object SystemConfigDto: properties: backup: $ref: '#/components/schemas/SystemConfigBackupsDto' ffmpeg: $ref: '#/components/schemas/SystemConfigFFmpegDto' image: $ref: '#/components/schemas/SystemConfigImageDto' job: $ref: '#/components/schemas/SystemConfigJobDto' library: $ref: '#/components/schemas/SystemConfigLibraryDto' logging: $ref: '#/components/schemas/SystemConfigLoggingDto' machineLearning: $ref: '#/components/schemas/SystemConfigMachineLearningDto' map: $ref: '#/components/schemas/SystemConfigMapDto' metadata: $ref: '#/components/schemas/SystemConfigMetadataDto' newVersionCheck: $ref: '#/components/schemas/SystemConfigNewVersionCheckDto' nightlyTasks: $ref: '#/components/schemas/SystemConfigNightlyTasksDto' notifications: $ref: '#/components/schemas/SystemConfigNotificationsDto' oauth: $ref: '#/components/schemas/SystemConfigOAuthDto' passwordLogin: $ref: '#/components/schemas/SystemConfigPasswordLoginDto' reverseGeocoding: $ref: '#/components/schemas/SystemConfigReverseGeocodingDto' server: $ref: '#/components/schemas/SystemConfigServerDto' storageTemplate: $ref: '#/components/schemas/SystemConfigStorageTemplateDto' templates: $ref: '#/components/schemas/SystemConfigTemplatesDto' theme: $ref: '#/components/schemas/SystemConfigThemeDto' trash: $ref: '#/components/schemas/SystemConfigTrashDto' user: $ref: '#/components/schemas/SystemConfigUserDto' required: - backup - ffmpeg - image - job - library - logging - machineLearning - map - metadata - newVersionCheck - nightlyTasks - notifications - oauth - passwordLogin - reverseGeocoding - server - storageTemplate - templates - theme - trash - user type: object SystemConfigFFmpegDto: properties: accel: allOf: - $ref: '#/components/schemas/TranscodeHWAccel' description: Transcode hardware acceleration accelDecode: description: Accelerated decode type: boolean acceptedAudioCodecs: description: Accepted audio codecs items: $ref: '#/components/schemas/AudioCodec' type: array acceptedContainers: description: Accepted containers items: $ref: '#/components/schemas/VideoContainer' type: array acceptedVideoCodecs: description: Accepted video codecs items: $ref: '#/components/schemas/VideoCodec' type: array bframes: description: B-frames maximum: 16 minimum: -1 type: integer cqMode: allOf: - $ref: '#/components/schemas/CQMode' description: CQ mode crf: description: CRF maximum: 51 minimum: 0 type: integer gopSize: description: GOP size minimum: 0 type: integer maxBitrate: description: Max bitrate type: string preferredHwDevice: description: Preferred hardware device type: string preset: description: Preset type: string refs: description: References maximum: 6 minimum: 0 type: integer targetAudioCodec: allOf: - $ref: '#/components/schemas/AudioCodec' description: Target audio codec targetResolution: description: Target resolution type: string targetVideoCodec: allOf: - $ref: '#/components/schemas/VideoCodec' description: Target video codec temporalAQ: description: Temporal AQ type: boolean threads: description: Threads minimum: 0 type: integer tonemap: allOf: - $ref: '#/components/schemas/ToneMapping' description: Tone mapping transcode: allOf: - $ref: '#/components/schemas/TranscodePolicy' description: Transcode policy twoPass: description: Two pass type: boolean required: - accel - accelDecode - acceptedAudioCodecs - acceptedContainers - acceptedVideoCodecs - bframes - cqMode - crf - gopSize - maxBitrate - preferredHwDevice - preset - refs - targetAudioCodec - targetResolution - targetVideoCodec - temporalAQ - threads - tonemap - transcode - twoPass type: object SystemConfigFacesDto: properties: import: description: Import type: boolean required: - import type: object SystemConfigGeneratedFullsizeImageDto: properties: enabled: description: Enabled type: boolean format: allOf: - $ref: '#/components/schemas/ImageFormat' description: Image format progressive: default: false description: Progressive type: boolean quality: description: Quality maximum: 100 minimum: 1 type: integer required: - enabled - format - quality type: object SystemConfigGeneratedImageDto: properties: format: allOf: - $ref: '#/components/schemas/ImageFormat' description: Image format progressive: default: false type: boolean quality: description: Quality maximum: 100 minimum: 1 type: integer size: description: Size minimum: 1 type: integer required: - format - quality - size type: object SystemConfigImageDto: properties: colorspace: allOf: - $ref: '#/components/schemas/Colorspace' description: Colorspace extractEmbedded: description: Extract embedded type: boolean fullsize: $ref: '#/components/schemas/SystemConfigGeneratedFullsizeImageDto' preview: $ref: '#/components/schemas/SystemConfigGeneratedImageDto' thumbnail: $ref: '#/components/schemas/SystemConfigGeneratedImageDto' required: - colorspace - extractEmbedded - fullsize - preview - thumbnail type: object SystemConfigJobDto: properties: backgroundTask: $ref: '#/components/schemas/JobSettingsDto' editor: $ref: '#/components/schemas/JobSettingsDto' faceDetection: $ref: '#/components/schemas/JobSettingsDto' library: $ref: '#/components/schemas/JobSettingsDto' metadataExtraction: $ref: '#/components/schemas/JobSettingsDto' migration: $ref: '#/components/schemas/JobSettingsDto' notifications: $ref: '#/components/schemas/JobSettingsDto' ocr: $ref: '#/components/schemas/JobSettingsDto' search: $ref: '#/components/schemas/JobSettingsDto' sidecar: $ref: '#/components/schemas/JobSettingsDto' smartSearch: $ref: '#/components/schemas/JobSettingsDto' thumbnailGeneration: $ref: '#/components/schemas/JobSettingsDto' videoConversion: $ref: '#/components/schemas/JobSettingsDto' workflow: $ref: '#/components/schemas/JobSettingsDto' required: - backgroundTask - editor - faceDetection - library - metadataExtraction - migration - notifications - ocr - search - sidecar - smartSearch - thumbnailGeneration - videoConversion - workflow type: object SystemConfigLibraryDto: properties: scan: $ref: '#/components/schemas/SystemConfigLibraryScanDto' watch: $ref: '#/components/schemas/SystemConfigLibraryWatchDto' required: - scan - watch type: object SystemConfigLibraryScanDto: properties: cronExpression: type: string enabled: description: Enabled type: boolean required: - cronExpression - enabled type: object SystemConfigLibraryWatchDto: properties: enabled: description: Enabled type: boolean required: - enabled type: object SystemConfigLoggingDto: properties: enabled: description: Enabled type: boolean level: allOf: - $ref: '#/components/schemas/LogLevel' required: - enabled - level type: object SystemConfigMachineLearningDto: properties: availabilityChecks: $ref: '#/components/schemas/MachineLearningAvailabilityChecksDto' clip: $ref: '#/components/schemas/CLIPConfig' duplicateDetection: $ref: '#/components/schemas/DuplicateDetectionConfig' enabled: description: Enabled type: boolean facialRecognition: $ref: '#/components/schemas/FacialRecognitionConfig' ocr: $ref: '#/components/schemas/OcrConfig' urls: format: uri items: format: uri type: string minItems: 1 type: array required: - availabilityChecks - clip - duplicateDetection - enabled - facialRecognition - ocr - urls type: object SystemConfigMapDto: properties: darkStyle: format: uri type: string enabled: description: Enabled type: boolean lightStyle: format: uri type: string required: - darkStyle - enabled - lightStyle type: object SystemConfigMetadataDto: properties: faces: $ref: '#/components/schemas/SystemConfigFacesDto' required: - faces type: object SystemConfigNewVersionCheckDto: properties: enabled: description: Enabled type: boolean required: - enabled type: object SystemConfigNightlyTasksDto: properties: clusterNewFaces: description: Cluster new faces type: boolean databaseCleanup: description: Database cleanup type: boolean generateMemories: description: Generate memories type: boolean missingThumbnails: description: Missing thumbnails type: boolean startTime: type: string syncQuotaUsage: description: Sync quota usage type: boolean required: - clusterNewFaces - databaseCleanup - generateMemories - missingThumbnails - startTime - syncQuotaUsage type: object SystemConfigNotificationsDto: properties: smtp: $ref: '#/components/schemas/SystemConfigSmtpDto' required: - smtp type: object SystemConfigOAuthDto: properties: autoLaunch: description: Auto launch type: boolean autoRegister: description: Auto register type: boolean buttonText: description: Button text type: string clientId: description: Client ID type: string clientSecret: description: Client secret type: string defaultStorageQuota: description: Default storage quota format: int64 minimum: 0 nullable: true type: integer enabled: description: Enabled type: boolean issuerUrl: description: Issuer URL type: string mobileOverrideEnabled: description: Mobile override enabled type: boolean mobileRedirectUri: description: Mobile redirect URI format: uri type: string profileSigningAlgorithm: description: Profile signing algorithm type: string roleClaim: description: Role claim type: string scope: description: Scope type: string signingAlgorithm: type: string storageLabelClaim: description: Storage label claim type: string storageQuotaClaim: description: Storage quota claim type: string timeout: description: Timeout minimum: 1 type: integer tokenEndpointAuthMethod: allOf: - $ref: '#/components/schemas/OAuthTokenEndpointAuthMethod' description: Token endpoint auth method required: - autoLaunch - autoRegister - buttonText - clientId - clientSecret - defaultStorageQuota - enabled - issuerUrl - mobileOverrideEnabled - mobileRedirectUri - profileSigningAlgorithm - roleClaim - scope - signingAlgorithm - storageLabelClaim - storageQuotaClaim - timeout - tokenEndpointAuthMethod type: object SystemConfigPasswordLoginDto: properties: enabled: description: Enabled type: boolean required: - enabled type: object SystemConfigReverseGeocodingDto: properties: enabled: description: Enabled type: boolean required: - enabled type: object SystemConfigServerDto: properties: externalDomain: description: External domain format: uri type: string loginPageMessage: description: Login page message type: string publicUsers: description: Public users type: boolean required: - externalDomain - loginPageMessage - publicUsers type: object SystemConfigSmtpDto: properties: enabled: description: Whether SMTP email notifications are enabled type: boolean from: description: Email address to send from type: string replyTo: description: Email address for replies type: string transport: $ref: '#/components/schemas/SystemConfigSmtpTransportDto' required: - enabled - from - replyTo - transport type: object SystemConfigSmtpTransportDto: properties: host: description: SMTP server hostname type: string ignoreCert: description: Whether to ignore SSL certificate errors type: boolean password: description: SMTP password type: string port: description: SMTP server port maximum: 65535 minimum: 0 type: number secure: description: Whether to use secure connection (TLS/SSL) type: boolean username: description: SMTP username type: string required: - host - ignoreCert - password - port - secure - username type: object SystemConfigStorageTemplateDto: properties: enabled: description: Enabled type: boolean hashVerificationEnabled: description: Hash verification enabled type: boolean template: description: Template type: string required: - enabled - hashVerificationEnabled - template type: object SystemConfigTemplateEmailsDto: properties: albumInviteTemplate: type: string albumUpdateTemplate: type: string welcomeTemplate: type: string required: - albumInviteTemplate - albumUpdateTemplate - welcomeTemplate type: object SystemConfigTemplateStorageOptionDto: properties: dayOptions: description: Available day format options for storage template items: type: string type: array hourOptions: description: Available hour format options for storage template items: type: string type: array minuteOptions: description: Available minute format options for storage template items: type: string type: array monthOptions: description: Available month format options for storage template items: type: string type: array presetOptions: description: Available preset template options items: type: string type: array secondOptions: description: Available second format options for storage template items: type: string type: array weekOptions: description: Available week format options for storage template items: type: string type: array yearOptions: description: Available year format options for storage template items: type: string type: array required: - dayOptions - hourOptions - minuteOptions - monthOptions - presetOptions - secondOptions - weekOptions - yearOptions type: object SystemConfigTemplatesDto: properties: email: $ref: '#/components/schemas/SystemConfigTemplateEmailsDto' required: - email type: object SystemConfigThemeDto: properties: customCss: description: Custom CSS for theming type: string required: - customCss type: object SystemConfigTrashDto: properties: days: description: Days minimum: 0 type: integer enabled: description: Enabled type: boolean required: - days - enabled type: object SystemConfigUserDto: properties: deleteDelay: description: Delete delay minimum: 1 type: integer required: - deleteDelay type: object TagBulkAssetsDto: properties: assetIds: description: Asset IDs items: format: uuid type: string type: array tagIds: description: Tag IDs items: format: uuid type: string type: array required: - assetIds - tagIds type: object TagBulkAssetsResponseDto: properties: count: description: Number of assets tagged type: integer required: - count type: object TagCreateDto: properties: color: description: Tag color (hex) pattern: ^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$ type: string name: description: Tag name type: string parentId: description: Parent tag ID format: uuid nullable: true type: string required: - name type: object TagResponseDto: properties: color: description: Tag color (hex) type: string createdAt: description: Creation date format: date-time type: string id: description: Tag ID type: string name: description: Tag name type: string parentId: description: Parent tag ID type: string updatedAt: description: Last update date format: date-time type: string value: description: Tag value (full path) type: string required: - createdAt - id - name - updatedAt - value type: object TagUpdateDto: properties: color: description: Tag color (hex) nullable: true type: string type: object TagUpsertDto: properties: tags: description: Tag names to upsert items: type: string type: array required: - tags type: object TagsResponse: properties: enabled: default: true description: Whether tags are enabled type: boolean sidebarWeb: default: true description: Whether tags appear in web sidebar type: boolean required: - enabled - sidebarWeb type: object TagsUpdate: properties: enabled: description: Whether tags are enabled type: boolean sidebarWeb: description: Whether tags appear in web sidebar type: boolean type: object TemplateDto: properties: template: description: Template name type: string required: - template type: object TemplateResponseDto: properties: html: description: Template HTML content type: string name: description: Template name type: string required: - html - name type: object TestEmailResponseDto: properties: messageId: description: Email message ID type: string required: - messageId type: object TimeBucketAssetResponseDto: properties: city: description: Array of city names extracted from EXIF GPS data items: nullable: true type: string type: array country: description: Array of country names extracted from EXIF GPS data items: nullable: true type: string type: array duration: description: Array of video durations in HH:MM:SS format (null for images) items: nullable: true type: string type: array fileCreatedAt: description: Array of file creation timestamps in UTC items: type: string type: array id: description: Array of asset IDs in the time bucket items: type: string type: array isFavorite: description: Array indicating whether each asset is favorited items: type: boolean type: array isImage: description: Array indicating whether each asset is an image (false for videos) items: type: boolean type: array isTrashed: description: Array indicating whether each asset is in the trash items: type: boolean type: array latitude: description: Array of latitude coordinates extracted from EXIF GPS data items: nullable: true type: number type: array livePhotoVideoId: description: Array of live photo video asset IDs (null for non-live photos) items: nullable: true type: string type: array localOffsetHours: description: Array of UTC offset hours at the time each photo was taken. Positive values are east of UTC, negative values are west of UTC. Values may be fractional (e.g., 5.5 for +05:30, -9.75 for -09:45). Applying this offset to 'fileCreatedAt' will give you the time the photo was taken from the photographer's perspective. items: type: number type: array longitude: description: Array of longitude coordinates extracted from EXIF GPS data items: nullable: true type: number type: array ownerId: description: Array of owner IDs for each asset items: type: string type: array projectionType: description: Array of projection types for 360° content (e.g., "EQUIRECTANGULAR", "CUBEFACE", "CYLINDRICAL") items: nullable: true type: string type: array ratio: description: Array of aspect ratios (width/height) for each asset items: type: number type: array stack: description: Array of stack information as [stackId, assetCount] tuples (null for non-stacked assets) items: items: type: string maxItems: 2 minItems: 2 nullable: true type: array type: array thumbhash: description: Array of BlurHash strings for generating asset previews (base64 encoded) items: nullable: true type: string type: array visibility: description: Array of visibility statuses for each asset (e.g., ARCHIVE, TIMELINE, HIDDEN, LOCKED) items: $ref: '#/components/schemas/AssetVisibility' type: array required: - city - country - duration - fileCreatedAt - id - isFavorite - isImage - isTrashed - livePhotoVideoId - localOffsetHours - ownerId - projectionType - ratio - thumbhash - visibility type: object TimeBucketsResponseDto: properties: count: description: Number of assets in this time bucket example: 42 type: integer timeBucket: description: Time bucket identifier in YYYY-MM-DD format representing the start of the time period example: 2024-01-01 type: string required: - count - timeBucket type: object ToneMapping: description: Tone mapping enum: - hable - mobius - reinhard - disabled type: string TranscodeHWAccel: description: Transcode hardware acceleration enum: - nvenc - qsv - vaapi - rkmpp - disabled type: string TranscodePolicy: description: Transcode policy enum: - all - optimal - bitrate - required - disabled type: string TrashResponseDto: properties: count: description: Number of items in trash type: integer required: - count type: object UpdateAlbumDto: properties: albumName: description: Album name type: string albumThumbnailAssetId: description: Album thumbnail asset ID format: uuid type: string description: description: Album description type: string isActivityEnabled: description: Enable activity feed type: boolean order: allOf: - $ref: '#/components/schemas/AssetOrder' description: Asset sort order type: object UpdateAlbumUserDto: properties: role: allOf: - $ref: '#/components/schemas/AlbumUserRole' description: Album user role required: - role type: object UpdateAssetDto: properties: dateTimeOriginal: description: Original date and time type: string description: description: Asset description type: string isFavorite: description: Mark as favorite type: boolean latitude: description: Latitude coordinate type: number livePhotoVideoId: description: Live photo video ID format: uuid nullable: true type: string longitude: description: Longitude coordinate type: number rating: description: Rating in range [1-5], or null for unrated maximum: 5 minimum: -1 nullable: true type: number x-immich-history: - version: v1 state: Added - version: v2 state: Stable - version: v2.6.0 state: Updated description: Using -1 as a rating is deprecated and will be removed in the next major version. x-immich-state: Stable visibility: allOf: - $ref: '#/components/schemas/AssetVisibility' description: Asset visibility type: object UpdateLibraryDto: properties: exclusionPatterns: description: Exclusion patterns (max 128) items: type: string maxItems: 128 type: array uniqueItems: true importPaths: description: Import paths (max 128) items: type: string maxItems: 128 type: array uniqueItems: true name: description: Library name type: string type: object UsageByUserDto: properties: photos: description: Number of photos type: integer quotaSizeInBytes: description: User quota size in bytes (null if unlimited) format: int64 nullable: true type: integer usage: description: Total storage usage in bytes format: int64 type: integer usagePhotos: description: Storage usage for photos in bytes format: int64 type: integer usageVideos: description: Storage usage for videos in bytes format: int64 type: integer userId: description: User ID type: string userName: description: User name type: string videos: description: Number of videos type: integer required: - photos - quotaSizeInBytes - usage - usagePhotos - usageVideos - userId - userName - videos type: object UserAdminCreateDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color nullable: true email: description: User email format: email type: string isAdmin: description: Grant admin privileges type: boolean name: description: User name type: string notify: description: Send notification email type: boolean password: description: User password type: string pinCode: description: PIN code example: '123456' nullable: true type: string quotaSizeInBytes: description: Storage quota in bytes format: int64 minimum: 0 nullable: true type: integer shouldChangePassword: description: Require password change on next login type: boolean storageLabel: description: Storage label nullable: true type: string required: - email - name - password type: object UserAdminDeleteDto: properties: force: description: Force delete even if user has assets type: boolean type: object UserAdminResponseDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color createdAt: description: Creation date format: date-time type: string deletedAt: description: Deletion date format: date-time nullable: true type: string email: description: User email type: string id: description: User ID type: string isAdmin: description: Is admin user type: boolean license: allOf: - $ref: '#/components/schemas/UserLicense' description: User license nullable: true name: description: User name type: string oauthId: description: OAuth ID type: string profileChangedAt: description: Profile change date format: date-time type: string profileImagePath: description: Profile image path type: string quotaSizeInBytes: description: Storage quota in bytes format: int64 nullable: true type: integer quotaUsageInBytes: description: Storage usage in bytes format: int64 nullable: true type: integer shouldChangePassword: description: Require password change on next login type: boolean status: allOf: - $ref: '#/components/schemas/UserStatus' description: User status storageLabel: description: Storage label nullable: true type: string updatedAt: description: Last update date format: date-time type: string required: - avatarColor - createdAt - deletedAt - email - id - isAdmin - license - name - oauthId - profileChangedAt - profileImagePath - quotaSizeInBytes - quotaUsageInBytes - shouldChangePassword - status - storageLabel - updatedAt type: object UserAdminUpdateDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color nullable: true email: description: User email format: email type: string isAdmin: description: Grant admin privileges type: boolean name: description: User name type: string password: description: User password type: string pinCode: description: PIN code example: '123456' nullable: true type: string quotaSizeInBytes: description: Storage quota in bytes format: int64 minimum: 0 nullable: true type: integer shouldChangePassword: description: Require password change on next login type: boolean storageLabel: description: Storage label nullable: true type: string type: object UserAvatarColor: description: Avatar color enum: - primary - pink - red - yellow - blue - green - purple - orange - gray - amber type: string UserLicense: properties: activatedAt: description: Activation date format: date-time type: string activationKey: description: Activation key type: string licenseKey: description: License key type: string required: - activatedAt - activationKey - licenseKey type: object UserMetadataKey: description: User metadata key enum: - preferences - license - onboarding type: string UserPreferencesResponseDto: properties: albums: $ref: '#/components/schemas/AlbumsResponse' cast: $ref: '#/components/schemas/CastResponse' download: $ref: '#/components/schemas/DownloadResponse' emailNotifications: $ref: '#/components/schemas/EmailNotificationsResponse' folders: $ref: '#/components/schemas/FoldersResponse' memories: $ref: '#/components/schemas/MemoriesResponse' people: $ref: '#/components/schemas/PeopleResponse' purchase: $ref: '#/components/schemas/PurchaseResponse' ratings: $ref: '#/components/schemas/RatingsResponse' sharedLinks: $ref: '#/components/schemas/SharedLinksResponse' tags: $ref: '#/components/schemas/TagsResponse' required: - albums - cast - download - emailNotifications - folders - memories - people - purchase - ratings - sharedLinks - tags type: object UserPreferencesUpdateDto: properties: albums: $ref: '#/components/schemas/AlbumsUpdate' avatar: $ref: '#/components/schemas/AvatarUpdate' cast: $ref: '#/components/schemas/CastUpdate' download: $ref: '#/components/schemas/DownloadUpdate' emailNotifications: $ref: '#/components/schemas/EmailNotificationsUpdate' folders: $ref: '#/components/schemas/FoldersUpdate' memories: $ref: '#/components/schemas/MemoriesUpdate' people: $ref: '#/components/schemas/PeopleUpdate' purchase: $ref: '#/components/schemas/PurchaseUpdate' ratings: $ref: '#/components/schemas/RatingsUpdate' sharedLinks: $ref: '#/components/schemas/SharedLinksUpdate' tags: $ref: '#/components/schemas/TagsUpdate' type: object UserResponseDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color email: description: User email type: string id: description: User ID type: string name: description: User name type: string profileChangedAt: description: Profile change date format: date-time type: string profileImagePath: description: Profile image path type: string required: - avatarColor - email - id - name - profileChangedAt - profileImagePath type: object UserStatus: description: User status enum: - active - removing - deleted type: string UserUpdateMeDto: properties: avatarColor: allOf: - $ref: '#/components/schemas/UserAvatarColor' description: Avatar color nullable: true email: description: User email format: email type: string name: description: User name type: string password: description: User password (deprecated, use change password endpoint) type: string type: object ValidateAccessTokenResponseDto: properties: authStatus: description: Authentication status type: boolean required: - authStatus type: object ValidateLibraryDto: properties: exclusionPatterns: description: Exclusion patterns (max 128) items: type: string maxItems: 128 type: array uniqueItems: true importPaths: description: Import paths to validate (max 128) items: type: string maxItems: 128 type: array uniqueItems: true type: object ValidateLibraryImportPathResponseDto: properties: importPath: description: Import path type: string isValid: default: false description: Is valid type: boolean message: description: Validation message type: string required: - importPath - isValid type: object ValidateLibraryResponseDto: properties: importPaths: description: Validation results for import paths items: $ref: '#/components/schemas/ValidateLibraryImportPathResponseDto' type: array type: object VersionCheckStateResponseDto: properties: checkedAt: description: Last check timestamp nullable: true type: string releaseVersion: description: Release version nullable: true type: string required: - checkedAt - releaseVersion type: object VideoCodec: description: Target video codec enum: - h264 - hevc - vp9 - av1 type: string VideoContainer: description: Accepted containers enum: - mov - mp4 - ogg - webm type: string WorkflowActionItemDto: properties: actionConfig: description: Action configuration type: object pluginActionId: description: Plugin action ID format: uuid type: string required: - pluginActionId type: object WorkflowActionResponseDto: properties: actionConfig: description: Action configuration nullable: true type: object id: description: Action ID type: string order: description: Action order type: number pluginActionId: description: Plugin action ID type: string workflowId: description: Workflow ID type: string required: - actionConfig - id - order - pluginActionId - workflowId type: object WorkflowCreateDto: properties: actions: description: Workflow actions items: $ref: '#/components/schemas/WorkflowActionItemDto' type: array description: description: Workflow description type: string enabled: description: Workflow enabled type: boolean filters: description: Workflow filters items: $ref: '#/components/schemas/WorkflowFilterItemDto' type: array name: description: Workflow name type: string triggerType: allOf: - $ref: '#/components/schemas/PluginTriggerType' description: Workflow trigger type required: - actions - filters - name - triggerType type: object WorkflowFilterItemDto: properties: filterConfig: description: Filter configuration type: object pluginFilterId: description: Plugin filter ID format: uuid type: string required: - pluginFilterId type: object WorkflowFilterResponseDto: properties: filterConfig: description: Filter configuration nullable: true type: object id: description: Filter ID type: string order: description: Filter order type: number pluginFilterId: description: Plugin filter ID type: string workflowId: description: Workflow ID type: string required: - filterConfig - id - order - pluginFilterId - workflowId type: object WorkflowResponseDto: properties: actions: description: Workflow actions items: $ref: '#/components/schemas/WorkflowActionResponseDto' type: array createdAt: description: Creation date type: string description: description: Workflow description type: string enabled: description: Workflow enabled type: boolean filters: description: Workflow filters items: $ref: '#/components/schemas/WorkflowFilterResponseDto' type: array id: description: Workflow ID type: string name: description: Workflow name nullable: true type: string ownerId: description: Owner user ID type: string triggerType: allOf: - $ref: '#/components/schemas/PluginTriggerType' description: Workflow trigger type required: - actions - createdAt - description - enabled - filters - id - name - ownerId - triggerType type: object WorkflowUpdateDto: properties: actions: description: Workflow actions items: $ref: '#/components/schemas/WorkflowActionItemDto' type: array description: description: Workflow description type: string enabled: description: Workflow enabled type: boolean filters: description: Workflow filters items: $ref: '#/components/schemas/WorkflowFilterItemDto' type: array name: description: Workflow name type: string triggerType: allOf: - $ref: '#/components/schemas/PluginTriggerType' description: Workflow trigger type type: object