Album sources API

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

• GET /album-sources — List album source links
• POST /album-sources/resolve — Resolve album sources
• DELETE /album-sources/{id} — Delete an album source link
• PATCH /album-sources/{id} — Update an album source link
• DELETE /album-sources/{id}/assets — Remove assets through an album source link
• POST /album-sources/{id}/assets — Add assets through an album source link

List album source links

GET /api/album-sources

List your phone albums and folders linked to server albums.

Authentication: API key. Permission: album.read.

Responses

Field definitions: AlbumSourceLinkResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AlbumSourceLinkResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Resolve album sources

POST /api/album-sources/resolve

For each phone album or folder, return its linked server album; otherwise link it to your oldest album with the same trimmed, case-insensitive name, or create an album. Never creates two albums for one source, also with several devices resolving at once.

Authentication: API key. Permission: album.create.

Request body

Required.

Field definitions: AlbumSourceResolveDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AlbumSourceResolveDto"
    }
  }
}

Responses

Field definitions: AlbumSourceResolveResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AlbumSourceResolveResponseDto"
        }
      }
    },
    "description": ""
  }
}

Delete an album source link

DELETE /api/album-sources/{id}

Unlink the phone album or folder. The server album and its photos are kept.

Authentication: API key. Permission: album.update.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Update an album source link

PATCH /api/album-sources/{id}

Record the source’s new name on the phone, renaming the server album only while its name still equals the name it last followed. An optional sourceId re-keys the link (409 when another link holds it).

Authentication: API key. Permission: album.update.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: AlbumSourceUpdateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AlbumSourceUpdateDto"
    }
  }
}

Responses

Field definitions: AlbumSourceUpdateResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AlbumSourceUpdateResponseDto"
        }
      }
    },
    "description": ""
  }
}

Remove assets through an album source link

DELETE /api/album-sources/{id}/assets

Take out only the album memberships this link's sync added. Assets are never deleted, trashed or hidden, and memberships added by hand or still recorded by another link stay.

Authentication: API key. Permission: albumAsset.delete.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Add assets through an album source link

POST /api/album-sources/{id}/assets

Add assets to the linked album and record that the sync added them. Idempotent; an asset already in the album by hand is reported as a duplicate and never recorded.

Authentication: API key. Permission: albumAsset.create.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}