openapi: 3.1.0

security: []

info:
  title: Simple API
  version: 6.10.0
  description: |
    Process files in one API call. Convert documents individually with a blocking call until the API delivers the converted files. Implement the Conversion Service with multiple applications, each with a dedicated API. Each application can include different Workflows and Profiles. Convert large files (larger than 100&nbsp;MB) using the plain HTTP input endpoint of the Simple API.

    By default, the Simple API operates synchronously, blocking until the conversion completes and returning the result in the response. If the **Response** setting in the REST Input Connector configuration is set to **Immediately**, the API returns a `202 Accepted` status and processes the file asynchronously. In this case, results are delivered through the configured output connectors.

    ## Pre-installed connections

    The Conversion Service comes with the following pre-installed Connections that you can use out of the box. Replace the `{connectionID}` path parameter in the endpoint URL with one of these values:

    | Connection ID | Profile | Description |
    |---|---|---|
    | `archive-pdfa2-default` | Archive PDF/A-2 | Outputs PDFs in the PDF/A-2 archival standard (recommended) |
    | `archive-pdfa3-default` | Archive PDF/A-3 | Outputs PDFs in the PDF/A-3 archival standard (for specific cases, such as e-invoices) |
    | `convert-to-pdf` | All to PDF | Converts any supported input document into a standard PDF |
    | `dossier-default` | Merge | Merges multiple documents into a single PDF dossier |
    | `archive-pdfa2-print-optimization` | Ready to Print PDF/A-2 | PDF/A-2 archival standard with print optimization |
    | `archive-pdfa2-web-optimization` | Ready for Web PDF/A-2 | PDF/A-2 archival standard with web optimization |
    | `archive-pdfa2-email-optimization` | Ready for Email PDF/A-2 | PDF/A-2 archival standard with email optimization |
    | `repair-pdf` | Repair | Converts any supported document to PDF and validates and repairs the output |

    You can also create custom Connections in the **Conversion Service Configurator** and use their Connection IDs with these endpoints.

    ### Optimization options

    The Ready to Print, Ready for Web, and Ready for Email profiles accept an `OPTIMIZEPROFILE` job option in the JSON request body:

    | Profile | `OPTIMIZEPROFILE` value |
    |---|---|
    | Ready to Print PDF/A-2 | `print` |
    | Ready for Web PDF/A-2 | `web` |
    | Ready for Email PDF/A-2 | `max` |

servers:
  - url: '{baseURL}'
    description: Production server
    variables:
      baseURL:
        description: |
          The base URL for the API requests. Use the IP address of the computer where the Conversion Service Configurator is running. If it's not the same machine as where you call the API, replace `localhost` with another IP address.
        default: http://localhost:13034

