Adobe Suite Data Merge & Create Rendition API

openapi: 3.2.0
info:
  title: Illustrator API - Firefly Services Data Merge & Create Rendition API
  description: Illustrator API allows you to perform various operations with an Adobe Illustrator template. The API processes requests asynchronously.
  version: 1.0.0
  license:
    name: Adobe Creative API License
    url: https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf
servers:
- url: https://illustrator-api.adobe.io
  description: Production endpoint.
security:
- AccessToken: []
  X-Api-Key: []
tags:
- name: Data Merge & Create Rendition
  description: Data merge, create rendition, and shared job status for asynchronous Illustrator API jobs.
paths:
  /v1/merge-data:
    post:
      tags:
      - Data Merge & Create Rendition
      operationId: dataMerge
      summary: Data merge
      description: This endpoint allows you to merge variable data from a CSV file with an Adobe Illustrator template. The request is processed asynchronously and the status of the job can be checked using the status URL provided in the response. The output is provided as an array of individual files, one for each row in the CSV data. If some rows succeed and others fail or require rerun, the job completes with status `partially_succeeded` when you poll the status endpoint; that status applies only to Data Merge jobs.
      x-ffs-async-job: true
      x-ffs-job-status-fetcher: facadeJobStatus
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataMergeRequest'
            example:
              data:
                source:
                  url: https://your-bucket.s3.amazonaws.com/your-data.csv
              template:
                source:
                  url: https://your-bucket.s3.amazonaws.com/your-template.ai
              fontFiles:
              - source:
                  url: https://your-bucket.s3.amazonaws.com/your-font.ttf
                mediaType: font/ttf
              settings:
                fontSettings:
                  autoReduceFontSizeToFit: false
                  minFontSize: 8
                  fallBackFont: Roboto-Thin
              output:
                fileName: your-output.pdf
                mediaType: application/pdf
      responses:
        '202':
          description: Accepted
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: string
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            retry-after:
              description: Indicates how long to wait before making a new request.
              schema:
                type: string
            link:
              description: Provides a link to related resources.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobLinkResponse'
              example:
                jobId: f246bc8a-45ef-4cdc-8217-6c1ab74c5dc4
                statusUrl: https://illustrator-api-beta.adobe.io/v1/status/f246bc8a-45ef-4cdc-8217-6c1ab74c5dc4
        '400':
          description: Bad Request
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: string
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
              example:
                error_code: invalid_json
                message: "Unexpected token 'a', ...\"ntSize\" : a\n      }\n\"... is not valid JSON"
        '401':
          description: Unauthorized
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              example:
                title: ErrInvalidOauthToken
                status: 401
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: Forbidden
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              example:
                title: ErrMissingAPIKey
                status: 403
                error_code: 403000
                message: API key is missing
        '422':
          description: Unprocessable Entity
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: string
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
              example:
                error_code: validation_error
                validation_errors:
                - minFontSize must be a positive number
                - minFontSize must be a number conforming to the specified constraints
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
  /v1/create-rendition:
    post:
      tags:
      - Data Merge & Create Rendition
      operationId: createRendition
      summary: Create rendition
      description: This endpoint allows you to convert Adobe Illustrator files into various output formats. It supports conversion of .ai documents into multiple web- and print-ready formats. The request is processed asynchronously and the status of the job can be checked using the status URL provided in the response. The output is provided as a single converted file.
      x-ffs-async-job: true
      x-ffs-job-status-fetcher: facadeJobStatus
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRenditionRequest'
            example:
              input:
                source:
                  url: https://your-bucket.s3.amazonaws.com/your-document.ai
                mediaType: application/illustrator
              output:
                mediaType: application/pdf
              settings:
                documentLevel: 0
                artboardRange: 1-3
                resolution: 72
      responses:
        '202':
          description: Accepted
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: integer
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            retry-after:
              description: Indicates how long to wait before making a new request.
              schema:
                type: integer
            link:
              description: Provides a link to related resources.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobLinkResponse'
              example:
                jobId: f246bc8a-45ef-4cdc-8217-6c1ab74c5dc4
                statusUrl: https://illustrator-api-beta.adobe.io/v1/status/f246bc8a-45ef-4cdc-8217-6c1ab74c5dc4
        '400':
          description: Bad Request
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: integer
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
              example:
                error_code: invalid_json
                message: Expected ',' or '}' after property value in JSON at position 276
        '401':
          description: Unauthorized
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: ''
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongJobError'
              example:
                title: ErrInvalidOauthToken
                status: 401
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: Forbidden
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: Indicates the software used by the origin server to handle the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongJobError'
              example:
                title: ErrMissingAPIKey
                status: 403
                error_code: 403000
                message: API key is missing
        '422':
          description: Unprocessable Entity
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: integer
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: Indicates the software used by the origin server to handle the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
              example:
                error_code: validation_error
                validation_errors:
                - 'documentLevel must be one of the following values: 0, 1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobError'
              example:
                error_code: runtime_error
                message: An unexpected error occurred while processing your request. Please retry or contact support if the issue persists.
  /v1/status/{jobId}:
    get:
      tags:
      - Data Merge & Create Rendition
      operationId: facadeJobStatus
      summary: Retrieve job status
      description: Retrieve the status of a job by providing the job ID. The job ID can be obtained from the response of other APIs. For all asynchronous jobs, polling this endpoint can return `running`, `succeeded`, or `failed`. The `partially_succeeded` status is returned only for Data Merge jobs when some CSV rows produce outputs while other rows fail or must be rerun after errors (for example, missing fonts). No other job types return the `partially_succeeded` status.<br>When `status` is `succeeded`, for Data Merge jobs each item in `outputs` includes a `row` field; for Create Rendition jobs, output items contain `destination` and `mediaType` only.
      x-ffs-status-fetcher: true
      x-ffs-job-name: FacadeAsyncJob
      parameters:
      - name: jobId
        required: true
        in: path
        description: The job ID to retrieve the status of.
        schema:
          type: string
          example: f246bc8a-45ef-4cdc-8217-6c1ab74c5dc4
      responses:
        '200':
          description: OK
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: string
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            retry-after:
              description: Indicates how long to wait before making a new request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: Indicates the software used by the origin server to handle the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/DataMergeJobApiResponse'
                - $ref: '#/components/schemas/CreateRenditionJobApiResponse'
                - $ref: '#/components/schemas/JobStatusPollPayload'
                - $ref: '#/components/schemas/DataMergeJobFailedResponse'
                - $ref: '#/components/schemas/DataMergeJobPartiallySucceededResponse'
              examples:
                succeeded_create_rendition:
                  summary: 'Status: Succeeded (Create Rendition)'
                  value:
                    jobId: 6f35a027-c578-41e6-9e53-034424c69d14
                    status: succeeded
                    outputs:
                    - destination:
                        url: https://example.com/output2.pdf
                      mediaType: application/pdf
                succeeded_data_merge:
                  summary: 'Status: Succeeded (Data Merge)'
                  value:
                    jobId: 856745ce-816e-476b-b517-debd9fd91e3b
                    status: succeeded
                    outputs:
                    - row: 1
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: image/png
                    - row: 2
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: image/png
                    - row: 3
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: image/png
                running:
                  summary: 'Status: Running'
                  value:
                    jobId: 48db6300-1cc5-4a31-84f6-5092fbd67484
                    status: running
                    Retry-After: '1'
                failed:
                  summary: 'Status: Failed'
                  value:
                    jobId: ef4f7daa-0d09-4dcf-9884-029bb7f374ac
                    status: failed
                    error_code: runtime_error
                    message: 'Missing fonts detected: Chabplan-Rg. Please provide font files.'
                partially_succeeded:
                  summary: 'Status: Partially Succeeded (Data Merge only)'
                  value:
                    jobId: 1dd551c5-6023-4ff9-b736-bc27b36cbb7f
                    status: partially_succeeded
                    outputs:
                    - row: 135
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: application/pdf
                    - row: 136
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: application/pdf
                    - row: 137
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: application/pdf
                    - row: 138
                      destination:
                        url: '{your_presigned_get_url}'
                      mediaType: application/pdf
                    errors:
                    - row: 47
                      error_code: runtime_error
                      message: 'Missing fonts detected: Chabplan-Rg. Please provide font files.'
                    - row: 113
                      error_code: runtime_error
                      message: 'Missing fonts detected: Chabplan-Rg. Please provide font files.'
                    - row: 211
                      error_code: runtime_error
                      message: 'Missing fonts detected: Chabplan-Rg. Please provide font files.'
                    - row: 427
                      error_code: runtime_error
                      message: 'Missing fonts detected: Chabplan-Rg. Please provide font files.'
                    needsRerun:
                    - rowRange:
                        start: 1
                        end: 67
                    - rowRange:
                        start: 68
                        end: 134
                    - rowRange:
                        start: 202
                        end: 268
                    - rowRange:
                        start: 403
                        end: 469
        '401':
          description: Unauthorized
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: Indicates the software used by the origin server to handle the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongJobError'
              example:
                title: ErrInvalidOauthToken
                status: 401
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: Forbidden
          headers:
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: integer
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: Indicates the software used by the origin server to handle the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongJobError'
              example:
                title: ErrMissingAPIKey
                status: 403
                error_code: 403000
                message: API key is missing
        '404':
          description: Not Found
          headers:
            access-control-allow-headers:
              description: Indicates which headers can be used during the actual request.
              schema:
                type: string
            access-control-allow-methods:
              description: Indicates which HTTP methods are allowed when accessing the resource.
              schema:
                type: string
            access-control-expose-headers:
              description: Indicates which headers can be exposed as part of the response.
              schema:
                type: string
            access-control-allow-origin:
              description: Indicates whether the response can be shared with requesting code from the given origin.
              schema:
                type: string
            access-control-max-age:
              description: Indicates how long the results of a preflight request can be cached.
              schema:
                type: string
            x-request-id:
              description: Unique identifier for the request.
              schema:
                type: string
            content-type:
              description: Indicates the media type of the resource.
              schema:
                type: string
            content-length:
              description: Indicates the size of the response body in bytes.
              schema:
                type: string
            date:
              description: Indicates the date and time at which the message was originated.
              schema:
                type: string
            server:
              description: I

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-data-merge-create-rendition-api-openapi.yml