Skip to main content
POST
Create Product Version

Headers

authorization
string | null
X-Organization-ID
string | null

Path Parameters

key
string
required

Cookies

stytch_session
string | null

Body

application/json

Request to create a new product version.

productType
ProductTypeReferenceRequest · object
required

Reference to a ProductType by key, as accepted in request bodies.

typeId is REQUIRED here even though the underlying KeyReference model (models/references.py) treats it as optional for other reference kinds. Every existing client already sends it: the admin UI's ManualEntryForm/NewVersionForm hardcode typeId: "product_type", and every internal builder (CSV import, JSON import, crawl-import, variant creation) hardcodes ReferenceTypeId.PRODUCT_TYPE.value. Meanwhile product_to_response/_product_to_version_response unconditionally read productType.typeId.value when building the API response — a request that omitted typeId used to sail through validation, get persisted, and only fail with a 500 once the response was built (or, on the create-version path, once ReferenceTypeId(...) was called on a mistyped default). Rejecting it here with a 422 keeps bad data out of Mongo instead of crashing after the write.

Only typeId presence/validity is tightened relative to the old Dict[str, Any] shape -- key keeps the same (non-empty-not-enforced) constraint it always had, to avoid an unrequested behavior change on an input the reported bug wasn't about.

commitMessage
string | null

Optional message describing changes

createdFrom
integer | null

Version number this was cloned from

enrichmentScore
number | null
isPublished
boolean
default:false
properties
Properties · object

Product properties dict

properties_metadata
Properties Metadata · object
reinitialize_attributes
boolean
default:false

Reinitialize properties from the target ProductType (discards properties)

setProduction
boolean
default:false

Set 'Production' label on this version

status
string | null

Response

Successful Response

Response model for a single product version.

id
string
required

MongoDB ObjectId as string

key
string
required

Internal unique identifier (shared across versions)

productType
Producttype · object
required

Product type reference

source
string
required

Source of product data

version
integer
required

Version number

aiTraceId
string | null

AI-observability trace ID for this enrichment run (PostHog $ai_trace_id)

confidence
number | null

Confidence score (0-1)

createdAt
string | null

Creation timestamp

createdBy
string | null

User who created this version

enrichmentScore
number | null

Quality score (0-1)

enrichmentSources
string[] | null

Buckets that contributed to merged product

isPublished
boolean
default:false

Published status

labels
string[]

Version labels

lakehouseMatched
boolean | null

Did lakehouse_search contribute any property?

lakehousePropertiesCount
integer | null

Properties sourced from lakehouse

langfuseTraceId
string | null
deprecated

DEPRECATED: use aiTraceId (same value). Kept for backward compatibility.

properties
Properties · object

Product data

properties_metadata
Properties Metadata · object

Per-property metadata

propertyCount
integer
default:0

Number of properties with values

scrapeWarnings
Scrapewarnings · object[] | null

Scrape-quality warnings if the brand-site scrape returned suspect content

status
string | null

Status: complete, failed, partial

version_commit_message
string | null

Commit message for this version

version_created_from
integer | null

Version this was cloned from