Importing CSV files using API endpoints

Step 1: Postman Environment Setup

This part of the guide walks you through setting up a Postman environment to interact with the Product Agent API.

Create a new environment

Open Postman.
Click Environments in the sidebar.
Click + to create a new environment. Provide a name such as Product Agent - Prod.

Add the environment variables

Add the following variables to your environment.

access_token, domain, and the various defined ID’s will be empty initially — they will be populated after making API calls.

Variable	Description	Example
`baseUrl`	Base URL for the API	`https://commerceos.aiagents.fabric.inc/api`
`authUrl`	Auth URL for the API	`https://commerceos.aiagents.fabric.inc`
`access_token`	JWT token used for authenticated requests (set after login)	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`taxonomyWorkflowId`	ID of the taxonomy workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`categoryWorkflowId`	ID of the category workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`attributeWorkflowId`	ID of the attribute workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`enrichmentWorkflowId`	ID of the enrichment workflow (used for status endpoints)	`a1462a91-f733-45fe-993b-5d0353f33ee3`
`password`	Password used for authentication	`your-password`
`domain`	Brand domain or identifier for scoping requests	`acme.com`
`catalogFileId`	The `output_file_id` returned when you approve a pending review	`69bd76435bnc4cf33c2440bf`

Step 2: Authentication

This part of the guide walks you through authenticating with the Product Agent API and storing your access token in Postman for future requests.

Create and set the access token

To authenticate, send a POST request to the login endpoint with your username and password.

The authentication endpoints use the authUrl variable not baseUrl.

curl --location '{{authUrl}}/platform/v1/auth/login' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--form 'username="username"' \
--form 'password="password"'

Example Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

To automatically save the access_token for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("access_token", pm.response.json().access_token);

With this script, the access_token environment variable is automatically updated each time a request to the endpoint is made.

Tokens expire every 24 hours.

Verify authentication and set your domain

You can verify your token and get your domain configuration by making a GET request to:

curl --location '{{authUrl}}/platform/v1/auth/me' \
--header 'Accept: application/json' \
--header 'Authorization: {{access_token}}'

Example Response:

{
  "id": "692d9d0eb8636aa1286823be",
  "company_id": "692d9d0eb8636aa1286823bd",
  "email": "jane.doe@acme.com",
  "name": "Jane Doe",
  "role": "admin",
  "email_verified": true,
  "brands": [
    {
      "id": "6914c75a8e982af39b9cc6af",
      "domain": "acme.com",
      "entitlements": {
        "monitor": true,
        "activate": true
      }
    }
  ]
}

In the brands object, your domain environment variable value is returned.

Step 3: Import Categories

Once you have a valid access_token and your domain set, the next step is to import category data. This endpoint accepts a CSV file and creates an import job you can monitor using the returned import_id. We will save this to our environment as categoryWorkflowId.

Expected CSV columns

Column	Required	Description
`name` or `category_name`	Yes	Category name
`parent_id` or `parent_category_id`	No	Parent category ID
`breadcrumb`	No	Full breadcrumb path
`inferred_category`	No	AI-inferred category

Request

curl --location '{{baseUrl}}/v2/categories/import' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--form 'file=@"/D:/Demo CSV files/categories.csv"'

To automatically save the categoryWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("categoryWorkflowId", pm.response.json().import_id);

Example Response:

{
  "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"
}

Check the import status

After the upload succeeds, use the saved categoryWorkflowId to check workflow status with:

curl --location '{{baseUrl}}/v2/categories/import/{{categoryWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

Example Response:

{
  "import_id": "a0cf63a0-55b8-4a25-9218-d972d4d65a79",
  "name": "categories.csv",
  "status": "COMPLETED",
  "total_rows": 333,
  "processed_rows": 333,
  "new_count": 333,
  "updated_count": 0,
  "skipped_count": 0,
  "failed_count": 0,
  "input_filename": "categories.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"
}

Wait for the status to be set to COMPLETED. Once completed you can review the categories you uploaded in the UI.

Log in to Product Agent.
In the left nav, click Settings. The Settings menu is displayed.
Click Taxonomy.

