Adobe Suite Albums API

openapi: 3.2.0
info:
  description: Lightroom API Documentation, made available through [adobe.io](https://developer.adobe.com). API Change Logs are available [here](https://developer.adobe.com/lightroom/lightroom-api-docs/release-notes/).
  version: 1.0.0
  title: Lightroom API Documentation Albums API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://lr.adobe.io/
tags:
- name: Albums
  description: Information for albums, which contain references to zero or more assets.
paths:
  /v2/catalogs/{catalog_id}/albums/{album_id}:
    put:
      tags:
      - Albums
      summary: Create album
      description: Create a new album.
      operationId: createAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Client-generated Lightroom unique identifier for the new album.
        required: true
        schema:
          type: string
      requestBody:
        description: Initial album metadata and information.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subtype:
                  type: string
                  enum:
                  - project
                  - project_set
                serviceId:
                  type: string
                  description: The API Key (client identifier) of the service creating the album.
                payload:
                  $ref: '#/components/schemas/albumPayload'
      responses:
        '201':
          description: Created
        '400':
          description: The request failed due to an invalid input
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvaildRequestJSON'
                - $ref: '#/components/schemas/InvaildRequestPayload'
              examples:
                InvaildRequestJSON:
                  $ref: '#/components/examples/InvaildRequestJSONExample'
                InvaildRequestPayload:
                  $ref: '#/components/examples/InvaildRequestPayloadExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ForbiddenKeyError'
                - $ref: '#/components/schemas/ResourceExistsError'
              examples:
                InvalidApiKey:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                ResourceExists:
                  $ref: '#/components/examples/AlbumResourceExistsErrorExample'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
    get:
      tags:
      - Albums
      summary: Get album
      description: Read a album.
      operationId: readAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Client-generated Lightroom unique identifier for the new album.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  base:
                    type: string
                    description: Base URL that can be prepended to the 'href' values in the 'links' to produce fully qualified URLs for future queries.
                  id:
                    $ref: '#/components/schemas/uuid'
                  type:
                    type: string
                    enum:
                    - album
                  subtype:
                    type: string
                  created:
                    $ref: '#/components/schemas/utcDateTime'
                  updated:
                    $ref: '#/components/schemas/utcDateTime'
                  links:
                    type: object
                  payload:
                    type: object
                example:
                  base: <base_url>/v2/catalogs/<catalog_id>/
                  id: <album_id>
                  type: album
                  subtype: <album_subtype>
                  created: <created_date>
                  updated: <updated_date>
                  payload:
                    name: <album_name>
                    cover:
                      id: <cover_asset_id>
                    parent:
                      id: <parent_album_id>
                  links:
                    self:
                      href: albums/<album_id>
                    /rels/album_assets:
                      href: albums/<album_id>/assets?embed=asset
                    /rels/parent_album:
                      href: albums/<parent_album_id>
                    /rels/cover_asset:
                      href: assets/<cover_asset_id>
                    /rels/rendition_type/320:
                      href: assets/<cover_asset_id>/renditions/320
                    /rels/rendition_type/640:
                      href: assets/<cover_asset_id>/renditions/640
                    /rels/rendition_type/1280:
                      href: assets/<cover_asset_id>/renditions/1280
                    /rels/rendition_type/2048:
                      href: assets/<cover_asset_id>/renditions/2048
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidAPIKeyError'
                - $ref: '#/components/schemas/AccessForbiddenError'
                - $ref: '#/components/schemas/OperationNotPermittedError'
              examples:
                ForbiddenKeyError:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                AccessForbiddenError:
                  $ref: '#/components/examples/AccessForbiddenExample'
                OperationNotPermittedError:
                  $ref: '#/components/examples/OperationNotPermittedExample'
        '404':
          description: The request failed because the resource being requested does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                ResourceNotFound:
                  $ref: '#/components/examples/AlbumNotFoundExample'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
    post:
      tags:
      - Albums
      summary: Update album
      description: Update an existing album. The existing album should be created via the same client app and of subtype project or project_set.
      operationId: updateAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Identifier for the album.
        required: true
        schema:
          type: string
      requestBody:
        description: Album metadata and information to be updated.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payload:
                  $ref: '#/components/schemas/albumPayload'
      responses:
        '204':
          description: No Content
        '400':
          description: The request failed due to an invalid input
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvaildRequestJSON'
                - $ref: '#/components/schemas/InvaildRequestPayload'
              examples:
                InvaildRequestJSON:
                  $ref: '#/components/examples/InvaildRequestJSONExample'
                InvaildRequestPayload:
                  $ref: '#/components/examples/InvaildRequestPayloadExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidAPIKeyError'
                - $ref: '#/components/schemas/AccessForbiddenError'
                - $ref: '#/components/schemas/OperationNotPermittedError'
              examples:
                ForbiddenKeyError:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                AccessForbiddenError:
                  $ref: '#/components/examples/AccessForbiddenExample'
                OperationNotPermittedError:
                  $ref: '#/components/examples/OperationNotPermittedExample'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
    delete:
      tags:
      - Albums
      summary: Delete album
      description: Delete an existing album. The existing album should be created via the same client app and of subtype project or project_set.
      operationId: deleteAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Identifier for the album.
        required: true
        schema:
          type: string
      - name: child_albums
        in: query
        description: 'This parameter when passed with a value, for example: true would delete all the child albums as well of the album specified. The deletion of child albums will be done asynchronously.'
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/InvaildRequestJSON'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidAPIKeyError'
                - $ref: '#/components/schemas/AccessForbiddenError'
                - $ref: '#/components/schemas/OperationNotPermittedError'
              examples:
                ForbiddenKeyError:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                AccessForbiddenError:
                  $ref: '#/components/examples/AccessForbiddenExample'
                OperationNotPermittedError:
                  $ref: '#/components/examples/OperationNotPermittedExample'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
  /v2/catalogs/{catalog_id}/albums:
    get:
      tags:
      - Albums
      summary: Retrieve albums
      description: Retrieve a list of existing albums.
      operationId: getAlbums
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: subtype
        in: query
        description: Comma-separated list of subtypes to enumerate. Subtype can be one of 'project' or 'project_set'.
        schema:
          type: string
      - name: name_after
        in: query
        description: UTF-8 string representing the name of the album that should precede the current page of results. In other words, the response will contain result with names greater than the 'name_after' value using standard string ordering relations.
        schema:
          type: string
      - name: limit
        in: query
        description: Number of albums to return. Default value is 100. Please note that the response may contain more than 'limit' number of albums returned if multiple albums at the 'limit' boundary have the same name_after.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  base:
                    type: string
                    description: Base URL that can be prepended to the 'href' values in the 'links' to produce fully qualified URLs for future queries.
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          $ref: '#/components/schemas/uuid'
                        created:
                          $ref: '#/components/schemas/utcDateTime'
                        updated:
                          $ref: '#/components/schemas/utcDateTime'
                        type:
                          type: string
                          enum:
                          - album
                        subtype:
                          type: string
                          enum:
                          - project
                          - project_set
                        serviceId:
                          type: string
                          description: The API Key (client identifier) of the service affiliated with the album.
                        payload:
                          $ref: '#/components/schemas/albumPayload'
                        links:
                          type: object
        '400':
          description: The request failed due to an invalid resource identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvaildRequestGUID'
              examples:
                InvaildRequestGUID:
                  $ref: '#/components/examples/CatalogInvaildRequestGUIDExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidAPIKeyError'
                - $ref: '#/components/schemas/AccessForbiddenError'
              examples:
                ForbiddenKeyError:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                AccessForbiddenError:
                  $ref: '#/components/examples/AccessForbiddenExample'
        '404':
          description: The request failed because the resource being requested does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                ResourceNotFound:
                  $ref: '#/components/examples/AlbumNotFoundExample'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
  /v2/catalogs/{catalog_id}/albums/{album_id}/assets:
    put:
      tags:
      - Albums
      summary: Add assets to album
      description: Add many assets to the album. Note that there is no default defined order/position for the asset in the album. A payload may be provided with cover, order, and any other data allowed in the data model. If the asset already exists in the album and the cover field is supplied, then no error is thrown but only the cover update is applied and other entries in the payload are completely ignored. In all other cases trying to add an asset to an album that is already in the album will return an error. Limited to 50 assets per API call. Returns http status 201 if at least one asset was added to the album. If all assets could not be added, http status 403 is returned. Individual error codes are returned for each asset in the response body.
      operationId: addAssetsToAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Identifier of the album.
        required: true
        schema:
          type: string
      requestBody:
        description: Album asset metadata and information.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resources:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        $ref: '#/components/schemas/uuid'
                        description: UUID of the asset to be added to the album.
                      payload:
                        type: object
                        properties:
                          cover:
                            type: boolean
                            description: Whether this asset should be used as the album cover.
                          order:
                            $ref: '#/components/schemas/lex64SortOrderString'
                          publishInfo:
                            type: object
                            properties:
                              servicePayload:
                                type: string
                                description: Album asset metadata, unique to the service, encapsulated as a single string with a maximum length of 1024 characters.
                              remoteId:
                                type: string
                                description: Identifier for the album asset that is unique to the publishing service.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  base:
                    type: string
                    description: Base URL that can be prepended to the 'href' values in the 'links' to produce fully qualified URLs for future queries.
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          $ref: '#/components/schemas/uuid'
                        href:
                          type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          $ref: '#/components/schemas/uuid'
                        http_status:
                          type: integer
                        code:
                          type: integer
                        description:
                          type: string
                        subtype:
                          type: string
                        errors:
                          type: object
                          properties:
                            asset:
                              type: array
                              items:
                                type: string
        '400':
          description: The request failed due to an invalid resource identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvaildRequestGUID'
              examples:
                InvaildRequestGUID:
                  $ref: '#/components/examples/AlbumInvaildRequestGUIDExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The request failed due to insufficient permissions.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidAPIKeyError'
                - $ref: '#/components/schemas/AccessForbiddenError'
              examples:
                ForbiddenKeyError:
                  $ref: '#/components/examples/ForbiddenKeyExample'
                AccessForbiddenError:
                  $ref: '#/components/examples/AccessForbiddenExample'
        '404':
          description: The request failed because the resource being requested does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                ResourceNotFound:
                  $ref: '#/components/examples/AlbumNotFoundExample'
        '503':
          description: The request failed because the service is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ServiceUnavailable'
                - $ref: '#/components/schemas/MaintenanceError'
              examples:
                ServiceUnavailable:
                  $ref: '#/components/examples/ServiceUnavailableExample'
                MaintenanceError:
                  $ref: '#/components/examples/MaintenanceErrorExample'
    get:
      tags:
      - Albums
      summary: List assets of an album
      description: Lists assets in an album. The assets in an album are returned sorted on either order if order* parameters are used. The assets in an album are returned sorted on captured date if order* parameters are not used and captured* parameters are used. Please note that the created and updated dates for Album asset documents will be returned as "0000-00-00T00:00:00". Successful response may also return invalid flag in the rendition link for the asset. A rendition becomes invalid when an asset is edited after rendition has been generated. New renditions (only 2560 and fullsize) can be generated via Generate Renditions API. The read xmp/develop link in the response will have the invalid flag as true if asset with SHA256 has been created but external xmp/develop has not been uploaded yet.
      operationId: listAssetsOfAlbum
      parameters:
      - name: X-API-Key
        in: header
        description: Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer [token] - User access token of an authenticated Lightroom customer
        required: true
        schema:
          type: string
      - name: catalog_id
        in: path
        description: Identifier of the catalog containing the album.
        required: true
        schema:
          type: string
      - name: album_id
        in: path
        description: Identifier of the album.
        required: true
        schema:
          type: string
      - name: captured_before
        in: query
        description: Used to request assets captured before a given time. captured_before will be found in the "links.next.href" link. If no links.next is included in a listing response, this is a hint from the server that there are no assets in the catalog with a date captured_before the last asset in the list (the client has reached the "bottom" of the list). captured_before may not be used in conjunction with captured_after.
        schema:
          type: string
      - name: captured_after
        in: query
        description: 'Used to request assets captured after a given time. captured_after will be found in the "links.prev.href" link. If no links.prev is included in a listing response, this is a hint from the server that there are no assets in the catalog with a date captured_after the first asset in the list (the client has reached the "top" of the list). Note: assets imported without a captureDate payload property default to the value "0000-00-00T00:00:00". To list these assets set captured_after to "-0001-12-31T23:59:59". captured_after may not be used in conjunction with captured_before.'
        schema:
          type: string
      - name: order_after
        in: query
        description: 'Used to request assets having order value greater than specified value. Next and previous pages will be found in the "links.next.href" and "links.prev.href" links respectively. If next/prev link is missing, it indicates that there is no next/prev page. Some rules about using order_after: 1) Specify "-" to get the first page. 2) Can be max of 1024 characters. 3) Should be a lex64 sort order string with characters in the set: [-0-9A-Z_a-z] with sort order in the same sequence as in the set [-0-9A-Z_a-z]. 4) captured_before cannot be used with order_after 5) captured_after can be used only if order_after==""'
        schema:
          type: string
      - name: order_before
        in: query
        description: 'Used to request assets having order value lesser than specified value. Next and previous pages will be found in the "links.next.href" and "links.prev.href" links respectively. If next/prev link is missing, it indicates that there is no next/prev page. Some rules about using order_before: 1) Specify order_before as "" and captured_before as a future date to get the first page. 2) Can be max of 1024 characters. 3) Should be a lex64 sort order string with characters in the set: [-0-9A-Z_a-z] with sort order in the same sequence as in the set [-0-9A-Z_a-z]. 4) captured_after cannot be used with order_before 5) captured_before can be used only if order_before==""'
        schema:
          type: string
      - name: limit
        in: query
        description: Number of assets to return. Default value is 100. Maximum is 500. Please note that the response may contain more than 'limit' number of assets returned if the assets at the 'limit' boundary has the same capture_date. For example if there are 5 assets in a catalog and the 3rd, 4th and 5th assets all have the same capture dates the response will contain all 5 assets whether 'limit' is 3, 4 or 5.
        schema:
          type: integer
      - name: hide_stacked_assets
        in: query
        description: To show or hide assets inside stacks in the catalog. If hide_stacked_assets is passed as true, assets inside stacks won't be returned. Default value is false.
        schema:
          type: boolean
      - name: subtype
        in: query
        description: Semi-colon separated asset subtype values.
        schema:
          type: string
      - name: flag
        in: query
        description: Semi-colon separated review flag values used to filter assets returned. Can be combined with subtype filter. Valid values for flags are 'pick', 'unflagged' and 'reject'. This parameter cannot be used along with album_filters parameter. Default behavior is to display all assets.
        schema:
          type: string
      - name: embed
        in: query
        description: Semicolon-delimited lis

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-albums-api-openapi.yml