> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an optimization workflow

> Creates an optimization workflow that processes a previously uploaded artifact. Provide the `artifact_id` returned by `POST /v2/optimize/artifacts` as `input.artifact.artifact_id`.

Workflows run in supervised mode by default. The workflow pauses at human-in-the-loop review gates that allow reviewers to approve taxonomy mappings, sample enrichments, and the final publish step.

**Review gates are approved in the CommerceOS web application, not through the API.** When a workflow reaches `status: REVIEW_PENDING`, direct a reviewer to [CommerceOS](https://commerceos.fabric.inc) to evaluate and approve the active gate. Once the reviewer acts in the UI, the workflow resumes automatically and the next poll of `GET /v2/optimize/workflows/{workflow_id}` reflects the new state.




## OpenAPI

````yaml product-agent.openapi post /v2/optimize/workflows
openapi: 3.0.1
info:
  contact:
    email: support@fabric.inc
    name: fabric Support Team
  description: >
    The Product Agent API helps brands optimize product data for AI-driven
    commerce.

    Monitor how your catalog performs in AI search experiences, enrich product

    content for stronger semantic visibility, and publish optimized data across

    channels. Designed for iterative improvement, Product Agent enables teams to

    measure, refine, and enhance product content as AI shopping behavior
    evolves.
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  termsOfService: https://fabric.inc/terms-of-use
  title: fabric Orders API
  version: 3.0.0
  x-audience: external-public
servers:
  - url: https://commerceos.aiagents.fabric.inc/api
    description: Production API
security:
  - authorization: []
externalDocs:
  description: Find out more about Product Agent.
  url: https://developer.fabric.inc/product-agent/overview
paths:
  /v2/optimize/workflows:
    post:
      summary: Create an optimization workflow
      description: >
        Creates an optimization workflow that processes a previously uploaded
        artifact. Provide the `artifact_id` returned by `POST
        /v2/optimize/artifacts` as `input.artifact.artifact_id`.


        Workflows run in supervised mode by default. The workflow pauses at
        human-in-the-loop review gates that allow reviewers to approve taxonomy
        mappings, sample enrichments, and the final publish step.


        **Review gates are approved in the CommerceOS web application, not
        through the API.** When a workflow reaches `status: REVIEW_PENDING`,
        direct a reviewer to [CommerceOS](https://commerceos.fabric.inc) to
        evaluate and approve the active gate. Once the reviewer acts in the UI,
        the workflow resumes automatically and the next poll of `GET
        /v2/optimize/workflows/{workflow_id}` reflects the new state.
      operationId: createOptimizeWorkflow
      parameters:
        - $ref: '#/components/parameters/DomainHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
            example:
              input:
                artifact:
                  artifact_id: art_95c650ded4824dc79bb6df16427e4a10
              name: Spring 2026 catalog enrichment
              origin: API
              tags: []
      responses:
        '201':
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptimizeWorkflowResponse'
              example:
                id: 9349773c-27fe-4d4f-a093-a5793dff8702
                brand_id: 691df5949676c8e0b1d7b6b3
                type: OPTIMIZE
                origin: API
                workflow_type: null
                status: PENDING
                current_step: null
                current_hitl_gate: null
                name: Spring 2026 catalog enrichment
                tags: []
                started_at: null
                completed_at: null
                last_error: null
                retry_count: 0
                workflow_metadata: null
                progress: null
                review_summary:
                  total_categories: 0
                  decided_categories: 0
                  pending_categories: 0
                  rerunning_categories: 0
                  rejected_categories: 0
                  ready_for_publish_categories: 0
                  published_categories: 0
                reviewer_summary: []
                created_by:
                  id: user_xyz
                  type: user
                  name: Integration Bot
                  email: integration@acme.com
                updated_by:
                  id: user_xyz
                  type: user
                  name: Integration Bot
                  email: integration@acme.com
                created_at: '2026-05-15T10:35:00Z'
                updated_at: '2026-05-15T10:35:00Z'
        '400':
          description: >-
            Bad request. The `input` field is missing or specifies more than one
            source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: >-
            Forbidden. The caller is not authorized for the brand specified in
            the `domain` header, or the referenced artifact belongs to a
            different brand.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Referenced artifact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
      security:
        - bearerAuth: []
components:
  parameters:
    DomainHeader:
      name: domain
      in: header
      required: true
      schema:
        type: string
        example: vessel.com
      description: >-
        The brand domain name (for example, `vessel.com` or
        `containerstore.com`) used to scope the request to a specific brand's
        data and configuration. The authenticated principal must be authorized
        for the specified brand.
  schemas:
    CreateWorkflowRequest:
      type: object
      required:
        - input
      description: >-
        Request body for creating an optimization workflow. Customer
        integrations should set `origin` to `API`. Supervised review gating is
        applied automatically.
      properties:
        input:
          $ref: '#/components/schemas/WorkflowInput'
        name:
          type: string
          nullable: true
          description: Human-readable name displayed in the Commerce OS UI.
          example: Spring 2026 catalog enrichment
        tags:
          type: array
          nullable: true
          items:
            type: string
          example: []
        origin:
          type: string
          nullable: true
          enum:
            - COMMERCEOS
            - API
          default: API
          description: >-
            Set to `API` for customer integrations. Defaults to `API` when
            omitted.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: Arbitrary JSON object stored on the workflow for caller use.
    OptimizeWorkflowResponse:
      type: object
      required:
        - id
        - brand_id
        - status
        - created_at
        - updated_at
      description: >
        Workflow state envelope returned by `POST /v2/optimize/workflows` and
        `GET /v2/optimize/workflows/{workflow_id}`. The `status` value
        progresses through `PENDING`, then `RUNNING` or `IN_PROGRESS`, then
        `REVIEW_PENDING`, and ultimately `COMPLETED`. `FAILED` and `CANCELLED`
        are terminal alternatives.
      properties:
        id:
          type: string
          description: >-
            Workflow identifier. Use this value to poll for status and to
            construct deep links into the Commerce OS UI.
          example: 9349773c-27fe-4d4f-a093-a5793dff8702
        brand_id:
          type: string
          example: 691df5949676c8e0b1d7b6b3
        type:
          type: string
          nullable: true
          example: OPTIMIZE
        origin:
          type: string
          nullable: true
          enum:
            - COMMERCEOS
            - API
          example: API
        workflow_type:
          type: string
          nullable: true
          example: null
        status:
          type: string
          description: Current lifecycle state.
          enum:
            - PENDING
            - RUNNING
            - IN_PROGRESS
            - REVIEW_PENDING
            - COMPLETED
            - FAILED
            - CANCELLED
          example: REVIEW_PENDING
        current_step:
          type: string
          nullable: true
          description: >
            Current step in the workflow. One of `VALIDATE` / `VALIDATION`,
            `TAXONOMY_MAP` / `TAXONOMY`, `ENRICH` / `ENRICHMENT`, or `PUBLISH` /
            `PUBLISHED`.
          example: TAXONOMY_MAP
        current_hitl_gate:
          type: string
          nullable: true
          description: >
            Active human-in-the-loop review gate. Populated when `status` is
            `REVIEW_PENDING`. One of `VALIDATION_REVIEW`, `TAXONOMY_REVIEW`,
            `SAMPLE_REVIEW`, `ENRICHMENT_SAMPLE_REVIEW`,
            `FULL_ENRICHMENT_REVIEW`, `ENRICHMENT_FULL_REVIEW`, or
            `PUBLISH_APPROVAL`.
          example: TAXONOMY_REVIEW
        name:
          type: string
          nullable: true
          example: Spring 2026 catalog enrichment
        tags:
          type: array
          items: {}
          example: []
        started_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-15T10:35:12Z'
        completed_at:
          type: string
          format: date-time
          nullable: true
          example: null
        last_error:
          type: string
          nullable: true
          description: Most recent error message. Populated when `status` is `FAILED`.
          example: null
        retry_count:
          type: integer
          default: 0
          example: 0
        workflow_metadata:
          type: object
          nullable: true
          additionalProperties: true
        progress:
          allOf:
            - $ref: '#/components/schemas/WorkflowProgress'
          nullable: true
        review_summary:
          $ref: '#/components/schemas/WorkflowReviewSummary'
        reviewer_summary:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowReviewerSummaryResponse'
        created_by:
          allOf:
            - $ref: '#/components/schemas/AuditPrincipal'
          nullable: true
        updated_by:
          allOf:
            - $ref: '#/components/schemas/AuditPrincipal'
          nullable: true
        created_at:
          type: string
          format: date-time
          example: '2026-05-15T10:35:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-05-15T10:42:08Z'
    errorResponse:
      description: Error response
      properties:
        errors:
          description: Errors
          items:
            $ref: '#/components/schemas/errorResponse'
          type: array
        message:
          description: Error message
          example: Bad request
          type: string
        type:
          description: Error type
          example: CLIENT_ERROR
          type: string
      type: object
    HTTPValidationError:
      type: object
      description: Validation error response body returned with HTTP 422.
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    WorkflowInput:
      type: object
      required:
        - artifact
      description: >-
        Specifies the source of the workflow's input data. Provide
        `artifact.artifact_id` from a prior call to `POST
        /v2/optimize/artifacts`.
      properties:
        artifact:
          $ref: '#/components/schemas/ArtifactInput'
    WorkflowProgress:
      type: object
      description: >
        Phase-keyed progress for the workflow, computed at read time. The
        `phases` object contains one key per phase (`validation`, `taxonomy`,
        `enrichment`, `publish`), each carrying a phase-specific structure.
      properties:
        current_phase:
          type: string
          nullable: true
          example: taxonomy
        current_step:
          type: string
          nullable: true
          example: TAXONOMY_MAP
        current_gate:
          type: string
          nullable: true
          example: TAXONOMY_REVIEW
        phases:
          type: object
          additionalProperties: true
          description: >-
            Phase-keyed progress map. Keys are `validation`, `taxonomy`,
            `enrichment`, `publish`; each value is a phase-specific progress
            object.
    WorkflowReviewSummary:
      type: object
      description: >
        Aggregate counts across categories at the current enrichment-side review
        gate. This summary supports diagnosing which categories are blocking
        progression. For non-enrichment gates (taxonomy, validation, publish)
        the counts are typically zero, because those gates are workflow-level
        rather than per-category.
      properties:
        total_categories:
          type: integer
          default: 0
        decided_categories:
          type: integer
          default: 0
        pending_categories:
          type: integer
          default: 0
        rerunning_categories:
          type: integer
          default: 0
        rejected_categories:
          type: integer
          default: 0
        ready_for_publish_categories:
          type: integer
          default: 0
        published_categories:
          type: integer
          default: 0
    WorkflowReviewerSummaryResponse:
      type: object
      required:
        - reviewer_user_id
      description: >-
        Per-reviewer summary included in the workflow response. The `name` and
        `email` fields are resolved from `auth_users` at read time.
      properties:
        reviewer_user_id:
          type: string
          example: user_xyz
        name:
          type: string
          nullable: true
          example: Alex Reviewer
        email:
          type: string
          nullable: true
          example: alex@acme.com
        first_name:
          type: string
          nullable: true
          example: Alex
        last_name:
          type: string
          nullable: true
          example: Reviewer
        category_ids:
          type: array
          items:
            type: string
          example:
            - cat_apparel
            - cat_outerwear
        categories_at_open_gate:
          type: integer
          default: 0
          example: 2
        current_gate:
          type: string
          nullable: true
          example: TAXONOMY_REVIEW
    AuditPrincipal:
      type: object
      required:
        - id
        - type
      description: >
        Resolved reference for the `created_by` and `updated_by` audit fields. A
        `type` of `unknown` is returned when the referenced identifier can no
        longer be resolved (for example, when a user has been hard-deleted).
      properties:
        id:
          type: string
          description: Either `auth_users.id` or `auth_service_clients.client_id`.
          example: user_xyz
        type:
          type: string
          enum:
            - user
            - service
            - unknown
          description: >-
            Indicates the principal type: `user` for end-user actors, `service`
            for machine clients, and `unknown` when the principal cannot be
            resolved.
        name:
          type: string
          nullable: true
          description: Display name. Null when `type` is `unknown`.
          example: Alex Reviewer
        email:
          type: string
          nullable: true
          description: Email address. Null when `type` is `service` or `unknown`.
          example: alex@acme.com
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            oneOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string
    ArtifactInput:
      type: object
      required:
        - artifact_id
      properties:
        artifact_id:
          type: string
          description: Identifier returned by `POST /v2/optimize/artifacts`.
          example: art_95c650ded4824dc79bb6df16427e4a10
  securitySchemes:
    authorization:
      bearerFormat: JWT
      scheme: bearer
      type: http

````