Albums

User-created albums for grouping photos.

User-created albums for grouping photos. A photo can belong to multiple albums simultaneously — the assigned album IDs are stored in the photo_album field on the photo. Deleting an album removes only the junction rows; the photos themselves are not deleted.

Fields

Field	Type	Required	Description
id	string	—	Primary key. Read-only, auto-generated
position	float		Fractional drag-sort position in the sidebar
enc_name	string	✅	Encrypted album title. Plain string after decryption
enc_icon	string		Encrypted icon name. Plain string after decryption. Value is a Bootstrap Icons name (e.g. "collection", "heart", "star")
enc_color	string		Encrypted color identifier. Plain string after decryption. Values: primary · secondary · success · danger · warning · info · dark
created_at	string	—	ISO 8601 creation timestamp. Read-only
updated_at	string	—	ISO 8601 last update timestamp. Read-only
album_user_role	UserRole[]	✅	Access control + encryption keys

UserRole

Access control entry. Each recipient gets their own copy of the record’s encryption key, wrapped with their public key.

Field	Type	Required	Description
user_id	string	✅	Recipient user id
role	string	✅	Role identifier. Values: owner · editor · viewer
wrapped_content_key	string	✅	Record key wrapped for this recipient (base64)

find

List albums accessible to the authenticated user.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.find",
  "params": {
    "limit": 100,
    "fields": [
      "id", "position",
      "enc_name", "enc_color", "enc_icon",
      "album_user_role.user_id",
      "album_user_role.wrapped_content_key"
    ]
  },
  "id": 10
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291900",
        "position": 1000.0,
        "enc_name": "<base64>",
        "enc_color": "<base64>",
        "enc_icon": "<base64>",
        "album_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ]
      }
    ],
    "total": 1
  },
  "id": 10
}

findOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.findOneById",
  "params": {
    "id": "1920438291900"
  },
  "id": 11
}

create

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.create",
  "params": {
    "document": {
      "position": 3000.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>",
      "album_user_role": [
        { "user_id": "42", "role": "owner", "wrapped_content_key": "<base64>" }
      ]
    }
  },
  "id": 12
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291920",
    "enc_name": "<base64>",
    "created_at": "2026-05-13T18:30:00Z"
  },
  "id": 12
}

updateOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.updateOneById",
  "params": {
    "id": "1920438291900",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64-new>"
    }
  },
  "id": 13
}

replaceOneById

Full replacement — all writable fields must be provided. Unlike updateOneById, omitted fields are reset to defaults. Nested collections (album_user_role) are not accepted — use updateOneById to modify them.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.replaceOneById",
  "params": {
    "id": "1920438291900",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>"
    }
  },
  "id": 13
}

update

Batch update albums in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.update",
  "params": {
    "items": [
      { "id": "1920438291900", "document": { "position": 500.0 } },
      { "id": "1920438291905", "document": { "position": 1500.0 } }
    ]
  },
  "id": 15
}

deleteOneById

Delete an album. Photos that belonged to this album are unlinked but not deleted.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.deleteOneById",
  "params": {
    "id": "1920438291900"
  },
  "id": 14
}

delete

Batch delete albums in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "photos.albums.delete",
  "params": {
    "items": [
      { "id": "1920438291900" },
      { "id": "1920438291905" }
    ]
  },
  "id": 16
}