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.

    ## Authentication

    Every endpoint below requires all four of the following, together:
    - `Authorization` header: ****** for authorization
    - `x-api-key` header: API key for authentication
    - `x-gw-ims-org-id` header: IMS organization ID, scopes the request to that organization
    - `x-gw-ims-user-id` header: IMS user ID

    ## Rate limiting

    Rate limits are applied per organization and user. When exceeded, a request returns
    **HTTP 429**. Responses include the current rate-limit window in these headers:
    - `x-ratelimit-limit`: Maximum number of requests allowed
    - `x-ratelimit-remaining`: Number of requests remaining
    - `x-ratelimit-reset`: Unix timestamp when the rate limit resets

    ## Contract versioning

    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
  - name: Workflows
    description: Publish, read, update, and delete workflows, manage in-progress drafts, and preview a workflow before publishing
  - name: Catalog
    description: Discover the actions available for building workflow definitions programmatically

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: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - 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: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - 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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - 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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - 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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /catalog/actions:
    get:
      tags:
        - Catalog
      summary: List catalog actions
      description: |
        Returns every workflow action available for building or introspecting workflow
        definitions programmatically. Results include Adobe's built-in actions
        (`orgId: "adobe"`) plus any custom actions registered under the caller's own
        organization.
      operationId: listCatalogActions
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - name: workflowEnabled
          in: query
          description: Filter to only actions enabled for the workflow builder UI.
          schema:
            type: boolean
        - name: category
          in: query
          description: Filter to a single category (for example `image`).
          schema:
            type: string
        - name: tags
          in: query
          description: Comma-separated tags. An action must have all of them (AND logic).
          schema:
            type: string
          example: "image,firefly"
        - name: compact
          in: query
          description: |
            Return the minimal `CompactCatalogAction` shape (`actionType`, `description`,
            `disabled`, `workflowEnabled`) instead of the full entry.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Catalog actions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogActionsResponse'
              example:
                catalogVersion: "2026.09.1"
                totalActions: 2
                categories: ["image"]
                actions:
                  - actionType: "remove-background"
                    version: "1.0.0"
                    lifecycle: "ga"
                    name: "Remove Background"
                    description: "Removes the background from an image."
                    category: "image"
                    disabled: false
                    workflowEnabled: true
                    inputs:
                      - name: "image"
                        type: "image"
                        required: true
                        mimeTypes: ["image/png", "image/jpeg"]
                    outputs:
                      - name: "result"
                        type: "image"
                        mimeTypes: ["image/png"]
                    parameters: []
                    tags: ["image", "firefly"]
                  - actionType: "input-images"
                    version: "1.0.0"
                    lifecycle: "ga"
                    name: "Input Images"
                    description: "Source node that provides one or more input images to a workflow."
                    category: "image"
                    disabled: false
                    workflowEnabled: true
                    inputs: []
                    outputs:
                      - name: "images"
                        type: "image"
                        mimeTypes: ["image/png", "image/jpeg"]
                    parameters: []
                    tags: ["image", "input"]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /catalog/actions/{actionType}:
    get:
      tags:
        - Catalog
      summary: Get a specific catalog action
      description: |
        Returns detailed info for a single action, including its input/output ports and
        configurable parameters.
      operationId: getCatalogAction
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: actionType
          in: path
          required: true
          description: Action type identifier.
          schema:
            type: string
          example: "remove-background"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - name: version
          in: query
          description: |
            Specific semantic version to fetch. Omitted resolves the caller-visible
            default (latest active version).
          schema:
            type: string
      responses:
        '200':
          description: Action retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogAction'
              example:
                actionType: "remove-background"
                version: "1.0.0"
                lifecycle: "ga"
                name: "Remove Background"
                description: "Removes the background from an image."
                category: "image"
                disabled: false
                workflowEnabled: true
                inputs:
                  - name: "image"
                    type: "image"
                    required: true
                    mimeTypes: ["image/png", "image/jpeg"]
                outputs:
                  - name: "result"
                    type: "image"
                    mimeTypes: ["image/png"]
                parameters: []
                tags: ["image", "firefly"]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No action matches the given `actionType` for the caller's org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Action type 'unknown-action' not found in catalog"
                status: "failed"
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /workflows:
    get:
      tags:
        - Workflows
      summary: List or get workflows
      description: |
        Lists workflows for the caller's organization, or retrieves a specific workflow
        with its full definition and execution history.

        Provide `workflowId` to retrieve a specific workflow. Otherwise, results are
        listed and can be filtered/paginated with the query parameters below.
      operationId: getWorkflows
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
        - name: workflowId
          in: query
          description: Get a specific workflow by ID (UUID). Omit to list workflows instead.
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of results per page.
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: offset
          in: query
          description: Pagination offset.
          schema:
            type: integer
            default: 0
        - name: scope
          in: query
          description: |
            Set to `org` for the org-wide published list (published workflows visible to
            everyone in the org, not just the author). Omit for the default caller-scoped
            behavior (the caller's own workflows).
          schema:
            type: string
            enum:
              - org
      responses:
        '200':
          description: Workflows retrieved successfully.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/WorkflowListResponse'
                  - $ref: '#/components/schemas/WorkflowDetailResponse'
              examples:
                workflowList:
                  summary: List of workflows
                  value:
                    workflows:
                      - workflowId: "550e8400-e29b-41d4-a716-446655440000"
                        name: "Product photo cleanup"
                        status: "active"
                        workflowType: "run-workflow"
                        createdAt: "2026-04-15T14:22:10.120Z"
                        updatedAt: "2026-04-15T14:23:45.880Z"
                        publishedAt: "2026-04-15T14:23:45.880Z"
                workflowDetail:
                  summary: Single workflow detail (workflowId supplied)
                  value:
                    workflowId: "550e8400-e29b-41d4-a716-446655440000"
                    name: "Product photo cleanup"
                    status: "active"
                    workflowType: "run-workflow"
                    version: "1"
                    workflow:
                      actions: []
                      connections: []
                    executionCount: 5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /publish:
    post:
      tags:
        - Workflows
      summary: Publish a workflow
      description: |
        Publishes a workflow, making it available for execution via `/execute`,
        `/batch/execute`, and `/preview`.

        If a workflow with the same `metadata.workflowId` already exists for the caller,
        the existing UUID is reused; otherwise a new UUID is generated and returned.
      operationId: publishWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishWorkflowRequest'
            example:
              workflow:
                metadata:
                  workflowId: "my-workflow-001"
                  name: "Product photo cleanup"
                actions:
                  - actionId: "action-1"
                    actionType: "input-images"
                  - actionId: "action-2"
                    actionType: "remove-background"
                connections:
                  - connectionId: "conn-1"
                    connectionSource: "action-1"
                    sourcePort: "images"
                    connectionTarget: "action-2"
                    targetPort: "image"
      responses:
        '200':
          description: Workflow published successfully.
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishWorkflowResponse'
              examples:
                newWorkflow:
                  summary: New workflow created
                  value:
                    status: "succeeded"
                    workflowId: "550e8400-e29b-41d4-a716-446655440000"
                    action: "created"
                    metadataWorkflowId: "my-workflow-001"
                reusedWorkflow:
                  summary: Existing workflow reused (same metadata.workflowId)
                  value:
                    status: "succeeded"
                    workflowId: "550e8400-e29b-41d4-a716-446655440000"
                    action: "reused"
                    metadataWorkflowId: "my-workflow-001"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /draft/{workflowId}:
    put:
      tags:
        - Workflows
      summary: Save a workflow draft
      description: |
        Saves an in-progress, unpublished draft of a workflow so it can be resumed later
        without publishing it.
      operationId: saveDraftWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          description: |
            Stable workflow id for the draft (mint a new UUID for a brand-new draft, or
            reuse an existing workflow's id to save a new draft version of it).
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveDraftRequest'
            example:
              matrix:
                actions:
                  - actionId: "action-1"
                    actionType: "input-images"
                connections: []
              name: "Product photo cleanup (draft)"
      responses:
        '200':
          description: Draft saved.
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveDraftResponse'
              example:
                status: "succeeded"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: |
            Either the caller is not a member of the requested organization, or an
            existing workflow with this id belongs to a different author (a draft save
            never overwrites another user's workflow).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                orgMismatch:
                  summary: Header-derived org does not belong to the caller
                  value:
                    error: "You do not have permission to access drafts for workflows in this organization."
                notAuthor:
                  summary: Existing workflow belongs to a different author
                  value:
                    status: "failed"
                    error: "You are not the author of this workflow and cannot save changes to it."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags:
        - Workflows
      summary: Get a workflow's in-progress draft
      description: |
        Returns a short-lived, read-only URL to the caller's own draft, plus the last
        update time so the caller can detect a stale local copy.
      operationId: readDraftWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          description: The workflow whose in-progress draft should be read.
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: A read-only URL to the caller's own draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadDraftResponse'
              example:
                sasUrl: "https://storage.example.com/A1B2C3D4567890ABCDEFFEDA51@AdobeOrg/550e8400/versions/draft/workflow.ui.json?sig=..."
                expiresAt: "2026-07-18T00:15:00.000Z"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
                updatedAt: "2026-07-17T23:50:00.000Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No draft exists for this workflow, or it belongs to a different caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Draft not found"
                status: "failed"
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags:
        - Workflows
      summary: Discard a workflow's in-progress draft
      description: |
        Discards a workflow's in-progress draft. If the workflow has a live published
        version, that published version is kept and the workflow reverts to `active`;
        otherwise (a draft that was never published) the whole workflow is removed.
      operationId: discardDraftWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          description: The workflow whose in-progress draft should be discarded.
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Draft discarded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveDraftResponse'
              example:
                status: "succeeded"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: |
            Either the caller is not a member of the requested organization, or the
            workflow belongs to a different author.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                orgMismatch:
                  summary: Header-derived org does not belong to the caller
                  value:
                    error: "You do not have permission to access drafts for workflows in this organization."
                notAuthor:
                  summary: Workflow belongs to a different author
                  value:
                    status: "failed"
                    error: "You are not the author of this workflow and cannot delete it."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /workflows/{workflowId}/metadata:
    patch:
      tags:
        - Workflows
      summary: Update a workflow's name or description
      description: |
        Updates the `name`/`description` of a workflow, without a full publish. A key
        present in the body but set to `""` clears that field; a key omitted entirely
        leaves it untouched. At least one of `name`/`description` must be present.
      operationId: updateWorkflowMetadata
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New workflow display name.
                description:
                  type: string
                  description: New workflow description.
            example:
              name: "Renamed workflow"
      responses:
        '200':
          description: Workflow metadata updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveDraftResponse'
              example:
                status: "succeeded"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /unpublish/{workflowId}:
    put:
      tags:
        - Workflows
      summary: Unpublish a workflow
      description: |
        Unpublishes a published workflow: it is no longer returned by `GET /workflows`
        (default scope) and can no longer be executed. The workflow is retained (not
        deleted) and reverts to an editable draft — republishing resumes from there.
        Unpublishing also revokes any shares for the workflow.
      operationId: unpublishWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          description: The published workflow's UUID.
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Workflow successfully unpublished.
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveDraftResponse'
              example:
                status: "succeeded"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
                message: "Workflow successfully unpublished"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            The workflow has a draft version that must be published or deleted before
            unpublishing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: "failed"
                error: "DRAFT_VERSION_EXISTS"
                message: "This workflow has a draft version. Please publish or delete the draft version before unpublishing."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /workflow/{workflowId}:
    delete:
      tags:
        - Workflows
      summary: Delete a workflow
      description: |
        Permanently deletes a workflow: its published version(s), execution history, any
        in-progress draft, and any shares.
      operationId: deleteWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: workflowId
          in: path
          required: true
          description: The workflow to delete.
          schema:
            type: string
          example: "550e8400-e29b-41d4-a716-446655440000"
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Workflow deleted.
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveDraftResponse'
              example:
                status: "succeeded"
                workflowId: "550e8400-e29b-41d4-a716-446655440000"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /preview:
    post:
      tags:
        - Workflows
      summary: Preview a workflow
      description: |
        Runs a workflow definition without publishing it first — useful for testing a
        workflow while building it. Returns links for polling status and cancelling.
      operationId: previewWorkflow
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewWorkflowRequest'
            example:
              metadata:
                workflowId: "my-workflow-001"
                name: "Product photo cleanup"
              actions:
                - actionId: "action-1"
                  actionType: "input-images"
                  parameters:
                    images:
                      - name: "photo.jpg"
                        sourceUrl: "https://example.com/photo.jpg"
                - actionId: "action-2"
                  actionType: "remove-background"
              connections:
                - connectionId: "conn-1"
                  connectionSource: "action-1"
                  sourcePort: "images"
                  connectionTarget: "action-2"
                  targetPort: "image"
      responses:
        '200':
          description: Workflow preview started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewWorkflowResponse'
              example:
                links:
                  result:
                    href: "https://run-workflow.adobe.io/preview/9f8e7d6c-5b4a-3210-fedc-ba9876543210"
                  cancel:
                    href: "https://run-workflow.adobe.io/preview/9f8e7d6c-5b4a-3210-fedc-ba9876543210/cancel"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: |
            An `Idempotency-Key` was reused with a different request body than the
            original request that used it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Idempotency key conflict"
                status: "failed"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /preview/{instanceId}:
    post:
      tags:
        - Workflows
      summary: Query workflow preview status
      description: Retrieves the current status of a workflow preview.
      operationId: queryPreviewStatus
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: instanceId
          in: path
          required: true
          description: The instance ID returned by `POST /preview`.
          schema:
            type: string
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Preview status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewStatusResponse'
              example:
                instanceId: "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
                runtimeStatus: "Completed"
                output:
                  result:
                    href: "https://storage.example.com/output/result.png?sig=..."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /preview/{instanceId}/cancel:
    post:
      tags:
        - Workflows
      summary: Cancel a workflow preview
      description: Cancels a running workflow preview.
      operationId: cancelPreview
      security:
        - BearerAuth: []
          ApiKeyAuth: []
      parameters:
        - name: instanceId
          in: path
          required: true
          description: The instance ID of the workflow preview to cancel.
          schema:
            type: string
        - $ref: '#/components/parameters/OrgId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Cancellation request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewCancelResponse'
              example:
                message: "Cancellation request accepted"
                instanceId: "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
                status: "canceling"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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"

    OrgId:
      name: x-gw-ims-org-id
      in: header
      required: true
      description: IMS organization ID for the authenticated caller. Scopes every request to that organization.
      schema:
        type: string
      example: "A1B2C3D4567890ABCDEFFEDA51@AdobeOrg"

    UserId:
      name: x-gw-ims-user-id
      in: header
      required: true
      description: IMS user ID for the authenticated caller.
      schema:
        type: string

  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"

    RateLimitLimit:
      description: Maximum number of requests allowed in the current rate-limit window.
      schema:
        type: integer

    RateLimitRemaining:
      description: Number of requests remaining in the current rate-limit window.
      schema:
        type: integer

    RateLimitReset:
      description: Unix timestamp (seconds) when the current rate-limit window resets.
      schema:
        type: integer

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authorization.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Required together with the bearer token and the `x-gw-ims-org-id`/`x-gw-ims-user-id` headers.

  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.
      additionalProperties: false
      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.
      additionalProperties: false
      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.
      additionalProperties: false
      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.

    CatalogPort:
      type: object
      description: An action's input or output port definition.
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Port name.
        label:
          type: string
          description: Human-readable display label.
        type:
          type: string
          description: Port type (for example `image`, `text`, `video`, `asset`, `any`).
        required:
          type: boolean
          description: Whether this port is required (input ports only).
        mimeTypes:
          type: array
          items:
            type: string
          description: Supported MIME types.

    CatalogParameter:
      type: object
      description: An action's configurable parameter definition.
      required:
        - name
        - type
      properties:
        name:
          type: string
        label:
          type: string
          description: Human-readable label.
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - object
            - array
          description: The JSON value shape of this parameter.
        required:
          type: boolean
        defaultValue:
          description: Default value, typed per `type`.
        description:
          type: string

    CatalogAction:
      type: object
      description: A single action entry in the catalog.
      required:
        - actionType
        - version
        - name
        - description
        - category
        - disabled
        - workflowEnabled
        - inputs
        - outputs
        - parameters
        - tags
      properties:
        actionType:
          type: string
          description: Canonical action identifier (kebab-case).
        version:
          type: string
          description: Semantic version.
        lifecycle:
          type: string
          enum:
            - preview
            - beta
            - ga
            - deprecated
          description: Lifecycle state.
        name:
          type: string
          description: Human-readable action name.
        description:
          type: string
        category:
          type: string
          description: Grouping category (for example `image`).
        disabled:
          type: boolean
        workflowEnabled:
          type: boolean
          description: Whether this action is visible in the workflow builder UI.
        workflowRole:
          type: string
          enum:
            - source
            - sink
            - processing
          description: Role in workflow graph validation. Defaults to `processing` when omitted.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/CatalogPort'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/CatalogPort'
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/CatalogParameter'
        tags:
          type: array
          items:
            type: string

    CompactCatalogAction:
      type: object
      description: |
        Minimal catalog entry shape, returned instead of `CatalogAction` when
        `?compact=true` is set on `GET /catalog/actions`.
      additionalProperties: false
      required:
        - actionType
        - description
        - disabled
        - workflowEnabled
      properties:
        actionType:
          type: string
        description:
          type: string
        disabled:
          type: boolean
        workflowEnabled:
          type: boolean

    CatalogActionsResponse:
      type: object
      description: Response body for `GET /catalog/actions`.
      required:
        - totalActions
        - categories
        - actions
      properties:
        catalogVersion:
          type: string
        totalActions:
          type: integer
        categories:
          type: array
          items:
            type: string
          description: Ordered list of category identifiers.
        actions:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CatalogAction'
              - $ref: '#/components/schemas/CompactCatalogAction'
          description: '`CompactCatalogAction` when the request set `?compact=true`, otherwise `CatalogAction`.'

    WorkflowAction:
      type: object
      description: A single action (node) in a workflow definition.
      properties:
        actionId:
          type: string
          description: Unique identifier for this action within the workflow.
        actionType:
          type: string
          description: Catalog action type this node runs (see `GET /catalog/actions`).
        parameters:
          type: object
          description: Action-specific parameters, per the catalog action's parameter definitions.

    WorkflowConnection:
      type: object
      description: A connection between two actions' ports in a workflow definition.
      properties:
        connectionId:
          type: string
        connectionSource:
          type: string
          description: Source action ID.
        sourcePort:
          type: string
          description: Source port name.
        connectionTarget:
          type: string
          description: Target action ID.
        targetPort:
          type: string
          description: Target port name.

    WorkflowDefinition:
      type: object
      description: A workflow's actions and connections, plus identifying metadata.
      properties:
        metadata:
          type: object
          properties:
            workflowId:
              type: string
              description: Caller-supplied workflow identifier (used to detect reuse on republish).
            name:
              type: string
            description:
              type: string
        actions:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowAction'
        connections:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowConnection'

    WorkflowListResponse:
      type: object
      description: Paginated list of workflows for the authenticated caller (or the whole org, with `scope=org`).
      properties:
        workflows:
          type: array
          items:
            type: object
            properties:
              workflowId:
                type: string
                format: uuid
              name:
                type: string
                nullable: true
              description:
                type: string
                nullable: true
              status:
                type: string
                description: Current workflow status (for example `active`, `draft`, `unpublished`).
              workflowType:
                type: string
                enum:
                  - matrix
                  - run-workflow
              createdAt:
                type: string
                format: date-time
                nullable: true
              updatedAt:
                type: string
                format: date-time
                nullable: true
              publishedAt:
                type: string
                format: date-time
                nullable: true

    WorkflowDetailResponse:
      type: object
      description: A single workflow with its full definition and execution history, returned when `workflowId` is supplied to `GET /workflows`.
      properties:
        workflowId:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        status:
          type: string
        workflowType:
          type: string
          enum:
            - matrix
            - run-workflow
        version:
          type: string
        workflow:
          $ref: '#/components/schemas/WorkflowDefinition'
        executionCount:
          type: integer
          description: Number of executions.
        executions:
          type: array
          items:
            type: object
            properties:
              executionId:
                type: string
              timestamp:
                type: string
                format: date-time
              actionsUrl:
                type: string
                format: uri

    PublishWorkflowRequest:
      type: object
      required:
        - workflow
      properties:
        workflow:
          $ref: '#/components/schemas/WorkflowDefinition'

    PublishWorkflowResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - succeeded
            - failed
        workflowId:
          type: string
          format: uuid
          description: Storage UUID for the published workflow.
        action:
          type: string
          enum:
            - created
            - reused
          description: Whether a new workflow UUID was minted, or an existing one (matching `metadata.workflowId`) was reused.
        metadataWorkflowId:
          type: string
          description: Echo of the `workflow.metadata.workflowId` supplied in the request.

    SaveDraftRequest:
      type: object
      required:
        - matrix
      properties:
        matrix:
          $ref: '#/components/schemas/WorkflowDefinition'
        name:
          type: string
          description: Workflow display name.
        description:
          type: string
          description: Optional workflow description.

    SaveDraftResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - succeeded
        workflowId:
          type: string
        message:
          type: string

    ReadDraftResponse:
      type: object
      properties:
        sasUrl:
          type: string
          description: Short-lived, read-only URL to the draft's stored workflow definition.
        expiresAt:
          type: string
          format: date-time
        workflowId:
          type: string
        updatedAt:
          type: string
          format: date-time
          description: Last-write time for this draft.

    PreviewWorkflowRequest:
      type: object
      description: Workflow definition to preview (same shape as `PublishWorkflowRequest.workflow`, but not wrapped in a `workflow` key).
      allOf:
        - $ref: '#/components/schemas/WorkflowDefinition'

    PreviewWorkflowResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            result:
              type: object
              properties:
                href:
                  type: string
                  format: uri
                  description: URL to query preview status.
            cancel:
              type: object
              properties:
                href:
                  type: string
                  format: uri
                  description: URL to cancel the preview.

    PreviewStatusResponse:
      type: object
      properties:
        instanceId:
          type: string
        runtimeStatus:
          type: string
          enum:
            - Running
            - Completed
            - Failed
            - Canceled
            - Terminated
          description: Current status of the preview run.
        output:
          type: object
          description: Output data from the preview (when completed).
        createdTime:
          type: string
          format: date-time
        lastUpdatedTime:
          type: string
          format: date-time

    PreviewCancelResponse:
      type: object
      properties:
        message:
          type: string
          example: "Cancellation request accepted"
        instanceId:
          type: string
        status:
          type: string
          example: "canceling"

  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"

    Forbidden:
      description: |
        The caller is not a member of the organization identified by `x-gw-ims-org-id`,
        or the requested resource belongs to a different user or organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "You do not have permission to access this resource in this organization."
            status: "failed"

    TooManyRequests:
      description: |
        Rate limit exceeded for this organization or user. Retry after the window
        indicated by the `x-ratelimit-reset` response header resets.
      headers:
        x-ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        x-ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-ratelimit-reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Rate limit exceeded"
            message: "Too many requests. Please retry after the window resets."
            status: "failed"

    ServiceUnavailable:
      description: |
        Organization membership could not be verified transiently (an upstream
        identity check returned a 5xx or timed out). The request was not attempted.
        Retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Unable to verify organization access at this time. Please try again."
            status: "failed"