paths:
  /http.input/{connectionID}:
    post:
      operationId: restInputPlainHttp
      summary: REST input plain HTTP
      description: |
        Submit a file for conversion using a binary upload. This endpoint supports large files (larger than 100 MB). Provide the file as `multipart/form-data` in the request body.

        The `connectionID` path parameter determines which pre-installed or custom Connection to use. For available values, refer to [Pre-installed connections](#pre-installed-connections).
      parameters:
        - $ref: '#/components/parameters/connectionId'
      requestBody:
        required: true
        description: |
          Upload the file to be converted as `multipart/form-data` content type. Include the binary data of your document in the `data` field.
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: string
                  format: binary
                  description: Include data of the file to be uploaded.
            encoding:
              data:
                contentType: application/octet-stream
      responses:
        '200':
          description: |
            The file was successfully submitted for conversion. The Simple API returned the converted file in the response.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '202':
          description: |
            The file was successfully submitted for conversion. This response is returned when the **Response** setting in the REST Input Connector is set to **Immediately**. The file will be processed asynchronously.
        '400':
          $ref: "#/components/responses/badRequest"
        '404':
          $ref: "#/components/responses/notFound"
        '415':
          $ref: "#/components/responses/unsupportedMediaType"
        '422':
          $ref: "#/components/responses/unprocessableFile"
        '500':
          $ref: "#/components/responses/serverError"

  /http.inputstructured/{connectionID}:
    post:
      operationId: restInputJson
      summary: REST input JSON
      description: |
        Submit files for conversion using structured JSON input. Upload documents using a URL or in Base64-encoded format. This endpoint supports structured input and output, including job options and metadata.

        The `connectionID` path parameter determines which pre-installed or custom Connection to use. For available values, refer to [Pre-installed connections](#pre-installed-connections).
      parameters:
        - $ref: '#/components/parameters/connectionId'
      requestBody:
        required: true
        description: |
          Include one or more files for conversion. There are two possibilities how to include files:
          - Encoded in Base64 format. Use the `content` parameter.
          - Share a URL pointing to the file. Use the `url` parameter.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/restInputJsonRequest'
            examples:
              basicConversion:
                $ref: "#/components/examples/requestMoreFiles"
              printOptimized:
                $ref: "#/components/examples/requestMoreFilesPrintOptimized"
              webOptimized:
                $ref: "#/components/examples/requestMoreFilesWebOptimized"
              emailOptimized:
                $ref: "#/components/examples/requestMoreFilesEmailOptimized"
      responses:
        '200':
          description: |
            The file was successfully submitted for conversion and the Simple API included the converted file in the API response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restInputJsonResponse'
        '202':
          description: |
            The file was successfully submitted for conversion. This response is returned when the **Response** setting in the REST Input Connector is set to **Immediately**. The file will be processed asynchronously.
        '400':
          $ref: "#/components/responses/badRequest"
        '404':
          $ref: "#/components/responses/notFound"
        '415':
          $ref: "#/components/responses/unsupportedMediaType"
        '422':
          $ref: "#/components/responses/unprocessableFile"
        '500':
          $ref: "#/components/responses/serverError"

components:
  responses:
      serverError:
        description: |
            An internal server error. Returns `ProblemDetails`:
            - The job was canceled.
            - The service is not configured correctly.
            - An internal error happened during processing.
            - A timeout occurred during processing.
            - If an unknown error occurs the message you receive is empty.
        content:
          application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetails'
              examples:
                serverErrorJson: {$ref: "#/components/examples/serverErrorJson"}
          application/problem+xml:
            schema:
              $ref: '#/components/schemas/problemDetails'
            examples:
              serverErrorXml: {$ref: "#/components/examples/serverErrorXml"}
      unprocessableFile:
        description: |
            Unprocessable file. Returns `ProblemDetails`:
            - The conformance is not compatible.
            - The file is corrupt.
            - A generic error happened during processing.
            - One of the specified options is invalid.
            - The password is missing or incorrect.
            - A file contains a feature that is not supported.
        content:
          application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetails'
              examples:
                serverErrorJson: {$ref: "#/components/examples/unprocessableFileJson"}
          application/problem+xml:
            schema:
              $ref: '#/components/schemas/problemDetails'
            examples:
              serverErrorXml: {$ref: "#/components/examples/unprocessableFileXml"}
      unsupportedMediaType:
        description: |
            Unsupported media type. Returns `ProblemDetails`:
            - A file format is not supported.
        content:
          application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetails'
              examples:
                serverErrorJson: {$ref: "#/components/examples/unsupportedMediaTypeJson"}
          application/problem+xml:
            schema:
              $ref: '#/components/schemas/problemDetails'
            examples:
              serverErrorXml: {$ref: "#/components/examples/unsupportedMediaTypeXml"}
      notFound:
          description: |
            - The provided `connectionID` was not found.
      badRequest:
          description: |
            - The job must contain at least one data element.
            - Exception message that occurred during processing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetails'
              examples:
                badRequestJson: {$ref: "#/components/examples/badRequestJson"}

  schemas:
    restInputJsonRequest:
      type: object
      description: |
        Request body for the REST input JSON endpoint. This includes the conversion job details and the files to be converted.
      required:
        - data
      properties:
        name:
          type: string
          description: Name of the conversion job.
          example: "file-conversion"
        data:
          type: array
          items:
            $ref: '#/components/schemas/jobData'
          example:
            - url: "https://example.com/image1.jpg"
              content: "SGVsbG8gd29ybGQuCg=="
              fileName: "hello_world.txt"
              options:
                - name: "DOC.PASSWORD"
                  value: "1234"
        variables:
          type:
            - object
            - 'null'
          description: Job variables represented as key-value pairs.
          additionalProperties:
            type: string
          example: {}
        options:
          type:
            - array
            - 'null'
          description: |
            Job options. Use these to control optimization profiles and metadata. Common options include:
            - `OPTIMIZEPROFILE`: Set to `print`, `web`, or `max` for optimization profiles.
            - `META.AUTHOR`: Set the author metadata of the output PDF.
          items:
            $ref: '#/components/schemas/jobOption'
          example:
            - name: "META.AUTHOR"
              value: "John Doe"

    jobData:
      type: object
      description: |
        Details of a single file to be converted. You can pass files as a binary content or a URL pointing to the file. Either `content` or `url` must be defined with `fileName`.
      required:
        - fileName
      anyOf:
        - required: [content]
        - required: [url]
      properties:
        url:
          type:
            - string
            - 'null'
          format: uri
          description: URL to a file.
          example: "https://example.com/image1.jpg"
        content:
          type:
            - string
            - 'null'
          description: Base64-encoded content of the file.
          example: "SGVsbG8gd29ybGQuCg=="
        fileName:
          type: string
          description: Name of the input file.
          example: "hello_world.txt"
        options:
          type:
            - array
            - 'null'
          description: "Document options."
          items:
            $ref: '#/components/schemas/docOption'
          example:
            - name: "DOC.PASSWORD"
              value: "1234"
    resultData:
      type: object
      description: |
        Details of a single file that has been converted.
      required:
        - fileName
        - content
      properties:
        fileName:
          type: string
          description: Name of the converted file.
        content:
          type: string
          description: Base64-encoded content of the resulting file.

    restInputJsonResponse:
      type: object
      description: |
        Response body for the REST input JSON endpoint. Contains the converted files in Base64 format.
      required:
        - data
      properties:
        data:
          type: array
          description: List of converted files.
          items:
            $ref: '#/components/schemas/resultData'
    problemDetails:
        type: object
        description: Problem details (RFC 7807).
        properties:
            "type": { type: string, description: "A URI reference that identifies the problem type. Note that this URI cannot be dereferenced." }
            "title": { type: string, description: "A short, human-readable summary of the problem type." }
            "status": { type: integer, description: "The HTTP status code." }
            "detail": { type: string, description: "A human-readable explanation specific to this occurrence of the problem." }
        required:
            - "title"
            - "detail"
            - "status"
        xml:
            name: "problem"
            namespace: "urn:ietf:rfc:7807"
    jobOption:
      type: object
      properties:
        name:
          description: Name of the option.
          type:
            - string
            - 'null'
          example: "META.AUTHOR"
        value:
          description: Value of the option.
          type:
            - string
            - 'null'
          example: "John Doe"
      additionalProperties: false
    docOption:
      type: object
      properties:
        name:
          description: Name of the option.
          type:
            - string
            - 'null'
          example: "DOC.PASSWORD"
        value:
          description: Value of the option.
          type:
            - string
            - 'null'
          example: "1234"
      additionalProperties: false

  parameters:
    connectionId:
        name: connectionID
        in: path
        required: true
        schema:
          type: string
        description: |
          The Connection ID that determines which integration to use. The Conversion Service comes with pre-installed Connections (see the [Pre-installed Connections](#pre-installed-connections) table). You can also use custom Connection IDs created in the Conversion Service Configurator:
            1. Go to the **Conversion Service Configurator** > **Integration**.
            1. Click the pencil icon next to one of the integrations.
            1. Under the **Input** section, click the pencil icon next to one of the **Input** configurations.
            1. Copy the `connectionID` from the **Connection ID** field.
        examples:
          custom:
            value: your-connection-id
            summary: Custom Connection ID
          archivePdfA2:
            value: archive-pdfa2-default
            summary: Archive PDF/A-2
          archivePdfA3:
            value: archive-pdfa3-default
            summary: Archive PDF/A-3
          convertToPdf:
            value: convert-to-pdf
            summary: All to PDF
          merge:
            value: dossier-default
            summary: Merge (dossier)
          readyToPrint:
            value: archive-pdfa2-print-optimization
            summary: Ready to Print PDF/A-2
          readyForWeb:
            value: archive-pdfa2-web-optimization
            summary: Ready for Web PDF/A-2
          readyForEmail:
            value: archive-pdfa2-email-optimization
            summary: Ready for Email PDF/A-2
          repair:
            value: repair-pdf
            summary: Repair

  examples:
    unsupportedMediaTypeJson:
      summary: Unsupported format
      value:
        type: "http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat"
        title: "Unsupported file format."
        detail: "A file format is not supported."
        status: 415
    unsupportedMediaTypeXml:
      summary: Unsupported format
      value: |
        <problem xmlns="urn:ietf:rfc:7807">
          <type>http://www.pdf-tools.com/service/rest/errors/workflow/unsupportedFormat</type>
          <title>Unsupported file format.</title>
          <detail>A file format is not supported.</detail>
          <status>415</status>
        </problem>
    unprocessableFileJson:
      summary: Incompatible conformance
      value:
        type: "http://www.pdf-tools.com/service/rest/errors/workflow/conformance"
        title: "Incompatible conformance."
        detail: "The conformance is not compatible."
        status: 422
    unprocessableFileXml:
      summary: Incompatible conformance
      value: |
        <problem xmlns="urn:ietf:rfc:7807">
          <type>http://www.pdf-tools.com/service/rest/errors/workflow/conformance</type>
          <title>Incompatible conformance.</title>
          <detail>The conformance is not compatible.</detail>
          <status>422</status>
        </problem>
    serverErrorJson:
      summary: Server error
      value:
        type: "http://www.pdf-tools.com/service/rest/errors/workflow/internal"
        title: "Internal server error."
        detail: "An internal error happened during processing."
        status: 500
    serverErrorXml:
      summary: Server error
      value: |
        <problem xmlns="urn:ietf:rfc:7807">
          <type>http://www.pdf-tools.com/service/rest/errors/workflow/internal</type>
          <title>Internal server error.</title>
          <detail>An internal error happened during processing.</detail>
          <status>500</status>
        </problem>
    requestMoreFiles:
      summary: Basic conversion (e.g. Archive PDF/A-2, All to PDF)
      value:
        name: "file-conversion"
        data:
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world1.txt"
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world2.txt"
    requestMoreFilesPrintOptimized:
      summary: Print-optimized conversion (Ready to Print PDF/A-2)
      value:
        name: "file-conversion"
        data:
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world1.txt"
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world2.txt"
        options:
          - name: "OPTIMIZEPROFILE"
            value: "print"
    requestMoreFilesWebOptimized:
      summary: Web-optimized conversion (Ready for Web PDF/A-2)
      value:
        name: "file-conversion"
        data:
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world1.txt"
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world2.txt"
        options:
          - name: "OPTIMIZEPROFILE"
            value: "web"
    requestMoreFilesEmailOptimized:
      summary: Email-optimized conversion (Ready for Email PDF/A-2)
      value:
        name: "file-conversion"
        data:
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world1.txt"
          - content: "SGVsbG8gd29ybGQuCg=="
            fileName: "hello_world2.txt"
        options:
          - name: "OPTIMIZEPROFILE"
            value: "max"
    badRequestJson:
      summary: Bad request
      value:
        type: "https://tools.ietf.org/html/rfc7231#section-6.5.1"
        status: 400
        title: "Bad request"
        detail: "The job must contain at least one data element."
