Skip to main content
POST
/
v2
/
optimize
/
workflows
Create an optimization workflow
curl --request POST \
  --url https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows \
  --header 'Content-Type: application/json' \
  --header 'domain: <domain>' \
  --data '
{
  "input": {
    "artifact": {
      "artifact_id": "art_95c650ded4824dc79bb6df16427e4a10"
    }
  },
  "name": "Spring 2026 catalog enrichment",
  "origin": "API",
  "tags": []
}
'
{
  "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"
}

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.

Headers

​
domain
string
required

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.

Example:

"vessel.com"

Body

application/json

Request body for creating an optimization workflow. Customer integrations should set origin to API. Supervised review gating is applied automatically.

​
input
object
required

Specifies the source of the workflow's input data. Provide artifact.artifact_id from a prior call to POST /v2/optimize/artifacts.

​
name
string | null

Human-readable name displayed in the Commerce OS UI.

Example:

"Spring 2026 catalog enrichment"

​
tags
string[] | null
Example:
[]
​
origin
enum<string> | null
default:API

Set to API for customer integrations. Defaults to API when omitted.

Available options:
COMMERCEOS,
API
​
metadata
object

Arbitrary JSON object stored on the workflow for caller use.

Response

Workflow created

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.

​
id
string
required

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
string
required
Example:

"691df5949676c8e0b1d7b6b3"

​
status
enum<string>
required

Current lifecycle state.

Available options:
PENDING,
RUNNING,
IN_PROGRESS,
REVIEW_PENDING,
COMPLETED,
FAILED,
CANCELLED
Example:

"REVIEW_PENDING"

​
created_at
string<date-time>
required
Example:

"2026-05-15T10:35:00Z"

​
updated_at
string<date-time>
required
Example:

"2026-05-15T10:42:08Z"

​
type
string | null
Example:

"OPTIMIZE"

​
origin
enum<string> | null
Available options:
COMMERCEOS,
API
Example:

"API"

​
workflow_type
string | null
Example:

null

​
current_step
string | null

Current step in the workflow. One of VALIDATE / VALIDATION, TAXONOMY_MAP / TAXONOMY, ENRICH / ENRICHMENT, or PUBLISH / PUBLISHED.

Example:

"TAXONOMY_MAP"

​
current_hitl_gate
string | null

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
string | null
Example:

"Spring 2026 catalog enrichment"

​
tags
any[]
Example:
[]
​
started_at
string<date-time> | null
Example:

"2026-05-15T10:35:12Z"

​
completed_at
string<date-time> | null
Example:

null

​
last_error
string | null

Most recent error message. Populated when status is FAILED.

Example:

null

​
retry_count
integer
default:0
Example:

0

​
workflow_metadata
object
​
progress
object

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.

​
review_summary
object

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.

​
reviewer_summary
object[]
​
created_by
object

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).

​
updated_by
object

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).