The Categories tab is displayed by default. Here you can review your category taxonomy.

Step 4: Import Attribute Definitions

Once categories are in place, you can import attribute definitions for enrichment and mapping workflows. This endpoint accepts a CSV file and creates an import job you can monitor using the returned import_id. We will save this to our environment as attributeWorkflowId.

Expected CSV columns for each attribute definition

Column	Required	Description
`attribute_name`	Yes	Attribute display name
`attribute_key`	No	Machine-readable key
`description`	No	Attribute description
`data_type`	No	Attribute data type
`scope`	No	Attribute scope
`enum_values`	No	Allowed values, pipe-delimited, for example `S\|M\|L`
`allow_ai_content`	No	Allow AI to generate values (`true` or `false`)
`source`	No	`MERCHANT` or `GOLD_STANDARD`
`guideline_reason`	No	Guidance for AI enrichment

Request

curl --location '{{baseUrl}}/v2/attributes/import' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--form 'file=@"/D:/Demo CSV files/attributes.csv"'

To automatically save the attributeWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("attributeWorkflowId", pm.response.json().import_id);

Example Response:

{
    "import_id": "e2716438-b763-4be8-82d2-36abe0cb92b1",
    "name": "attribute.csv",
    "status": "PENDING",
    "total_rows": 36,
    "processed_rows": 0,
    "created_count": 0,
    "updated_count": 0,
    "skipped_count": 0,
    "failed_count": 0,
    "input_filename": "attribute.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"
}

Check the import status

After the upload succeeds, use the saved attributeWorkflowId to check workflow status with:

curl --location '{{baseUrl}}/v2/attributes/import/{{attributeWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

Example Response:

{
    "import_id": "e2716438-b763-4be8-82d2-36abe0cb92b1",
    "name": "attribute.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://product-agent-data-prod-ue2.s3.amazonaws.com/attribute/vessel/e2716438-b763-4be8-82d2-36abe0cb92b1.csv...",
    "error_file_url": "https://product-agent-data-prod-ue2.s3.amazonaws.com/attribute/vessel/e2716438-b763-4be8-82d2-36abe0cb92b1_errors.csv?X-...",
    "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"
}

In this example, an error was flagged in the upload. You can resolve and publish updates to just that row or re-upload the entire file. Rows with errors are skipped. Once completed, you can review the attribute definitions you uploaded in the UI.

Log in to Product Agent.
In the left nav, click Settings. The Settings menu is displayed.
Click Taxonomy. The Categories tab is displayed by default.
Click Attributes.

Here you can review your attribute definitions.

Step 5: Import Your Products

After importing your categories and attribute definitions, you can upload products. During processing, products will be automatically mapped to your categories and aligned with the attribute definitions you’ve provided. This endpoint accepts a CSV file and creates a taxonomy workflow you can monitor using the returned workflow id. We will save this to our environment as taxonomyWorkflowId.

Expected CSV columns

Column	Required	Description
`title`	Yes	Product title
`breadcrumb`	Yes	Category breadcrumb path
`sku`	No	Product SKU
`category`	No	Product category
`description`	No	Product description
`images`	No	Image URLs
`attribute.*`	No	Custom attributes, for example `attribute.color`

Request

curl --location '{{baseUrl}}/v2/taxonomy-workflow' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--form 'file=@"/D:/Demo CSV files/products.csv"'

To automatically save the taxonomyWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("taxonomyWorkflowId", pm.response.json().workflow_id);

Example Response:

