Guide
Catalog Import API
Create, inspect, advance, review, and commit catalog jobs, then attach permitted private delivery files.
Developer account permissions
Use a developer account session, not a product credential or partner key. All calls require product-view access. New-catalog operations require product-create permission and all-products scope. Filling a target draft requires product-edit permission and access to that product; allowUpdates also requires edit permission.
Private delivery actions additionally require file-management permission and product access. Without file-management permission, the job response hides download links, export samples, and the delivery manifest. Discovery and copy operations only accept supported public or authorized sources.
SoundSync
Job lifecycle
GET
/api/developer/catalog-imports
List the latest workspace import jobs
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- { jobs: [...] }; current list is limited to the latest 10 jobs.
- Notes
- Returns the latest 10 workspace jobs. Import access requires the appropriate create/edit scope.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports
Start an import
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- storeUrl: string
- mode: catalog | single
- targetId: integer
- export: string
- Returns
- 201 with the visible job and current status.
- Notes
- export is one CSV/TSV/XLSX/JSON multipart file up to 8 MB. Use a public authorized source URL or export. Imported products remain drafts; do not copy accounts, billing authority or consent implicitly.
Request, response and error reference
Request (application/json or multipart/form-data)
{
"type": "object",
"properties": {
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"catalog",
"single"
]
},
"targetId": {
"type": "integer",
"minimum": 1
},
"export": {
"type": "string",
"format": "binary"
}
},
"additionalProperties": true,
"anyOf": [
{
"required": [
"storeUrl"
]
},
{
"required": [
"export"
]
}
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/catalog-imports/:id
Read a workspace-owned job
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Visible job, candidates, warnings, progress, and permitted results.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/advance
Advance the next bounded discovery step
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated visible job. The client drives subsequent steps.
- Notes
- Advances one browser-driven discovery step; polling the job alone does not drive all future discovery.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/mapping
Review export column mappings
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- mapping: object (required). Canonical product field to an existing export header.
- Returns
- Updated visible job.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"mapping": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Canonical product field to an existing export header."
}
},
"required": [
"mapping"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/retry-discovery
Retry supported discovery work
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job; inspect warnings and status before continuing.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/media
Copy a discovered image or audio asset
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- kind: images | audio (required)
- url: string (required)
- Returns
- { asset: ... }; allowed during review, before committing.
- Notes
- The URL must be an allowed candidate source. Only review-stage media is copied.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"images",
"audio"
]
},
"url": {
"type": "string"
}
},
"required": [
"kind",
"url"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"name": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/commit
Save reviewed products as drafts
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- confirmed: true (required)
- products: array (required)
- allowUpdates: boolean
- Returns
- Completed visible job with saved-product results; repeated completed commits return the job.
- Notes
- Copy selected media before committing. Published products are skipped; matching existing drafts requires explicit allowUpdates. A completed-job replay returns the existing result rather than republishing.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"confirmed": {
"const": true
},
"products": {
"type": "array",
"minItems": 1,
"maxItems": 200,
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"allowUpdates": {
"type": "boolean"
}
},
"required": [
"confirmed",
"products"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"storeUrl": {
"type": "string"
},
"mode": {
"type": "string"
},
"targetId": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
},
"type": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"audio": {
"type": "array",
"items": {
"type": "string"
}
},
"videos": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"downloadLinks": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"existingProductId": {
"type": [
"integer",
"null"
]
},
"existingPublished": {
"type": "boolean"
},
"matchConflict": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"progress": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pendingPages": {
"type": "integer"
},
"minimumPaidPriceCents": {
"type": "integer",
"minimum": 0
},
"export": {
"type": [
"object",
"null"
],
"properties": {
"filename": {
"type": "string"
},
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"rowCount": {
"type": "integer"
},
"sample": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
SoundSync
Start discovery
Start discovery
curl -X POST "$SOUNDSYNC_ORIGIN/api/developer/catalog-imports" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" \
-H "Content-Type: application/json" \
--data '{"storeUrl":"https://example.com/products/example","mode":"single"}'SoundSync
Private delivery after draft creation
POST
/api/developer/catalog-imports/:id/delivery-manifest
Match an export to completed import results
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- export: string (required)
- nameColumn: string
- linkColumns: string
- Returns
- Manifest with rows, direct links, productId, and exact/ambiguous/unmatched state; review every match.
- Notes
- linkColumns is a JSON-encoded array of export header names. Review exact, ambiguous and unmatched product matches before starting file imports.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"export": {
"type": "string",
"format": "binary"
},
"nameColumn": {
"type": "string"
},
"linkColumns": {
"type": "string"
}
},
"required": [
"export"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": [
"integer",
"null"
]
},
"name": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"state": {
"type": "string"
}
},
"additionalProperties": true
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/catalog-imports/:id/delivery/:productId
List delivery upload jobs for an imported product
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Upload job list.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId
Start a remote-file copy
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- url: string (required)
- Returns
- 202 with upload job; repeated source requests use the job/product/source identity.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
],
"additionalProperties": true
}HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/direct
Start or resume multipart delivery upload
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- filename: string (required)
- sizeBytes: integer (required)
- mimeType: string
- multipart: boolean
- fileFingerprint: string
- Returns
- 201 with job and upload-session instructions; catalog delivery forces multipart mode.
- Notes
- Catalog delivery forces multipart mode. The product must be part of this completed import and within the actor product scope.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"sizeBytes": {
"type": "integer",
"minimum": 1,
"maximum": 10000000000
},
"mimeType": {
"type": "string"
},
"multipart": {
"type": "boolean"
},
"fileFingerprint": {
"type": "string",
"pattern": "^v1:[a-f0-9]{64}$"
}
},
"required": [
"filename",
"sizeBytes"
],
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/part
Prepare an allowed upload part
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- partNumber: integer (required)
- Returns
- Signed upload instructions; use the returned method, URL, and headers.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
}
},
"required": [
"partNumber"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/complete
Verify multipart completion and attachment
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job and attachment outcome; do not attach an incomplete file yourself.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/direct/:uploadId/cancel
Cancel a multipart upload
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Updated job state.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/local
Upload a supported buffered local file
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Request fields
- file: string (required)
- Returns
- 201 with the local upload job.
- Notes
- Buffered uploads have a lower limit than direct multipart delivery. The current upload policy determines the returned limit.
Request, response and error reference
Request (multipart/form-data)
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
},
"required": [
"file"
],
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId
Inspect an upload
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current authorized job.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/catalog-imports/:id/delivery/:productId/:uploadId/retry
Retry eligible failed delivery work
- Auth
- Account Bearer JWT
- Scope
- Workspace permissions and product assignments are checked.
- Returns
- Current job; a remote import can restart from the source.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"sourceType": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"filename": {
"type": "string"
},
"storageKey": {
"type": "string"
},
"fileSizeBytes": {
"type": [
"integer",
"null"
]
},
"mimeType": {
"type": "string"
},
"checksum": {
"type": "string"
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"attachedProductFileId": {
"type": [
"string",
"integer"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expectedSizeBytes": {
"type": [
"integer",
"null"
]
},
"resumable": {
"type": "boolean"
},
"resumeExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"upload": {
"type": "object",
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"partSize": {
"type": "integer"
},
"partNumber": {
"type": "integer",
"minimum": 1
},
"parts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"expiresIn": {
"type": "integer"
}
},
"additionalProperties": true
},
"processing": {
"type": "boolean"
},
"deduplicated": {
"type": "boolean"
},
"file": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
SoundSync
Error handling
| HTTP status | Action |
|---|---|
| 400 | Correct the URL, export, mapping, product selection, price/type, or confirmation. |
| 403 / 404 | Check workspace, product assignments, permission, and job ownership; do not probe other accounts. |
| 409 | Refresh the job: work may be busy, the state changed, media is not copied, or a product match requires review. |
| 429 | Reuse an existing job or wait for the workspace import limit. |
| 500 | Preserve the job ID and inspect its current state before retrying. |
Examples and returned data
These examples describe the current request contract, not a seeded response fixture for every source website. Treat source copy and filenames as untrusted data. Keep private links, tokens, and full job payloads out of public issue reports.