openapi: 3.0.3
info:
  title: Firefly Creative Production Workflow API
  version: "1.0"
  description: |
    Firefly Creative Production Workflow API for executing workflows and creating assets at scale.

    Runtime batch requests use the HTTP header `api-version` to pin the API version.

    - If you **omit** `api-version`, the service assumes **`1.0`**.
    - If you send an **unsupported** value, the API returns **HTTP 400** with `status: "error"` in the JSON body.
    - **Responses** include an **`api-version`** header indicating which contract handled the request (the value you sent, or **`1.0`** when omitted).
  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://run-workflow.adobe.io
    description: Production

tags:
  - name: Batches
    description: Execute published workflows over multiple assets, list batches, monitor status, cancel jobs, and retrieve per-asset results

paths:
  /batch/execute:
    post:
      tags:
        - Batches
      summary: Execute a batch of assets through a workflow
      description: |
        Start a new batch job to process multiple assets through a published workflow.

        The request body supplies the workflow identifier and `inputs`: a list of runs, where each run is an array of node input mappings (`node_id` plus `content` and/or `template`).

        Each run is processed separately through the workflow in parallel.

        Returns a `batchId` and `links` that can be used to track progress and retrieve results.
      operationId: batchExecute
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchExecuteRequest'
            example:
              workflow:
                workflowId: "121dc48a-f50b-427a-8aeb-f84c12c946a8"
                inputs:
                  - - node_id: "node_1775258981781_301b7cc7v_0_j5iaha"
                      content:
                        - presignedUrl: "{presigned_url_1}"
                          storageType: "AWS"
                        - presignedUrl: "{presigned_url_2}"
                          storageType: "AWS"
                    - node_id: "node_1775258983939_zoc3490s7_1_7jx86h"
                      content:
                        - presignedUrl: "{presigned_url_1}"
                          storageType: "AWS"
                        - presignedUrl: "{presigned_url_2}"
                          storageType: "AWS"
                    - node_id: "node_1775258991082_1lfvzsgqz_2_vhjjoc"
                      content: "{text}"
                    - node_id: "node_1775259058091_zzgybxfcg_5_j6g2al"
                      content: "{text}"
                    - node_id: "node-1775259002055-ztu8i4fpz"
                      template:
                        presignedUrl: "{presignedUrl}"
                        storageType: "AWS"
      responses:
        '202':
          description: Accepted
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersionResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExecuteAcceptedResponse'
              example:
                batchId: "batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb"
                workflowId: "run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9"
                status: "pending"
                assets:
                  total: 1
                  pending: 1
                  processing: 0
                  completed: 0
                  failed: 0
                createdAt: "2026-04-03T23:46:39.374Z"
                links:
                  result:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb/status?format=preview"
                  status:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb/status"
                  cancel:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb/cancel"
                  executions:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb/executions"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /batches:
    get:
      tags:
        - Batches
      summary: List batches
      description: |
        List all batches created by the authenticated user within their organization.

        Results are automatically filtered by the authenticated user's ID.
        Users can only view their own batches, not batches created by other users in the organization.

        Results are sorted by creation date (most recent first) and include pagination metadata.
      operationId: listBatches
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: status
          in: query
          description: Filter by batch status.
          schema:
            type: string
            enum: [pending, running, completed, failed, cancelled]
        - name: workflowId
          in: query
          description: Filter by workflow ID.
          schema:
            type: string
        - name: createdAfter
          in: query
          description: Filter by creation date (ISO 8601 format).
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter by creation date (ISO 8601 format).
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results per page (default 50, max 100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          description: Pagination offset (default 0).
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Success
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersionResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchesResponse'
              example:
                orgId: "A1B2C3D4567890ABCDEFFEDA51@AdobeOrg"
                batches:
                  - batchId: "batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301"
                    workflowId: "run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    jobName: "Product catalog resize"
                    status: "completed"
                    assets:
                      total: 1
                      pending: 0
                      processing: 0
                      completed: 1
                      failed: 0
                    executions:
                      total: 1
                      completed: 1
                      failed: 0
                      allExecutionIds:
                        - "batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301_exec-0"
                      failedExecutionIds: []
                    endpoint: "batch"
                    createdAt: "2026-04-15T14:22:10.120Z"
                    updatedAt: "2026-04-15T14:23:45.880Z"
                    completedAt: "2026-04-15T14:23:45.600Z"
                  - batchId: "batch-run-workflow_f9e8d7c6-b5a4-3210-fedc-ba9876543210-20260415-def45602"
                    workflowId: "run-workflow_f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                    jobName: "Social crops batch"
                    status: "running"
                    assets:
                      total: 2
                      pending: 2
                      processing: 0
                      completed: 0
                      failed: 0
                    executions:
                      total: 2
                      completed: 0
                      failed: 0
                      allExecutionIds:
                        - "batch-run-workflow_f9e8d7c6-b5a4-3210-fedc-ba9876543210-20260415-def45602_exec-0"
                        - "batch-run-workflow_f9e8d7c6-b5a4-3210-fedc-ba9876543210-20260415-def45602_exec-1"
                      failedExecutionIds: []
                    endpoint: "batch"
                    createdAt: "2026-04-15T13:05:00.000Z"
                    updatedAt: "2026-04-15T13:07:12.340Z"
                    completedAt: null
                pagination:
                  limit: 50
                  offset: 0
                  count: 2
                  hasMore: false
                filters:
                  status: "completed"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /batch/{batchId}/status:
    get:
      tags:
        - Batches
      summary: Get batch status
      description: |
        Get the current status and progress of a batch job.

        Returns the batch identifier, workflow identifier, status, asset and execution counters (including execution IDs), timestamps, and hypermedia links to cancel or list executions.
      operationId: getBatchStatus
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: batchId
          in: path
          required: true
          description: Batch identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersionResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              example:
                batchId: "batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301"
                workflowId: "run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                status: "completed"
                assets:
                  total: 1
                  pending: 0
                  processing: 0
                  completed: 1
                  failed: 0
                executions:
                  total: 1
                  completed: 1
                  failed: 0
                  allExecutionIds:
                    - "batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301_exec-0"
                  failedExecutionIds: []
                createdAt: "2026-04-15T14:22:10.120Z"
                updatedAt: "2026-04-15T14:23:45.880Z"
                completedAt: "2026-04-15T14:23:45.600Z"
                links:
                  cancel:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301/cancel"
                  executions:
                    href: "https://run-workflow.adobe.io/batch/batch-run-workflow_a1b2c3d4-e5f6-7890-abcd-ef1234567890-20260415-abc12301/executions"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /batch/{batchId}/cancel:
    post:
      tags:
        - Batches
      summary: Cancel a batch
      description: |
        Cancel a batch job that is currently pending or running.

        Once cancelled, no new assets will be processed. Assets currently being
        processed may complete. The batch status will be updated to 'cancelled'.

        Cannot cancel batches that are already completed, failed, or cancelled.
      operationId: cancelBatch
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: batchId
          in: path
          required: true
          description: Batch identifier.
          schema:
            type: string
      responses:
        '200':
          description: Success
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersionResponse'
          content:
            application/json:
              schema:
                type: object
                properties:
                  batchId:
                    type: string
                  status:
                    type: string
                    enum: [cancelled]
                  message:
                    type: string
                  previousStatus:
                    type: string
                  assets:
                    $ref: '#/components/schemas/BatchAssetCounts'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /batch/{batchId}/executions:
    get:
      tags:
        - Batches
      summary: List individual execution results
      description: |
        List all individual asset execution results within a batch, with optional filtering.

        Returns detailed results for each asset including:
        - Execution status (pending, running, success, failed)
        - Input asset data
        - Output results (if successful)
        - Error messages (if failed)
        - Timing information

        The response supports pagination and filtering by execution status.
      operationId: listBatchExecutions
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: batchId
          in: path
          required: true
          description: Batch identifier.
          schema:
            type: string
        - name: status
          in: query
          description: Filter by execution status.
          schema:
            type: string
            enum: [pending, running, success, failed]
        - name: limit
          in: query
          description: Maximum number of results (default 100).
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: offset
          in: query
          description: Pagination offset (default 0).
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Success
          headers:
            api-version:
              $ref: '#/components/headers/ApiVersionResponse'
          content:
            application/json:
              schema:
                type: object
                properties:
                  batchId:
                    type: string
                  total:
                    type: integer
                    description: Total number of assets in batch.
                  executions:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatchExecutionResult'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      count:
                        type: integer
                      hasMore:
                        type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  parameters:
    ApiVersion:
      name: api-version
      in: header
      required: false
      example: "1.0"
      description: |
        Public API contract version for **batch** operations (`/batch/…`, `GET /batches`). The supported value is **`1.0`**.
        If omitted, the service assumes **`1.0`**. Unsupported values return **400** with `status: "error"`.
      schema:
        type: string
        enum:
          - "1.0"
        default: "1.0"

  headers:
    ApiVersionResponse:
      description: |
        Echoes the contract version that handled the request. Matches the `api-version` request header, or **`1.0`** when the client omitted it.
      schema:
        type: string
        example: "1.0"

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authorization.

  schemas:
    BatchExecuteRequest:
      type: object
      description: Batch execute request payload.
      required:
        - workflow
      properties:
        workflow:
          $ref: '#/components/schemas/BatchExecuteWorkflow'

    BatchExecuteWorkflow:
      type: object
      description: Published workflow identifier and per-run input mappings by node ID.
      required:
        - workflowId
        - inputs
      properties:
        workflowId:
          type: string
          format: uuid
          description: Identifier of the published workflow to run.
          example: "121dc48a-f50b-427a-8aeb-f84c12c946a8"
        inputs:
          type: array
          description: |
            Outer list: each element is one parallel batch execution. Inner list: node input mappings for that execution (images, text, templates, and so on).
          items:
            type: array
            description: Node input mappings for a single workflow execution.
            minItems: 1
            items:
              $ref: '#/components/schemas/BatchWorkflowNodeInput'

    PresignedStorageRef:
      type: object
      description: Asset location using a presigned URL and storage kind.
      required:
        - presignedUrl
      properties:
        presignedUrl:
          type: string
          format: uri
          description: Presigned GET URL for the asset.
          example: "https://storage.example.com/bucket/asset.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"
        storageType:
          type: string
          description: Storage provider for the presigned URL.
          example: "AWS"

    BatchWorkflowNodeInput:
      oneOf:
        - $ref: '#/components/schemas/BatchNodeInputContentAssets'
        - $ref: '#/components/schemas/BatchNodeInputContentText'
        - $ref: '#/components/schemas/BatchNodeInputTemplate'

    BatchNodeInputContentAssets:
      type: object
      description: Maps a workflow node to one or more image (or binary) inputs via presigned URLs.
      required:
        - node_id
        - content
      properties:
        node_id:
          type: string
          description: Workflow canvas node identifier for this input.
          example: "node_1775258981781_301b7cc7v_0_j5iaha"
        content:
          type: array
          description: List of presigned asset references for this node.
          minItems: 1
          items:
            $ref: '#/components/schemas/PresignedStorageRef'

    BatchNodeInputContentText:
      type: object
      description: Maps a workflow node to a text input value.
      required:
        - node_id
        - content
      properties:
        node_id:
          type: string
          description: Workflow canvas node identifier for this input.
          example: "node_1775258991082_1lfvzsgqz_2_vhjjoc"
        content:
          type: string
          description: Text content for the node.
          example: "Summer campaign headline"

    BatchNodeInputTemplate:
      type: object
      description: Maps a workflow node to a template file via presigned URL.
      required:
        - node_id
        - template
      properties:
        node_id:
          type: string
          description: Workflow canvas node identifier for this input.
          example: "node-1775259002055-ztu8i4fpz"
        template:
          $ref: '#/components/schemas/PresignedStorageRef'

    BatchExecuteAcceptedResponse:
      type: object
      description: Response returned when a batch job is accepted for processing.
      required:
        - batchId
        - workflowId
        - status
        - assets
        - createdAt
        - links
      properties:
        batchId:
          type: string
          description: Unique batch identifier.
          example: "batch-run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9-20260403-750642eb"
        workflowId:
          type: string
          description: Identifier of the workflow associated with this batch.
          example: "run-workflow_2402b5a2-bd2b-4309-a4a4-d7983bba64e9"
        status:
          type: string
          enum: [pending, running, completed, failed, cancelled]
          description: Current batch status.
        assets:
          $ref: '#/components/schemas/BatchAssetCounts'
        createdAt:
          type: string
          format: date-time
          description: Batch creation timestamp.
        links:
          $ref: '#/components/schemas/BatchExecuteLinks'

    BatchHrefLink:
      type: object
      description: Hypermedia link with an absolute URL.
      required:
        - href
      properties:
        href:
          type: string
          format: uri
          description: Target URL for the related resource.

    BatchExecuteLinks:
      type: object
      description: Hypermedia links for batch status, preview result, cancellation, and executions.
      required:
        - result
        - status
        - cancel
        - executions
      properties:
        result:
          description: Link to batch status with preview-friendly formatting (`format=preview`).
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'
        status:
          description: Link to poll batch status.
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'
        cancel:
          description: Link to cancel the batch job.
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'
        executions:
          description: Link to list per-asset executions for the batch.
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'

    BatchStatusDetailLinks:
      type: object
      description: Hypermedia links returned when getting a single batch by ID.
      required:
        - cancel
        - executions
      properties:
        cancel:
          description: Link to cancel the batch job.
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'
        executions:
          description: Link to list per-asset executions for the batch.
          allOf:
            - $ref: '#/components/schemas/BatchHrefLink'

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message.
        message:
          type: string
          description: Additional error details.
        status:
          type: string
          enum:
            - failed
            - error
          description: |
            Error category. Use **`error`** for contract failures such as an unsupported `api-version` value (HTTP 400). Other validation errors often use **`failed`**.

    BatchConfig:
      type: object
      description: Batch configuration options.
      properties:
        concurrencyLimit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Maximum concurrent executions per chunk.
        priority:
          type: string
          enum: [HIGH, NORMAL, LOW]
          default: NORMAL
          description: Batch priority for fair-share throttling.
        continueOnError:
          type: boolean
          default: true
          description: Continue processing remaining assets if some fail.
        webhookUrl:
          type: string
          format: uri
          description: Optional webhook URL for completion notification.

    BatchAssetCounts:
      type: object
      description: Asset counts for batch progress tracking.
      properties:
        total:
          type: integer
          description: Total number of assets in the batch.
        pending:
          type: integer
          description: Assets waiting to be processed.
        processing:
          type: integer
          description: Assets currently being processed.
        completed:
          type: integer
          description: Successfully completed assets.
        failed:
          type: integer
          description: Failed assets.

    ListBatchesResponse:
      type: object
      description: Paginated list of batches for the authenticated user within their organization.
      required:
        - orgId
        - Batches
        - pagination
      properties:
        orgId:
          type: string
          description: IMS organization ID for the authenticated caller.
          example: "A1B2C3D4567890ABCDEFFEDA51@AdobeOrg"
        batches:
          type: array
          description: Batch summaries, typically sorted with the most recently created first.
          items:
            $ref: '#/components/schemas/BatchListItem'
        pagination:
          $ref: '#/components/schemas/BatchListPagination'
        filters:
          type: object
          description: Echo of query parameters applied to this response.
          properties:
            status:
              type: string
              description: Status filter, if provided.
            workflowId:
              type: string
              description: Workflow ID filter, if provided.
            createdAfter:
              type: string
              format: date-time
              description: Created-after filter, if provided.
            createdBefore:
              type: string
              format: date-time
              description: Created-before filter, if provided.

    BatchListPagination:
      type: object
      description: Pagination metadata for batch list results.
      required:
        - limit
        - offset
        - count
        - hasMore
      properties:
        limit:
          type: integer
          description: Maximum number of batches returned per page.
          example: 50
        offset:
          type: integer
          description: Zero-based index of the first batch in this page.
          example: 0
        count:
          type: integer
          description: Number of batch records returned in this page.
          example: 3
        hasMore:
          type: boolean
          description: Whether additional pages exist beyond this result set.
          example: false

    BatchExecutionsSummary:
      type: object
      description: Execution counts and identifiers for a batch.
      required:
        - total
        - completed
        - failed
        - allExecutionIds
        - failedExecutionIds
      properties:
        total:
          type: integer
          description: Total number of executions in the batch.
        completed:
          type: integer
          description: Number of executions that finished successfully.
        failed:
          type: integer
          description: Number of executions that failed.
        allExecutionIds:
          type: array
          description: Identifiers for all executions in the batch.
          items:
            type: string
        failedExecutionIds:
          type: array
          description: Identifiers of failed executions, suitable for retry or inspection.
          items:
            type: string

    BatchListItem:
      type: object
      description: Summary of a single batch as returned by the list batches endpoint.
      required:
        - batchId
        - workflowId
        - jobName
        - status
        - assets
        - executions
        - endpoint
        - createdAt
        - updatedAt
      properties:
        batchId:
          type: string
          description: Unique batch identifier.
        workflowId:
          type: string
          description: Identifier of the workflow run for this batch.
        jobName:
          type: string
          description: Display name of the workflow job.
        status:
          type: string
          enum: [pending, running, completed, failed, cancelled]
          description: Current batch status.
        assets:
          $ref: '#/components/schemas/BatchAssetCounts'
        executions:
          $ref: '#/components/schemas/BatchExecutionsSummary'
        endpoint:
          type: string
          enum: [batch, preview, execute]
          description: API surface used to create the batch.
        createdAt:
          type: string
          format: date-time
          description: Batch creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp.
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: Completion timestamp when the batch has finished, or null if still in progress.

    BatchStatusResponse:
      type: object
      description: Current status and progress for a single batch job.
      required:
        - batchId
        - workflowId
        - status
        - assets
        - executions
        - createdAt
        - updatedAt
        - links
      properties:
        batchId:
          type: string
          description: Unique batch identifier.
        workflowId:
          type: string
          description: Identifier of the workflow run for this batch.
        status:
          type: string
          enum: [pending, running, completed, failed, cancelled]
          description: Current batch status.
        assets:
          $ref: '#/components/schemas/BatchAssetCounts'
        executions:
          $ref: '#/components/schemas/BatchExecutionsSummary'
        createdAt:
          type: string
          format: date-time
          description: Batch creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp.
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: Completion timestamp when the batch has finished, or null if still in progress.
        links:
          $ref: '#/components/schemas/BatchStatusDetailLinks'

    BatchExecutionResult:
      type: object
      description: Individual execution result within a batch.
      properties:
        executionId:
          type: string
          description: Execution ID.
        batchId:
          type: string
          description: Batch ID this execution belongs to.
        assetIndex:
          type: integer
          description: Asset index in the batch.
        inputAsset:
          type: object
          description: Input asset data.
          properties:
            index:
              type: integer
            assetId:
              type: string
            inputs:
              type: array
              items:
                type: object
        status:
          type: string
          enum: [pending, running, success, failed]
          description: Execution status.
        error:
          type: string
          description: Error message if failed.
        outputs:
          type: array
          description: Output results if successful.
          items:
            type: object
        startedAt:
          type: string
          format: date-time
          description: Execution start time.
        completedAt:
          type: string
          format: date-time
          description: Execution completion time.
        durationMs:
          type: integer
          description: Duration in milliseconds.

  responses:
    BadRequest:
      description: |
        Bad request. May include `status: "error"` when the request violates a contract (for example an unsupported **`api-version`** on batch routes).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidInput:
              summary: Typical validation failure
              value:
                error: "Invalid request"
                message: "Request body is not valid JSON"
                status: "failed"
            unsupportedApiVersion:
              summary: Unsupported api-version (batch routes)
              value:
                status: "error"
                error: "The api-version value is not supported. Supported version: 1.0"

    NotFound:
      description: Requested Resource Was Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Not found"
            message: "Workflow or batch not found"
            status: "failed"

    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Internal server error"
            message: "An unexpected error occurred"
            status: "failed"

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Unauthorized"
            message: "Missing or invalid authentication"
            status: "failed"