{
  "id": "a1462a91-f733-45fe-993b-5d0353f33ee3",
  "brand_id": "268465dd-71f5-4179-959c-9bac01029451",
  "status": "PENDING",
  "workflow_type": "ATTRIBUTE_AND_CATEGORY_MAPPING",
  "import_document_path": "taxonomy-workflow/vessel/d6441888-f25d-4acb-8898-07808526ecdb/d6441888-f25d-4acb-8898-07808526ecdb_input.csv",
  "created_at": "2026-03-12T17:54:07.374339Z",
  "updated_at": "2026-03-12T17:54:07.374339Z",
  "total_category_mappings": 0,
  "total_attribute_mappings": 0,
  "workflow_id": "a1462a91-f733-45fe-993b-5d0353f33ee3",
  "workflow_status": "PENDING",
  "tenant_id": "268465dd-71f5-4179-959c-9bac01029451",
  "workflow_phase": "PRE_PROCESS",
  "domain": "acme.com",
  "total_items": 0,
  "processed_items": 0,
  "successful_items": 0,
  "failed_items": 0,
  "total_chunks": 0,
  "processed_chunks": 0,
  "input_file_id": "69b2fdbfd1dcca3911c666e6",
  "output_file_id": null,
  "error_file_id": null,
  "review_required": false,
  "review_task_id": null,
  "enrichment_workflow_id": null,
  "error_message": null
}

Check the import status

After the upload succeeds, use the saved taxonomyWorkflowId to check workflow status with:

curl --location '{{baseUrl}}/v2/taxonomy-workflow/{{taxonomyWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

Example Response:

{
    "id": "2345943b-91dd-4a3b-a923-b5c524049dcc",
    "brand_id": "268465dd-71f5-4179-959c-9bac01029451",
    "status": "REVIEW_PENDING",
    "workflow_type": "ATTRIBUTE_AND_CATEGORY_MAPPING",
    "import_document_path": "taxonomy-workflow/vessel/3c007843-d82b-4805-93f1-1afef9d1968e/3c007843-d82b-4805-93f1-1afef9d1968e_input.csv",
    "created_at": "2026-03-18T20:35:03.936559Z",
    "updated_at": "2026-03-18T20:35:16.658894Z",
    "total_category_mappings": 4,
    "total_attribute_mappings": 0,
    "workflow_id": "2345943b-91dd-4a3b-a923-b5c524049dcc",
    "workflow_status": "REVIEW_PENDING",
    "tenant_id": "268465dd-71f5-4179-959c-9bac01029451",
    "workflow_phase": "PRE_PROCESS",
    "domain": "acme.com",
    "total_items": 0,
    "processed_items": 0,
    "successful_items": 0,
    "failed_items": 0,
    "total_chunks": 0,
    "processed_chunks": 0,
    "input_file_id": "69bb0c78826cb2bb154da262",
    "output_file_id": null,
    "error_file_id": null,
    "review_required": false,
    "review_task_id": null,
    "enrichment_workflow_id": null,
    "error_message": null
}

Wait for the status to be set to REVIEW_PENDING before proceeding to the next step.

Step 6: Review Imported Products

After uploading your product CSV, use the review endpoint to approve the data and proceed with enrichment.

curl --location --request POST '{{hostUrl}}/api/v2/taxonomy-workflow/{{{taxonomyWorkflowId}}/review/complete' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}'

To automatically save the catalogFileId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("catalogFileId", pm.response.json().output_file_id);

Example Response:

{
    "message": "Review completed",
    "workflow_id": "76a618ef-66c9-4792-a833-34543c1r36ed",
    "output_file_id": "69bd76435bnc4cf33c2440bf",
    "category_count": 4,
    "attribute_count": 0
}

Step 7: Run Enrichment

The final step is to run enrichment on your uploaded products. fabric NEON automatically maps products to your defined categories and attributes, then enhances product data by enriching fields such as the title, description, and other attributes. The output_file_id in the previous request is required in the body of this request and was set to catalogFileId by our script.

curl --location 'https://commerceos.aiagents.fabric.inc/v3/product-agent-api/catalog-workflow?is_temporal=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' \
--data '{
    "name": "Product Catalog v2",
    "type": "CATALOG_ENRICHMENT",
    "enrichment_configuration": {
        "catalog_scope": "FULL",
        "force_refresh": true,
        "catalog_file_id": "{{catalogFileId}}",
        "use_v2_orchestrator": true,
        "brand_guidelines": []
    }
}'

To automatically save the enrichmentWorkflowId for future requests:

Go to the Scripts tab in your Postman request.
Select Post-response.
Add the following script: pm.environment.set("enrichmentWorkflowId", pm.response.json().id);

Allow a few minutes for the enrichment to complete.

Example Response:

