fabric NEON's Product Agent — the agentic commerce control plane that monitors product visibility across AI search surfaces, benchmarks against custom prompts, and enriches product data with intent signals for downstream channel activation. fabric's headline 2026 capability.
externalDocs:
description: Find out more about Product Agent.
url: https://developer.fabric.inc/product-agent/overview
servers:
- url: https://commerceos.aiagents.fabric.inc/api
description: Production API
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
openapi: 3.0.1
"x-mint": {
"mcp": {
"enabled": true
}
}
paths:
/platform/v1/auth/token:
post:
servers:
- url: https://commerceos.aiagents.fabric.inc
description: Auth Server
security: []
summary: Create Access Token
description: |
Generates an access token using the client credentials flow. Tokens expire every 60 minutes.
To authenticate, provide your `client_id`, `client_secret`, and set `grant_type` to `client_credentials`.
If you do not have a `client_id` and `client_secret`, contact fabric support to request API access credentials.
operationId: loginUser
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- client_id
- client_secret
- grant_type
properties:
grant_type:
type: string
example: client_credentials
client_id:
type: string
example: ser_zUe74HYT98d6ItDhIQWYYur0k
client_secret:
type: string
example: bv_1s9uWC_7324598gjdsh_ijSUVmm6YCt-6Ahd8Nt3GsTb8w8
responses:
'200':
description: Successful authentication
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
"400":
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
"401":
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
"500":
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
/v2/categories/import:
post:
summary: Bulk Import Categories
description: |
Upload a CSV file to import category data for the specified brand/domain. The import is processed asynchronously.
**Expected CSV columns**
- **name** or **category_name** (required): Category name
- **parent_id** or **parent_category_id** (optional): Parent category ID
- **breadcrumb** (optional): Full breadcrumb path
- **inferred_category** (optional): AI-inferred category
operationId: importCategories
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/DomainHeader'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: CSV file containing categories (e.g. categories.csv)
name:
type: string
description: Human friendly import name
example: Spring catalog category import
notify_email:
type: boolean
description: Send an email when the import completes.
default: true
example: true
responses:
'202':
description: Import accepted for asynchronous processing
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryImportAcceptedResponse'
example:
import_id: a0cf63a0-55b8-4a25-9218-d972d4d65a79
status: PENDING
message: Import queued. Use GET /categories/import/{import_id} to track progress.
created_at: '2026-03-12T17:58:13.605818Z'
'400':
description: Bad request - invalid CSV or missing file
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'401':
description: Unauthorized - missing or invalid token
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/v2/categories/import/{import_id}:
get:
summary: Get Category Import Status
description: Retrieve the current status and results of a category import created using `POST /api/v2/categories/import`.
operationId: getCategoryImportStatus
parameters:
- $ref: '#/components/parameters/DomainHeader'
- name: import_id
in: path
required: true
description: Import ID returned from `POST /api/v2/categories/import`.
schema:
type: string
format: uuid
example: a0cf63a0-55b8-4a25-9218-d972d4d65a79
responses:
'200':
description: Import status
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryImportStatusResponse'
example:
import_id: a0cf63a0-55b8-4a25-9218-d972d4d65a79
name: tcs_category_test.csv
status: COMPLETED
total_rows: 333
processed_rows: 333
new_count: 333
updated_count: 0
skipped_count: 0
failed_count: 0
input_filename: tcs_category_test.csv
input_file_url: https://example.com/input.csv
error_file_url: null
error_message: null
started_at: '2026-03-12T17:58:13.722428Z'
completed_at: '2026-03-12T17:58:14.564840Z'
created_at: '2026-03-12T17:58:13.605818Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Import not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/v2/attributes/import:
post:
summary: Import Attributes from CSV
description: |
Upload a CSV file to import attribute definitions for the specified brand/domain. The import is processed asynchronously.
**Expected CSV columns**
- **attribute_name** (required): Attribute display name
- **attribute_key** (optional): Machine-readable key
- **description** (optional): Attribute description
- **data_type** (optional): Data type
- **scope** (optional): Attribute scope
- **enum_values** (optional): Allowed values, pipe-delimited (e.g. `S|M|L`)
- **allow_ai_content** (optional): Allow AI to generate values (`true`/`false`)
- **source** (optional): `MERCHANT` or `GOLD_STANDARD`
- **guideline_reason** (optional): Guidance for AI enrichment
operationId: importAttributes
parameters:
- $ref: '#/components/parameters/DomainHeader'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: CSV file containing attribute definitions.
name:
type: string
description: Human-friendly import name.
example: Spring attributes import
responses:
'202':
description: Import accepted for asynchronous processing
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeImportAcceptedResponse'
example:
import_id: e2716438-b763-4be8-82d2-36abe0cb92b1
name: attribute_test.csv
status: PENDING
total_rows: 36
processed_rows: 0
created_count: 0
updated_count: 0
skipped_count: 0
failed_count: 0
input_filename: attribute_test.csv
input_file_url: null
error_file_url: null
error_message: null
errors: []
started_at: null
completed_at: null
created_at: '2026-03-12T18:04:03.879876Z'
'400':
description: Bad request - invalid CSV or missing file
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'401':
description: Unauthorized - missing or invalid token
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/v2/attributes/import/{import_id}:
get:
summary: Get Attribute Import Status
description: Retrieve the current status and results of an attribute import created using `POST /v2/attributes/import`.
operationId: getAttributeImportStatus
parameters:
- $ref: '#/components/parameters/DomainHeader'
- name: import_id
in: path
required: true
description: Import ID returned from `POST /v2/attributes/import`.
schema:
type: string
format: uuid
example: e2716438-b763-4be8-82d2-36abe0cb92b1
responses:
'200':
description: Import status
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeImportStatusResponse'
example:
import_id: e2716438-b763-4be8-82d2-36abe0cb92b1
name: attribute_test.csv
status: COMPLETED
total_rows: 36
processed_rows: 36
created_count: 35
updated_count: 0
skipped_count: 0
failed_count: 1
input_filename: attribute_test.csv
input_file_url: https://example.com/input.csv
error_file_url: https://example.com/errors.csv
error_message: null
errors:
- "Row 35: invalid data_type 'BOOLREAN'"
started_at: '2026-03-12T18:04:03.998437Z'
completed_at: '2026-03-12T18:04:04.724584Z'
created_at: '2026-03-12T18:04:03.879876Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Import not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/v2/optimize/artifacts:
post:
summary: Upload a Catalog Artifact
description: |
Uploads a catalog CSV as multipart form data and returns an `artifact_id` for use when starting an optimization workflow.
The HTTP client must set the `Content-Type: multipart/form-data` header with the appropriate boundary; the header should not be set manually. The `domain` header is required and must be a brand domain (for example, `vessel.com`) that the authenticated principal is authorized to access.
Each request creates a new artifact, even when the file content is identical to a previously uploaded file. Retain the returned `artifact_id` for the workflow that will reference it.
For catalogs larger than approximately 100 MB, contact fabric support to enable the presigned-URL upload flow.
### Catalog CSV format
The uploaded file must be UTF-8 encoded, comma-delimited, and include a header row. The supported columns are:
| Column | Required | Description |
| :------------------- | :---------- | :---------- |
| `title` | Yes | Product display name as shown on the product detail page. |
| `sku` | Yes | Unique product identifier within the brand catalog. |
| `description` | Yes | Full product description from the product detail page. |
| `category_id` | Conditional | The brand's category identifier. Each row must provide either `category_id` or `breadcrumb`. |
| `breadcrumb` | Conditional | Full category hierarchy separated by ` > ` (for example, `Mens > Clothing > Pants`). Each row must provide either `breadcrumb` or `category_id`. |
| `category` | No | Free-text category label. Used as a hint when neither `category_id` nor `breadcrumb` resolves to a known category. |
| `product_group_id` | No | Identifier shared by product variants that belong to the same family. |
| `price` | No | Numeric price value for the product. |
| `currency` | No | Currency code corresponding to `price`. |
| `url` | No | Canonical product detail page URL. |
| `images` | No | One or more image URLs separated by the pipe character (`\|`). |
| `attribute.<name>` | No | Custom attribute value. Free-form string, single value per cell. The `<name>` segment must match an attribute key configured for the brand. |
For a worked end-to-end example including auth and workflow creation, see the [Product Import Developer Guide](/product-agent/developer-guides/postman-import-csv-guide).
operationId: uploadOptimizeArtifact
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/DomainHeader'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UploadArtifactRequest'
responses:
'201':
description: Artifact uploaded
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactResponse'
example:
artifact_id: art_95c650ded4824dc79bb6df16427e4a10
kind: csv
source: upload
bytes: 45678
sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
content_type: text/csv
uri: s3://product-agent-data-prod-ue2/optimize-artifacts/svc_yourClientId/art_95c650ded4824dc79bb6df16427e4a10/catalog.csv
original_filename: catalog.csv
brand_id: 691df5949676c8e0b1d7b6b3
created_at: '2026-05-15T10:30:00Z'
'401':
description: Unauthorized. The access token is missing or has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'403':
description: Forbidden. The caller is not authorized for the brand specified in the `domain` header.
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'
/v2/optimize/artifacts/{artifact_id}:
get:
summary: Retrieve Artifact Metadata and Download URL
description: |
Returns metadata for a previously uploaded artifact along with a short-lived signed `download_url` for retrieving the original file contents. This endpoint supports inspection, auditing, and re-download of an artifact prior to starting a workflow.
The `download_url` is a presigned URL that remains valid until `download_url_expires_at`. After expiry, call this endpoint again to obtain a new URL.
operationId: getOptimizeArtifact
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/DomainHeader'
- name: artifact_id
in: path
required: true
description: Artifact identifier returned by `POST /v2/optimize/artifacts`.
schema:
type: string
example: art_95c650ded4824dc79bb6df16427e4a10
- name: expires_seconds
in: query
required: false
description: Lifetime of the signed `download_url` in seconds. Minimum 60, maximum 3600, default 900.
schema:
type: integer
minimum: 60
maximum: 3600
default: 900
example: 900
responses:
'200':
description: Artifact metadata and signed download URL
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactReadResponse'
example:
artifact_id: art_95c650ded4824dc79bb6df16427e4a10
kind: csv
source: upload
bytes: 45678
sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
content_type: text/csv
uri: s3://product-agent-data-prod-ue2/optimize-artifacts/svc_yourClientId/art_95c650ded4824dc79bb6df16427e4a10/catalog.csv
original_filename: catalog.csv
brand_id: 691df5949676c8e0b1d7b6b3
created_at: '2026-05-15T10:30:00Z'
download_url: https://product-agent-data-prod-ue2.s3.amazonaws.com/optimize-artifacts/svc_yourClientId/art_95c650ded4824dc79bb6df16427e4a10/catalog.csv?X-Amz-Signature=...
download_url_expires_at: '2026-05-15T10:45:00Z'
'401':
description: Unauthorized. The access token is missing or has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'403':
description: Forbidden. The artifact belongs to a different brand.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: 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'
/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
security:
- bearerAuth: []
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'
/v2/optimize/workflows/{workflow_id}:
get:
summary: Retrieve Optimization Workflow Status
description: |
Returns the current state of an optimization workflow, including `status`, `current_step`, `current_hitl_gate` (when the workflow is paused at a review gate), per-phase progress, and aggregated review and reviewer summaries.
Poll this endpoint to track a workflow through its lifecycle. A `401` response indicates that the access token has expired; re-authenticate and retry the request.
The `status` value progresses through `PENDING`, then `RUNNING` or `IN_PROGRESS`, then `REVIEW_PENDING` when paused at a human-in-the-loop gate, and ultimately `COMPLETED`. `FAILED` and `CANCELLED` are terminal alternatives.
**When `status` is `REVIEW_PENDING`**, the value of `current_hitl_gate` identifies the active gate. Gate approval is performed in the [CommerceOS](https://commerceos.fabric.inc) web application — direct the assigned reviewer to CommerceOS to evaluate and approve the gate. Once the reviewer acts, the workflow resumes and subsequent polls reflect the new state.
operationId: getOptimizeWorkflowStatus
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/DomainHeader'
- name: workflow_id
in: path
required: true
description: Workflow identifier returned by `POST /v2/optimize/workflows`.
schema:
type: string
example: 9349773c-27fe-4d4f-a093-a5793dff8702
responses:
'200':
description: Workflow state
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: REVIEW_PENDING
current_step: TAXONOMY_MAP
current_hitl_gate: TAXONOMY_REVIEW
name: Spring 2026 catalog enrichment
tags: []
started_at: '2026-05-15T10:35:12Z'
completed_at: null
last_error: null
retry_count: 0
workflow_metadata: null
progress:
current_phase: taxonomy
current_step: TAXONOMY_MAP
current_gate: TAXONOMY_REVIEW
phases:
validation:
status: COMPLETED
taxonomy:
status: REVIEW_PENDING
enrichment:
status: NOT_STARTED
publish:
status: NOT_STARTED
review_summary:
total_categories: 12
decided_categories: 3
pending_categories: 9
rerunning_categories: 0
rejected_categories: 0
ready_for_publish_categories: 0
published_categories: 0
reviewer_summary:
- reviewer_user_id: user_xyz
name: Alex Reviewer
email: alex@acme.com
first_name: Alex
last_name: Reviewer
category_ids:
- cat_apparel
- cat_outerwear
categories_at_open_gate: 2
current_gate: TAXONOMY_REVIEW
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:42:08Z'
'401':
description: Unauthorized. The access token is missing or has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'403':
description: Forbidden. The workflow belongs to a different brand.
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Workflow not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
components:
headers:
domain:
description: The brand domain associated with the request. Used to scope the request to a specific brand.
example: Vessel
required: false
schema:
type: string
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:
AttributeImportAcceptedResponse:
type: object
required:
- import_id
- name
- status
- total_rows
- processed_rows
- created_count
- updated_count
- skipped_count
- failed_count
- input_filename
- errors
- created_at
properties:
import_id:
type: string
format: uuid
description: Identifier for the attribute import job.
example: e2716438-b763-4be8-82d2-36abe0cb92b1
name:
type: string
description: Import name.
example: attribute_test.csv
status:
type: string
example: PENDING
total_rows:
type: integer
example: 36
processed_rows:
type: integer
example: 0
created_count:
type: integer
example: 0
updated_count:
type:
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-product-agent-openapi.yml