{"openapi":"3.1.0","info":{"title":"SKU Normalize and Collision Guard API","version":"1.0.0","description":"Inspect and normalize bounded merchant-scoped SKU strings, compare identifiers under explicit rules, find collisions in caller-supplied batches, build unreserved candidates, and apply caller-defined length, charset, namespace, and canonical-form policy. The API never queries a marketplace, reserves a candidate, writes to a catalog, proves product identity, or verifies uniqueness outside the supplied request."},"paths":{"/marketplace/rapid/sku/v1/inspect":{"post":{"tags":["SKU Inspect"],"summary":"Inspect SKU","description":"Inspect one bounded merchant SKU and return exact Unicode, whitespace, length, and selected-profile evidence.","operationId":"inspectSKU","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUInspectRequest"},"examples":{"example":{"summary":"Inspect SKU","value":{"sku":"TSHIRT-BLUE-M","profile":"GOOGLE_MERCHANT_ID_2026"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUInspectResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/sku/v1/normalize":{"post":{"tags":["SKU Normalize"],"summary":"Normalize SKU","description":"Normalize one SKU under explicit Unicode, whitespace, case, and separator rules without claiming identity equivalence.","operationId":"normalizeSKU","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUNormalizeRequest"},"examples":{"example":{"summary":"Normalize SKU","value":{"sku":" tshirt  blue__m ","policy":{"unicode_form":"NFKC","trim_outer_whitespace":true,"internal_whitespace":"REPLACE","whitespace_replacement":"-","case":"UPPER","collapse_separators":true,"separator":"-"}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUNormalizeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/sku/v1/compare":{"post":{"tags":["SKU Compare"],"summary":"Compare SKUs","description":"Compare two SKU strings exactly, case-insensitively, and under explicit normalization rules.","operationId":"compareSKUs","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUCompareRequest"},"examples":{"example":{"summary":"Compare SKUs","value":{"left":"TSHIRT-BLUE-M","right":"tshirt blue m","mode":"NORMALIZED"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUCompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/sku/v1/batch/inspect":{"post":{"tags":["SKU Collision Check"],"summary":"Find SKU Collisions","description":"Find exact, case-insensitive, and normalized collision groups in up to 1,000 caller-supplied rows.","operationId":"inspectSKUBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUBatchRequest"},"examples":{"example":{"summary":"Find SKU Collisions","value":{"items":[{"sku":"ABC-1","reference":"row-1"},{"sku":"abc_1","reference":"row-2"}]}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUBatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/sku/v1/build":{"post":{"tags":["SKU Candidate Build"],"summary":"Build SKU Candidate","description":"Build a deterministic candidate from caller components and check it against a supplied known-SKU set without reserving it.","operationId":"buildSKUCandidate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUBuildRequest"},"examples":{"example":{"summary":"Build SKU Candidate","value":{"components":["Acme","Tshirt","Blue","M"],"max_length":50,"known_skus":["ACME-TSHIRT-RED-M"]}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUBuildResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/marketplace/rapid/sku/v1/policy-check":{"post":{"tags":["SKU Policy"],"summary":"Check SKU Policy","description":"Apply explicit length, charset, prefix, reserved-value, and canonical-form policy.","operationId":"checkSKUPolicy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUPolicyRequest"},"examples":{"example":{"summary":"Check SKU Policy","value":{"sku":"ACME-TSHIRT-BLUE-M","min_length":3,"max_length":50,"charset":"ASCII_ALNUM_DASH_UNDERSCORE","required_prefixes":["ACME-"],"blocked_prefixes":["TEST-"],"reserved_values":["UNKNOWN"]}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SKUPolicyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NormalizationPolicy":{"properties":{"unicode_form":{"type":"string","enum":["NONE","NFC","NFKC"],"title":"Unicode Form","default":"NFKC"},"trim_outer_whitespace":{"type":"boolean","title":"Trim Outer Whitespace","default":true},"internal_whitespace":{"type":"string","enum":["PRESERVE","COLLAPSE","REPLACE","REJECT"],"title":"Internal Whitespace","default":"REPLACE"},"whitespace_replacement":{"type":"string","title":"Whitespace Replacement","default":"-"},"case":{"type":"string","enum":["PRESERVE","UPPER","LOWER"],"title":"Case","default":"UPPER"},"collapse_separators":{"type":"boolean","title":"Collapse Separators","default":true},"separator":{"type":"string","enum":["-","_"],"title":"Separator","default":"-"}},"additionalProperties":false,"type":"object","title":"NormalizationPolicy"},"SKUBatchItem":{"properties":{"sku":{"type":"string","maxLength":128,"title":"Sku"},"reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Reference"}},"additionalProperties":false,"type":"object","required":["sku"],"title":"SKUBatchItem"},"SKUBatchItemResult":{"properties":{"index":{"type":"integer","title":"Index"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference"},"original":{"type":"string","title":"Original"},"normalized":{"type":"string","title":"Normalized"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"}},"additionalProperties":false,"type":"object","required":["index","reference","original","normalized","decision","findings"],"title":"SKUBatchItemResult"},"SKUBatchRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SKUBatchItem"},"type":"array","maxItems":1000,"minItems":1,"title":"Items"},"policy":{"$ref":"#/components/schemas/NormalizationPolicy"}},"additionalProperties":false,"type":"object","required":["items"],"title":"SKUBatchRequest"},"SKUBatchResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"item_count":{"type":"integer","title":"Item Count"},"exact_collision_groups":{"items":{"$ref":"#/components/schemas/SKUCollisionGroup"},"type":"array","title":"Exact Collision Groups"},"case_collision_groups":{"items":{"$ref":"#/components/schemas/SKUCollisionGroup"},"type":"array","title":"Case Collision Groups"},"normalized_collision_groups":{"items":{"$ref":"#/components/schemas/SKUCollisionGroup"},"type":"array","title":"Normalized Collision Groups"},"items":{"items":{"$ref":"#/components/schemas/SKUBatchItemResult"},"type":"array","title":"Items"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"uniqueness_verified_outside_request":{"type":"boolean","const":false,"title":"Uniqueness Verified Outside Request","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","item_count","exact_collision_groups","case_collision_groups","normalized_collision_groups","items","next_action"],"title":"SKUBatchResponse"},"SKUBuildRequest":{"properties":{"components":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":1,"title":"Components"},"policy":{"$ref":"#/components/schemas/NormalizationPolicy"},"max_length":{"type":"integer","maximum":128.0,"minimum":1.0,"title":"Max Length","default":50},"known_skus":{"items":{"type":"string"},"type":"array","maxItems":1000,"title":"Known Skus"}},"additionalProperties":false,"type":"object","required":["components"],"title":"SKUBuildRequest"},"SKUBuildResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"candidate":{"type":"string","title":"Candidate"},"normalized_components":{"items":{"type":"string"},"type":"array","title":"Normalized Components"},"length":{"type":"integer","title":"Length"},"max_length":{"type":"integer","title":"Max Length"},"collides_with_known_indexes":{"items":{"type":"integer"},"type":"array","title":"Collides With Known Indexes"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"candidate_reserved":{"type":"boolean","const":false,"title":"Candidate Reserved","default":false},"candidate_persisted":{"type":"boolean","const":false,"title":"Candidate Persisted","default":false},"uniqueness_verified_outside_request":{"type":"boolean","const":false,"title":"Uniqueness Verified Outside Request","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","candidate","normalized_components","length","max_length","collides_with_known_indexes","findings","next_action"],"title":"SKUBuildResponse"},"SKUCollisionGroup":{"properties":{"basis":{"type":"string","enum":["EXACT","CASE_INSENSITIVE","NORMALIZED"],"title":"Basis"},"key":{"type":"string","title":"Key"},"indexes":{"items":{"type":"integer"},"type":"array","title":"Indexes"},"references":{"items":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"array","title":"References"}},"additionalProperties":false,"type":"object","required":["basis","key","indexes","references"],"title":"SKUCollisionGroup"},"SKUCompareRequest":{"properties":{"left":{"type":"string","maxLength":128,"title":"Left"},"right":{"type":"string","maxLength":128,"title":"Right"},"mode":{"type":"string","enum":["EXACT","CASE_INSENSITIVE","NORMALIZED"],"title":"Mode","default":"NORMALIZED"},"policy":{"$ref":"#/components/schemas/NormalizationPolicy"}},"additionalProperties":false,"type":"object","required":["left","right"],"title":"SKUCompareRequest"},"SKUCompareResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"requested_mode":{"type":"string","enum":["EXACT","CASE_INSENSITIVE","NORMALIZED"],"title":"Requested Mode"},"match":{"type":"boolean","title":"Match"},"exact_match":{"type":"boolean","title":"Exact Match"},"case_insensitive_match":{"type":"boolean","title":"Case Insensitive Match"},"normalized_match":{"type":"boolean","title":"Normalized Match"},"left_normalized":{"type":"string","title":"Left Normalized"},"right_normalized":{"type":"string","title":"Right Normalized"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"same_product_claimed":{"type":"boolean","const":false,"title":"Same Product Claimed","default":false},"marketplace_queried":{"type":"boolean","const":false,"title":"Marketplace Queried","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","requested_mode","match","exact_match","case_insensitive_match","normalized_match","left_normalized","right_normalized","findings","next_action"],"title":"SKUCompareResponse"},"SKUFinding":{"properties":{"code":{"type":"string","title":"Code"},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH"],"title":"Severity"},"path":{"type":"string","title":"Path"},"message":{"type":"string","title":"Message"},"evidence":{"additionalProperties":true,"type":"object","title":"Evidence"},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["code","severity","path","message","next_action"],"title":"SKUFinding"},"SKUInspectRequest":{"properties":{"sku":{"type":"string","maxLength":128,"title":"Sku"},"profile":{"type":"string","enum":["GENERIC_COMMERCE","GOOGLE_MERCHANT_ID_2026"],"title":"Profile","default":"GENERIC_COMMERCE"}},"additionalProperties":false,"type":"object","required":["sku"],"title":"SKUInspectRequest"},"SKUInspectResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"sku":{"type":"string","title":"Sku"},"length_codepoints":{"type":"integer","title":"Length Codepoints"},"length_utf8_bytes":{"type":"integer","title":"Length Utf8 Bytes"},"ascii_only":{"type":"boolean","title":"Ascii Only"},"contains_whitespace":{"type":"boolean","title":"Contains Whitespace"},"contains_control_characters":{"type":"boolean","title":"Contains Control Characters"},"nfc":{"type":"string","title":"Nfc"},"nfkc":{"type":"string","title":"Nfkc"},"sha256":{"type":"string","title":"Sha256"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"},"profile":{"type":"string","enum":["GENERIC_COMMERCE","GOOGLE_MERCHANT_ID_2026"],"title":"Profile"},"profile_version":{"type":"string","title":"Profile Version"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"validation_scope":{"type":"string","const":"CALLER_SUPPLIED_VALUE_ONLY","title":"Validation Scope","default":"CALLER_SUPPLIED_VALUE_ONLY"},"marketplace_queried":{"type":"boolean","const":false,"title":"Marketplace Queried","default":false},"uniqueness_verified_outside_request":{"type":"boolean","const":false,"title":"Uniqueness Verified Outside Request","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","sku","length_codepoints","length_utf8_bytes","ascii_only","contains_whitespace","contains_control_characters","nfc","nfkc","sha256","findings","profile","profile_version","next_action"],"title":"SKUInspectResponse"},"SKUNormalizeRequest":{"properties":{"sku":{"type":"string","maxLength":128,"title":"Sku"},"policy":{"$ref":"#/components/schemas/NormalizationPolicy"}},"additionalProperties":false,"type":"object","required":["sku"],"title":"SKUNormalizeRequest"},"SKUNormalizeResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"original":{"type":"string","title":"Original"},"normalized":{"type":"string","title":"Normalized"},"changed":{"type":"boolean","title":"Changed"},"changes":{"items":{"type":"string"},"type":"array","title":"Changes"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"},"source_sha256":{"type":"string","title":"Source Sha256"},"normalized_sha256":{"type":"string","title":"Normalized Sha256"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"identity_equivalence_claimed":{"type":"boolean","const":false,"title":"Identity Equivalence Claimed","default":false},"uniqueness_verified_outside_request":{"type":"boolean","const":false,"title":"Uniqueness Verified Outside Request","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","original","normalized","changed","changes","findings","source_sha256","normalized_sha256","next_action"],"title":"SKUNormalizeResponse"},"SKUPolicyRequest":{"properties":{"sku":{"type":"string","maxLength":128,"title":"Sku"},"normalization":{"$ref":"#/components/schemas/NormalizationPolicy"},"min_length":{"type":"integer","maximum":128.0,"minimum":1.0,"title":"Min Length","default":1},"max_length":{"type":"integer","maximum":128.0,"minimum":1.0,"title":"Max Length","default":50},"charset":{"type":"string","enum":["ANY_VALID_UNICODE","ASCII_PRINTABLE","ASCII_ALNUM_DASH_UNDERSCORE"],"title":"Charset","default":"ASCII_ALNUM_DASH_UNDERSCORE"},"required_prefixes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Required Prefixes"},"blocked_prefixes":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Blocked Prefixes"},"reserved_values":{"items":{"type":"string"},"type":"array","maxItems":200,"title":"Reserved Values"},"case_sensitive_lists":{"type":"boolean","title":"Case Sensitive Lists","default":false},"require_alphanumeric":{"type":"boolean","title":"Require Alphanumeric","default":true},"require_normalized_input":{"type":"boolean","title":"Require Normalized Input","default":false}},"additionalProperties":false,"type":"object","required":["sku"],"title":"SKUPolicyRequest"},"SKUPolicyResponse":{"properties":{"status":{"type":"string","const":"COMPLETED","title":"Status","default":"COMPLETED"},"decision":{"type":"string","enum":["CLEAR","REVIEW_REQUIRED","BLOCKED"],"title":"Decision"},"original":{"type":"string","title":"Original"},"normalized":{"type":"string","title":"Normalized"},"findings":{"items":{"$ref":"#/components/schemas/SKUFinding"},"type":"array","title":"Findings"},"ruleset_version":{"type":"string","title":"Ruleset Version","default":"2026-08-11"},"validation_scope":{"type":"string","const":"CALLER_POLICY_AND_VALUE_ONLY","title":"Validation Scope","default":"CALLER_POLICY_AND_VALUE_ONLY"},"marketplace_queried":{"type":"boolean","const":false,"title":"Marketplace Queried","default":false},"uniqueness_verified_outside_request":{"type":"boolean","const":false,"title":"Uniqueness Verified Outside Request","default":false},"payload_stored":{"type":"boolean","const":false,"title":"Payload Stored","default":false},"next_action":{"type":"string","title":"Next Action"}},"additionalProperties":false,"type":"object","required":["decision","original","normalized","findings","next_action"],"title":"SKUPolicyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"SKU Inspect","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."},{"name":"SKU Normalize","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."},{"name":"SKU Compare","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."},{"name":"SKU Collision Check","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."},{"name":"SKU Candidate Build","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."},{"name":"SKU Policy","description":"A bounded, stateless SKU preflight for agents, catalog imports, inventory workflows, merchant feeds, and e-commerce integrations."}],"servers":[{"url":"https://api-production-9502.up.railway.app"}]}