redocly logoAPI docs by Redocly

Lightroom API Documentation (1.0.0)

License: Apache 2.0

Lightroom API Documentation, made available through adobe.io. API Change Logs are available here.

Find out more about Lightroom

Health

Lightroom Services status.

Lightroom Services health check

Will return the Lightroom server version ID (a hexadecimal value not guaranteed to be sequential) if the services are up.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Responses

Response samples

Content type
application/json
{
  • "version": "string"
}

Accounts

Account information for the authenticated user.

Retrieve the user account metadata

An account is associated with each Adobe customer and contains the personal information and subscription status. This information can be obtained through the authentication APIs and is provided by Lightroom as a convenience.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "base": "https://lr.adobe.io/",
  • "id": "96e656e3812b4c2fb670fa74b6a7ad74",
  • "type": "account",
  • "created": "2017-09-12T17:22:41.751746Z",
  • "updated": "2019-02-02T17:17:39.663862Z",
  • "email": "customer@domain.com",
  • "full_name": "Adobe Customer",
  • "first_name": "Adobe",
  • "last_name": "Customer",
  • "wcd_guid": "6CEE5CFE464CC743992017B8",
  • "country": "US",
  • "config": {
    },
  • "entitlement": {
    }
}

Catalogs

Catalog information for the authenticated user.

Retrieve the user catalog metadata

A catalog is the topmost container of resources for a user. Each catalog contains zero or more assets, albums, or other resources.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "created": "2019-07-02T15:16:13.556610Z",
  • "updated": "2019-07-02T15:26:42.838366Z",
  • "base": "https://lr.adobe.io/v2/",
  • "id": "bf7337d9355c41b7875c9392f918362a",
  • "type": "catalog",
  • "subtype": "lightroom",
  • "payload": {
    },
  • "links": {
    }
}

Assets

Information for assets, typically images or videos.

Create asset

Create a new asset with initial metadata and import information.

path Parameters
catalog_id
required
string

Identifier of the catalog in which the asset will be created.

asset_id
required
string

Client-generated Lightroom unique identifier for the new asset.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Request Body schema: application/json

Initial asset metadata and import information.

subtype
string
Enum: "image" "video"
object

Responses

Request samples

Content type
application/json
{
  • "subtype": "image",
  • "payload": {
    }
}

Response samples

Content type
application/json
Example
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Get a catalog asset

Retrieves information about a single asset in a catalog that the caller owns. 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.

path Parameters
catalog_id
required
string

Identifier of the catalog

asset_id
required
string

Identifier of the asset

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
Example
{
  • "base": "<base_url>",
  • "id": "<asset_id>",
  • "type": "asset",
  • "subtype": "image",
  • "created": "<created_date>",
  • "updated": "<updated_date>",
  • "links": {
    },
  • "payload": {
    }
}

Retrieve assets

Retrieve a list of existing assets that caller owns. 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.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

query Parameters
updated_since
string

Starting timestamp

captured_before
string

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.

captured_after
string

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.

limit
integer

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.

sha256
string

SHA256 hash value of original file. Assets with a matching SHA256 hash will be returned. May be used in conjunction with subtype.

hide_stacked_assets
boolean

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.

subtype
string

Semi-colon separated asset subtype values.

asset_ids
string

Set of 1 - 100 comma separated asset_id values. Other parameters can not be used in conjunction with this parameter.

exclude
string

Used to request the list for different types of assets excluding incomplete or complete image and video assets. The valid values are "incomplete" and "complete". An image or video asset is considered to be complete if its proxy or original upload exists. An asset of subtypes profile, preset, camera_profile or lens_profile is considered complete if its original upload exists.

group
string

Semi-colon separated group values. Subtype parameter of "preset" or "profile" is required when using this parameter.

name
string

Semi-colon separated name values. Subtype parameter of "preset" or "profile" is required when using this parameter.

favorite
string

Favorite status, subtype parameter of "preset" is required when using this parameter.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
Example
{
  • "base": "<base_url>",
  • "resources": [
    ],
  • "links": {
    }
}

Create an asset original file

Create and upload an original file for the asset. Up to 200 MB may be uploaded per invocation, and larger files may be uploaded by calling this API multiple times with Content-Range headers for each part. When all parts are received the upload will be consolidated asynchronously. All partial uploads should include optional rendition type parameters to ensure the last part received has the necessary options for request post-processing.

path Parameters
catalog_id
required
string

Identifier of the catalog in which the asset will be created.

asset_id
required
string

Identifier of the asset to which the XMP settings are associated.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Content-Length
integer

Length in bytes of the content.

Content-Range
string

Byte range for the request, including first and last bytes and entity length as defined in RFC 2616. Should be included only when the data cannot be uploaded in a single call.

Content-Type
required
string

