Adobe Suite Lr Service API

openapi: 3.2.0
info:
  title: Adobe Lightroom Lr Service API
  description: This is the API reference documentation for Firefly's Lightroom API.
  license:
    name: Adobe Creative API License
    url: https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf
  version: '1.0'
servers:
- url: https://image.adobe.io
  description: Adobe Lightroom Production Server.
  variables: {}
security:
- AccessToken: []
  X-Api-Key: []
tags:
- name: LrService
paths:
  /lrService/autoStraighten:
    post:
      summary: Auto-straighten
      description: Auto-straighten an image by applying the Auto Upright transformation.
      operationId: autoStraightenImage
      x-ffs-async-job: 'true'
      x-ffs-job-status-fetcher: lrJobStatus
      requestBody:
        description: Request body for the auto straighten operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoStraightenImageRequest'
            examples:
              default:
                summary: Example request
                value:
                  inputs:
                    href: https://storage.example.com/source-image.jpg
                    storage: external
                  options:
                    uprightMode: auto
                    constrainCrop: true
                  outputs:
                  - href: https://storage.example.com/output-image.jpg
                    storage: external
                    type: image/jpeg
        required: true
      responses:
        '202':
          $ref: '#/components/responses/JobAccepted'
        '400':
          $ref: '#/components/responses/InputValidationErrorResponse'
        '402':
          $ref: '#/components/responses/TrialLimitExceededErrorResponse'
        '403':
          $ref: '#/components/responses/JobErrorForbidden'
        '404':
          $ref: '#/components/responses/JobErrorNotFound'
        '409':
          $ref: '#/components/responses/JobErrorUnableToUpload'
        '410':
          $ref: '#/components/responses/JobErrorAssetLinkInvalid'
      deprecated: true
      tags:
      - LrService
  /lrService/autoTone:
    post:
      summary: Auto-tone
      description: Automatically correct exposure, contrast, sharpness, and saturation on an image.
      operationId: applyAutoTone
      x-ffs-async-job: 'true'
      x-ffs-job-status-fetcher: lrJobStatus
      requestBody:
        description: Request body for the auto tone operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyAutoToneRequest'
            examples:
              default:
                summary: Example request
                value:
                  inputs:
                    href: https://storage.example.com/source-image.jpg
                    storage: external
                  outputs:
                  - href: https://storage.example.com/output-image.jpg
                    storage: external
                    type: image/jpeg
        required: true
      responses:
        '202':
          $ref: '#/components/responses/JobAccepted'
        '400':
          $ref: '#/components/responses/InputValidationErrorResponse'
        '402':
          $ref: '#/components/responses/TrialLimitExceededErrorResponse'
        '403':
          $ref: '#/components/responses/JobErrorForbidden'
        '404':
          $ref: '#/components/responses/JobErrorNotFound'
        '409':
          $ref: '#/components/responses/JobErrorUnableToUpload'
        '410':
          $ref: '#/components/responses/JobErrorAssetLinkInvalid'
      deprecated: true
      tags:
      - LrService
  /lrService/edit:
    post:
      summary: Apply Lightroom edits
      description: Apply one or more Lightroom edits (exposure, contrast, sharpness, saturation) to an image.
      operationId: applyEdits
      x-ffs-async-job: 'true'
      x-ffs-job-status-fetcher: lrJobStatus
      requestBody:
        description: Request body for the edit operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyEditsRequest'
            examples:
              default:
                summary: Example request
                value:
                  inputs:
                    source:
                      href: https://storage.example.com/source-image.jpg
                      storage: external
                  options:
                    Exposure: 0.5
                    Contrast: 10
                  outputs:
                  - href: https://storage.example.com/output-image.jpg
                    storage: external
                    type: image/jpeg
        required: true
      responses:
        '202':
          $ref: '#/components/responses/JobAccepted'
        '400':
          $ref: '#/components/responses/InputValidationErrorResponse'
        '402':
          $ref: '#/components/responses/TrialLimitExceededErrorResponse'
        '403':
          $ref: '#/components/responses/JobErrorForbidden'
        '404':
          $ref: '#/components/responses/JobErrorNotFound'
        '409':
          $ref: '#/components/responses/JobErrorUnableToUpload'
        '410':
          $ref: '#/components/responses/JobErrorAssetLinkInvalid'
      deprecated: true
      tags:
      - LrService
  /lrService/presets:
    post:
      summary: Apply Lightroom presets
      description: Apply one or more XMP Lightroom presets to the given image, by using the given preset XMP file(s).
      operationId: applyPreset
      x-ffs-async-job: 'true'
      x-ffs-job-status-fetcher: lrJobStatus
      requestBody:
        description: Request body for the presets operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyPresetRequest'
            examples:
              default:
                summary: Example request
                value:
                  inputs:
                    source:
                      href: https://storage.example.com/source-image.jpg
                      storage: external
                    presets:
                    - href: https://storage.example.com/preset.xmp
                      storage: external
                  outputs:
                  - href: https://storage.example.com/output-image.jpg
                    storage: external
                    type: image/jpeg
        required: true
      responses:
        '202':
          $ref: '#/components/responses/JobAccepted'
        '400':
          $ref: '#/components/responses/InputValidationErrorResponse'
        '402':
          $ref: '#/components/responses/TrialLimitExceededErrorResponse'
        '403':
          $ref: '#/components/responses/JobErrorForbidden'
        '404':
          $ref: '#/components/responses/JobErrorNotFound'
        '409':
          $ref: '#/components/responses/JobErrorUnableToUpload'
        '410':
          $ref: '#/components/responses/JobErrorAssetLinkInvalid'
      deprecated: true
      tags:
      - LrService
  /lrService/xmp:
    post:
      summary: Add XMP to image
      description: Apply XMP-based Lightroom preset to an image. XMP content is passed inline to the API.
      operationId: applyPresetFromXmpContent
      x-ffs-async-job: 'true'
      x-ffs-job-status-fetcher: lrJobStatus
      requestBody:
        description: Request body for the XMP operation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyPresetFromXmpContentRequest'
            examples:
              default:
                summary: Example request
                value:
                  inputs:
                    source:
                      href: https://storage.example.com/source-image.jpg
                      storage: external
                  options:
                    xmp: '{your_xmp_content}'
                  outputs:
                  - href: https://storage.example.com/output-image.jpg
                    storage: external
                    type: image/jpeg
        required: true
      responses:
        '202':
          $ref: '#/components/responses/JobAccepted'
        '400':
          $ref: '#/components/responses/InputValidationErrorResponse'
        '402':
          $ref: '#/components/responses/TrialLimitExceededErrorResponse'
        '403':
          $ref: '#/components/responses/JobErrorForbidden'
        '404':
          $ref: '#/components/responses/JobErrorNotFound'
        '409':
          $ref: '#/components/responses/JobErrorUnableToUpload'
        '410':
          $ref: '#/components/responses/JobErrorAssetLinkInvalid'
      deprecated: true
      tags:
      - LrService
  /lrService/status/{jobId}:
    get:
      summary: Get status
      description: Get job status of a Lightroom job.
      operationId: lrJobStatus
      x-ffs-status-fetcher: 'true'
      x-ffs-job-name: LrAsyncJob
      parameters:
      - name: jobId
        in: path
        description: Identifier of the job to get status for.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Job Status
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LrJobApiResponse'
              examples:
                jobSucceeded:
                  summary: Job succeeded
                  value:
                    jobId: ff7b0f8e-47f3-4d8f-9a8b-7a9f9b2f4c42
                    created: '2024-01-15T10:30:00.000Z'
                    modified: '2024-01-15T10:30:05.000Z'
                    outputs:
                    - input: /path/to/source.jpg
                      status: succeeded
                      _links:
                        self:
                          href: https://storage.example.com/result.jpg
                          storage: external
                    _links:
                      self:
                        href: https://image.adobe.io/lrService/status/ff7b0f8e-47f3-4d8f-9a8b-7a9f9b2f4c42
      deprecated: true
      tags:
      - LrService
