# Albums API

Source: https://frameleaf.app/docs/api/reference/albums/

Use your own server and its scoped API keys.

## List all albums

GET /api/albums

Retrieve a list of albums available to the authenticated user.

```json
{
  "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 other parameters)",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": false,
      "in": "query",
      "description": "Album ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "isOwned",
      "required": false,
      "in": "query",
      "description": "Filter by ownership: true = only owned, false = only shared-with-me, undefined = no filter",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isShared",
      "required": false,
      "in": "query",
      "description": "Filter by shared status: true = only shared, false = not shared, undefined = no filter",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "name",
      "required": false,
      "in": "query",
      "description": "Album name (exact match)",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "suppressedOnly",
      "required": false,
      "in": "query",
      "description": "Return album metadata for suppressed content only",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/AlbumResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "List all albums",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Create an album

POST /api/albums

Create a new album. The album can also be created with initial users and assets.

```json
{
  "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Create an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.create"
}
```

## Add assets to albums

PUT /api/albums/assets

Send a list of asset IDs and album IDs to add each asset to each album.

```json
{
  "description": "Send a list of asset IDs and album IDs to add each asset to each album.",
  "operationId": "addAssetsToAlbums",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AlbumsAddAssetsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumsAddAssetsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Add assets to albums",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumAsset.create"
}
```

## Retrieve the album icon catalogue

GET /api/albums/icons

Every Material Design Icons name an album or collection may use, plus the categorised suggested set shown first in icon choosers. Served as data so clients never bundle the catalogue.

```json
{
  "description": "Every Material Design Icons name an album or collection may use, plus the categorised suggested set shown first in icon choosers. Served as data so clients never bundle the catalogue.",
  "operationId": "getAlbumIconCatalogue",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumIconCatalogueResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve the album icon catalogue",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Arrange a group of the album directory

PUT /api/albums/order

Save the authenticated user's own custom order for one group of their album directory: the albums inside a collection, or at the top level the collections, the albums on their own, or the shared spaces. The order is personal and changes organization only; access and membership are untouched. The ids must be exactly the group as it is now, otherwise 409.

```json
{
  "description": "Save the authenticated user's own custom order for one group of their album directory: the albums inside a collection, or at the top level the collections, the albums on their own, or the shared spaces. The order is personal and changes organization only; access and membership are untouched. The ids must be exactly the group as it is now, otherwise 409.",
  "operationId": "setAlbumOrder",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AlbumOrderDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Arrange a group of the album directory",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Retrieve album statistics

GET /api/albums/statistics

Returns statistics about the albums available to the authenticated user.

```json
{
  "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve album statistics",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.statistics"
}
```

## Retrieve the album directory

GET /api/albums/tree

Collections with their albums, albums that stand on their own, and shared spaces, for everything the authenticated user owns or is shared with. Albums nest one level deep inside collections only; collections and shared spaces are always top level.

```json
{
  "description": "Collections with their albums, albums that stand on their own, and shared spaces, for everything the authenticated user owns or is shared with. Albums nest one level deep inside collections only; collections and shared spaces are always top level.",
  "operationId": "getAlbumTree",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumTreeResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve the album directory",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Delete an album

DELETE /api/albums/{id}

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.

```json
{
  "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",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.delete"
}
```

## Retrieve an album

GET /api/albums/{id}

Retrieve information about a specific album by its ID.

```json
{
  "description": "Retrieve information about a specific album by its ID.",
  "operationId": "getAlbumInfo",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "key",
      "required": false,
      "in": "query",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "slug",
      "required": false,
      "in": "query",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "suppressedOnly",
      "required": false,
      "in": "query",
      "description": "Return album metadata for suppressed content only",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Update an album

PATCH /api/albums/{id}

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.

```json
{
  "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",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Update an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Remove assets from an album

DELETE /api/albums/{id}/assets

Remove multiple assets from a specific album by its ID.

```json
{
  "description": "Remove multiple assets from a specific album by its ID.",
  "operationId": "removeAssetFromAlbum",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Remove assets from an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumAsset.delete"
}
```

## Add assets to an album

PUT /api/albums/{id}/assets

Add multiple assets to a specific album by its ID.

```json
{
  "description": "Add multiple assets to a specific album by its ID.",
  "operationId": "addAssetsToAlbum",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Add assets to an album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumAsset.create"
}
```

## Move an album into or out of a collection

PUT /api/albums/{id}/collection

Move an album into a collection, or send null to take it out so it stands on its own. Only the album owner can move it (an editor gets 403); the destination must be a collection the user can edit. Collections and shared spaces cannot be moved.

```json
{
  "description": "Move an album into a collection, or send null to take it out so it stands on its own. Only the album owner can move it (an editor gets 403); the destination must be a collection the user can edit. Collections and shared spaces cannot be moved.",
  "operationId": "moveAlbumToCollection",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MoveAlbumDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Move an album into or out of a collection",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Count descendant albums

GET /api/albums/{id}/descendant-count

Return the number of descendant albums (children, grandchildren, etc.) for a specific album. Used by the UI to show "Delete X and N nested albums?" confirmations.

```json
{
  "description": "Return the number of descendant albums (children, grandchildren, etc.) for a specific album. Used by the UI to show \"Delete X and N nested albums?\" confirmations.",
  "operationId": "getAlbumDescendantCount",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AlbumDescendantCountResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Count descendant albums",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Retrieve album map markers

GET /api/albums/{id}/map-markers

Retrieve map marker information for a specific album by its ID.

```json
{
  "description": "Retrieve map marker information for a specific album by its ID.",
  "operationId": "getAlbumMapMarkers",
  "parameters": [
    {
      "name": "fileCreatedAfter",
      "required": false,
      "in": "query",
      "description": "Filter assets created after this date",
      "schema": {
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
        "example": "2024-01-01T00:00:00.000Z",
        "type": "string"
      }
    },
    {
      "name": "fileCreatedBefore",
      "required": false,
      "in": "query",
      "description": "Filter assets created before this date",
      "schema": {
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
        "example": "2024-01-01T00:00:00.000Z",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "isArchived",
      "required": false,
      "in": "query",
      "description": "Include archived items (the album default); false leaves them out",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isFavorite",
      "required": false,
      "in": "query",
      "description": "Filter by the viewer's own favorites; other members' favorites are never matched",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "key",
      "required": false,
      "in": "query",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "slug",
      "required": false,
      "in": "query",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "withPartners",
      "required": false,
      "in": "query",
      "description": "Include the album's items owned by anyone else (the album default); false keeps only your own",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "withSharedAlbums",
      "required": false,
      "in": "query",
      "description": "Accepted for the shared map settings; has no effect on an album map",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MapMarkerResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve album map markers",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Remove user from album

DELETE /api/albums/{id}/user/{userId}

Remove a user from an album. Use an ID of "me" to leave a shared album.

```json
{
  "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",
      "description": "Album ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "userId",
      "required": true,
      "in": "path",
      "description": "Album user ID, or \"me\" to reference the current user.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Remove user from album",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumUser.delete"
}
```

## Update user role

PUT /api/albums/{id}/user/{userId}

Change the role for a specific user in a specific album.

```json
{
  "description": "Change the role for a specific user in a specific album.",
  "operationId": "updateAlbumUser",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "description": "Album ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "userId",
      "required": true,
      "in": "path",
      "description": "Album user ID, or \"me\" to reference the current user.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateAlbumUserDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update user role",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumUser.update"
}
```

## Share album with users

PUT /api/albums/{id}/users

Share an album with multiple users. Each user can be given a specific role in the album.

```json
{
  "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",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "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": [
    {
      "api_key": []
    }
  ],
  "summary": "Share album with users",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "albumUser.create"
}
```

## Retrieve classification contributions for an asset

GET /api/classification/assets/{id}

Which of your rules put this item in a smart album, added a tag to it or archived it.

```json
{
  "description": "Which of your rules put this item in a smart album, added a tag to it or archived it.",
  "operationId": "getAssetClassifications",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/ClassificationContributionDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve classification contributions for an asset",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "asset.read"
}
```

## Preview a classification rule

POST /api/classification/preview

What a draft rule matches, without writing anything. Rules with visual categories are previewed over a bounded sample of your newest items.

```json
{
  "description": "What a draft rule matches, without writing anything. Rules with visual categories are previewed over a bounded sample of your newest items.",
  "operationId": "previewClassificationRule",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ClassificationPreviewDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationPreviewResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Preview a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## List classification rules

GET /api/classification/rules

Your smart album rules, optionally only the one behind an album.

```json
{
  "description": "Your smart album rules, optionally only the one behind an album.",
  "operationId": "getClassificationRules",
  "parameters": [
    {
      "name": "albumId",
      "required": false,
      "in": "query",
      "description": "Only the rule behind this album",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/ClassificationRuleResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "List classification rules",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Create a classification rule

POST /api/classification/rules

Create a smart album and the rule that fills it. Nothing is matched until the rule is applied. Archiving matches requires `archiveConsent`.

```json
{
  "description": "Create a smart album and the rule that fills it. Nothing is matched until the rule is applied. Archiving matches requires `archiveConsent`.",
  "operationId": "createClassificationRule",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ClassificationRuleCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationRuleResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.create"
}
```

## Delete a classification rule

DELETE /api/classification/rules/{id}

Stop the rule. Its album stays as an ordinary album with everything in it.

```json
{
  "description": "Stop the rule. Its album stays as an ordinary album with everything in it.",
  "operationId": "deleteClassificationRule",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Retrieve a classification rule

GET /api/classification/rules/{id}

One of your smart album rules and its counts.

```json
{
  "description": "One of your smart album rules and its counts.",
  "operationId": "getClassificationRule",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationRuleResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Update a classification rule

PATCH /api/classification/rules/{id}

Change what the rule matches, what it does, or turn it off. A rule that is off keeps what it applied. Turning archiving on requires `archiveConsent`.

```json
{
  "description": "Change what the rule matches, what it does, or turn it off. A rule that is off keeps what it applied. Turning archiving on requires `archiveConsent`.",
  "operationId": "updateClassificationRule",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ClassificationRuleUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationRuleResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Apply a classification rule

POST /api/classification/rules/{id}/apply

Apply the rule to up to 500 items from its plan. Larger plans run as an `apply-classification-rule` bulk media operation.

```json
{
  "description": "Apply the rule to up to 500 items from its plan. Larger plans run as an `apply-classification-rule` bulk media operation.",
  "operationId": "applyClassificationRule",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ClassificationApplyDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationApplyResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Apply a classification rule",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## Review classification rule matches

POST /api/classification/rules/{id}/decisions

Accept matches (they stay whatever later processing finds) or reject them (what the rule applied is taken back and never applied again).

```json
{
  "description": "Accept matches (they stay whatever later processing finds) or reject them (what the rule applied is taken back and never applied again).",
  "operationId": "decideClassificationRuleMatches",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ClassificationDecisionDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationDecisionResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Review classification rule matches",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.update"
}
```

## List classification rule matches

GET /api/classification/rules/{id}/matches

The rule’s matches with one decision, suggestions to review by default.

```json
{
  "description": "The rule’s matches with one decision, suggestions to review by default.",
  "operationId": "getClassificationRuleMatches",
  "parameters": [
    {
      "name": "decision",
      "required": false,
      "in": "query",
      "schema": {
        "default": "suggested",
        "$ref": "#/components/schemas/ClassificationMatchDecision"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "page",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "default": 1,
        "type": "integer"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 1,
        "maximum": 500,
        "default": 100,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationMatchPageDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "List classification rule matches",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Plan a classification rule re-evaluation

POST /api/classification/rules/{id}/plan

What applying the rule now would add, suggest and take back, without writing anything. Manual decisions are never part of it.

```json
{
  "description": "What applying the rule now would add, suggest and take back, without writing anything. Manual decisions are never part of it.",
  "operationId": "planClassificationRule",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationPlanResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Plan a classification rule re-evaluation",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```

## Retrieve classification rule settings

GET /api/classification/settings

Whether rules may use visual categories, whether those can be compared now, and the default action.

```json
{
  "description": "Whether rules may use visual categories, whether those can be compared now, and the default action.",
  "operationId": "getClassificationSettings",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ClassificationSettingsDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve classification rule settings",
  "tags": [
    "Albums"
  ],
  "x-frameleaf-permission": "album.read"
}
```