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": []
}
'import requests
url = "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows"
payload = {
"input": { "artifact": { "artifact_id": "art_95c650ded4824dc79bb6df16427e4a10" } },
"name": "Spring 2026 catalog enrichment",
"origin": "API",
"tags": []
}
headers = {
"domain": "<domain>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {domain: '<domain>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: {artifact: {artifact_id: 'art_95c650ded4824dc79bb6df16427e4a10'}},
name: 'Spring 2026 catalog enrichment',
origin: 'API',
tags: []
})
};
fetch('https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => [
'artifact' => [
'artifact_id' => 'art_95c650ded4824dc79bb6df16427e4a10'
]
],
'name' => 'Spring 2026 catalog enrichment',
'origin' => 'API',
'tags' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"domain: <domain>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows"
payload := strings.NewReader("{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("domain", "<domain>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows")
.header("domain", "<domain>")
.header("Content-Type", "application/json")
.body("{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["domain"] = '<domain>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}"
response = http.request(request)
puts response.read_body{
"id": "9349773c-27fe-4d4f-a093-a5793dff8702",
"brand_id": "691df5949676c8e0b1d7b6b3",
"type": "OPTIMIZE",
"origin": "API",
"mode": "prod",
"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"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}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 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.
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": []
}
'import requests
url = "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows"
payload = {
"input": { "artifact": { "artifact_id": "art_95c650ded4824dc79bb6df16427e4a10" } },
"name": "Spring 2026 catalog enrichment",
"origin": "API",
"tags": []
}
headers = {
"domain": "<domain>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {domain: '<domain>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: {artifact: {artifact_id: 'art_95c650ded4824dc79bb6df16427e4a10'}},
name: 'Spring 2026 catalog enrichment',
origin: 'API',
tags: []
})
};
fetch('https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => [
'artifact' => [
'artifact_id' => 'art_95c650ded4824dc79bb6df16427e4a10'
]
],
'name' => 'Spring 2026 catalog enrichment',
'origin' => 'API',
'tags' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"domain: <domain>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows"
payload := strings.NewReader("{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("domain", "<domain>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows")
.header("domain", "<domain>")
.header("Content-Type", "application/json")
.body("{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["domain"] = '<domain>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": {\n \"artifact\": {\n \"artifact_id\": \"art_95c650ded4824dc79bb6df16427e4a10\"\n }\n },\n \"name\": \"Spring 2026 catalog enrichment\",\n \"origin\": \"API\",\n \"tags\": []\n}"
response = http.request(request)
puts response.read_body{
"id": "9349773c-27fe-4d4f-a093-a5793dff8702",
"brand_id": "691df5949676c8e0b1d7b6b3",
"type": "OPTIMIZE",
"origin": "API",
"mode": "prod",
"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"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}Headers
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.
"vessel.com"
Body
Request body for creating an optimization workflow. Customer integrations should set origin to API. Supervised review gating is applied automatically.
Specifies the source of the workflow's input data. Provide artifact.artifact_id from a prior call to POST /v2/optimize/artifacts.
Show child attributes
Show child attributes
Human-readable name displayed in the Commerce OS UI.
"Spring 2026 catalog enrichment"
[]
Set to API for customer integrations. Defaults to API when omitted.
COMMERCEOS, API Selects the publish target for the run's enriched catalog. Each value maps to a separate destination, allowing the same brand to publish to distinct environments.
Optional. When omitted, the run publishes to the brand's existing configured destination.
dev, test, prod 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.
Workflow identifier. Use this value to poll for status and to construct deep links into the Commerce OS UI.
"9349773c-27fe-4d4f-a093-a5793dff8702"
"691df5949676c8e0b1d7b6b3"
Current lifecycle state.
PENDING, RUNNING, IN_PROGRESS, REVIEW_PENDING, COMPLETED, FAILED, CANCELLED "REVIEW_PENDING"
"2026-05-15T10:35:00Z"
"2026-05-15T10:42:08Z"
"OPTIMIZE"
COMMERCEOS, API "API"
The publish target the run's enriched catalog is published to. Null when the run uses the brand's existing configured destination.
dev, test, prod "prod"
null
Current step in the workflow. One of VALIDATE / VALIDATION, TAXONOMY_MAP / TAXONOMY, ENRICH / ENRICHMENT, or PUBLISH / PUBLISHED.
"TAXONOMY_MAP"
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.
"TAXONOMY_REVIEW"
"Spring 2026 catalog enrichment"
[]
"2026-05-15T10:35:12Z"
null
Most recent error message. Populated when status is FAILED.
null
0
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes
Was this page helpful?