Content type. For jpeg assets, the only allowed type is 'image/jpeg'. For camera raw assets the type is 'application/octet-stream'. For video assets, the content-type is of the format video/* where * depends upon the video type and can contain only ASCII characters. Or the content-type of video can be application/octet-stream;video

Responses

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Generate renditions for an original file

Generate renditions for an original file asynchronously. Allowed rendition types are fullsize and 2560. Generated rendition will be deleted after 1 day automatically.

path Parameters
catalog_id
required
string

Identifier of the catalog in which the asset was created.

asset_id
required
string

Identifier of the asset for which rendition gets generated.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

X-Generate-Renditions
required
string

One or multiple of the supported rendition types separated by ','. Supported rendition types are : ['fullsize', '2560'].

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Content-Length
integer

Length in bytes of the content.

Responses

Response samples

Content type
application/json
{
  • "base": "<base_url>",
  • "links": {
    }
}

Get latest asset rendition

Get latest asset rendition of specified type. It returns 404 if rendition does not exist. It returns 404 in another case when rendition is invalid (only for rendition type 2560 and fullsize)

path Parameters
catalog_id
required
string

Identifier of the catalog in which asset exists.

asset_id
required
string

Identifier of the asset for which to fetch rendition.

rendition_type
required
string

One of the supported rendition types. Supported rendition types are : ['thumbnail2x', 'fullsize', '640', '1280', '2048', '2560'].

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
Example
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Create asset external xmp develop setting file

This API support two workflows. The first workflow is to upload external XMP develop settings file for the asset. Content-type header for this case is application/rdf+xml. The second workflow is to create an external XMP develop settings file by copying from another asset's external xmp develop setting file. Content-type header for this case is application/json.

path Parameters
catalog_id
required
string

Identifier of the catalog in which the asset will be created.

asset_id
required
string

Client-generated Lightroom unique identifier for the new asset.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Content-Length
required
integer

Content length, in bytes. Current maximum size is 200 Mb.

Content-Type
required
string

For uploading a new xmp/develop file content-type='application/rdf+xml' and for copying xmp/develop file from another asset content-type='application/json'

Request Body schema: application/json

The below request body example is for copying external xmp/develop file from another asset. (For upload external xmp/develop case the body will be a xml string. Eg. '<xml.../xml>')

file_href
string

External xmp/develop link of source asset.

Responses

Request samples

Content type
application/json
{
  • "file_href": "/v2/catalogs/{catalog_id}/assets/{source_asset_id}/xmp/develop"
}

Response samples

Content type
application/json
Example
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Get latest asset external xmp develop setting

Get latest asset external xmp develop setting file

path Parameters
catalog_id
required
string

Identifier of the catalog in which asset exists.

asset_id
required
string

Identifier of the asset for which to fetch rendition.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Albums

Information for albums, which contain references to zero or more assets.

Create album

Create a new album.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Client-generated Lightroom unique identifier for the new album.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Request Body schema: application/json

Initial album metadata and information.

subtype
string
Enum: "project" "project_set"
serviceId
string

The API Key (client identifier) of the service creating the album.

object (albumPayload)

Responses

Request samples

Content type
application/json
{
  • "subtype": "project",
  • "serviceId": "string",
  • "payload": {
    }
}

Response samples

Content type
application/json
Example
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Get album

Read a album.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Client-generated Lightroom unique identifier for the new album.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "base": "<base_url>/v2/catalogs/<catalog_id>/",
  • "id": "<album_id>",
  • "type": "album",
  • "subtype": "<album_subtype>",
  • "created": "<created_date>",
  • "updated": "<updated_date>",
  • "payload": {
    },
  • "links": {
    }
}

Update album

Update an existing album. The existing album should be created via the same client app and of subtype project or project_set.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Identifier for the album.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Request Body schema: application/json

Album metadata and information to be updated.

object (albumPayload)

Responses

Request samples

Content type
application/json
{
  • "payload": {
    }
}

Response samples

Content type
application/json
Example
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Delete album

Delete an existing album. The existing album should be created via the same client app and of subtype project or project_set.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Identifier for the album.

query Parameters
child_albums
string

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.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "code": 1005,
  • "description": "Input Validation Error"
}

Retrieve albums

Retrieve a list of existing albums.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

query Parameters
subtype
string

Comma-separated list of subtypes to enumerate. Subtype can be one of 'project' or 'project_set'.

name_after
string

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.

limit
integer

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.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "base": "string",
  • "resources": [
    ]
}

Add assets to album

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.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Identifier of the album.

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Request Body schema: application/json

Album asset metadata and information.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "base": "string",
  • "resources": [
    ],
  • "errors": [
    ]
}

List assets of an album

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.

path Parameters
catalog_id
required
string

Identifier of the catalog containing the album.

album_id
required
string

Identifier of the album.

query Parameters
captured_before
string

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.

captured_after
string

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.

order_after
string

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==""

order_before
string

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==""

limit
integer

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.

hide_stacked_assets
boolean

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.

subtype
string

Semi-colon separated asset subtype values.

flag
string

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.

embed
string

Semicolon-delimited list of additional data to include. When the list includes "asset", the asset subdocuments contains all the fields. Otherwise, only the id and self href link are returned in the asset subdocuments.

exclude
string

Used to request the list for different types of assets excluding incomplete or complete image and video assets. The valid values are "incomplete" and "complete". An image or video asset is considered to be complete if its proxy or original upload exists. An asset of subtypes profile, preset, camera_profile or lens_profile is considered complete if its original upload exists.

asset_ids
string

Set of 1 - 100 comma separated asset_id values. Other parameters can not be used in conjunction with this parameter.

album_filters
string

When album_filters is set to 'true', it filters out all the album assets based on the presentation filters set on the album. With this parameter, rejected assets always get filtered out irrespective of settings in presentation filters. Presentation filters are not applied when any value other than 'true' is set for album_filters. Default behavior is to display all assets. This parameter cannot be used along with flag parameter. no Response: 200 OK

header Parameters
X-API-Key
required
string

Client ID (API Key) which is subscribed to the Lightroom APIs through console.adobe.io

Authorization
required
string

Bearer [token] - User access token of an authenticated Lightroom customer

Responses

Response samples

Content type
application/json
{
  • "base": "<base_url>",
  • "album": {
    },
  • "resources": [
    ],
  • "links": {
    }
}