Skip to main content
POST
Create Product

Headers

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

Query Parameters

validate
boolean
default:false

Validate against ProductType

publish_event
boolean
default:true

Publish ProductEvent to NATS for enrichment

Cookies

stytch_session
string | null

Body

application/json

Request model for creating a Product.

key
string
required
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.

source
string
required
enrichProduct
boolean
default:true
isPublished
boolean
default:false
properties
Properties · object

Product properties dict

properties_metadata
Properties Metadata · object
scrapeBrandSite
boolean
default:true
searchLakehouse
boolean
default:true
status
string | null

Response

Successful Response

Response model for a single Product.

id
string
required

MongoDB ObjectId as string

key
string
required

Internal unique identifier

productType
Producttype · object
required

Product type reference

source
string
required

Source of product data

aiTraceId
string | null

AI-observability trace ID (PostHog $ai_trace_id; equals the Langfuse trace id while dual-running)

confidence
number | null

Confidence score (0-1)

createdAt
string | null

Creation timestamp

createdBy
string | null

User who created this

enrichmentScore
number | null

Enrichment completeness score (0-1)

enrichmentSources
string[] | null

Buckets that contributed to merged product

errorMessage
string | null

Error message if status=failed

isPublished
boolean
default:false

DEPRECATED manual flag; superseded by publish_status

job_id
string | null

Job ID for tracking enrichment progress

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.

lastModifiedAt
string | null

Last modification timestamp

lastModifiedBy
string | null

User who last modified this

properties
Properties · object

Product data keyed by PropertyDefinition key

properties_metadata
Properties Metadata · object

Per-property metadata

propertyCount
integer
default:0

Number of properties with values

publish_chips
Publish Chips · object[]

Per-enabled-target publish chips: {target_key, target_env, name, state(in_sync|drifted|never_published), published_version, published_at}

publish_status
string | null

Computed publish status: draft | live | changed

quality_finding_count
integer | null

Advisory quality findings for this product's latest scoring run. null = never scored; 0 = scored and clean; >0 = scored with that many findings.

scrapeWarnings
Scrapewarnings · object[] | null

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

status
string | null

Status: complete, failed, partial

version
integer
default:1

Version number