document tri-state matrix

mobile/openapi/lib/api/albums_api.dart

@@ -499,7 +499,7 @@ class AlbumsApi {
 
   /// List all albums
   ///
-  /// Retrieve a list of albums available to the authenticated user.
+  /// Retrieve a list of albums available to the authenticated user. Results are filtered by the `owned` and `shared` query parameters:  | `owned` | `shared` | Result | |---------|----------|--------| | — | — | All accessible albums (owned + shared-with-me) | | `true` | — | Only albums owned by the user | | `false` | — | Only albums shared with the user (not owned) | | `true` | `true` | Owned albums that have been shared out | | `true` | `false` | Owned private albums (not shared) | | — | `true` | Owned albums shared out, plus all albums shared with the user | | — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) | | `false` | `true` | Albums shared with the user (same as `owned=false`) | | `false` | `false` | Empty (logically impossible combination) |
   ///
   /// Note: This method returns the HTTP [Response].
   ///
@@ -550,7 +550,7 @@ class AlbumsApi {
 
   /// List all albums
   ///
-  /// Retrieve a list of albums available to the authenticated user.
+  /// Retrieve a list of albums available to the authenticated user. Results are filtered by the `owned` and `shared` query parameters:  | `owned` | `shared` | Result | |---------|----------|--------| | — | — | All accessible albums (owned + shared-with-me) | | `true` | — | Only albums owned by the user | | `false` | — | Only albums shared with the user (not owned) | | `true` | `true` | Owned albums that have been shared out | | `true` | `false` | Owned private albums (not shared) | | — | `true` | Owned albums shared out, plus all albums shared with the user | | — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) | | `false` | `true` | Albums shared with the user (same as `owned=false`) | | `false` | `false` | Empty (logically impossible combination) |
   ///
   /// Parameters:
   ///

open-api/immich-openapi-specs.json

@@ -1634,7 +1634,7 @@
     },
     "/albums": {
       "get": {
-        "description": "Retrieve a list of albums available to the authenticated user.",
+        "description": "Retrieve a list of albums available to the authenticated user.\nResults are filtered by the `owned` and `shared` query parameters:\n\n| `owned` | `shared` | Result |\n|---------|----------|--------|\n| — | — | All accessible albums (owned + shared-with-me) |\n| `true` | — | Only albums owned by the user |\n| `false` | — | Only albums shared with the user (not owned) |\n| `true` | `true` | Owned albums that have been shared out |\n| `true` | `false` | Owned private albums (not shared) |\n| — | `true` | Owned albums shared out, plus all albums shared with the user |\n| — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) |\n| `false` | `true` | Albums shared with the user (same as `owned=false`) |\n| `false` | `false` | Empty (logically impossible combination) |",
         "operationId": "getAllAlbums",
         "parameters": [
           {

server/src/controllers/album.controller.ts

@@ -29,7 +29,22 @@ export class AlbumController {
   @Authenticated({ permission: Permission.AlbumRead })
   @Endpoint({
     summary: 'List all albums',
-    description: 'Retrieve a list of albums available to the authenticated user.',
+    description: [
+      'Retrieve a list of albums available to the authenticated user.',
+      'Results are filtered by the `owned` and `shared` query parameters:',
+      '',
+      '| `owned` | `shared` | Result |',
+      '|---------|----------|--------|',
+      '| — | — | All accessible albums (owned + shared-with-me) |',
+      '| `true` | — | Only albums owned by the user |',
+      '| `false` | — | Only albums shared with the user (not owned) |',
+      '| `true` | `true` | Owned albums that have been shared out |',
+      '| `true` | `false` | Owned private albums (not shared) |',
+      '| — | `true` | Owned albums shared out, plus all albums shared with the user |',
+      '| — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) |',
+      '| `false` | `true` | Albums shared with the user (same as `owned=false`) |',
+      '| `false` | `false` | Empty (logically impossible combination) |',
+    ].join('\n'),
     history: new HistoryBuilder().added('v1').beta('v1').stable('v2'),
   })
   getAllAlbums(@Auth() auth: AuthDto, @Query() query: GetAlbumsDto): Promise<AlbumResponseDto[]> {