Skip to main content
POST
Bulk import products

Authorizations

Authorization
string
header
required

Bearer token authentication via Auth0. Users authenticate through Auth0 Universal Login. Include the access token in the Authorization header: Authorization: Bearer <token>

Path Parameters

workspaceId
string
required

The workspace ID

Pattern: ^ws_[a-z0-9]+$

Query Parameters

catalog_id
string

Body

multipart/form-data
file
file
required

CSV or JSON file with products

format
enum<string>
default:csv
Available options:
csv,
json

Response

Import job enqueued. Poll statusUrl for the import; when pipeline is queued, poll pipelineStatusUrl for the chained Silver/Gold pipeline (ADR 015).

Returned when a background job is successfully enqueued for async processing (202 Accepted). Poll GET /api/workspace/{workspaceId}/jobs/{backgroundJobId} for status updates. An in-app toast notification is shown when the job reaches a terminal state. Pass notify_email: true in the request to also receive an email on completion or failure.

jobId
string
required

BullMQ job ID (matches backgroundJobId for correlation)

backgroundJobId
string<uuid>
required

Internal background_jobs record ID. Use this to poll the jobs status endpoint.

queue
enum<string>
required

Worker queue the job was added to

Available options:
ingest,
catalog,
media
jobName
string
required

Job type identifier (e.g. pipeline_run, platform_sync, workflow_batch)

status
enum<string>
required

Initial status. Transitions to active → completed | failed as the worker processes it.

Available options:
queued
catalog_id
string<uuid>
required
productCount
integer
required
pipeline
enum<string>
required

Whether the Bronze→Silver→Gold pipeline is chained after this import. The worker enqueues pipeline_run once the products are saved; not_queued only when no catalog could be resolved.

Available options:
queued,
not_queued
notify_email
boolean

Whether the user opted in to receive an email notification when the job completes or fails. Defaults to false if not provided in the request.

catalog_slug
string | null
pipelineJobId
string<uuid> | null

Deterministic background_jobs id of the chained pipeline_run (dedupe key pipeline_run:import:<jobId>).

pipelineStatusUrl
string | null
Last modified on February 16, 2026