openapi: 3.1.0
info:
  title: Adobe Creative Suite Adobe PDF Services API
  description: >-
    The Adobe PDF Services API provides cloud-based tools for creating, converting,
    combining, compressing, and extracting content from PDF documents. Part of the
    Adobe Acrobat Services platform, it supports operations such as Office-to-PDF,
    HTML-to-PDF, PDF-to-Word, PDF-to-Excel, OCR, accessibility auto-tagging, document
    generation from templates, and PDF linearization. The API follows an asynchronous
    job model where operations are submitted and polled for completion.
  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://pdf-services.adobe.io
  description: Adobe PDF Services API production server
security:
- bearerAuth: []
tags:
- name: Accessibility
  description: Auto-tag PDFs for accessibility compliance
- name: Assets
  description: Upload and manage input/output assets for PDF operations
- name: Combine PDF
  description: Combine multiple PDFs into one
- name: Compress PDF
  description: Reduce PDF file size
- name: Create PDF
  description: Create PDF documents from other formats
- name: Document Generation
  description: Generate documents from templates and data
- name: Export PDF
  description: Export PDF documents to other formats
- name: Linearize PDF
  description: Optimize PDFs for fast web viewing
- name: OCR
  description: Apply optical character recognition to scanned PDFs
- name: Operations
  description: Check operation job status
