openapi: 3.1.0
info:
  title: Adobe Creative Suite Adobe Photoshop API
  description: >-
    The Adobe Photoshop API provides programmatic access to Photoshop image manipulation
    capabilities including automated editing, masking, compositing, layer management, and
    document operations. It enables developers to integrate Photoshop processing into workflows
    and applications without requiring a desktop installation. Operations are performed
    asynchronously and return a job ID for status polling.
  version: 1.0.0
  termsOfService: https://www.adobe.com/legal/terms.html
  contact:
    name: Adobe Developer Support
    url: https://developer.adobe.com/support/
  license:
    name: Adobe Developer Terms
    url: https://www.adobe.com/legal/developer-terms.html
servers:
- url: https://image.adobe.io
  description: Adobe Photoshop API production server
security:
- bearerAuth: []
tags:
- name: Artboard
  description: Artboard creation and management
- name: Cutout
  description: Background removal and masking operations
- name: Document
  description: Document-level operations
- name: Layers
  description: PSD layer management operations
- name: Mask
  description: Alpha mask creation operations
- name: Rendition
  description: Rendition and export operations
- name: Smart Object
  description: Smart object editing operations
- name: Status
  description: Asynchronous job status operations
- name: Text
  description: Text layer editing operations
paths:
  /sensei/cutout:
    post:
      operationId: removeBackground
      summary: Adobe Creative Suite Remove Background
      description: >-
        Removes the background from an image using Adobe Sensei AI. Accepts an input image
        stored in cloud storage and produces a cutout image with the background removed.
        The operation is asynchronous; poll the returned job URL for completion.
      tags:
      - Cutout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CutoutRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sensei/mask:
    post:
      operationId: createMask
      summary: Adobe Creative Suite Create Alpha Mask
      description: >-
        Creates an alpha mask for an image using Adobe Sensei AI. The mask isolates the
        foreground subject from the background and is returned as a separate grayscale
        image that can be applied as a layer mask in compositing workflows.
      tags:
      - Mask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaskRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sensei/product_crop:
    post:
      operationId: productCrop
      summary: Adobe Creative Suite Product Crop
      description: >-
        Automatically crops an image to focus on the primary product subject using Adobe
        Sensei AI. Useful for e-commerce workflows where product images need to be
        consistently cropped and centered.
      tags:
      - Cutout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCropRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sensei/straighten:
    post:
      operationId: straightenImage
      summary: Adobe Creative Suite Straighten Image
      description: >-
        Automatically detects and corrects the rotation of an image so that horizontal and
        vertical lines are properly aligned. Uses Adobe Sensei AI to analyze the image
        content and apply the appropriate rotation correction.
      tags:
      - Cutout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StraightenRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/text:
    post:
      operationId: editTextLayers
      summary: Adobe Creative Suite Edit Text Layers
      description: >-
        Edits text content, font properties, and styling of text layers within a PSD
        document. Supports changing text content, font family, size, color, alignment,
        and other text attributes across one or more named text layers.
      tags:
      - Text
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextEditRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/layers:
    post:
      operationId: manageLayers
      summary: Adobe Creative Suite Manage Layers
      description: >-
        Reads, adds, modifies, or deletes layers within a PSD document. Supports pixel,
        adjustment, fill, shape, text, and group layer types. Layer operations include
        visibility changes, opacity adjustments, blend mode changes, and positional
        transformations.
      tags:
      - Layers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayerManageRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/documentOperations:
    post:
      operationId: applyDocumentOperations
      summary: Adobe Creative Suite Apply Document Operations
      description: >-
        Applies one or more operations to a PSD document such as image resizing, canvas
        size changes, image flattening, and color mode conversions. Multiple operations
        can be chained together in a single request to produce a modified output document.
      tags:
      - Document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentOperationsRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/renditionCreate:
    post:
      operationId: createRendition
      summary: Adobe Creative Suite Create Rendition
      description: >-
        Generates one or more renditions from a PSD or image file in formats such as
        JPEG, PNG, or TIFF at specified dimensions. Supports generating multiple
        renditions in a single request for different sizes or formats simultaneously.
      tags:
      - Rendition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenditionCreateRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/smartObject:
    post:
      operationId: editSmartObject
      summary: Adobe Creative Suite Edit Smart Objects
      description: >-
        Replaces the content of a smart object layer within a PSD document with new
        image content. Smart object replacement preserves the layer's transform, blend
        mode, and effects while substituting the embedded image data.
      tags:
      - Smart Object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmartObjectRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/artboard:
    post:
      operationId: createArtboard
      summary: Adobe Creative Suite Create Artboards
      description: >-
        Creates one or more artboards within a PSD document at specified sizes and
        positions. Artboards allow multiple design variations or screen sizes to be
        organized within a single PSD file.
      tags:
      - Artboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtboardRequest'
      responses:
        '202':
          description: Job accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/status/{jobId}:
    get:
      operationId: getJobStatus
      summary: Adobe Creative Suite Get Job Status
      description: >-
        Retrieves the current status of an asynchronous Photoshop API job. Poll this
        endpoint after submitting an operation to check if the job is pending, running,
        succeeded, or failed. On success, the response includes output file locations.
      tags:
      - Status
      parameters:
      - name: jobId
        in: path
        required: true
        description: The unique identifier of the job to check
        schema:
          type: string
        example: asset_abc123
      responses:
        '200':
          description: Job status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Server-to-Server (S2S) access token from Adobe IMS
  schemas:
    JobInput:
      type: object
      description: Reference to an input file stored in cloud storage
      required:
      - href
      - storage
      properties:
        href:
          type: string
          description: URL or path to the input file in cloud storage
          example: https://my-storage.blob.core.windows.net/images/input.psd
        storage:
          type: string
          description: Cloud storage provider type
          enum:
          - adobe
          - external
          - azure
          - dropbox
          example: external
        type:
          type: string
          description: MIME type of the input file
          example: image/vnd.adobe.photoshop
    JobOutput:
      type: object
      description: Reference to an output file location in cloud storage
      required:
      - href
      - storage
      - type
      properties:
        href:
          type: string
          description: URL or path where the output file will be stored
          example: https://my-storage.blob.core.windows.net/images/output.png
        storage:
          type: string
          description: Cloud storage provider type
          enum:
          - adobe
          - external
          - azure
          - dropbox
          example: external
        type:
          type: string
          description: MIME type of the output file
          example: image/png
        width:
          type: integer
          description: Output width in pixels
          example: 1920
        height:
          type: integer
          description: Output height in pixels
          example: 1080
        overwrite:
          type: boolean
          description: Whether to overwrite the output file if it already exists
          default: true
          example: true
    JobSubmitted:
      type: object
      description: Response returned immediately after a job is submitted
      properties:
        jobId:
          type: string
          description: Unique identifier for the submitted job
          example: f54e0fcb-260b-47c3-b520-de0d17dc2b67
        statusUrl:
          type: string
          description: URL to poll for job status
          example: https://image.adobe.io/pie/psdService/status/f54e0fcb-260b-47c3-b520-de0d17dc2b67
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: https://image.adobe.io/pie/psdService/status/f54e0fcb-260b-47c3-b520-de0d17dc2b67
    JobStatus:
      type: object
      description: Current status and result of an asynchronous job
      properties:
        jobId:
          type: string
          description: Unique identifier of the job
          example: f54e0fcb-260b-47c3-b520-de0d17dc2b67
        status:
          type: string
          description: Current job status
          enum:
          - pending
          - running
          - succeeded
          - failed
          example: succeeded
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was created
          example: example_value
        modified:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was last modified
          example: example_value
        outputs:
          type: array
          description: List of output files produced by a successful job
          items:
            $ref: '#/components/schemas/RenderOutput'
        errors:
          type: array
          description: List of errors if the job failed
          items:
            $ref: '#/components/schemas/JobError'
    RenderOutput:
      type: object
      description: Details of a rendered output file
      properties:
        input:
          type: string
          description: Reference to the input file used to produce this output
          example: example_value
        status:
          type: string
          description: Status of this specific output
          enum:
          - pending
          - running
          - succeeded
          - failed
          example: pending
        details:
          type: string
          description: Additional detail message for this output
          example: example_value
        _links:
          type: object
          properties:
            renditions:
              type: array
              items:
                type: object
                properties:
                  href:
                    type: string
                    description: URL of the rendered output file
                  storage:
                    type: string
                  type:
                    type: string
                  width:
                    type: integer
                  height:
                    type: integer
    Layer:
      type: object
      description: Representation of a Photoshop document layer
      properties:
        id:
          type: integer
          description: Unique layer identifier within the document
          example: 1920
        index:
          type: integer
          description: Layer stack index (0 = bottom)
          example: 1920
        name:
          type: string
          description: Layer name as shown in the Layers panel
          example: Example Asset
        type:
          type: string
          description: Layer type
          enum:
          - layer
          - textLayer
          - adjustmentLayer
          - fillLayer
          - smartObject
          - backgroundLayer
          - groupLayer
          example: layer
        visible:
          type: boolean
          description: Whether the layer is visible
          example: true
        locked:
          type: boolean
          description: Whether the layer is locked
          example: true
        opacity:
          type: integer
          description: Layer opacity from 0 to 255
          minimum: 0
          maximum: 255
          example: 1920
        blendMode:
          type: string
          description: Blend mode of the layer
          example: normal
        bounds:
          type: object
          description: Layer bounding box in pixels
          properties:
            top:
              type: integer
            left:
              type: integer
            bottom:
              type: integer
            right:
              type: integer
        children:
          type: array
          description: Child layers for group layers
          items:
            $ref: '#/components/schemas/Layer'
    DocumentOperations:
      type: object
      description: Operations to apply to a PSD document
      properties:
        resize:
          type: object
          description: Resize the document canvas or image
          properties:
            width:
              type: integer
            height:
              type: integer
            unit:
              type: string
              enum:
              - pixel
              - percent
            resampleMethod:
              type: string
              enum:
              - bicubic
              - bilinear
              - nearestNeighbor
              - preserve
        flatten:
          type: boolean
          description: Whether to flatten all layers into a single layer
          example: true
        trim:
          type: object
          description: Trim transparent borders from the image
          properties:
            basedOn:
              type: string
              enum:
              - transparentPixels
              - topLeftPixelColor
              - bottomRightPixelColor
    CutoutRequest:
      type: object
      description: Request to remove the background from an image
      required:
      - input
      - output
      properties:
        input:
          $ref: '#/components/schemas/JobInput'
        output:
          $ref: '#/components/schemas/JobOutput'
    MaskRequest:
      type: object
      description: Request to create an alpha mask for an image
      required:
      - input
      - output
      properties:
        input:
          $ref: '#/components/schemas/JobInput'
        output:
          $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            optimize:
              type: string
              description: Optimization mode for mask generation
              enum:
              - performance
              - batch
    ProductCropRequest:
      type: object
      description: Request to automatically crop an image to the primary product
      required:
      - input
      - output
      properties:
        input:
          $ref: '#/components/schemas/JobInput'
        output:
          $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            unit:
              type: string
              enum:
              - pixel
              - percent
            padding:
              type: number
              description: Padding to add around the product crop
    StraightenRequest:
      type: object
      description: Request to automatically straighten an image
      required:
      - input
      - output
      properties:
        input:
          $ref: '#/components/schemas/JobInput'
        output:
          $ref: '#/components/schemas/JobOutput'
    TextEditRequest:
      type: object
      description: Request to edit text layer content and properties in a PSD
      required:
      - inputs
      - outputs
      - options
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            layers:
              type: array
              description: List of text layer edits to apply
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the text layer to edit
                  text:
                    type: object
                    properties:
                      content:
                        type: string
                        description: New text content for the layer
                      characterStyles:
                        type: array
                        items:
                          type: object
                          properties:
                            fontSize:
                              type: number
                            fontName:
                              type: string
                            color:
                              type: object
                              properties:
                                red:
                                  type: integer
                                green:
                                  type: integer
                                blue:
                                  type: integer
    LayerManageRequest:
      type: object
      description: Request to read or modify layers within a PSD document
      required:
      - inputs
      - outputs
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            layers:
              type: array
              description: Layer operations to apply
              items:
                $ref: '#/components/schemas/Layer'
    DocumentOperationsRequest:
      type: object
      description: Request to apply document-level operations to a PSD
      required:
      - inputs
      - outputs
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutput'
        options:
          $ref: '#/components/schemas/DocumentOperations'
    RenditionCreateRequest:
      type: object
      description: Request to create one or more renditions from a PSD or image
      required:
      - inputs
      - outputs
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          description: List of rendition outputs to generate
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/JobOutput'
            - type: object
              properties:
                quality:
                  type: integer
                  description: JPEG quality (1-100)
                  minimum: 1
                  maximum: 100
                compression:
                  type: string
                  description: PNG compression level
                  enum:
                  - small
                  - medium
                  - large
    SmartObjectRequest:
      type: object
      description: Request to replace smart object content within a PSD
      required:
      - inputs
      - outputs
      - options
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            layers:
              type: array
              description: Smart object layers to replace
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the smart object layer
                  input:
                    $ref: '#/components/schemas/JobInput'
    ArtboardRequest:
      type: object
      description: Request to create artboards within a PSD document
      required:
      - inputs
      - outputs
      - options
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/JobOutput'
        options:
          type: object
          properties:
            artboards:
              type: array
              description: List of artboards to create
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Artboard name
                  width:
                    type: integer
                    description: Artboard width in pixels
                  height:
                    type: integer
                    description: Artboard height in pixels
    JobError:
      type: object
      description: Error detail from a failed job or output
      properties:
        code:
          type: string
          description: Error code
          example: example_value
        title:
          type: string
          description: Short error title
          example: example_value
        description:
          type: string
          description: Detailed error description
          example: example_value
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
          example: example_value
        message:
          type: string
          description: Human-readable error message
          example: example_value