{
    "id": "69c1784f9184cbdb46675449",
    "tenant_id": "-",
    "domain": "acme.com",
    "created_at": "2026-03-23T17:28:47.903000",
    "updated_at": "2026-03-23T17:28:47.903000",
    "created_by": "692d9d0eb8636aa1286823be",
    "name": "Product Catalog v2",
    "source": "EXTENSION",
    "type": "CATALOG_ENRICHMENT",
    "status": "COMPLETE",
    "step": "FULL_PRODUCT_CATALOG_INITIATED",
    "crawling_configuration": null,
    "enrichment_configuration": {
        "catalog_scope": "FULL",
        "catalog_file_id": "69c178281bf0405f07f02dcd",
        "force_refresh": true,
        "is_citation_enabled": false,
        "include_ads_feed": false,
        "use_v2_orchestrator": true,
        "brand_guidelines": [],
        "factual_feedback": null,
        "additional_attributes": null,
        "concurrency": 10
    },
    "brand_inference_configuration": null,
    "notification": null,
    "last_event_at": "2026-03-23T17:28:47.903841Z",
    "retry_count": 0,
    "max_retries": 3,
    "last_error": null,
    "catalog_scope": "FULL",
    "catalog_file_id": "69c178281bf0405f07f02dcd"
}

Check enrichment status

After the upload succeeds, use the saved enrichmentWorkflowId to check workflow status with:

curl --location 'https://commerceos.aiagents.fabric.inc/v3/product-agent-api/catalog-workflow/{{enrichmentWorkflowId}}' \
--header 'Authorization: {{access_token}}' \
--header 'domain: {{domain}}' 

Example Response:

{
    "id": "69bd7e9f476258f0ca961c0c",
    "tenant_id": "-",
    "domain": "acme.com",
    "created_at": "2026-03-20T17:06:39.307000",
    "updated_at": "2026-03-20T17:07:39.910225Z",
    "created_by": "692d9d0eb8636aa1286823be",
    "name": "Product Catalog v2",
    "source": "EXTENSION",
    "type": "CATALOG_ENRICHMENT",
    "status": "COMPLETED",
    "step": "FULL_PRODUCT_CATALOG_COMPLETED",
    "crawling_configuration": null,
    "enrichment_configuration": {
        "catalog_scope": "FULL",
        "catalog_file_id": "69bd7e7f476258f0ca961c07",
        "force_refresh": true,
        "is_citation_enabled": false,
        "include_ads_feed": false,
        "use_v2_orchestrator": true,
        "brand_guidelines": [],
        "factual_feedback": null,
        "additional_attributes": null,
        "concurrency": 10
    },
    "brand_inference_configuration": null,
    "notification": null,
    "last_event_at": "2026-03-20T17:07:39.910225Z",
    "retry_count": 0,
    "max_retries": 3,
    "last_error": null,
    "catalog_scope": "FULL",
    "catalog_file_id": "69bd7e7f476258f0ca961c07"
}

Once processing is complete, your products will appear in Activate. Based on your category structure, products will be organized accordingly—for example, sweaters under Tops > Sweaters and t-shirts under Tops > T-Shirts.

Activate

API Endpoints

​Step 1: Postman Environment Setup

​Create a new environment

​Add the environment variables

​Step 2: Authentication

​Create and set the access token

​Verify authentication and set your domain

​Step 3: Import Categories

​Expected CSV columns

​Request

​Check the import status

​Step 4: Import Attribute Definitions

​Expected CSV columns for each attribute definition

​Request

​Check the import status

​Step 5: Import Your Products

​Expected CSV columns

​Request

​Check the import status

​Step 6: Review Imported Products

​Step 7: Run Enrichment

​Check enrichment status

Step 1: Postman Environment Setup

Create a new environment

Add the environment variables

Step 2: Authentication

Create and set the access token

Verify authentication and set your domain

Step 3: Import Categories

Expected CSV columns

Request

Check the import status

Step 4: Import Attribute Definitions

Expected CSV columns for each attribute definition

Request

Check the import status

Step 5: Import Your Products

Expected CSV columns

Request

Check the import status

Step 6: Review Imported Products

Step 7: Run Enrichment

Check enrichment status