paths:
  /assets:
    post:
      operationId: uploadAsset
      summary: Adobe Creative Suite Upload Asset
      description: >-
        Initiates an asset upload by returning a pre-signed upload URI and an asset ID.
        The caller must then PUT the file content to the returned upload URI. Once the
        upload is complete, the asset ID can be referenced as input to PDF operations.
      tags:
      - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetUploadRequest'
      responses:
        '200':
          description: Asset upload URI and ID returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetUploadResponse'
        '400':
          description: Bad request - invalid media type or 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
  /assets/{assetID}:
    get:
      operationId: getAsset
      summary: Adobe Creative Suite Get Asset
      description: >-
        Retrieves metadata and a temporary download URI for a previously uploaded asset.
        The download URI is time-limited and can be used to download the asset content
        directly.
      tags:
      - Assets
      parameters:
      - name: assetID
        in: path
        required: true
        description: Unique identifier of the asset to retrieve
        schema:
          type: string
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
      responses:
        '200':
          description: Asset metadata and download URI retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '404':
          description: Asset 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
    delete:
      operationId: deleteAsset
      summary: Adobe Creative Suite Delete Asset
      description: >-
        Permanently deletes an uploaded asset. Assets are automatically deleted after
        24 hours, but this endpoint allows immediate deletion when the asset is no
        longer needed.
      tags:
      - Assets
      parameters:
      - name: assetID
        in: path
        required: true
        description: Unique identifier of the asset to delete
        schema:
          type: string
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
      responses:
        '200':
          description: Asset deleted successfully
        '404':
          description: Asset 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
  /operation/createpdf:
    post:
      operationId: createPDF
      summary: Adobe Creative Suite Create PDF
      description: >-
        Creates a PDF document from a source file in formats such as Microsoft Word,
        Excel, PowerPoint, or HTML. The source file must be uploaded first using the
        asset upload endpoint. Returns a job ID for polling the operation status.
      tags:
      - Create PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePDFRequest'
      responses:
        '201':
          description: Create PDF operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid source format or 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
  /operation/exportpdf:
    post:
      operationId: exportPDF
      summary: Adobe Creative Suite Export PDF
      description: >-
        Exports a PDF document to a target format such as Microsoft Word (.docx),
        Excel (.xlsx), PowerPoint (.pptx), RTF, or plain text. The source PDF must
        be uploaded first. Returns a job ID for polling the operation status.
      tags:
      - Export PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportPDFRequest'
      responses:
        '201':
          description: Export PDF operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - unsupported export format or 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
  /operation/combinepdf:
    post:
      operationId: combinePDFs
      summary: Adobe Creative Suite Combine PDFs
      description: >-
        Combines two or more PDF documents into a single output PDF. The source PDFs
        are specified in order and merged sequentially. Page ranges from each source
        can optionally be specified to include only specific pages.
      tags:
      - Combine PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CombinePDFRequest'
      responses:
        '201':
          description: Combine PDF operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid asset references or 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
  /operation/compressPDF:
    post:
      operationId: compressPDF
      summary: Adobe Creative Suite Compress PDF
      description: >-
        Reduces the file size of a PDF document by applying compression to embedded
        images and removing redundant data. Compression level can be set to balance
        between file size and output quality.
      tags:
      - Compress PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompressPDFRequest'
      responses:
        '201':
          description: Compress PDF operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid asset reference or 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
  /operation/linearizePDF:
    post:
      operationId: linearizePDF
      summary: Adobe Creative Suite Linearize PDF
      description: >-
        Linearizes (web-optimizes) a PDF document so that the first page can be
        displayed in a browser before the entire file has downloaded. This is also
        known as fast web view optimization.
      tags:
      - Linearize PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinearizePDFRequest'
      responses:
        '201':
          description: Linearize PDF operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid asset reference
          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
  /operation/ocr:
    post:
      operationId: ocrPDF
      summary: Adobe Creative Suite OCR PDF
      description: >-
        Applies optical character recognition (OCR) to a scanned or image-based PDF,
        making the text content searchable and selectable. Supports multiple locales
        for improved recognition accuracy with non-English documents.
      tags:
      - OCR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OCRRequest'
      responses:
        '201':
          description: OCR operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid asset reference or locale
          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
  /operation/autotagpdf:
    post:
      operationId: autoTagPDF
      summary: Adobe Creative Suite Auto-tag PDF for Accessibility
      description: >-
        Automatically adds accessibility tags to a PDF document to make it compliant
        with PDF/UA and WCAG standards. Tags identify headings, paragraphs, tables,
        figures, and other document structure elements for screen readers and assistive
        technologies.
      tags:
      - Accessibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoTagRequest'
      responses:
        '201':
          description: Auto-tag operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid asset reference or 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
  /operation/documentgeneration:
    post:
      operationId: generateDocument
      summary: Adobe Creative Suite Generate Document from Template
      description: >-
        Generates a PDF or Word document by merging JSON data into a Word document
        template. Template tags in the document are replaced with corresponding data
        values. Supports tables, lists, conditional sections, and images in templates.
      tags:
      - Document Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentGenerationRequest'
      responses:
        '201':
          description: Document generation operation accepted
          headers:
            Location:
              description: URL to poll for operation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationSubmitted'
        '400':
          description: Bad request - invalid template or data 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
  /operation/{jobId}:
    get:
      operationId: getOperationStatus
      summary: Adobe Creative Suite Get Operation Status
      description: >-
        Retrieves the current status of a PDF Services operation job. Poll this
        endpoint after submitting any operation to check progress. On success, the
        response contains a reference to the output asset.
      tags:
      - Operations
      parameters:
      - name: jobId
        in: path
        required: true
        description: Unique identifier of the operation job to check
        schema:
          type: string
          example: urn:aaid:AS:UE1:operation:abc123
        example: urn:aaid:AS:UE1:operation:abc123
      responses:
        '200':
          description: Operation status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatus'
        '404':
          description: Operation 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 access token from Adobe IMS
  schemas:
    Asset:
      type: object
      description: Metadata and download reference for an uploaded asset
      properties:
        assetID:
          type: string
          description: Unique identifier for the asset
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        mediaType:
          type: string
          description: MIME type of the asset
          example: application/pdf
        downloadUri:
          type: string
          description: Temporary signed URL to download the asset
          example: https://dcplatformstorageservice-us-east-1.s3-accelerate.amazonaws.com/...
        size:
          type: integer
          description: File size in bytes
          example: 204800
    AssetUploadRequest:
      type: object
      description: Request to initiate an asset upload
      required:
      - mediaType
      properties:
        mediaType:
          type: string
          description: MIME type of the file to be uploaded
          example: application/vnd.openxmlformats-officedocument.wordprocessingml.document
    AssetUploadResponse:
      type: object
      description: Response containing the upload URI and asset ID
      properties:
        assetID:
          type: string
          description: Asset ID to reference in subsequent operations
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        uploadUri:
          type: string
          description: Pre-signed URI to PUT the file content to
          example: https://dcplatformstorageservice-us-east-1.s3-accelerate.amazonaws.com/...
    AssetReference:
      type: object
      description: Reference to an existing uploaded asset
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: ID of the asset returned by the upload endpoint
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
    PageRange:
      type: object
      description: Specifies a range of pages from a PDF document
      properties:
        start:
          type: integer
          description: Starting page number (1-indexed)
          example: 1
        end:
          type: integer
          description: Ending page number (1-indexed, inclusive)
          example: 5
    OperationSubmitted:
      type: object
      description: Response returned when an operation has been accepted
      properties:
        jobID:
          type: string
          description: Unique identifier for the submitted operation job
          example: urn:aaid:AS:UE1:operation:abc123
    OperationStatus:
      type: object
      description: Current status and result of a PDF Services operation
      properties:
        status:
          type: string
          description: Current status of the operation
          enum:
          - in progress
          - done
          - failed
          example: done
        asset:
          $ref: '#/components/schemas/Asset'
        errors:
          type: array
          description: Error details if the operation failed
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    CreatePDFRequest:
      type: object
      description: Request body for creating a PDF from another format
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: Asset ID of the source file to convert to PDF
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        documentLanguage:
          type: string
          description: BCP 47 language code of the source document for better conversion
          example: en-US
    ExportPDFRequest:
      type: object
      description: Request body for exporting a PDF to another format
      required:
      - assetID
      - targetFormat
      properties:
        assetID:
          type: string
          description: Asset ID of the PDF to export
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        targetFormat:
          type: string
          description: Target output format for the exported file
          enum:
          - docx
          - xlsx
          - pptx
          - rtf
          - txt
          example: docx
        exportOCRLocale:
          type: string
          description: Locale for OCR during export, if the PDF contains scanned text
          example: en-US
    CombinePDFRequest:
      type: object
      description: Request body for combining multiple PDFs
      required:
      - assets
      properties:
        assets:
          type: array
          description: Ordered list of PDF assets to combine
          minItems: 2
          items:
            type: object
            required:
            - assetID
            properties:
              assetID:
                type: string
                description: Asset ID of the PDF to include
              pageRanges:
                type: array
                description: Optional page ranges to extract from this PDF
                items:
                  $ref: '#/components/schemas/PageRange'
    CompressPDFRequest:
      type: object
      description: Request body for compressing a PDF
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: Asset ID of the PDF to compress
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        compressionLevel:
          type: string
          description: Compression level to apply
          enum:
          - LOW
          - MEDIUM
          - HIGH
          default: MEDIUM
          example: LOW
    LinearizePDFRequest:
      type: object
      description: Request body for linearizing a PDF for fast web view
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: Asset ID of the PDF to linearize
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
    OCRRequest:
      type: object
      description: Request body for applying OCR to a PDF
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: Asset ID of the scanned PDF to OCR
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        ocrLang:
          type: string
          description: BCP 47 locale for OCR language model selection
          example: en-US
    AutoTagRequest:
      type: object
      description: Request body for auto-tagging a PDF for accessibility
      required:
      - assetID
      properties:
        assetID:
          type: string
          description: Asset ID of the PDF to auto-tag
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        generateReport:
          type: boolean
          description: Whether to generate an accessibility report alongside the tagged PDF
          default: false
          example: true
        shiftHeadings:
          type: boolean
          description: Whether to shift heading levels in the output for better document structure
          default: false
          example: true
    DocumentGenerationRequest:
      type: object
      description: Request body for generating a document from a template
      required:
      - assetID
      - outputFormat
      - jsonDataForMerge
      properties:
        assetID:
          type: string
          description: Asset ID of the Word document template
          example: urn:aaid:AS:UE1:23c30ee0-2e4d-46d6-87f2-087832fca718
        outputFormat:
          type: string
          description: Output format of the generated document
          enum:
          - pdf
          - docx
          example: pdf
        jsonDataForMerge:
          type: object
          description: JSON data object whose keys map to template tags in the document
          additionalProperties: true
          example:
            customerName: John Doe
            invoiceDate: 2026-03-02
            totalAmount: 1500.00
        notTaggedAdds:
          type: boolean
          description: Whether to include non-tagged content as plain text additions
          default: false
          example: true
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: example_value
        message:
          type: string
          description: Human-readable error message
          example: example_value
        requestId:
          type: string
          description: Unique identifier for the failed request
          example: asset_abc123