components:
  schemas:
    JobError:
      title: JobError
      type: object
      properties:
        type:
          type: string
          description: Type of the error.
        code:
          type: string
          description: The error code.
        title:
          type: string
          description: Description of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
          description: Details of the error returned.
      description: Any errors reported for the requested output.
    LrOutputDetails:
      title: LrOutputDetails
      type: object
      required:
      - href
      - storage
      - type
      properties:
        href:
          type: string
          description: Pre-signed POST URL to the output file.
        storage:
          $ref: '#/components/schemas/StorageType'
        type:
          $ref: '#/components/schemas/ImageFormatType'
        overwrite:
          type: boolean
          default: true
          description: Determines if the output file should be overwritten if it already exists. This flag is used only for Adobe cloud storage.
        quality:
          maximum: 12
          minimum: 1
          type: integer
          default: 12
          description: Quality of the JPEG outputs (will be ignored for other output types). Ranges from 1 to 12, with 12 as the highest quality.
    StorageType:
      title: StorageType
      enum:
      - external
      - azure
      - dropbox
      type: string
      description: Storage location.
    AutoStraightenImageRequest:
      title: AutoStraightenImageRequest
      type: object
      required:
      - inputs
      - outputs
      properties:
        inputs:
          $ref: '#/components/schemas/StorageDetails'
        options:
          $ref: '#/components/schemas/AutoStraightOptions'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/LrOutputDetails'
          description: Only a single output is supported currently.
    ApplyPresetInput:
      title: ApplyPresetInput
      type: object
      required:
      - source
      - presets
      properties:
        source:
          $ref: '#/components/schemas/StorageDetails'
        presets:
          type: array
          items:
            $ref: '#/components/schemas/StorageDetails'
          description: An array describing the list of presets to apply. The preset objects will be one of 'external', 'azure', or 'dropbox'.
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        name:
          type: string
          description: Parameter name.
        reason:
          type: string
          description: Reason for the error.
      description: Details of the error returned.
    Links:
      title: Links
      type: object
      properties:
        self:
          $ref: '#/components/schemas/StorageDetails'
    SelfLink:
      title: SelfLink
      type: object
      description: Self link for the job status.
      properties:
        href:
          type: string
          description: Job Status URL.
    JobStatusLinkResponse:
      title: JobStatusLinkResponse
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/JobStatusLink'
    TrialLimitExceededError:
      title: TrialLimitExceededError
      type: object
      properties:
        type:
          type: string
          description: Type of the error.
        code:
          type: string
          description: The error code.
        title:
          type: string
          description: Description of the error.
        details:
          type: string
          description: Details of the error returned.
          default: You have exceeded the limit for the free trial. To subscribe and get more API calls, check out our pricing page at https://developer.adobe.com/photoshop/api/pricing/
      description: Any errors reported for the requested output.
    ApplyPresetXmpOptions:
      title: ApplyPresetXmpOptions
      description: Options for applying a preset XMP to an image.
      type: object
      required:
      - xmp
      properties:
        xmp:
          type: string
          description: The XMP to apply.
        orientation:
          maximum: 8.0
          minimum: 1.0
          type: number
          description: The combination of flip and/or rotate to apply.
    ApplyPresetFromXmpContentRequest:
      title: ApplyPresetFromXmpContentRequest
      type: object
      required:
      - inputs
      - options
      - outputs
      properties:
        inputs:
          $ref: '#/components/schemas/ApplyPresetXmpInput'
        options:
          $ref: '#/components/schemas/ApplyPresetXmpOptions'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/LrOutputDetails'
          description: Apply preset XMP output parameters.
    JobStatusLink:
      title: Job Status Link
      type: object
      properties:
        self:
          $ref: '#/components/schemas/SelfLink'
    ImageFormatType:
      title: ImageFormatType
      enum:
      - image/jpeg
      - image/png
      - image/x-adobe-dng
      - application/rdf+xml
      type: string
      description: Desired output image format.
    InputValidationErrorDetails:
      title: InputValidationErrorDetails
      type: object
      properties:
        allowedValues:
          type: string
          description: Comma-separated list of allowed values for the input parameter.
          default: adobe, external, dropbox, azure
        reason:
          type: string
          description: Reason for the error.
      description: Details of the input validation error returned.
    LrJobApiResponse:
      title: Lightroom Job Status Response
      type: object
      properties:
        jobId:
          type: string
          description: The job's ID requested.
        created:
          type: string
          description: Created timestamp of the job.
        modified:
          type: string
          description: Modified timestamp of the job.
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutputDetails'
          description: Output parameters for the job.
        _links:
          $ref: '#/components/schemas/JobStatusLink'
    InputValidationError:
      title: InputValidationError
      type: object
      properties:
        type:
          type: string
          description: Type of the error.
        code:
          type: string
          description: The error code.
        title:
          type: string
          description: Description of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/InputValidationErrorDetails'
          description: Details of the error returned.
      description: Any errors reported for the requested output.
    JobOutputDetails:
      title: JobOutputDetails
      type: object
      properties:
        input:
          type: string
          description: The original input file path.
        status:
          $ref: '#/components/schemas/JobStatus'
        _links:
          $ref: '#/components/schemas/Links'
        details:
          type: string
          description: Description of the exact error that is reported by the requested job. Will appear in the response only if there is an error.
    UprightMode:
      title: UprightMode
      enum:
      - auto
      - full
      - level
      - vertical
      type: string
      description: The upright mode to use. If you have the options block, then this is a required field. If options block is not specified, then the appropriate upright mode will automatically be selected.
    ApplyPresetRequest:
      title: ApplyPresetRequest
      type: object
      required:
      - inputs
      - outputs
      properties:
        inputs:
          $ref: '#/components/schemas/ApplyPresetInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/LrOutputDetails'
          description: Apply preset output parameters.
    ApplyPresetXmpInput:
      title: ApplyPresetXmpInput
      type: object
      required:
      - source
      properties:
        source:
          $ref: '#/components/schemas/StorageDetails'
    ApplyAutoToneRequest:
      title: ApplyAutoToneRequest
      type: object
      required:
      - inputs
      - outputs
      properties:
        inputs:
          $ref: '#/components/schemas/StorageDetails'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/LrOutputDetails'
          description: Only a single output is supported currently.
    EditOptions:
      title: EditOptions
      type: object
      properties:
        Contrast:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Saturation:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        VignetteAmount:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Vibrance:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Highlights:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Shadows:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Whites:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Blacks:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Clarity:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Dehaze:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Texture:
          maximum: 100.0
          minimum: -100.0
          type: integer
          format: int32
        Sharpness:
          maximum: 150.0
          minimum: 0.0
          type: integer
          format: int32
        ColorNoiseReduction:
          maximum: 100.0
          minimum: 0.0
          type: integer
          format: int32
        NoiseReduction:
          maximum: 100.0
          minimum: 0.0
          type: integer
          format: int32
        SharpenDetail:
          maximum: 100.0
          minimum: 0.0
          type: integer
          format: int32
        SharpenEdgeMasking:
          maximum: 10.0
          minimum: 0.0
          type: integer
          format: int32
        Exposure:
          maximum: 5.0
          minimum: -5.0
          type: number
        SharpenRadius:
          maximum: 3.0
          minimum: 0.5
          type: number
        WhiteBalance:
          $ref: '#/components/schemas/WhiteBalance'
    WhiteBalance:
      title: WhiteBalance
      description: White balance settings.
      enum:
      - As Shot
      - Auto
      - Cloudy
      - Custom
      - Daylight
      - Flash
      - Fluorescent
      - Shade
      - Tungsten
      type: string
    ApplyEditsRequest:
      title: ApplyEditsRequest
      type: object
      required:
      - inputs
      - options
      - outputs
      properties:
        inputs:
          type: object
          description: A hash describing an input image to edit. The input object will be one of 'external', 'azure', or 'dropbox'.
          required:
          - source
          properties:
            source:
              $ref: '#/components/schemas/StorageDetails'
        options:
          $ref: '#/components/schemas/EditOptions'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/LrOutputDetails'
          description: Edit photo output parameters.
    JobStatus:
      title: JobStatus
      enum:
      - pending
      - running
      - succeeded
      - failed
      type: string
      description: Status of the job.
    AutoStraightOptions:
      title: AutoStraightOptions
      required:
      - uprightMode
      type: object
      properties:
        uprightMode:
          $ref: '#/components/schemas/UprightMode'
        constrainCrop:
          type: boolean
          description: If the straightened image should be constrained and cropped to remove all blank edges around an image.
          default: true
    StorageDetails:
      title: StorageDetails
      type: object
      required:
      - href
      - storage
      properties:
        href:
          type: string
          description: Pre-signed GET URL for the source asset.
        storage:
          $ref: '#/components/schemas/StorageType'
      description: File on Adobe's cloud or an external service (like AWS S3, Azure, Dropbox).
  responses:
    JobAccepted:
      description: Accepted
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobStatusLinkResponse'
          examples:
            jobAccepted:
              summary: Job accepted
              value:
                _links:
                  self:
                    href: https://image.adobe.io/lrService/status/ff7b0f8e-47f3-4d8f-9a8b-7a9f9b2f4c42
    JobErrorUnableToUpload:
      description: Unable To Upload Asset
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobError'
          examples:
            unableToUpload:
              summary: Unable to upload asset
              value:
                type: error
                code: upload_failed
                title: Unable To Upload Asset
                details:
                - name: output
                  reason: Unable to upload the output asset.
    TrialLimitExceededErrorResponse:
      description: Trial Limit Exceeded Error
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrialLimitExceededError'
          examples:
            limitExceeded:
              summary: Trial limit exceeded
              value:
                type: trial_limit_exceeded
                code: limit_exceeded
                title: Trial Limit Exceeded Error
                details: You have exceeded the limit for the free trial.
    JobErrorForbidden:
      description: Forbidden
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobError'
          examples:
            forbidden:
              summary: Forbidden
              value:
                type: error
                code: forbidden
                title: Forbidden
                details:
                - name: request
                  reason: Access denied for this resource.
    JobErrorAssetLinkInvalid:
      description: Asset Link Invalid
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobError'
          examples:
            assetLinkInvalid:
              summary: Asset link invalid
              value:
                type: error
                code: invalid_asset_link
                title: Asset Link Invalid
                details:
                - name: href
                  reason: The provided asset link is invalid or expired.
    JobErrorNotFound:
      description: Requested Resource Was Not Found
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JobError'
          examples:
            notFound:
              summary: Resource not found
              value:
                type: error
                code: not_found
                title: Requested Resource Was Not Found
                details:
                - name: resource
                  reason: The requested resource was not found.
    InputValidationErrorResponse:
      description: Input Validation Error
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InputValidationError'
          examples:
            invalidStorage:
              summary: Invalid input
              value:
                type: validation_error
                code: invalid_input
                title: Input Validation Error
                details:
                - allowedValues: adobe, external, dropbox, azure
                  reason: Invalid storage type provided.
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: The Adobe-generated access token, S2S format.
    X-Api-Key:
      type: apiKey
      name: x-api-key
      in: header
      description: The client ID for authentication.