Adobe Suite Custom Scripts API

openapi: 3.2.0
info:
  description: Firefly Service's RESTful InDesign API offers resources to automate tedious, time-consuming design tasks through scalable cloud services, encouraging more personalization at scale, creative automation, and faster content delivery.
  version: ''
  title: Firefly Services - InDesign Custom Scripts API
  termsOfService: https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf
  contact:
    email: idservices@adobe.com
servers:
- url: https://indesign.adobe.io
security:
- AccessToken: []
  X-Api-Key: []
tags:
- name: Custom Scripts
  description: Submit and execute custom scripts for InDesign automation. Supports comprehensive scripting capabilities for document manipulation and processing.
paths:
  /v3/scripts:
    post:
      summary: Submit a Custom Script
      description: Submits custom script bundles for registration. Returns a URL for posting execution requests for the registered script.
      operationId: submitCustomScript
      tags:
      - Custom Scripts
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
        description: The custom script bundle, in ZIP format. This package describes the script to the app engine.
        required: true
      responses:
        '202':
          description: Status of a job execution.
          content:
            application/json:
              schema:
                properties:
                  capability:
                    type: string
                    description: The name of the custom script, as specified in the custom script manifest.
                  version:
                    type: string
                    description: The version of the custom script, as specified in the custom script manifest.
                  url:
                    type: string
                    description: The URL to submit an execution request for the custom script.
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: List custom scripts API
      description: Retrieves details of the latest version of all registered custom scripts. Includes version, download link, registration date, and script name. Response is paginated based on list length.
      operationId: listCustomScripts
      tags:
      - Custom Scripts
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of registered custom scripts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomScriptsListResponse'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/{script_id}/{script_name}:
    post:
      summary: Submit a custom script execution request
      description: Submits execution requests for custom scripts. Defines input assets and parameters that the custom script will use during execution.
      operationId: executeCustomScript
      tags:
      - Custom Scripts
      parameters:
      - name: script_id
        in: path
        description: script_id as reported in the response to custom script submit request.
        required: true
        schema:
          type: string
      - name: script_name
        in: path
        description: The name of the custom script, specified in the custom script manifest.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseJobRequestWithOutput'
        description: This job request object specifies parameters for the execution of the custom script.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/scripts/{script_name}:
    get:
      summary: Get Custom Script details
      description: Retrieves details of a single registered custom script. Includes version, download link, registration date, and script name.
      operationId: getCustomScriptDetails
      tags:
      - Custom Scripts
      parameters:
      - name: script_name
        in: path
        description: Name of the custom script
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Details of the custom script
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomScriptDetails'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete a Custom Script
      description: Deletes a single registered custom script. All versions of the script will be permanently removed.
      operationId: deleteCustomScript
      tags:
      - Custom Scripts
      parameters:
      - name: script_name
        in: path
        description: Name of the custom script to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Script successfully deleted
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/scripts/{script_name}/app-version:
    put:
      summary: Update Custom Script App Version
      description: 'Updates the InDesign app version configuration for a registered custom script. Allows customers to specify version strategies: use latest version, fix to a major version, or fix to a specific major and minor version.'
      operationId: updateScriptAppVersion
      tags:
      - Custom Scripts
      parameters:
      - name: script_name
        in: path
        description: Name of the custom script to update
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppVersionUpdateRequest'
        description: Configuration for the app version strategy. The majorAppVersion and minorAppVersion fields are optional and their requirement depends on the selected strategy.
      responses:
        '200':
          description: App version configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: App version configuration updated successfully
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v3/app-versions:
    get:
      summary: Get Current App Versions
      description: Retrieves information about all available InDesign app versions. Returns major version, minor version, and status for each registered app version.
      operationId: listAppVersions
      tags:
      - Custom Scripts
      parameters: []
      responses:
        '200':
          description: List of registered app versions for the product
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppVersionInfo'
        '400':
          $ref: '#/components/responses/BadParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The format of the content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Retry-After:
          schema:
            type: integer
          description: The number of seconds until the user should try again.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    Accepted:
      description: The job has been accepted for processing.
      content:
        application/json:
          schema:
            properties:
              jobId:
                type: string
                description: The job ID.
              statusUrl:
                type: string
                description: The status URL.
      headers:
        link:
          schema:
            type: string
          description: The status URL for a retry.
        retry-after:
          schema:
            type: integer
          description: The number of seconds until the user should try again.
        Content-Type:
          schema:
            type: string
          description: The type of content that is returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
    BadParams:
      description: Bad Parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Content-Type:
          schema:
            type: string
          description: The type of content returned (e.g., `application/json`).
        Content-Length:
          schema:
            type: integer
          description: The length of the response content.
        Access-Control-Allow-Origin:
          schema:
            type: string
          description: The Cross Origin Resource Sharing (CORS) header.
        Access-Control-Allow-Methods:
          schema:
            type: string
          description: This header indicates what HTTP methods are allowed.
        Access-Control-Allow-Headers:
          schema:
            type: string
          description: This indicates which HTTP headers can be used during the actual request.
        Access-Control-Allow-Credentials:
          schema:
            type: string
          description: This header is used by servers to indicate that the client shall share HTTP responses.
        Access-Control-Max-Age:
          schema:
            type: integer
          description: This indicates how long the results of a preflight request can be cached.
  schemas:
    BaseJobRequest:
      description: The base job request for any job.
      required:
      - assets
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/InputAsset'
          description: Information about the assets, which will be used to process the job.
        params:
          type: object
          properties:
            generalSettings:
              description: General settings.
              type: object
              properties:
                fonts:
                  description: Settings related to fonts. It is recommended to include fonts to avoid missing fonts warnings when processing the job.
                  type: object
                  properties:
                    fontsDirectories:
                      description: This lists the font directories for the input InDesign documents. "Document Fonts" in parallel to the document will continue to work even without specifying them.  <br></br> If none are specified, a temporary base directory (working directory) will be considered as a font directory.
                      type: array
                      items:
                        type: string
                        description: This provides a path to a directory relative to a temporary base directory (working directory) where the fonts can be found. It cannot go up using '..' or '/'. Should be a valid path. For specifying a working directory, mention '.'.
                links:
                  description: Settings related to links.
                  type: object
                  properties:
                    replaceLinks:
                      type: array
                      items:
                        type: object
                        required:
                        - targetDocument
                        - mapping
                        properties:
                          targetDocument:
                            description: The document in which the relinking is to be done. Relinking of assets is required to ensure that there are no missing links in the output document.
                            type: string
                          mapping:
                            type: array
                            items:
                              type: object
                              required:
                              - newAssetRelativePath
                              properties:
                                newAssetRelativePath:
                                  type: string
                                  description: This provides a path relative to a temporary base directory (working directory) where the asset to be linked to can be found. It cannot go up using '..' or '/'. Should be a valid file name.
                                currentURI:
                                  type: string
                                  description: The existing URI of the link that needs relinking. If multiple links with this URI are found, all will be relinked. If `linkID` is provided, this attribute will be ignored. Either `currentURI` or `linkID` should be present.
                                linkID:
                                  type: integer
                                  description: The ID of the link which is to be relinked. If `currentURI` is also provided, it will be ignored. Either `currentURI` or `linkID` should be present.
                appLogs:
                  description: Describes parameters regarding application logs.
                  type: object
                  properties:
                    logsRelativePath:
                      type: string
                      description: This provides a path to a file, relative to the temporary base directory (working directory). This file is where the application's logs are to be dumped.
    CustomScriptDetails:
      type: object
      description: Details of a custom script
      properties:
        version:
          type: string
          description: Version of the custom script
          example: 1.0.2
        url:
          type: string
          description: URL that was generated during registration
          example: https://indesign.adobe.io/v3/634aaf2dd50c8d198/idml/export
        downloadurl:
          type: string
          description: Pre-signed URL for downloading the script (valid for 30 minutes)
          example: https://example.com/download/script.zip
        createdDate:
          type: string
          format: date-time
          description: Registration date of the script
          example: '2025-07-03T08:44:26.051Z'
        scriptName:
          type: string
          description: Name of the custom script
          example: 3p-testing/test1
        appVersionStrategy:
          type: string
          description: Strategy used to determine the InDesign app version for this script
          enum:
          - latest_version
          - fixed_major_version
          - fixed_major_and_minor_version
          example: fixed_major_and_minor_version
        majorAppVersion:
          type: string
          description: Major version of the InDesign app required for this script
          example: '20'
        minorAppVersion:
          type: string
          description: Minor version of the InDesign app required for this script
          example: '1'
    BaseJobRequestWithOutput:
      allOf:
      - $ref: '#/components/schemas/BaseJobRequest'
      - description: The base job request for any job with the option to specify output URLs.
        type: object
        properties:
          outputs:
            type: array
            items:
              $ref: '#/components/schemas/OutputAsset'
    CustomScriptsListResponse:
      type: object
      description: Response containing list of registered custom scripts
      properties:
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/CustomScriptDetails'
        paging:
          type: object
          properties:
            nextUrl:
              type: string
              description: URL for the next page of results
              example: https://indesign.adobe.io/api/v3/scripts?page=1
    AppVersionInfo:
      type: object
      description: Information about a registered InDesign app version
      properties:
        product:
          type: string
          description: The product name
          example: indesign
        majorAppVersion:
          type: string
          description: Major version of the InDesign app
          example: '20'
        minorAppVersion:
          type: string
          description: Minor version of the InDesign app
          example: '1'
        status:
          type: string
          description: Status of this app version
          enum:
          - active
          - preview
          example: active
    AppVersionUpdateRequest:
      type: object
      description: Request body for updating app version configuration for a custom script
      required:
      - appVersionStrategy
      properties:
        appVersionStrategy:
          type: string
          description: Strategy for determining the InDesign app version to use. latest_version uses the most recent version, fixed_major_version locks to a major version, fixed_major_and_minor_version locks to a specific version.
          enum:
          - latest_version
          - fixed_major_version
          - fixed_major_and_minor_version
          example: fixed_major_and_minor_version
        majorAppVersion:
          type: string
          description: Major version of the InDesign app. Required when appVersionStrategy is fixed_major_version or fixed_major_and_minor_version.
          example: '20'
        minorAppVersion:
          type: string
          description: Minor version of the InDesign app. Required when appVersionStrategy is fixed_major_and_minor_version.
          example: '1'
    OutputAsset:
      description: The URL where the output assets are to be posted after the job is processed.
      type: object
      required:
      - destination
      - source
      properties:
        destination:
          type: object
          required:
          - url
          properties:
            url:
              type: string
              description: The URL of the asset.
            storageType:
              type: string
              description: This is an optional parameter, however IT IS RECOMMENDED to provide this information.
              enum:
              - Azure
              - Dropbox
              - AWS
        source:
          type: string
          description: This provides a path relative of the output where the resource would be generated. It cannot go up using '..' or '/'. Should be a valid file name.
    InputAsset:
      type: object
      description: The URL where the asset will be fetched.
      required:
      - source
      properties:
        source:
          type: object
          required:
          - url
          properties:
            url:
              type: string
              description: The pre-signed URL of the input asset. This is the URL of the asset that will be downloaded and acted upon during the job.
        destination:
          type: string
          description: This provides a path relative to a temporary base directory (working directory) where the resource would be downloaded. This would be used to identify the assets within the parameters. It cannot go up using '..' or '/'. Should be a valid file name.
    Error:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: string
      required:
      - message
      - error_code
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: The Adobe-generated access token, S2S format.
    X-Api-Key:
      type: apiKey
      name: x-api-key
      in: header
      description: The client ID for authentication.