openapi: 3.1.0
info:
  title: Adobe Photoshop Actions Document Operations API
  description: A cloud-based REST API that provides programmatic access to Photoshop's image editing capabilities without requiring a local installation. Part of Adobe Firefly Services, the API supports PSD document operations including layer editing, Smart Object replacement, text layer editing, rendition creation, and artboard management. It also provides AI-powered features such as background removal, mask creation, product crop, and depth blur. All operations are asynchronous, returning a polling URL to check job status.
  version: 2.0.0
  contact:
    name: Adobe Developer Support
    url: https://developer.adobe.com/
  license:
    name: Proprietary
    url: https://www.adobe.com/legal/terms.html
  x-logo:
    url: https://www.adobe.com/content/dam/cc/icons/photoshop-appicon-256.png
servers:
- url: https://image.adobe.io
  description: Adobe Photoshop API Production
security:
- BearerAuth: []
  ApiKeyAuth: []
tags:
- name: Document Operations
  description: Create, modify, and inspect PSD documents including layer editing, adjustments, and metadata retrieval.
paths:
  /pie/psdService/documentManifest:
    post:
      operationId: getDocumentManifest
      summary: Adobe Photoshop Get PSD Document Manifest
      description: Retrieves the manifest (metadata) of a PSD document including the complete layer tree with layer types, names, bounds, visibility, text content, and Smart Object information. Optionally generates layer thumbnails.
      tags:
      - Document Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentManifestRequest'
      responses:
        '202':
          $ref: '#/components/responses/AsyncJobAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/documentOperations:
    post:
      operationId: modifyDocument
      summary: Adobe Photoshop Edit a PSD Document
      description: Performs layer-level edits on a PSD document. Supports adding, editing, moving, and deleting layers. Can apply adjustments such as brightness and contrast, modify layer bounds and visibility, edit text layers, and replace Smart Object content. Outputs can be saved as PSD, JPEG, PNG, or TIFF.
      tags:
      - Document Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentOperationsRequest'
      responses:
        '202':
          $ref: '#/components/responses/AsyncJobAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/documentCreate:
    post:
      operationId: createDocument
      summary: Adobe Photoshop Create a New PSD Document
      description: Creates a new PSD document with specified dimensions, resolution, color mode, and bit depth. Layers can be added during creation including image layers, text layers, and adjustment layers.
      tags:
      - Document Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
      responses:
        '202':
          $ref: '#/components/responses/AsyncJobAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pie/psdService/artboardCreate:
    post:
      operationId: createArtboard
      summary: Adobe Photoshop Create Artboards from PSD Inputs
      description: Creates a PSD document containing multiple artboards from one or more input PSD files.
      tags:
      - Document Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtboardCreateRequest'
      responses:
        '202':
          $ref: '#/components/responses/AsyncJobAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    StorageInput:
      type: object
      required:
      - href
      - storage
      properties:
        href:
          type: string
          description: Pre-signed GET URL or Creative Cloud asset path.
          example: https://image.adobe.io/example
        storage:
          type: string
          enum:
          - external
          - adobe
          - azure
          - dropbox
          description: Storage type for the input file.
          example: external
    StorageOutput:
      type: object
      required:
      - href
      - storage
      - type
      properties:
        href:
          type: string
          description: Pre-signed PUT URL or Creative Cloud asset path.
          example: https://image.adobe.io/example
        storage:
          type: string
          enum:
          - external
          - adobe
          - azure
          - dropbox
          description: Storage type for the output file.
          example: external
        type:
          type: string
          enum:
          - image/jpeg
          - image/png
          - image/tiff
          - vnd.adobe.photoshop
          description: Output file format.
          example: image/jpeg
        width:
          type: integer
          description: Optional output width in pixels for resizing.
          example: 1920
        overwrite:
          type: boolean
          description: Whether to overwrite existing files.
          default: true
          example: true
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          description: Error type code.
          example: image
        title:
          type: string
          description: Human-readable error description.
          example: example_value
        code:
          type: integer
          description: HTTP status code.
          example: 1920
        details:
          type: object
          properties:
            reason:
              type: string
            name:
              type: string
              description: Parameter name causing the error.
    DocumentOperationsRequest:
      type: object
      required:
      - inputs
      - outputs
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/StorageInput'
        options:
          type: object
          properties:
            layers:
              type: array
              items:
                $ref: '#/components/schemas/LayerOperation'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/StorageOutput'
    TextContent:
      type: object
      properties:
        content:
          type: string
          description: Text string content.
          example: example_value
        orientation:
          type: string
          enum:
          - horizontal
          - vertical
          example: horizontal
        characterStyles:
          type: array
          items:
            type: object
            properties:
              fontPostScriptName:
                type: string
              size:
                type: number
              color:
                type: object
                properties:
                  red:
                    type: integer
                  green:
                    type: integer
                  blue:
                    type: integer
              leading:
                type: number
              tracking:
                type: number
              syntheticBold:
                type: boolean
              syntheticItalic:
                type: boolean
              underline:
                type: boolean
              strikethrough:
                type: boolean
              from:
                type: integer
                description: Character range start index.
              to:
                type: integer
                description: Character range end index.
        paragraphStyles:
          type: array
          items:
            type: object
            properties:
              alignment:
                type: string
                enum:
                - left
                - center
                - right
                - justify
                - justifyLeft
                - justifyCenter
                - justifyRight
    DocumentCreateRequest:
      type: object
      required:
      - options
      - outputs
      properties:
        options:
          type: object
          required:
          - document
          properties:
            document:
              type: object
              required:
              - width
              - height
              properties:
                width:
                  type: integer
                  description: Document width in pixels.
                height:
                  type: integer
                  description: Document height in pixels.
                resolution:
                  type: integer
                  default: 72
                  description: Document resolution in PPI.
                fill:
                  type: string
                  enum:
                  - white
                  - transparent
                  - backgroundColor
                  default: white
                mode:
                  type: string
                  enum:
                  - rgb
                  - cmyk
                  - grayscale
                  default: rgb
                depth:
                  type: integer
                  enum:
                  - 8
                  - 16
                  - 32
                  default: 8
                  description: Bit depth per channel.
            layers:
              type: array
              items:
                $ref: '#/components/schemas/LayerOperation'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/StorageOutput'
    DocumentManifestRequest:
      type: object
      required:
      - inputs
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/StorageInput'
        options:
          type: object
          properties:
            thumbnails:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - image/png
                  - image/jpeg
                  description: Format for layer thumbnails.
    ArtboardCreateRequest:
      type: object
      required:
      - options
      - outputs
      properties:
        options:
          type: object
          required:
          - artboards
          properties:
            artboards:
              type: array
              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.
                  layers:
                    type: array
                    items:
                      $ref: '#/components/schemas/LayerOperation'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/StorageOutput'
    LayerOperation:
      type: object
      properties:
        id:
          type: integer
          description: Layer ID.
          example: 1920
        name:
          type: string
          description: Layer name.
          example: Example Layer
        type:
          type: string
          enum:
          - layer
          - textLayer
          - smartObject
          - adjustmentLayer
          - layerSection
          description: Layer type.
          example: layer
        visible:
          type: boolean
          description: Layer visibility.
          example: true
        locked:
          type: boolean
          description: Whether the layer is locked.
          example: true
        bounds:
          $ref: '#/components/schemas/LayerBounds/properties/bounds'
        add:
          type: object
          description: Add this layer relative to another.
          properties:
            insertAbove:
              type: object
              properties:
                id:
                  type: integer
            insertBelow:
              type: object
              properties:
                id:
                  type: integer
            insertInto:
              type: object
              properties:
                id:
                  type: integer
            insertTop:
              type: boolean
            insertBottom:
              type: boolean
        edit:
          type: object
          description: Edit this existing layer.
        move:
          type: object
          description: Move this layer relative to another.
          properties:
            insertAbove:
              type: object
              properties:
                id:
                  type: integer
            insertBelow:
              type: object
              properties:
                id:
                  type: integer
        delete:
          type: object
          description: Delete this layer.
        input:
          $ref: '#/components/schemas/StorageInput'
        adjustments:
          type: object
          properties:
            brightnessContrast:
              type: object
              properties:
                brightness:
                  type: number
                contrast:
                  type: number
        text:
          $ref: '#/components/schemas/TextContent'
    LayerBounds:
      properties:
        bounds:
          type: object
          properties:
            top:
              type: number
            left:
              type: number
            width:
              type: number
            height:
              type: number
  responses:
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or token expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AsyncJobAccepted:
      description: Job accepted for asynchronous processing.
      content:
        application/json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    type: object
                    properties:
                      href:
                        type: string
                        description: URL to poll for job status.
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded. Retry after the period in the retry-after header.
      headers:
        retry-after:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: File overwrite conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth Server-to-Server access token obtained from Adobe IMS at https://ims-na1.adobelogin.com/ims/token/v3 using client_credentials grant type.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Adobe Developer Console Client ID.
externalDocs:
  description: Adobe Photoshop API Documentation
  url: https://developer.adobe.com/firefly-services/docs/photoshop/