{ "openapi": "3.1.0", "info": { "title": "FitMyType public API", "version": "1", "description": "Storefront API for the widget, tag and pixels. Every answer carries `X-Request-Id` and `X-Api-Version`; every error is `{error:{code,message,request_id}}`." }, "servers": [ { "url": "https://api.fitmytype.com" } ], "paths": { "/v1/brands/{brand_id}/client": { "get": { "operationId": "getBrandClient", "summary": "The client of a brand (for `createWidget` with `brand_id` only)", "description": "Public, cacheable 1 hour. An unknown brand, or one of a paused or churned client, answers 404 `brand_not_found`.", "parameters": [ { "name": "brand_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,10}$", "description": "The brand's numeric id." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["client_id"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugins/customization": { "get": { "operationId": "getPluginCustomization", "summary": "Widget customization (theme and texts) of a client", "description": "Browsers may cache it 5 minutes; the CDN never does (D40). From a domain the client does not allow, the answer is `{eligible:false, reason:\"not_whitelisted\"}` (D39).", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "type": "string" } } ] } }, "i18n": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } } }, "required": ["theme", "i18n"] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" } }, "required": ["eligible", "reason"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugins/origin_check": { "get": { "operationId": "checkParentOrigin", "summary": "Is the page that framed the widget iframe an allowed domain of the client?", "description": "Called once per page load by the iframe (T13.03.01) before it talks to the parent page. Exact host or wildcard subdomain, as CORS; `www.` and no `www.` differ unless both are listed, and `http:` pages count only outside production. Never cached. From a domain the client does not allow, the answer is `{allowed:false, reason:\"not_whitelisted\"}` (D39).", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "origin", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512, "description": "The parent page origin, e.g. `https://www.trimtexstore.com`." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "const": "not_whitelisted" } }, "required": ["allowed"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugins/frame_policy": { "get": { "operationId": "getFramePolicy", "summary": "Which pages may frame the widget iframe of a client (frame-ancestors)", "description": "Asked by the plugin host for every iframe page request (T13.03.02), which copies the value into the page's `Content-Security-Policy: frame-ancestors`. The same origins the origin check allows: `https://` for each allowed domain, `https://*.` for a wildcard, plus `https://admin.shopify.com` for a Shopify client (theme editor), plus the environment's back-office origin for every serving client (its live and reference previews frame the same page). An unknown, malformed or not-serving client gets `'none'`. Also sent in the `X-Fmt-Frame-Ancestors` header. Never cached; follows a domain change within 60 s.", "parameters": [ { "name": "cid", "in": "query", "required": false, "schema": { "description": "The client id from the iframe URL (`?cid=`).", "type": "string", "maxLength": 12 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "frame_ancestors": { "type": "string" } }, "required": ["frame_ancestors"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sizing_charts/{id_or_slug}": { "get": { "operationId": "getSizingChart", "summary": "One size chart, published version, in the shape the widget and the engine read", "description": "By numeric id or unique name. Cached 5 minutes by the CDN and browsers, purged when the chart is published or deleted. An unknown chart, a chart of another client, a chart never published, or a paused or churned client answers 404 (never cached). From a domain the client does not allow, the answer is `{eligible:false, reason:\"not_whitelisted\"}` (D39).", "parameters": [ { "name": "id_or_slug", "in": "path", "required": true, "schema": { "type": "string", "description": "The chart's numeric id, or its unique name (slug) such as `1_Bottom`." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "system", "in": "query", "required": false, "schema": { "description": "Size system to present as primary (e.g. `FR`); default the chart's own. Unknown → 400 naming the chart's systems.", "type": "string", "pattern": "^[A-Za-z0-9_-]{1,16}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Added: the chart id; a recommendation records it with `version`." }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Added: the published version served (0 = stored before versions)." }, "revision": { "type": "string", "description": "Added: sha256 of the served version's content." }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "gender": { "anyOf": [ { "type": "string", "enum": ["female", "male", "unisex", "babies", "boys", "girls"] }, { "type": "null" } ] }, "body_part": { "type": "string", "enum": ["top", "bottom", "full", "bosom", "feet", "head"] }, "fit": { "anyOf": [ { "type": "string", "enum": ["tight", "regular", "loose", "extreme", "custom"] }, { "type": "null" } ] }, "basis": { "type": "string", "enum": ["body", "garment"], "description": "Added: `garment` charts carry garment values and ease (D11)." }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "systems": { "type": "array", "items": { "type": "string" }, "description": "Added: every size system the chart has labels in, primary first." }, "primary_measurements": { "type": "array", "items": { "type": "string", "enum": [ "Chest", "Underchest", "Waist", "Hips", "Height", "Weight", "ShoulderSpan", "ArmLength", "LegContour", "Inseam", "InseamFloor", "FootLength", "HeadCircumference" ] } }, "length_unit": { "type": "string", "enum": ["cm", "in"] }, "comment": { "type": "string" }, "sizes": { "type": "array", "items": { "type": "object", "properties": { "size_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "labels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "garment_cm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": ["size_id", "size_order", "labels"] } }, "ease_cm": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 } } }, { "type": "null" } ] }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string", "enum": [ "Chest", "Underchest", "Waist", "Hips", "Height", "Weight", "ShoulderSpan", "ArmLength", "LegContour", "Inseam", "InseamFloor", "FootLength", "HeadCircumference" ] }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" }, "measurement_name": { "type": "string", "enum": [ "Chest", "Underchest", "Waist", "Hips", "Height", "Weight", "ShoulderSpan", "ArmLength", "LegContour", "Inseam", "InseamFloor", "FootLength", "HeadCircumference" ] } }, "required": ["relation", "value", "measurement_name"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size_name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] }, "description": "One row per size and measurement: `=` for an exact value, a `>` min and a `<` max for a range." } }, "required": [ "id", "version", "revision", "unique_name", "name", "gender", "body_part", "fit", "basis", "primary_system", "systems", "primary_measurements", "length_unit", "comment", "sizes", "ease_cm", "measurements" ] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" } }, "required": ["eligible", "reason"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugin_references": { "get": { "operationId": "getPluginReferences", "summary": "Reference brands for the shopper reference step, most used first", "description": "The D19-compatible wire format (D91): `type_of_references` is `cloth`, `shoe` or `head`; the answer maps brand name → category slug → reference products, with `most_used_brands` (default 5, at most 20) and `client_brand`. With the client's `plugin_use_client_references` flag on and a non-empty list, only those brands in the merchant's order. Readable from any origin (`*`) and cached 10 minutes, keyed by the full URL. An unknown or paused client answers 404, a bad gender or type 422 naming the field, the database down 503 (errors never cached). From a domain the client does not allow: `{eligible:false, reason:\"not_whitelisted\", references:{}, most_used_brands:[], client_brand:null}` (D39).", "parameters": [ { "name": "gender", "in": "query", "required": true, "schema": { "type": "string", "enum": ["female", "male", "unisex", "boys", "girls", "babies"], "description": "D19 compatible: the shopper's gender." } }, { "name": "type_of_references", "in": "query", "required": true, "schema": { "type": "string", "enum": ["cloth", "shoe", "head"], "description": "D19 compatible: `cloth`, `shoe` or `head`." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "number_of_most_used", "in": "query", "required": false, "schema": { "description": "D19 compatible: how many most-used brand names (default 5, at most 20, 0 for none).", "type": "string", "pattern": "^\\d{1,4}$" } }, { "name": "language", "in": "query", "required": false, "schema": { "description": "Added: the language of the category labels (default `en`; a missing label falls back to EN).", "type": "string", "pattern": "^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "references": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "D19 compatible: `\"{brand_id}-{brand_type_id}\"`." }, "brand_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "D19 compatible." }, "brand_type_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Added: the reference product id (the id's last part)." }, "brand": { "type": "string", "description": "D19 compatible: the brand name." }, "brand_logo_url": { "description": "D19 compatible: null shows a name tile (D91).", "type": ["string", "null"] }, "name": { "type": "string", "description": "D19 compatible." }, "unique_name": { "type": "string", "description": "D19 compatible: the reference chart's slug." }, "slug": { "type": "string", "description": "D19 compatible: the same slug." }, "sizing_chart_slug": { "type": "string", "description": "D19 compatible: the slug a reco request names." }, "sizing_chart_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "D19 compatible." }, "gender": { "type": "string", "enum": ["female", "male", "unisex", "boys", "girls", "babies"], "description": "D19 compatible." }, "type": { "type": "string", "enum": ["cloth", "shoe", "head"], "description": "D19 compatible." }, "status": { "type": "string", "const": "active", "description": "D19 compatible: only active (published, not archived) products are listed." }, "category": { "type": "object", "properties": { "slug": { "type": "string", "description": "D19 compatible: e.g. `running-tights`." }, "translation_key": { "type": "string", "description": "D19 compatible: the i18n key of the category name." }, "label": { "type": "string", "description": "Added: the category name in the asked language (EN fallback)." }, "body_part": { "type": "string", "description": "Added: `top`, `bottom`, `full`, `bosom`, `feet` or `head`." } }, "required": ["slug", "translation_key", "label", "body_part"] }, "measurement_names": { "type": "array", "items": { "type": "string" }, "description": "D19 compatible: the chart's measurements." } }, "required": [ "id", "brand_id", "brand_type_id", "brand", "brand_logo_url", "name", "unique_name", "slug", "sizing_chart_slug", "sizing_chart_id", "gender", "type", "status", "category", "measurement_names" ] } } }, "description": "D19 compatible: brand name → category slug → reference products." }, "most_used_brands": { "type": "array", "items": { "type": "string" }, "description": "D19 compatible: brand names, most used first." }, "client_brand": { "description": "D19 compatible: the client's own brand when it is in the catalogue.", "type": ["string", "null"] } }, "required": ["references", "most_used_brands", "client_brand"] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "references": { "type": "object", "properties": {} }, "most_used_brands": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "client_brand": { "type": "null" } }, "required": ["eligible", "reason"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A query field is missing or invalid (`error.fields` names it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plugin_sizing_charts": { "get": { "operationId": "getPluginSizingCharts", "summary": "A reference brand's published size charts for a category and gender", "description": "Only the reference catalogue's published, current charts of the brand (a merged brand answers for the kept one), for the shopper's gender and unisex (children: their own gender only), each with its size systems and sizes. An unknown brand or category answers `[]`; no `brand_id` 422. Readable from any origin (`*`), cached 10 minutes. From a domain the client does not allow: `{eligible:false, reason:\"not_whitelisted\"}` (D39).", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "gender", "in": "query", "required": true, "schema": { "type": "string", "enum": ["female", "male", "unisex", "boys", "girls", "babies"], "description": "D19 compatible: the shopper's gender." } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "D19 compatible: always `active`.", "type": "string", "const": "active" } }, { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "D19 compatible: the reference brand." } }, { "name": "category", "in": "query", "required": false, "schema": { "description": "D19 compatible: a category slug; without it every category of the brand.", "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "language", "in": "query", "required": false, "schema": { "description": "Added: the language of the category labels (default `en`; a missing label falls back to EN).", "type": "string", "pattern": "^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})?$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "sizing_chart_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "D19 compatible." }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "D19 compatible: the same id." }, "slug": { "type": "string", "description": "D19 compatible." }, "unique_name": { "type": "string", "description": "D19 compatible." }, "name": { "type": "string", "description": "D19 compatible." }, "brand_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "D19 compatible." }, "brand_type_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Added: the reference product id." }, "gender": { "type": "string", "enum": ["female", "male", "unisex", "boys", "girls", "babies"], "description": "D19 compatible." }, "type": { "type": "string", "enum": ["cloth", "shoe", "head"], "description": "D19 compatible." }, "status": { "type": "string", "const": "active", "description": "D19 compatible." }, "models": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "D19 compatible." }, "measurement_names": { "type": "array", "items": { "type": "string" }, "description": "D19 compatible." }, "category": { "type": "object", "properties": { "slug": { "type": "string", "description": "D19 compatible: e.g. `running-tights`." }, "translation_key": { "type": "string", "description": "D19 compatible: the i18n key of the category name." }, "label": { "type": "string", "description": "Added: the category name in the asked language (EN fallback)." }, "body_part": { "type": "string", "description": "Added: `top`, `bottom`, `full`, `bosom`, `feet` or `head`." } }, "required": ["slug", "translation_key", "label", "body_part"] }, "primary_system": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "D19 compatible: the size system id (`GET /v1/sizes`; EU = 2)." }, "system": { "type": "string", "description": "D19 compatible: e.g. `EU`." }, "description": { "description": "D19 compatible: the system's name.", "type": ["string", "null"] } }, "required": ["id", "system", "description"], "description": "D19 compatible: the chart's primary size system." }, "size_systems": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "D19 compatible: the size system id (`GET /v1/sizes`; EU = 2)." }, "system": { "type": "string", "description": "D19 compatible: e.g. `EU`." }, "description": { "description": "D19 compatible: the system's name.", "type": ["string", "null"] }, "sizes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": ["id", "name"] }, "description": "D19 compatible: the chart's sizes labelled in this system, smallest first." } }, "required": ["id", "system", "description", "sizes"] }, "description": "D19 compatible: every size system the chart has labels in, primary first." } }, "required": [ "sizing_chart_id", "id", "slug", "unique_name", "name", "brand_id", "brand_type_id", "gender", "type", "status", "models", "measurement_names", "category", "primary_system", "size_systems" ] } }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" } }, "required": ["eligible", "reason"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A query field is missing or invalid (`error.fields` names it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sizes": { "get": { "operationId": "getSizeSystems", "summary": "The size system catalogue (EU, FR, UK, US, … and shoe scales)", "description": "The same for every shop: no `client_id`, readable from any origin (`Access-Control-Allow-Origin: *`), cached 5 minutes by the CDN and browsers. Ids never change (EU is 2). There is no write route (405). The catalogue unreadable answers 503 (never cached).", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "description": "Language of the names (`fr`, `fr-FR`). A language with no translation gets the English names.", "type": "string", "maxLength": 16 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Fixed id, never changes. EU is 2 (the compatible id, D19, D89)." }, "code": { "type": "string", "description": "The code chart labels use: `EU`, `FR`, `IT`, `DE`, `UK`, `US`, `INT`, `JP`, …" }, "name": { "type": "string", "minLength": 1, "description": "The name in the asked language, else English." }, "scope": { "type": "string", "enum": ["clothing", "shoes"], "description": "`clothing`, or `shoes` for a shoe scale (its own entry)." }, "gender": { "type": "string", "enum": ["all", "female", "male"], "description": "Who the system is for (`all`, or one gender for US shoes)." }, "body_part": { "type": "string", "enum": ["all", "feet"], "description": "`all` clothing body parts, or `feet` for shoe scales." }, "country_codes": { "type": "array", "items": { "type": "string" }, "description": "Countries (ISO 3166-1 alpha-2) whose shops show this system by default." } }, "required": ["id", "code", "name", "scope", "gender", "body_part", "country_codes"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/plugin_info": { "get": { "operationId": "getPluginInfo", "summary": "Is this product eligible, and the widget's set-up for it (compatible keys, then ours)", "description": "The compatible answer (D19, CONTRACTS §1.1) with our keys added after it; each field's description starts with `D19 compatible:` or `Added:`. Not eligible: only `{eligible:false, reason}` (D50 reasons). From a domain the client does not allow, from an unknown client, or without `Origin` (curl, a server), the answer is `{eligible:false, reason:\"not_whitelisted\"}` (D39). An eligible answer may be kept 60 s by the browser; the CDN never keeps it (D52). The database down answers 503 with `Retry-After`.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "client_product_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed (no trimming, no case change)." } }, { "name": "available_sizes", "in": "query", "required": false, "schema": { "description": "The page's size names, comma-separated (`S,M,L`). Only part of the cache key; never makes a product not eligible.", "type": "string", "maxLength": 2000 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "eligible": { "type": "boolean", "const": true, "description": "D19 compatible: the widget may show." }, "social_proof": { "type": "boolean", "description": "D19 compatible: social-proof data drives the reco." }, "reco_mode": { "anyOf": [ { "type": "string", "enum": ["classic", "social_proof", "usual_size"] }, { "type": "null" } ], "description": "D19 compatible: explicit mode, then social proof, then chart, then usual size." }, "shoe_shape_slug": { "description": "D19 compatible: shoe last (E07), `null` for clothes.", "type": ["string", "null"] }, "widget_customization": { "type": "object", "properties": { "auto_reco": { "type": "boolean" }, "show_tooltip": { "type": "boolean" } }, "required": ["auto_reco", "show_tooltip"], "additionalProperties": false, "description": "D19 compatible: widget flags; both `true` when the client saved none." }, "gender": { "anyOf": [ { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, { "type": "null" } ], "description": "D19 compatible: product gender." }, "measurement_names": { "type": "array", "items": { "type": "string" }, "description": "D19 compatible: the chart's measurement names only (no ranges)." }, "body_part": { "anyOf": [ { "type": "string", "enum": ["clothes", "feet", "head"] }, { "type": "null" } ], "description": "D19 compatible: routing body part (E07)." }, "sizes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["name", "order"], "additionalProperties": false }, "description": "D19 compatible: the chart's sizes in chart order, `order` from 1." }, "sizing_chart_slug": { "description": "D19 compatible: the chart's slug.", "type": ["string", "null"] }, "comfort_renderer_theme": { "type": "object", "properties": { "adjusted": { "type": "string" }, "tight": { "type": "string" }, "too_tight": { "type": "string" }, "loose": { "type": "string" }, "too_loose": { "type": "string" } }, "required": ["adjusted", "tight", "too_tight", "loose", "too_loose"], "additionalProperties": false, "description": "D19 compatible: fit-scale colours (ours by default, D8)." }, "has_references_step": { "type": "boolean", "description": "D19 compatible: the reference-brands step is shown." }, "has_usual_size_step": { "type": "boolean", "description": "D19 compatible: the usual-size step is shown." }, "preferred_size_system_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "D19 compatible: the id of `usual_size_system_name` in `GET /v1/sizes` (EU = 2); `null` when `usual_size_list` is empty." }, "usual_size_list": { "type": "array", "items": { "type": "string" }, "description": "D19 compatible: the sizes a usual-size shopper picks from, in that system (the merchant's list or the chart sizes): in usual-size mode, and for every product with a chart when the merchant shows the usual-size path (D105); `[]` otherwise." }, "usual_size_system_name": { "description": "D19 compatible: the size system code of `usual_size_list` (`EU`); `null` when the list is empty.", "type": ["string", "null"] }, "sizing_adjustment": { "type": "number", "description": "D19 compatible: the product's merchant size offset (−1, 0 or +1; T04.07.03, D104), 0 by default. Fit, whitelist and note stay on the server." }, "reason": { "type": "null", "description": "Added: `null` when eligible." }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "gender": { "anyOf": [ { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, { "type": "null" } ] }, "body_part": { "anyOf": [ { "type": "string", "enum": ["bosom", "top", "bottom", "full", "feet", "head"] }, { "type": "null" } ] }, "image_url": { "type": ["string", "null"] } }, "required": ["id", "name", "gender", "body_part", "image_url"], "additionalProperties": false, "description": "Added: the product's public fields (no database ids or validation data)." }, "product_body_part": { "anyOf": [ { "type": "string", "enum": ["bosom", "top", "bottom", "full", "feet", "head"] }, { "type": "null" } ], "description": "Added: the garment region." }, "steps": { "type": "object", "properties": { "body_shapes": { "type": "boolean" }, "bra": { "type": "string", "enum": ["hidden", "optional", "mandatory"] } }, "required": ["body_shapes", "bra"], "additionalProperties": false, "description": "Added: which optional steps the flow shows." }, "fit_preferences": { "type": "array", "items": { "type": "string", "enum": ["slim", "regular", "relaxed"] }, "description": "Added: the fit preferences (`slim`, `regular`, `relaxed`) the chart has ease for; `[]` for body charts (D105)." }, "garment_type": { "anyOf": [ { "type": "string", "enum": ["top", "jacket", "tights", "shorts", "one_piece", "shoe", "helmet"] }, { "type": "null" } ], "description": "Added: the 3D garment template the clothed body wears for the product (`top`, `jacket`, `tights`, `shorts`, `one_piece`, `shoe`, `helmet`): the merchant's pick, else the linking rule's, else derived from the category and body part; `null` = no garment, the widget shows the skin fit view. The widget also shows none when the merchant turned clothes off (`plugin_show_garments` in the customization `theme`) or the template is not published yet (T14.14.09)." }, "garment_look": { "anyOf": [ { "type": "string", "enum": ["base", "tee"] }, { "type": "null" } ], "description": "Added: the look of `garment_type` (D131 3): `tee` = the CC0 T-shirt (a `top` product whose category says t-shirt / tee / singlet, or the merchant's \"T-shirt\" pick), else `base` (the generated garment); `null` when `garment_type` is `null`. The widget asks the garment route for this look." } }, "required": [ "eligible", "social_proof", "reco_mode", "shoe_shape_slug", "widget_customization", "gender", "measurement_names", "body_part", "sizes", "sizing_chart_slug", "comfort_renderer_theme", "has_references_step", "has_usual_size_step", "preferred_size_system_id", "usual_size_list", "usual_size_system_name", "sizing_adjustment", "reason", "product", "product_body_part", "steps", "fit_preferences", "garment_type", "garment_look" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false, "description": "D19 compatible: the widget must not show." }, "reason": { "type": "string", "enum": [ "client_inactive", "unknown_product", "inactive", "removed_from_feed", "not_validated", "no_size_chart", "missing_fields", "not_whitelisted" ], "description": "Added: why (D50); `not_whitelisted` is the soft refusal of D39." } }, "required": ["eligible", "reason"], "additionalProperties": false } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "post": { "operationId": "postEvents", "summary": "Send one tracking event, an array or `{events:[…]}` of up to 50 (64 KiB)", "description": "One event `{client_id, event, tracking_id, …}` (the compatible form, D19), a JSON array or `{events:[…]}`. `text/plain` (sendBeacon) is read as JSON. The call is queued and answered 202 `{received, accepted, rejected}` (D72); events are validated, enriched and stored by the workers. An unknown `event` is listed in `rejected` (a single event: 400 `unknown_event`); an `event_id` already sent with other data is `event_id_conflict` (a single event: 409). An unknown client answers 400 `unknown_client`; a bot or a paused client is dropped with a 2xx. Events from a domain the client does not allow are dropped with a 200 (D39). Limits: the per-call limit plus 200 events/s per `tracking_id` and 5,000 events/s per client (429). The queue down answers 503 `queue_unavailable`; another content type 415.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} }, { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } }, { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } } }, "required": ["events"] } ] } }, "text/plain": { "schema": { "anyOf": [ { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} }, { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } }, { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } } }, "required": ["events"] } ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events in the call (the compatible key, D19)." }, "accepted": { "description": "Events taken into the queue (or already stored).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "description": "Events refused at the door, by their index in the call.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "type": "string", "enum": [ "not_an_object", "missing_event", "unknown_event", "missing_client_id", "event_id_conflict", "duplicate_event_id" ] } }, "required": ["index", "error"] } }, "dropped": { "description": "Events dropped without an error to fix: origin not allowed (D39), a bot, a paused client.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": ["not_whitelisted", "bot", "client_not_serving"] } }, "required": ["received"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/debug": { "post": { "operationId": "postDebug", "summary": "Integration-script heartbeat and debug events (`__debug__`)", "description": "Same body forms, limits, origin rules and answer as `POST /events`; every item is stored as a `__debug__` event (kept 7 days).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} }, { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } }, { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } } }, "required": ["events"] } ] } }, "text/plain": { "schema": { "anyOf": [ { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} }, { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } }, { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {} } } }, "required": ["events"] } ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events in the call (the compatible key, D19)." }, "accepted": { "description": "Events taken into the queue (or already stored).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "description": "Events refused at the door, by their index in the call.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "type": "string", "enum": [ "not_an_object", "missing_event", "unknown_event", "missing_client_id", "event_id_conflict", "duplicate_event_id" ] } }, "required": ["index", "error"] } }, "dropped": { "description": "Events dropped without an error to fix: origin not allowed (D39), a bot, a paused client.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": ["not_whitelisted", "bot", "client_not_serving"] } }, "required": ["received"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/mixpanel/{name}": { "post": { "operationId": "postMixpanelEvent", "summary": "Product-analytics proxy: one UX event under its name (the compatible `sendMixpanelEvent`)", "description": "The compatible body `{payload: {client_id, tracking_id, …event fields}, mixpanel_properties: {$referrer, $screen_width, $screen_height, utm_source}}`; only those four page properties are kept. The name (URL-encoded) is a catalogue event name or a mapped older product-analytics name (`Plugin Opened` → `plugin_open`, `Size Validated` → `size_validated`, …); any other name is listed in `rejected` as `unknown_event` (202). The event then goes through the same intake as `POST /events` (origin rules and the D39 soft refusal, bots, rate limits, 64 KiB, the queue) and is stored like it (`ux` events are kept 90 days). No vendor is called in the request: with the client's analytics forwarding on, the worker forwards stored UX events later (T08.08.02).", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "description": "The event name, URL-encoded, such as `size_validated` or `Size%20Validated`." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {}, "description": "The event without its name: `client_id`, `tracking_id` and the event's fields." }, "mixpanel_properties": { "type": "object", "properties": { "$referrer": { "type": "string", "maxLength": 2048 }, "$screen_width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "$screen_height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "utm_source": { "type": "string", "maxLength": 2048 } } } }, "required": ["payload"] } }, "text/plain": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "event": { "type": "string", "minLength": 1, "maxLength": 64 }, "tracking_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timestamp_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "event_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "schema_version": { "type": "number", "const": 1 }, "user_agent": { "type": "string", "maxLength": 2048 }, "shop_country": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "store_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "instance_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "product_associated": { "type": "boolean" }, "ab_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "testEvent": { "type": "boolean", "const": true }, "extra": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["client_id", "event"], "additionalProperties": {}, "description": "The event without its name: `client_id`, `tracking_id` and the event's fields." }, "mixpanel_properties": { "type": "object", "properties": { "$referrer": { "type": "string", "maxLength": 2048 }, "$screen_width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "$screen_height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "utm_source": { "type": "string", "maxLength": 2048 } } } }, "required": ["payload"] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events in the call (the compatible key, D19)." }, "accepted": { "description": "Events taken into the queue (or already stored).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "description": "Events refused at the door, by their index in the call.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "type": "string", "enum": [ "not_an_object", "missing_event", "unknown_event", "missing_client_id", "event_id_conflict", "duplicate_event_id" ] } }, "required": ["index", "error"] } }, "dropped": { "description": "Events dropped without an error to fix: origin not allowed (D39), a bot, a paused client.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": ["not_whitelisted", "bot", "client_not_serving"] } }, "required": ["received"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/pixel/shopify": { "post": { "operationId": "postShopifyPixel", "summary": "Shopify Web Pixel event (cart, checkout)", "description": "Sent from Shopify's pixel sandbox, so the body's `origin` (the shop page) must be an allowed domain of `client_id`; otherwise the event is dropped with a 200. An optional `ingest_key` is verified when sent: a wrong one answers 401 `invalid_ingest_key`. Accepted events are queued (202) like `POST /events`; `checkout` becomes `transaction_end`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ] }, "origin": { "type": "string" }, "event": { "type": "string", "minLength": 1 }, "ingest_key": { "description": "Optional `fmt_ik_…` key (a string); verified when sent." }, "tracking_id": { "type": ["string", "null"] }, "shop_country": { "type": ["string", "null"] }, "product_id": { "type": ["string", "number", "null"] }, "variant_id": { "type": ["string", "number", "null"] }, "timestamp": { "type": "string" } }, "required": ["client_id", "event"], "additionalProperties": {} } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ] }, "origin": { "type": "string" }, "event": { "type": "string", "minLength": 1 }, "ingest_key": { "description": "Optional `fmt_ik_…` key (a string); verified when sent." }, "tracking_id": { "type": ["string", "null"] }, "shop_country": { "type": ["string", "null"] }, "product_id": { "type": ["string", "number", "null"] }, "variant_id": { "type": ["string", "number", "null"] }, "timestamp": { "type": "string" } }, "required": ["client_id", "event"], "additionalProperties": {} } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events in the call (the compatible key, D19)." }, "accepted": { "description": "Events taken into the queue (or already stored).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rejected": { "description": "Events refused at the door, by their index in the call.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "type": "string", "enum": [ "not_an_object", "missing_event", "unknown_event", "missing_client_id", "event_id_conflict", "duplicate_event_id" ] } }, "required": ["index", "error"] } }, "dropped": { "description": "Events dropped without an error to fix: origin not allowed (D39), a bot, a paused client.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": ["not_whitelisted", "bot", "client_not_serving"] } }, "required": ["received"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wrong_sizing_chart_products": { "put": { "operationId": "putWrongSizingChartProduct", "summary": "Report that a product page's sizes do not match its size chart", "description": "Unchanged legacy path. The body is optional (the legacy SDK sends none): `{page_sizes, status}`, at most 200 sizes. The server computes the status itself with the shared size match. One report per product per day is kept (later ones update it). An unknown client or product, a paused client, or a domain the client does not allow is dropped with a 200 (D39).", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "client_product_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page_sizes": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "status": { "type": "string", "enum": ["SOMEHOW_VALID", "INVALID"] } }, "additionalProperties": false } }, "text/plain": { "schema": { "type": "object", "properties": { "page_sizes": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "status": { "type": "string", "enum": ["SOMEHOW_VALID", "INVALID"] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer", "minimum": 0, "maximum": 1, "description": "1 when the report was stored." }, "dropped": { "type": "integer", "minimum": 0, "maximum": 1 }, "reason": { "type": "string", "const": "not_whitelisted" } }, "required": ["received"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api_keys/me": { "get": { "operationId": "getApiKeySelf", "summary": "The scoped API key of this call (server-to-server)", "description": "Send `Authorization: Bearer fmt_sk_…`. A missing or invalid key answers 401 `invalid_api_key`. With a key, `POST /events` needs the `events:write` scope (403 `insufficient_scope`), and a call may only name the key's own client.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key_id": { "type": "string" }, "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "recommend", "catalog:write", "analytics", "orders:write", "launch", "events:write" ] } }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": ["key_id", "client_id", "scopes", "expires_at"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/body/schema": { "get": { "operationId": "getBodySchema", "summary": "The measurement vocabulary (ids, label keys, groups, ranges, definitions) and the body model version", "description": "Served from memory, built once per model version from the shared vocabulary; fitter-only dimensions (`pelvisGirth`) are left out. `ETag` names the model version and a digest of the vocabulary; cached 5 min. Model data with no shopper data: any origin may read it (D82). The body-service down or loading answers 503.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelVersion": { "type": "string" }, "units": { "type": "string", "const": "cm" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "labelKey": { "type": "string" }, "group": { "type": "string" }, "minCm": { "type": "number" }, "maxCm": { "type": "number" }, "definition": { "type": "string" }, "meshMethod": { "type": "string" }, "advanced": { "type": "boolean" }, "fittable": { "type": "boolean" }, "metadataOnly": { "type": "boolean" } }, "required": [ "id", "labelKey", "group", "minCm", "maxCm", "definition", "meshMethod", "advanced", "fittable", "metadataOnly" ], "additionalProperties": false } } }, "required": ["modelVersion", "units", "dimensions"], "additionalProperties": false } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/default": { "get": { "operationId": "getDefaultBody", "summary": "The default female or male body of the current body model (a public, immutable CDN artifact)", "description": "Without `modelVersion`: a 302 (cached 60 s) to `?bodyType=…&modelVersion=`. With it: the body-service's default-body report (params, measurements, rest joints, tape paths), `Cache-Control: public, max-age=31536000, immutable`, built once per body type and model version (no job per shopper). Another model version answers 404. Model data with no shopper data: any origin may read it (D82).", "parameters": [ { "name": "bodyType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["female", "male"], "description": "`female` or `male`." } }, { "name": "modelVersion", "in": "query", "required": false, "schema": { "description": "Body model version (`anny-0.6.1-fmt-1`). Without it the answer is a 302 to the current one.", "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelVersion": { "type": "string", "description": "Body model version; part of the URL and of every cache key." }, "bodyType": { "type": "string", "enum": ["female", "male"] }, "params": { "type": "array", "items": { "type": "number" }, "description": "`[logScale, ...morphs]` of the default body." }, "measuredCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "Every mesh dimension of the vocabulary, in cm." } }, "required": ["modelVersion", "bodyType", "params", "measuredCm"], "additionalProperties": {} } } } }, "302": { "description": "To the current model version's immutable URL.", "headers": { "Location": { "description": "The target URL.", "schema": { "type": "string" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/predict": { "post": { "operationId": "postBodyPredict", "summary": "Simple-mode answers → every body measurement with its own sd, and the live body's morph params", "description": "Anonymous shopper call from an allowed domain of `client_id` (D14); another origin, no `Origin` or an unknown or paused client is refused (403). Units are cm and kg. Synchronous, answered by the body-service predictor within 1 s (no job). Boys and girls get `{status:\"needs_measurements\"}` while the predictor has no child data. Values outside the widget's limits, unknown fields, a shape of the other gender or a bra on a male body answer 422 `validation_failed` with `error.fields` (never the values). No answer and no measurement is logged or stored. Rate limited per device (`tracking_id`, else client and IP): 429. The body-service down or slow answers 503; no trained predictor answers 501 `predictor_not_available` with `accuracyValidated:false`. `accuracyValidated` stays false until the accuracy validation (S14.09) signs off.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (or the `X-Fmt-Client` header)." } }, { "name": "tracking_id", "in": "query", "required": false, "schema": { "description": "The widget's tracking id: the device the rate limit counts (else client and IP).", "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gender": { "type": "string", "enum": ["female", "male", "boys", "girls"] }, "age": { "type": "integer", "minimum": 4, "maximum": 100 }, "heightCm": { "type": "number", "minimum": 80, "maximum": 210 }, "weightKg": { "type": "number", "minimum": 15, "maximum": 200 }, "bodyShape": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "bra": { "anyOf": [ { "anyOf": [ { "type": "string", "const": "N/A" }, { "type": "object", "properties": { "band": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "number" } ] }, "cup": { "type": "string", "maxLength": 4 }, "region": { "type": "string", "maxLength": 4 } }, "required": ["band", "cup"], "additionalProperties": false } ] }, { "type": "null" } ] }, "entered": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "valueCm": { "type": "number" }, "sdCm": { "type": "number", "minimum": 0, "maximum": 5 } }, "required": ["valueCm"], "additionalProperties": false } ] } } }, "required": ["gender", "age", "heightCm", "weightKg"], "additionalProperties": false } }, "text/plain": { "schema": { "type": "object", "properties": { "gender": { "type": "string", "enum": ["female", "male", "boys", "girls"] }, "age": { "type": "integer", "minimum": 4, "maximum": 100 }, "heightCm": { "type": "number", "minimum": 80, "maximum": 210 }, "weightKg": { "type": "number", "minimum": 15, "maximum": 200 }, "bodyShape": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "bra": { "anyOf": [ { "anyOf": [ { "type": "string", "const": "N/A" }, { "type": "object", "properties": { "band": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "number" } ] }, "cup": { "type": "string", "maxLength": 4 }, "region": { "type": "string", "maxLength": 4 } }, "required": ["band", "cup"], "additionalProperties": false } ] }, { "type": "null" } ] }, "entered": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "valueCm": { "type": "number" }, "sdCm": { "type": "number", "minimum": 0, "maximum": 5 } }, "required": ["valueCm"], "additionalProperties": false } ] } } }, "required": ["gender", "age", "heightCm", "weightKg"], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "predicted" }, "bodyType": { "type": "string", "enum": ["female", "male"] }, "measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "valueCm": { "type": "number" }, "sdCm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["predicted", "entered"] } }, "required": ["valueCm", "sdCm", "source"], "additionalProperties": false } }, "morphParams": { "type": "array", "items": { "type": "number" } }, "morphParamLabels": { "type": "array", "items": { "type": "string" } }, "bodyGapCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "outsideTrainingData": { "type": "boolean" }, "modelVersion": { "type": "string", "minLength": 1 }, "predictorVersion": { "type": "string", "minLength": 1 }, "accuracyValidated": { "type": "boolean" } }, "required": [ "status", "bodyType", "measurements", "morphParams", "morphParamLabels", "bodyGapCm", "outsideTrainingData", "modelVersion", "predictorVersion", "accuracyValidated" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_measurements" }, "reason": { "type": "string" }, "modelVersion": { "type": "string", "minLength": 1 }, "predictorVersion": { "type": "string", "minLength": 1 }, "accuracyValidated": { "type": "boolean" } }, "required": ["status", "reason", "modelVersion", "predictorVersion", "accuracyValidated"], "additionalProperties": false } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "501": { "description": "No trained predictor yet (`predictor_not_available`, `accuracyValidated:false`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/fit": { "post": { "operationId": "postBodyFit", "summary": "Fit the body to tape values in a background job (202 + the job)", "description": "Anonymous shopper call from an allowed domain of `client_id` (D14); another origin, no `Origin` or an unknown or paused client is refused (403). Needs `Idempotency-Key`. Answers 202 with the job and `Location`; poll `GET /v1/body/jobs/{id}` every `retryAfterMs`. The request and the result are stored encrypted and kept 24 h. Limits: per device (`tracking_id`, else client and IP; 15 a minute) and per client (429), at most 100 queued fits per client (429). The body-service down or loading answers 503.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (or the `X-Fmt-Client` header)." } }, { "name": "tracking_id", "in": "query", "required": false, "schema": { "description": "The widget's tracking id: the device the rate limit counts (else client and IP).", "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{8,96}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bodyType": { "type": "string", "enum": ["female", "male"] }, "measurementsCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "locked": { "maxItems": 40, "type": "array", "items": { "type": "string" } }, "parameters": { "minItems": 13, "maxItems": 17, "type": "array", "items": { "type": "number", "minimum": -1000000, "maximum": 1000000 } }, "shape": { "anyOf": [ { "type": "object", "properties": { "cupSize": { "type": "string", "enum": ["A", "B", "C", "D"] } }, "required": ["cupSize"], "additionalProperties": false }, { "type": "object", "properties": { "bustVolume": { "type": "number", "minimum": 0, "maximum": 100 }, "bustFirmness": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } ] }, "population": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 14, "maximum": 100 }, "heightCm": { "type": "number", "minimum": 140, "maximum": 210 }, "weightKg": { "type": "number", "minimum": 40, "maximum": 200 }, "bodyShape": { "type": "string", "maxLength": 40 }, "sdCm": { "type": "number", "minimum": 0, "maximum": 5 } }, "additionalProperties": false } }, "required": ["bodyType", "measurementsCm"], "additionalProperties": false }, "examples": { "example1": { "value": { "bodyType": "female", "measurementsCm": { "chest": 92, "waist": 74, "hipsMax": 100 } } } } }, "text/plain": { "schema": { "type": "object", "properties": { "bodyType": { "type": "string", "enum": ["female", "male"] }, "measurementsCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "locked": { "maxItems": 40, "type": "array", "items": { "type": "string" } }, "parameters": { "minItems": 13, "maxItems": 17, "type": "array", "items": { "type": "number", "minimum": -1000000, "maximum": 1000000 } }, "shape": { "anyOf": [ { "type": "object", "properties": { "cupSize": { "type": "string", "enum": ["A", "B", "C", "D"] } }, "required": ["cupSize"], "additionalProperties": false }, { "type": "object", "properties": { "bustVolume": { "type": "number", "minimum": 0, "maximum": 100 }, "bustFirmness": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } ] }, "population": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 14, "maximum": 100 }, "heightCm": { "type": "number", "minimum": 140, "maximum": 210 }, "weightKg": { "type": "number", "minimum": 40, "maximum": 200 }, "bodyShape": { "type": "string", "maxLength": 40 }, "sdCm": { "type": "number", "minimum": 0, "maximum": 5 } }, "additionalProperties": false } }, "required": ["bodyType", "measurementsCm"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "kind": { "type": "string", "const": "fit" }, "state": { "type": "string", "enum": ["queued", "running", "done", "failed", "cancelled"] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "retryAfterMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "modelVersion": { "type": ["string", "null"] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": ["invalid_request", "body_service_unavailable", "deadline_exceeded", "fit_failed"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false }, { "type": "null" } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "glb": { "type": "string", "description": "GLB of the fitted body (add `&morphs=1` for morph targets)." }, "json": { "type": "string", "description": "The fit report." }, "obj": { "type": "string", "description": "OBJ export (Body Studio downloads)." } }, "required": ["glb", "json", "obj"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "createdAt", "finishedAt", "expiresAt", "attempts", "retryAfterMs", "modelVersion", "error", "results" ], "additionalProperties": false } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "409": { "description": "The `Idempotency-Key` was used with another body (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "This Idempotency-Key was already used for another fit", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/jobs/{id}": { "get": { "operationId": "getBodyJob", "summary": "A body job's state (`queued`, `running`, `done`, `failed`, `cancelled`) and, when done, its result links", "description": "Anonymous shopper call from an allowed domain of `client_id` (D14); another origin, no `Origin` or an unknown or paused client is refused (403). Another client's job, or an unknown id, is 404; after 24 h 410. `retryAfterMs` (also `Retry-After`) is 300 ms during the first 3 s, then longer; null once final. A failed job carries an error code (`invalid_request`, `body_service_unavailable`, `deadline_exceeded`, `fit_failed`).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "The job id from `POST /v1/body/fit`." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (or the `X-Fmt-Client` header)." } }, { "name": "tracking_id", "in": "query", "required": false, "schema": { "description": "The widget's tracking id: the device the rate limit counts (else client and IP).", "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "kind": { "type": "string", "const": "fit" }, "state": { "type": "string", "enum": ["queued", "running", "done", "failed", "cancelled"] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "retryAfterMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "modelVersion": { "type": ["string", "null"] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": ["invalid_request", "body_service_unavailable", "deadline_exceeded", "fit_failed"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false }, { "type": "null" } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "glb": { "type": "string", "description": "GLB of the fitted body (add `&morphs=1` for morph targets)." }, "json": { "type": "string", "description": "The fit report." }, "obj": { "type": "string", "description": "OBJ export (Body Studio downloads)." } }, "required": ["glb", "json", "obj"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "createdAt", "finishedAt", "expiresAt", "attempts", "retryAfterMs", "modelVersion", "error", "results" ], "additionalProperties": false } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } }, "delete": { "operationId": "cancelBodyJob", "summary": "Cancel a queued or running body job", "description": "Anonymous shopper call from an allowed domain of `client_id` (D14); another origin, no `Origin` or an unknown or paused client is refused (403). A queued or running job becomes `cancelled` and never gets a result, even when its fit ends later. A job already `done`, `failed` or `cancelled` stays as it is, with `cancelled: false`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "The job id from `POST /v1/body/fit`." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (or the `X-Fmt-Client` header)." } }, { "name": "tracking_id", "in": "query", "required": false, "schema": { "description": "The widget's tracking id: the device the rate limit counts (else client and IP).", "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "kind": { "type": "string", "const": "fit" }, "state": { "type": "string", "enum": ["queued", "running", "done", "failed", "cancelled"] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "retryAfterMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "modelVersion": { "type": ["string", "null"] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": ["invalid_request", "body_service_unavailable", "deadline_exceeded", "fit_failed"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false }, { "type": "null" } ] }, "results": { "anyOf": [ { "type": "object", "properties": { "glb": { "type": "string", "description": "GLB of the fitted body (add `&morphs=1` for morph targets)." }, "json": { "type": "string", "description": "The fit report." }, "obj": { "type": "string", "description": "OBJ export (Body Studio downloads)." } }, "required": ["glb", "json", "obj"], "additionalProperties": false }, { "type": "null" } ] }, "cancelled": { "type": "boolean" } }, "required": [ "id", "kind", "state", "createdAt", "finishedAt", "expiresAt", "attempts", "retryAfterMs", "modelVersion", "error", "results", "cancelled" ], "additionalProperties": false } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/results/{file}": { "get": { "operationId": "getBodyResult", "summary": "A fitted body: `.glb` (Y-up metres, joints as nodes), `.json` (the fit report) or `.obj`", "description": "Anonymous shopper call from an allowed domain of `client_id` (D14); another origin, no `Origin` or an unknown or paused client is refused (403). Only for a `done` job of this client (else 404); 410 after 24 h. The GLB has the feet at y=0 and, with `morphs=1`, one morph target per morph parameter. The JSON report holds body numbers only. The old `.mtl` routes are gone (404).", "parameters": [ { "name": "file", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}\\.(glb|json|obj)$", "description": "`.glb`, `.json` or `.obj`." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (or the `X-Fmt-Client` header)." } }, { "name": "tracking_id", "in": "query", "required": false, "schema": { "description": "The widget's tracking id: the device the rate limit counts (else client and IP).", "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" } }, { "name": "morphs", "in": "query", "required": false, "schema": { "description": "`1`: the GLB carries one morph target per morph parameter (GLB only).", "type": "string", "enum": ["0", "1"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelVersion": { "type": "string" }, "bodyType": { "type": "string", "enum": ["female", "male"] }, "units": { "type": "string", "const": "cm" }, "coordinateSystem": { "type": "string" }, "requestedCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "constrained": { "type": "array", "items": { "type": "string" } }, "notConstrained": { "type": "array", "items": { "type": "string" } }, "params": { "type": "array", "items": { "type": "number" } }, "paramLabels": { "type": "array", "items": { "type": "string" } }, "measuredCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "errorsCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "gapsCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "toleranceCm": { "type": "number" }, "matched": { "type": "boolean" }, "message": { "type": "string" }, "shape": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "cupSize": { "type": ["string", "null"] }, "cupConvention": { "type": ["string", "null"] }, "solver": { "type": "object", "properties": { "success": { "type": "boolean" }, "evaluations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "seconds": { "type": "number" } }, "required": ["success", "evaluations", "seconds"], "additionalProperties": false }, "vertexCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "triangleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "restJoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "parent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "number" } } }, "required": ["name", "parent", "position"], "additionalProperties": false } }, "paths": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } }, "pathNotes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "convention": { "type": "string" }, "limitations": { "type": "string" }, "population": { "type": "object", "properties": { "predictorVersion": { "type": "string" }, "weightKg": { "type": "number" }, "weightInferred": { "type": "boolean" }, "heightCm": { "type": "number" }, "heightInferred": { "type": "boolean" }, "softCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "valueCm": { "type": "number" }, "sdCm": { "type": "number", "minimum": 0 } }, "required": ["valueCm", "sdCm"], "additionalProperties": false } }, "predictedCm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "valueCm": { "type": "number" }, "sdCm": { "type": "number", "minimum": 0 } }, "required": ["valueCm", "sdCm"], "additionalProperties": false } } }, "required": [ "predictorVersion", "weightKg", "weightInferred", "heightCm", "heightInferred", "softCm", "predictedCm" ], "additionalProperties": false } }, "required": [ "modelVersion", "bodyType", "units", "coordinateSystem", "requestedCm", "constrained", "notConstrained", "params", "paramLabels", "measuredCm", "errorsCm", "toleranceCm", "matched", "message", "shape", "cupSize", "cupConvention", "solver", "vertexCount", "triangleCount", "restJoints", "paths", "pathNotes", "convention", "limitations" ], "additionalProperties": false } }, "model/gltf-binary": { "schema": { "type": "string", "format": "binary" } }, "text/plain; charset=utf-8": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/morph_basis": { "get": { "operationId": "getBodyMorphBasis", "summary": "The client morph basis GLB: base mesh, 16 positive and 16 negative morphs, bust grid, joints, paths", "description": "Without `modelVersion`: a 302 (cached 60 s) to the current version. With it: the GLB (`model/gltf-binary`, gzip when accepted), `Cache-Control: public, max-age=31536000, immutable`; another model version is 404, a bodyType other than female/male or a lod other than 1/2 is 400. The manifest (bounds, target scales, joint deltas, measurement indices) is at `asset.extras.fmtMorphBasis` (contract: `morphBasisManifestSchema`). Model data with no shopper data: any origin may read it (D82).", "parameters": [ { "name": "bodyType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["female", "male"], "description": "`female` or `male`." } }, { "name": "lod", "in": "query", "required": true, "schema": { "description": "`1` full resolution (Body Studio), `2` decimated (widget).", "type": "string", "enum": ["1", "2"] } }, { "name": "modelVersion", "in": "query", "required": false, "schema": { "description": "Body model version (`anny-0.6.1-fmt-1`). Without it the answer is a 302 to the current one.", "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" } } ], "responses": { "200": { "description": "OK", "content": { "model/gltf-binary": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "To the current model version's immutable URL.", "headers": { "Location": { "description": "The target URL.", "schema": { "type": "string" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/body/garments/{template}": { "get": { "operationId": "getBodyGarment", "summary": "A garment GLB bound to the body: rest mesh, 41 morph targets in the basis order, binding, fit zones", "description": "T14.14.02 (D127–D129). Without `modelVersion`: a 302 (cached 60 s) to the current version. With it: the GLB (`model/gltf-binary`, brotli when accepted, else gzip), `Cache-Control: public, max-age=31536000, immutable`. An unknown template, bodyType, lod (only 1) or look (`tee` is a `top` look) is 400 naming the field; another model version is 404 `not_found`; a template not built yet (`shoe`, `helmet`) is 404 `garment_not_built`; the body-service down is 503, never cached. The manifest is at `asset.extras.fmtGarment` (contract: `garmentManifestSchema`). Model data with no shopper data: any origin may read it (D82).", "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string", "enum": ["top", "jacket", "tights", "shorts", "one_piece", "shoe", "helmet"], "description": "Garment template (`top`, `jacket`, …)." } }, { "name": "bodyType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["female", "male"], "description": "`female` or `male`." } }, { "name": "lod", "in": "query", "required": true, "schema": { "description": "Level of detail: only `1` (the full Anny mesh, D92).", "type": "string", "enum": ["1"] } }, { "name": "look", "in": "query", "required": false, "schema": { "default": "base", "description": "`base` (generated, default) or `tee` (the CC0 T-shirt, `top` only).", "type": "string", "enum": ["base", "tee"] } }, { "name": "modelVersion", "in": "query", "required": false, "schema": { "description": "Body model version (`anny-0.6.1-fmt-1`). Without it the answer is a 302 to the current one.", "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" } } ], "responses": { "200": { "description": "OK", "content": { "model/gltf-binary": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "To the current model version's immutable URL.", "headers": { "Location": { "description": "The target URL.", "schema": { "type": "string" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Invalid query parameter: bodyType", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_whitelisted", "message": "Origin not allowed for this client", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such job", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "410": { "description": "Expired: jobs and results are kept 24 h (`gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "gone", "message": "This job has expired (jobs and results are kept 24 h)", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body fails validation (`validation_failed`); `error.fields` names the fields, never the values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Invalid fields: measurementsCm.chest", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The body service is not available right now, retry later", "request_id": "req_01HZX3Q4V8M2N7P5R9T6W1Y0AB" } } } } } } } }, "/v1/reco/clothes": { "post": { "operationId": "postRecoClothes", "summary": "Size-chart (classic) size recommendation for clothes: the D19-compatible answer keys, then ours (CONTRACTS §8)", "description": "From a shop page on an allowed domain of `client_id` (or a server with a `recommend` API key); anyone else gets `{eligible:false, reason:\"not_whitelisted\", comfort:[]}` (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 `validation_failed` with `error.fields` (never the values). An unknown or not-eligible product, or a paused client, answers 404 `product_not_eligible` with its D50 `reason`. 60 calls a minute per `tracking_id` (429), on top of the client + IP limit. Answers are `no-store`; nothing the shopper sent is logged or stored. The database down answers 503. Quick answers go to the body-service predictor (sd per dimension); tape values in `measurements_cm` are used as entered (`uncertainty_cm`, default 1). `comfort[0]` is `recommended_size ?? closest_size`; `status` is `recommended`, `between_sizes`, `needs_measurements` (also when the predictor is down or untrained) or `no_match`. `available` never changes the pick. `size_conversions` (contract v2) holds every chart size in up to 3 other systems, the `shop_country`'s system first. `auto: true` marks the silent page-load reco: the same answer, counted apart, and an incomplete saved profile answers `needs_measurements` instead of 422.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "body_shape": { "description": "Female A|XA|H|X, male slug such as `regular-athletic-narrow`.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "bra": { "description": "`{region, band, cup}` (band as a number or text); `{region:\"N/A\", band:\"N/A\", cup:\"N/A\"}` = no bra.", "anyOf": [ { "anyOf": [ { "type": "string", "const": "N/A" }, { "type": "object", "properties": { "region": { "type": "string", "maxLength": 8 }, "band": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 8 } ] }, "cup": { "type": "string", "maxLength": 4 } } } ] }, { "type": "null" } ] }, "sizing_chart_slug": { "description": "Ignored when the product has a chart (D76).", "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "with_comfort": { "type": "boolean" }, "usualSize": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "measurements_cm": { "description": "Tape measurements (measured path, D13), keyed by vocabulary id (`chest`, `waist`, `hips`…).", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "uncertainty_cm": { "description": "The shopper's own ± for tape values, 0–5 cm (default 1).", "type": "number", "minimum": 0, "maximum": 5 }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed"] } }, "required": ["client_id", "product_id", "gender"] }, "examples": { "example1": { "value": { "age": 34, "gender": "female", "bra": { "region": "UK", "band": 34, "cup": "B" }, "weight": 62, "height": 168, "body_shape": "X", "client_id": 1000, "product_id": "W144-120", "sizing_chart_slug": "trimtextopextremefit", "references": [], "with_comfort": true } }, "example2": { "value": { "gender": "male", "age": 41, "height": 181, "weight": 80, "body_shape": "regular-athletic-narrow", "measurements_cm": { "chest": 97.5 }, "uncertainty_cm": 1, "fit_preference": "regular", "client_id": 1000, "product_id": "U640-066", "tracking_id": "7d1c2f0e-5c1b-4a61-9a4e-2b9f3c3d1a10", "available_sizes": ["S", "M", "L"] } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "body_shape": { "description": "Female A|XA|H|X, male slug such as `regular-athletic-narrow`.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "bra": { "description": "`{region, band, cup}` (band as a number or text); `{region:\"N/A\", band:\"N/A\", cup:\"N/A\"}` = no bra.", "anyOf": [ { "anyOf": [ { "type": "string", "const": "N/A" }, { "type": "object", "properties": { "region": { "type": "string", "maxLength": 8 }, "band": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 8 } ] }, "cup": { "type": "string", "maxLength": 4 } } } ] }, { "type": "null" } ] }, "sizing_chart_slug": { "description": "Ignored when the product has a chart (D76).", "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "with_comfort": { "type": "boolean" }, "usualSize": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": {} }, { "type": "null" } ] }, "measurements_cm": { "description": "Tape measurements (measured path, D13), keyed by vocabulary id (`chest`, `waist`, `hips`…).", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "uncertainty_cm": { "description": "The shopper's own ± for tape values, 0–5 cm (default 1).", "type": "number", "minimum": 0, "maximum": 5 }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed"] } }, "required": ["client_id", "product_id", "gender"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "comfort": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comfort": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Chart measurement names (`Chest`, `ArmLength`…) → level." }, "comparison": { "type": "string", "enum": ["SMALLER", "BIGGER"] } }, "required": ["name", "size_order", "comfort"], "additionalProperties": false }, "description": "D19: best first; `comfort[0]` is the shown size. Empty when none." }, "sizing_chart_info": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "primary_measurements": { "type": "array", "items": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" } }, "required": ["relation", "value"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "number" }, "size_name": { "type": "string" }, "size_order": { "type": "number" } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] } } }, "required": [ "id", "unique_name", "name", "primary_system", "primary_measurements", "measurements" ] }, { "type": "null" } ], "description": "D19: the full chart used." }, "user_measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "D19: the estimated body under the chart measurement names; Height and Weight as given." }, "size_conversions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_name": { "type": "string" } }, "required": ["size_name"], "additionalProperties": false } }, "description": "D19, D89: every chart size (primary label) → its label in up to 3 other systems, the shop country's system first: `{M: {FR: {size_name: \"38\"}, UK: {size_name: \"10\"}}}`. Never the primary system; an empty entry for a size with no other label; present for every status.", "examples": [ { "S": { "FR": { "size_name": "36" }, "UK": { "size_name": "8" } }, "M": { "FR": { "size_name": "38" }, "UK": { "size_name": "10" } }, "XXL": {} } ] }, "contract_version": { "type": "number", "const": 2 }, "id": { "type": "string", "minLength": 1, "description": "Reco id, sent as `reco_id` in the reco event." }, "engine_version": { "type": "string" }, "body_model_version": { "type": "string" }, "predictor_version": { "type": "string" }, "chart_id": { "description": "The chart used; null for a social-proof answer on a product with no chart.", "type": ["string", "null"] }, "chart_revision": { "description": "The chart's content hash; null when `chart_id` is null.", "type": ["string", "null"] }, "product_id": { "type": "string" }, "mode": { "type": "string", "enum": ["classic", "social_proof", "usual_size", "shoes", "head"] }, "input_source": { "type": "string", "enum": ["questions", "measurements", "mixed", "usual_size", "profile"] }, "status": { "type": "string", "enum": ["recommended", "between_sizes", "needs_measurements", "no_match"] }, "recommended_size": { "type": ["string", "null"] }, "closest_size": { "type": ["string", "null"] }, "alternatives": { "type": "array", "items": { "type": "string" } }, "direction_hint": { "anyOf": [ { "type": "string", "enum": ["size_up_for_relaxed", "size_down_for_slim"] }, { "type": "null" } ] }, "deciding_measurement": { "description": "D98, T07.09.09 (additive, contract version unchanged): the predicted primary measurement (vocabulary id, e.g. `waist`) whose tape value would most raise the chance of the right size; `null` when the gain is under the engine threshold, when every primary value is entered, for `needs_measurements` and single-size answers. Absent on usual-size, social-proof, shoe and head answers.", "type": ["string", "null"] }, "available": { "type": ["boolean", "null"] }, "message_key": { "type": "string", "enum": [ "RESULT_RECOMMENDED", "RESULT_BETWEEN_SIZES", "RESULT_NEEDS_MEASUREMENTS", "RESULT_NO_MATCH", "RESULT_NOT_AVAILABLE", "PRODUCT_UNIQUE_SIZE", "EDGE_OF_CHART", "SORRY_SOCIAL_PROOF" ] }, "missing_measurements": { "type": "array", "items": { "type": "string" } }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed", "brand"] }, "measurements_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value_cm": { "type": "number" }, "sd_cm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["entered", "predicted"] } }, "required": ["value_cm", "sd_cm", "source"], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "size": { "type": "string" }, "size_order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "available": { "type": ["boolean", "null"] }, "ranking_score": { "type": "number", "description": "Deterministic cost, lower is better; not a probability." }, "within_chart": { "type": "boolean" }, "robust_to_uncertainty": { "type": "boolean" }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Vocabulary id (`chest`, `hipsMax`…), or `weight`." }, "body_cm": { "type": "number" }, "body_range_cm": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 }, "relation": { "type": "string", "enum": ["below_range", "within_range", "above_range"] }, "outside_by_cm": { "type": "number", "minimum": 0 }, "uncertainty_outside_by_cm": { "type": "number", "minimum": 0 }, "comfort": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "comfort_alt": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "garment_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "dimension", "body_cm", "body_range_cm", "relation", "outside_by_cm", "uncertainty_outside_by_cm", "comfort" ], "additionalProperties": false } } }, "required": [ "size", "size_order", "available", "ranking_score", "within_chart", "robust_to_uncertainty", "comparisons" ], "additionalProperties": false } }, "comforts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Vocabulary id → level of the shown size." }, "primary_size_system": { "type": "string" }, "incoherent_references": { "description": "S05.04: references that contradict the body data or each other (D91), by their place in the request. On every classic answer (empty when none is flagged); a flag never blocks the size.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The reference's place in the request's `references` as sent." }, "reason": { "type": "string", "enum": [ "INCOHERERANCE_WARNING_REFERENCES", "INCOHERERANCE_WARNING_FOOT_LENGTH_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_FOOT_LENGTH_MULTIPLE_REFERENCES", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_MULTIPLE_REFERENCES" ] } }, "required": ["index", "reason"], "additionalProperties": false } }, "social_proof_sizes": { "description": "Social proof (S05.05): each size's share among similar shoppers who kept the product, best first, ratios rounded to 2 decimals summing to 1; empty for `no_match`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratio": { "type": "number" } }, "required": ["name", "ratio"] } }, "first_size": { "description": "Social proof (D19 key): the top size and its ratio; `{name: null, ratio: null}` for `no_match`.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "second_size": { "description": "Social proof (D19 key): the second size, or nulls.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "primary_system": { "description": "Social proof (D19 key): the size system of the names, `{name: \"EU\"}`; null without a chart.", "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, { "type": "null" } ] }, "sizing_chart_id": { "description": "Social proof (D19 key): the product's linked chart, or null when it has none.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ratio_high": { "description": "Social proof: the top ratio is above 0.6.", "type": "boolean" }, "social_proof_level": { "description": "Social proof: which rows gave the shares (the product, then fallbacks); null for `no_match`.", "anyOf": [ { "type": "string", "enum": ["product", "category_gender_body_part", "body_part_gender"] }, { "type": "null" } ] }, "social_proof_samples": { "description": "Social proof: how many similar shoppers were used (or found, for `no_match`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "morph_params": { "type": "array", "items": { "type": "number" } }, "found": { "description": "Usual size (D19 key): a size was found.", "type": "boolean" }, "name": { "description": "Usual size (D19 key): the size, as `recommended_size`.", "type": ["string", "null"] }, "size_order": { "description": "Usual size (D19 key): 0-based place in the chart.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_usual_size": { "description": "Usual size: lets the widget send `usual_size_add_to_cart`.", "type": "boolean", "const": true }, "offset_applied": { "description": "Usual size: sizes actually moved from the usual size. Classic with a product offset (T04.07.03): sizes the offset moved (0 at the chart's edge).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizing_adjustment": { "description": "Usual size, or classic with a product offset: the product's merchant offset that was used.", "type": "number" }, "precision": { "type": "null", "description": "Stays null until calibrated (S14.09)." }, "accuracy_validated": { "type": "boolean", "const": false }, "confidence_probability": { "type": "null" } }, "required": [ "comfort", "sizing_chart_info", "user_measurements", "size_conversions", "contract_version", "id", "engine_version", "chart_id", "chart_revision", "product_id", "mode", "input_source", "status", "recommended_size", "closest_size", "alternatives", "direction_hint", "available", "message_key", "missing_measurements", "fit_preference", "measurements_used", "candidates", "comforts", "primary_size_system", "precision", "accuracy_validated", "confidence_probability" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "comfort": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "comfort"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource, or a product with no reco (`product_not_eligible` with `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Values fail validation (`validation_failed`); `error.fields` names them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reco/shoes": { "post": { "operationId": "postRecoShoes", "summary": "Foot-length size recommendation: shoes (CONTRACTS §8, S05.07)", "description": "From a shop page on an allowed domain of `client_id` (or a server with a `recommend` API key); anyone else gets `{eligible:false, reason:\"not_whitelisted\", comfort:[]}` (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 `validation_failed` with `error.fields` (never the values). An unknown or not-eligible product, or a paused client, answers 404 `product_not_eligible` with its D50 `reason`. 60 calls a minute per `tracking_id` (429), on top of the client + IP limit. Answers are `no-store`; nothing the shopper sent is logged or stored. The database down answers 503. `foot_length` (cm, 10–34) is matched with the product's `feet` chart, ±0.25 cm (D111); a chart that gives the shoe's inner length adds the toe allowance (0.5–1.0 cm). Without it, adult `male` / `female` get an estimate from `height` (`source: predicted`, a larger ±), moved by shoe references (`type_of_references=shoe`); with no height, shoe references alone give it; children and `unisex` without a foot length answer `needs_measurements`. With none of foot length, height or a reference: 422 naming `foot_length`. A product that is not `feet` is a 422 naming `product_id`. One zone, `FootLength` (`TOO_TIGHT` = too short … `TOO_LOOSE` = too long); between two sizes the size where the foot is too short is never first. The §8 shape with `mode: shoes`, no `deciding_measurement`, no `morph_params`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "foot_length": { "description": "cm, 10–34. Optional with `height` or a shoe reference.", "type": "number" } }, "required": ["client_id", "product_id", "gender"] }, "examples": { "example1": { "value": { "client_id": 1000, "product_id": "SHOE-1", "gender": "female", "foot_length": 24.5 } }, "example2": { "value": { "client_id": 1000, "product_id": "SHOE-1", "gender": "male", "height": 180 } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "foot_length": { "description": "cm, 10–34. Optional with `height` or a shoe reference.", "type": "number" } }, "required": ["client_id", "product_id", "gender"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "comfort": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comfort": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Chart measurement names (`Chest`, `ArmLength`…) → level." }, "comparison": { "type": "string", "enum": ["SMALLER", "BIGGER"] } }, "required": ["name", "size_order", "comfort"], "additionalProperties": false }, "description": "D19: best first; `comfort[0]` is the shown size. Empty when none." }, "sizing_chart_info": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "primary_measurements": { "type": "array", "items": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" } }, "required": ["relation", "value"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "number" }, "size_name": { "type": "string" }, "size_order": { "type": "number" } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] } } }, "required": [ "id", "unique_name", "name", "primary_system", "primary_measurements", "measurements" ] }, { "type": "null" } ], "description": "D19: the full chart used." }, "user_measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "D19: the estimated body under the chart measurement names; Height and Weight as given." }, "size_conversions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_name": { "type": "string" } }, "required": ["size_name"], "additionalProperties": false } }, "description": "D19, D89: every chart size (primary label) → its label in up to 3 other systems, the shop country's system first: `{M: {FR: {size_name: \"38\"}, UK: {size_name: \"10\"}}}`. Never the primary system; an empty entry for a size with no other label; present for every status.", "examples": [ { "S": { "FR": { "size_name": "36" }, "UK": { "size_name": "8" } }, "M": { "FR": { "size_name": "38" }, "UK": { "size_name": "10" } }, "XXL": {} } ] }, "contract_version": { "type": "number", "const": 2 }, "id": { "type": "string", "minLength": 1, "description": "Reco id, sent as `reco_id` in the reco event." }, "engine_version": { "type": "string" }, "body_model_version": { "type": "string" }, "predictor_version": { "type": "string" }, "chart_id": { "description": "The chart used; null for a social-proof answer on a product with no chart.", "type": ["string", "null"] }, "chart_revision": { "description": "The chart's content hash; null when `chart_id` is null.", "type": ["string", "null"] }, "product_id": { "type": "string" }, "mode": { "type": "string", "enum": ["classic", "social_proof", "usual_size", "shoes", "head"] }, "input_source": { "type": "string", "enum": ["questions", "measurements", "mixed", "usual_size", "profile"] }, "status": { "type": "string", "enum": ["recommended", "between_sizes", "needs_measurements", "no_match"] }, "recommended_size": { "type": ["string", "null"] }, "closest_size": { "type": ["string", "null"] }, "alternatives": { "type": "array", "items": { "type": "string" } }, "direction_hint": { "anyOf": [ { "type": "string", "enum": ["size_up_for_relaxed", "size_down_for_slim"] }, { "type": "null" } ] }, "deciding_measurement": { "description": "D98, T07.09.09 (additive, contract version unchanged): the predicted primary measurement (vocabulary id, e.g. `waist`) whose tape value would most raise the chance of the right size; `null` when the gain is under the engine threshold, when every primary value is entered, for `needs_measurements` and single-size answers. Absent on usual-size, social-proof, shoe and head answers.", "type": ["string", "null"] }, "available": { "type": ["boolean", "null"] }, "message_key": { "type": "string", "enum": [ "RESULT_RECOMMENDED", "RESULT_BETWEEN_SIZES", "RESULT_NEEDS_MEASUREMENTS", "RESULT_NO_MATCH", "RESULT_NOT_AVAILABLE", "PRODUCT_UNIQUE_SIZE", "EDGE_OF_CHART", "SORRY_SOCIAL_PROOF" ] }, "missing_measurements": { "type": "array", "items": { "type": "string" } }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed", "brand"] }, "measurements_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value_cm": { "type": "number" }, "sd_cm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["entered", "predicted"] } }, "required": ["value_cm", "sd_cm", "source"], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "size": { "type": "string" }, "size_order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "available": { "type": ["boolean", "null"] }, "ranking_score": { "type": "number", "description": "Deterministic cost, lower is better; not a probability." }, "within_chart": { "type": "boolean" }, "robust_to_uncertainty": { "type": "boolean" }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Vocabulary id (`chest`, `hipsMax`…), or `weight`." }, "body_cm": { "type": "number" }, "body_range_cm": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 }, "relation": { "type": "string", "enum": ["below_range", "within_range", "above_range"] }, "outside_by_cm": { "type": "number", "minimum": 0 }, "uncertainty_outside_by_cm": { "type": "number", "minimum": 0 }, "comfort": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "comfort_alt": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "garment_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "dimension", "body_cm", "body_range_cm", "relation", "outside_by_cm", "uncertainty_outside_by_cm", "comfort" ], "additionalProperties": false } } }, "required": [ "size", "size_order", "available", "ranking_score", "within_chart", "robust_to_uncertainty", "comparisons" ], "additionalProperties": false } }, "comforts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Vocabulary id → level of the shown size." }, "primary_size_system": { "type": "string" }, "incoherent_references": { "description": "S05.04: references that contradict the body data or each other (D91), by their place in the request. On every classic answer (empty when none is flagged); a flag never blocks the size.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The reference's place in the request's `references` as sent." }, "reason": { "type": "string", "enum": [ "INCOHERERANCE_WARNING_REFERENCES", "INCOHERERANCE_WARNING_FOOT_LENGTH_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_FOOT_LENGTH_MULTIPLE_REFERENCES", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_MULTIPLE_REFERENCES" ] } }, "required": ["index", "reason"], "additionalProperties": false } }, "social_proof_sizes": { "description": "Social proof (S05.05): each size's share among similar shoppers who kept the product, best first, ratios rounded to 2 decimals summing to 1; empty for `no_match`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratio": { "type": "number" } }, "required": ["name", "ratio"] } }, "first_size": { "description": "Social proof (D19 key): the top size and its ratio; `{name: null, ratio: null}` for `no_match`.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "second_size": { "description": "Social proof (D19 key): the second size, or nulls.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "primary_system": { "description": "Social proof (D19 key): the size system of the names, `{name: \"EU\"}`; null without a chart.", "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, { "type": "null" } ] }, "sizing_chart_id": { "description": "Social proof (D19 key): the product's linked chart, or null when it has none.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ratio_high": { "description": "Social proof: the top ratio is above 0.6.", "type": "boolean" }, "social_proof_level": { "description": "Social proof: which rows gave the shares (the product, then fallbacks); null for `no_match`.", "anyOf": [ { "type": "string", "enum": ["product", "category_gender_body_part", "body_part_gender"] }, { "type": "null" } ] }, "social_proof_samples": { "description": "Social proof: how many similar shoppers were used (or found, for `no_match`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "morph_params": { "type": "array", "items": { "type": "number" } }, "found": { "description": "Usual size (D19 key): a size was found.", "type": "boolean" }, "name": { "description": "Usual size (D19 key): the size, as `recommended_size`.", "type": ["string", "null"] }, "size_order": { "description": "Usual size (D19 key): 0-based place in the chart.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_usual_size": { "description": "Usual size: lets the widget send `usual_size_add_to_cart`.", "type": "boolean", "const": true }, "offset_applied": { "description": "Usual size: sizes actually moved from the usual size. Classic with a product offset (T04.07.03): sizes the offset moved (0 at the chart's edge).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizing_adjustment": { "description": "Usual size, or classic with a product offset: the product's merchant offset that was used.", "type": "number" }, "precision": { "type": "null", "description": "Stays null until calibrated (S14.09)." }, "accuracy_validated": { "type": "boolean", "const": false }, "confidence_probability": { "type": "null" } }, "required": [ "comfort", "sizing_chart_info", "user_measurements", "size_conversions", "contract_version", "id", "engine_version", "chart_id", "chart_revision", "product_id", "mode", "input_source", "status", "recommended_size", "closest_size", "alternatives", "direction_hint", "available", "message_key", "missing_measurements", "fit_preference", "measurements_used", "candidates", "comforts", "primary_size_system", "precision", "accuracy_validated", "confidence_probability" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "comfort": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "comfort"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource, or a product with no reco (`product_not_eligible` with `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Values fail validation (`validation_failed`); `error.fields` names them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reco/head": { "post": { "operationId": "postRecoHead", "summary": "Head-circumference size recommendation: helmets and hats (CONTRACTS §8, S05.07)", "description": "From a shop page on an allowed domain of `client_id` (or a server with a `recommend` API key); anyone else gets `{eligible:false, reason:\"not_whitelisted\", comfort:[]}` (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 `validation_failed` with `error.fields` (never the values). An unknown or not-eligible product, or a paused client, answers 404 `product_not_eligible` with its D50 `reason`. 60 calls a minute per `tracking_id` (429), on top of the client + IP limit. Answers are `no-store`; nothing the shopper sent is logged or stored. The database down answers 503. `head_circumference` (cm; adults 50–65, `boys` / `girls` 48–58, `babies` 40–58) is matched with the product's `head` chart, ±0.5 cm (D109). It is never estimated from height or weight: without it a helmet reference (`type_of_references=head`) gives it, and with neither the answer is 422 naming `head_circumference`. A product that is not `head` is a 422 naming `product_id`. One girth zone, `HeadCircumference`. The §8 shape with `mode: head`, no `deciding_measurement`, no `morph_params`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "head_circumference": { "description": "cm. Optional with a helmet reference.", "type": "number" } }, "required": ["client_id", "product_id", "gender"] }, "examples": { "example1": { "value": { "client_id": 1000, "product_id": "HELMET-1", "gender": "male", "head_circumference": 57 } }, "example2": { "value": { "client_id": 1000, "product_id": "HELMET-1", "gender": "female", "references": [ { "brand_id": 12, "size_name": "M" } ] } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "head_circumference": { "description": "cm. Optional with a helmet reference.", "type": "number" } }, "required": ["client_id", "product_id", "gender"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "comfort": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comfort": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Chart measurement names (`Chest`, `ArmLength`…) → level." }, "comparison": { "type": "string", "enum": ["SMALLER", "BIGGER"] } }, "required": ["name", "size_order", "comfort"], "additionalProperties": false }, "description": "D19: best first; `comfort[0]` is the shown size. Empty when none." }, "sizing_chart_info": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "primary_measurements": { "type": "array", "items": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" } }, "required": ["relation", "value"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "number" }, "size_name": { "type": "string" }, "size_order": { "type": "number" } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] } } }, "required": [ "id", "unique_name", "name", "primary_system", "primary_measurements", "measurements" ] }, { "type": "null" } ], "description": "D19: the full chart used." }, "user_measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "D19: the estimated body under the chart measurement names; Height and Weight as given." }, "size_conversions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_name": { "type": "string" } }, "required": ["size_name"], "additionalProperties": false } }, "description": "D19, D89: every chart size (primary label) → its label in up to 3 other systems, the shop country's system first: `{M: {FR: {size_name: \"38\"}, UK: {size_name: \"10\"}}}`. Never the primary system; an empty entry for a size with no other label; present for every status.", "examples": [ { "S": { "FR": { "size_name": "36" }, "UK": { "size_name": "8" } }, "M": { "FR": { "size_name": "38" }, "UK": { "size_name": "10" } }, "XXL": {} } ] }, "contract_version": { "type": "number", "const": 2 }, "id": { "type": "string", "minLength": 1, "description": "Reco id, sent as `reco_id` in the reco event." }, "engine_version": { "type": "string" }, "body_model_version": { "type": "string" }, "predictor_version": { "type": "string" }, "chart_id": { "description": "The chart used; null for a social-proof answer on a product with no chart.", "type": ["string", "null"] }, "chart_revision": { "description": "The chart's content hash; null when `chart_id` is null.", "type": ["string", "null"] }, "product_id": { "type": "string" }, "mode": { "type": "string", "enum": ["classic", "social_proof", "usual_size", "shoes", "head"] }, "input_source": { "type": "string", "enum": ["questions", "measurements", "mixed", "usual_size", "profile"] }, "status": { "type": "string", "enum": ["recommended", "between_sizes", "needs_measurements", "no_match"] }, "recommended_size": { "type": ["string", "null"] }, "closest_size": { "type": ["string", "null"] }, "alternatives": { "type": "array", "items": { "type": "string" } }, "direction_hint": { "anyOf": [ { "type": "string", "enum": ["size_up_for_relaxed", "size_down_for_slim"] }, { "type": "null" } ] }, "deciding_measurement": { "description": "D98, T07.09.09 (additive, contract version unchanged): the predicted primary measurement (vocabulary id, e.g. `waist`) whose tape value would most raise the chance of the right size; `null` when the gain is under the engine threshold, when every primary value is entered, for `needs_measurements` and single-size answers. Absent on usual-size, social-proof, shoe and head answers.", "type": ["string", "null"] }, "available": { "type": ["boolean", "null"] }, "message_key": { "type": "string", "enum": [ "RESULT_RECOMMENDED", "RESULT_BETWEEN_SIZES", "RESULT_NEEDS_MEASUREMENTS", "RESULT_NO_MATCH", "RESULT_NOT_AVAILABLE", "PRODUCT_UNIQUE_SIZE", "EDGE_OF_CHART", "SORRY_SOCIAL_PROOF" ] }, "missing_measurements": { "type": "array", "items": { "type": "string" } }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed", "brand"] }, "measurements_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value_cm": { "type": "number" }, "sd_cm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["entered", "predicted"] } }, "required": ["value_cm", "sd_cm", "source"], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "size": { "type": "string" }, "size_order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "available": { "type": ["boolean", "null"] }, "ranking_score": { "type": "number", "description": "Deterministic cost, lower is better; not a probability." }, "within_chart": { "type": "boolean" }, "robust_to_uncertainty": { "type": "boolean" }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Vocabulary id (`chest`, `hipsMax`…), or `weight`." }, "body_cm": { "type": "number" }, "body_range_cm": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 }, "relation": { "type": "string", "enum": ["below_range", "within_range", "above_range"] }, "outside_by_cm": { "type": "number", "minimum": 0 }, "uncertainty_outside_by_cm": { "type": "number", "minimum": 0 }, "comfort": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "comfort_alt": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "garment_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "dimension", "body_cm", "body_range_cm", "relation", "outside_by_cm", "uncertainty_outside_by_cm", "comfort" ], "additionalProperties": false } } }, "required": [ "size", "size_order", "available", "ranking_score", "within_chart", "robust_to_uncertainty", "comparisons" ], "additionalProperties": false } }, "comforts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Vocabulary id → level of the shown size." }, "primary_size_system": { "type": "string" }, "incoherent_references": { "description": "S05.04: references that contradict the body data or each other (D91), by their place in the request. On every classic answer (empty when none is flagged); a flag never blocks the size.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The reference's place in the request's `references` as sent." }, "reason": { "type": "string", "enum": [ "INCOHERERANCE_WARNING_REFERENCES", "INCOHERERANCE_WARNING_FOOT_LENGTH_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_FOOT_LENGTH_MULTIPLE_REFERENCES", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_MULTIPLE_REFERENCES" ] } }, "required": ["index", "reason"], "additionalProperties": false } }, "social_proof_sizes": { "description": "Social proof (S05.05): each size's share among similar shoppers who kept the product, best first, ratios rounded to 2 decimals summing to 1; empty for `no_match`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratio": { "type": "number" } }, "required": ["name", "ratio"] } }, "first_size": { "description": "Social proof (D19 key): the top size and its ratio; `{name: null, ratio: null}` for `no_match`.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "second_size": { "description": "Social proof (D19 key): the second size, or nulls.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "primary_system": { "description": "Social proof (D19 key): the size system of the names, `{name: \"EU\"}`; null without a chart.", "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, { "type": "null" } ] }, "sizing_chart_id": { "description": "Social proof (D19 key): the product's linked chart, or null when it has none.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ratio_high": { "description": "Social proof: the top ratio is above 0.6.", "type": "boolean" }, "social_proof_level": { "description": "Social proof: which rows gave the shares (the product, then fallbacks); null for `no_match`.", "anyOf": [ { "type": "string", "enum": ["product", "category_gender_body_part", "body_part_gender"] }, { "type": "null" } ] }, "social_proof_samples": { "description": "Social proof: how many similar shoppers were used (or found, for `no_match`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "morph_params": { "type": "array", "items": { "type": "number" } }, "found": { "description": "Usual size (D19 key): a size was found.", "type": "boolean" }, "name": { "description": "Usual size (D19 key): the size, as `recommended_size`.", "type": ["string", "null"] }, "size_order": { "description": "Usual size (D19 key): 0-based place in the chart.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_usual_size": { "description": "Usual size: lets the widget send `usual_size_add_to_cart`.", "type": "boolean", "const": true }, "offset_applied": { "description": "Usual size: sizes actually moved from the usual size. Classic with a product offset (T04.07.03): sizes the offset moved (0 at the chart's edge).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizing_adjustment": { "description": "Usual size, or classic with a product offset: the product's merchant offset that was used.", "type": "number" }, "precision": { "type": "null", "description": "Stays null until calibrated (S14.09)." }, "accuracy_validated": { "type": "boolean", "const": false }, "confidence_probability": { "type": "null" } }, "required": [ "comfort", "sizing_chart_info", "user_measurements", "size_conversions", "contract_version", "id", "engine_version", "chart_id", "chart_revision", "product_id", "mode", "input_source", "status", "recommended_size", "closest_size", "alternatives", "direction_hint", "available", "message_key", "missing_measurements", "fit_preference", "measurements_used", "candidates", "comforts", "primary_size_system", "precision", "accuracy_validated", "confidence_probability" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "comfort": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "comfort"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource, or a product with no reco (`product_not_eligible` with `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Values fail validation (`validation_failed`); `error.fields` names them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reco/social_proof": { "post": { "operationId": "postRecoSocialProof", "summary": "Social-proof size recommendation: sizes kept by similar shoppers (CONTRACTS §8, S05.05)", "description": "From a shop page on an allowed domain of `client_id` (or a server with a `recommend` API key); anyone else gets `{eligible:false, reason:\"not_whitelisted\", comfort:[]}` (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 `validation_failed` with `error.fields` (never the values). An unknown or not-eligible product, or a paused client, answers 404 `product_not_eligible` with its D50 `reason`. 60 calls a minute per `tracking_id` (429), on top of the client + IP limit. Answers are `no-store`; nothing the shopper sent is logged or stored. The database down answers 503. For clothes, shoes and headwear in social-proof mode (the product's `reco_mode` override, or the client's default mode): `gender`, `age`, `height` and `weight` are required, `foot_length` / `head_circumference` sharpen shoes and headwear, `sizing_chart_slug` is `null`. The shares come from the shopper's nearest neighbours (same gender, about 50) among the shoppers who kept the product, falling back to its category + body part, then its body part; `social_proof_sizes` lists them best first, rounded to 2 decimals and summing to 1, and the top one is `recommended_size` (`available: false` when out of stock; no other size is swapped in). The older widget keys `first_size`, `second_size`, `size_conversions`, `primary_system` and `sizing_chart_id` (null without a chart) are kept. Fewer than the configured minimum (default 30) similar shoppers at every level, or no training data yet, answer `status: no_match` with `message_key: SORRY_SOCIAL_PROOF`, empty `social_proof_sizes` and null `first_size` / `second_size`. A product that is not in social-proof mode answers 404 `product_not_eligible` with `reason: not_social_proof`. Shares change only after the next daily training run; training data that cannot be read answers 503.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "foot_length": { "type": "number", "minimum": 10, "maximum": 34 }, "head_circumference": { "type": "number", "minimum": 40, "maximum": 66 }, "sizing_chart_slug": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] } }, "required": ["client_id", "product_id", "gender"] }, "examples": { "example1": { "value": { "client_id": 1000, "product_id": "U640-066", "gender": "male", "age": 30, "height": 180, "weight": 75 } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "type": "number" }, "height": { "description": "cm", "type": "number" }, "weight": { "description": "kg", "type": "number" }, "foot_length": { "type": "number", "minimum": 10, "maximum": 34 }, "head_circumference": { "type": "number", "minimum": 40, "maximum": 66 }, "sizing_chart_slug": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] } }, "required": ["client_id", "product_id", "gender"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "comfort": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comfort": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Chart measurement names (`Chest`, `ArmLength`…) → level." }, "comparison": { "type": "string", "enum": ["SMALLER", "BIGGER"] } }, "required": ["name", "size_order", "comfort"], "additionalProperties": false }, "description": "D19: best first; `comfort[0]` is the shown size. Empty when none." }, "sizing_chart_info": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "primary_measurements": { "type": "array", "items": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" } }, "required": ["relation", "value"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "number" }, "size_name": { "type": "string" }, "size_order": { "type": "number" } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] } } }, "required": [ "id", "unique_name", "name", "primary_system", "primary_measurements", "measurements" ] }, { "type": "null" } ], "description": "D19: the full chart used." }, "user_measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "D19: the estimated body under the chart measurement names; Height and Weight as given." }, "size_conversions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_name": { "type": "string" } }, "required": ["size_name"], "additionalProperties": false } }, "description": "D19, D89: every chart size (primary label) → its label in up to 3 other systems, the shop country's system first: `{M: {FR: {size_name: \"38\"}, UK: {size_name: \"10\"}}}`. Never the primary system; an empty entry for a size with no other label; present for every status.", "examples": [ { "S": { "FR": { "size_name": "36" }, "UK": { "size_name": "8" } }, "M": { "FR": { "size_name": "38" }, "UK": { "size_name": "10" } }, "XXL": {} } ] }, "contract_version": { "type": "number", "const": 2 }, "id": { "type": "string", "minLength": 1, "description": "Reco id, sent as `reco_id` in the reco event." }, "engine_version": { "type": "string" }, "body_model_version": { "type": "string" }, "predictor_version": { "type": "string" }, "chart_id": { "description": "The chart used; null for a social-proof answer on a product with no chart.", "type": ["string", "null"] }, "chart_revision": { "description": "The chart's content hash; null when `chart_id` is null.", "type": ["string", "null"] }, "product_id": { "type": "string" }, "mode": { "type": "string", "enum": ["classic", "social_proof", "usual_size", "shoes", "head"] }, "input_source": { "type": "string", "enum": ["questions", "measurements", "mixed", "usual_size", "profile"] }, "status": { "type": "string", "enum": ["recommended", "between_sizes", "needs_measurements", "no_match"] }, "recommended_size": { "type": ["string", "null"] }, "closest_size": { "type": ["string", "null"] }, "alternatives": { "type": "array", "items": { "type": "string" } }, "direction_hint": { "anyOf": [ { "type": "string", "enum": ["size_up_for_relaxed", "size_down_for_slim"] }, { "type": "null" } ] }, "deciding_measurement": { "description": "D98, T07.09.09 (additive, contract version unchanged): the predicted primary measurement (vocabulary id, e.g. `waist`) whose tape value would most raise the chance of the right size; `null` when the gain is under the engine threshold, when every primary value is entered, for `needs_measurements` and single-size answers. Absent on usual-size, social-proof, shoe and head answers.", "type": ["string", "null"] }, "available": { "type": ["boolean", "null"] }, "message_key": { "type": "string", "enum": [ "RESULT_RECOMMENDED", "RESULT_BETWEEN_SIZES", "RESULT_NEEDS_MEASUREMENTS", "RESULT_NO_MATCH", "RESULT_NOT_AVAILABLE", "PRODUCT_UNIQUE_SIZE", "EDGE_OF_CHART", "SORRY_SOCIAL_PROOF" ] }, "missing_measurements": { "type": "array", "items": { "type": "string" } }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed", "brand"] }, "measurements_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value_cm": { "type": "number" }, "sd_cm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["entered", "predicted"] } }, "required": ["value_cm", "sd_cm", "source"], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "size": { "type": "string" }, "size_order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "available": { "type": ["boolean", "null"] }, "ranking_score": { "type": "number", "description": "Deterministic cost, lower is better; not a probability." }, "within_chart": { "type": "boolean" }, "robust_to_uncertainty": { "type": "boolean" }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Vocabulary id (`chest`, `hipsMax`…), or `weight`." }, "body_cm": { "type": "number" }, "body_range_cm": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 }, "relation": { "type": "string", "enum": ["below_range", "within_range", "above_range"] }, "outside_by_cm": { "type": "number", "minimum": 0 }, "uncertainty_outside_by_cm": { "type": "number", "minimum": 0 }, "comfort": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "comfort_alt": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "garment_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "dimension", "body_cm", "body_range_cm", "relation", "outside_by_cm", "uncertainty_outside_by_cm", "comfort" ], "additionalProperties": false } } }, "required": [ "size", "size_order", "available", "ranking_score", "within_chart", "robust_to_uncertainty", "comparisons" ], "additionalProperties": false } }, "comforts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Vocabulary id → level of the shown size." }, "primary_size_system": { "type": "string" }, "incoherent_references": { "description": "S05.04: references that contradict the body data or each other (D91), by their place in the request. On every classic answer (empty when none is flagged); a flag never blocks the size.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The reference's place in the request's `references` as sent." }, "reason": { "type": "string", "enum": [ "INCOHERERANCE_WARNING_REFERENCES", "INCOHERERANCE_WARNING_FOOT_LENGTH_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_FOOT_LENGTH_MULTIPLE_REFERENCES", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_MULTIPLE_REFERENCES" ] } }, "required": ["index", "reason"], "additionalProperties": false } }, "social_proof_sizes": { "description": "Social proof (S05.05): each size's share among similar shoppers who kept the product, best first, ratios rounded to 2 decimals summing to 1; empty for `no_match`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratio": { "type": "number" } }, "required": ["name", "ratio"] } }, "first_size": { "description": "Social proof (D19 key): the top size and its ratio; `{name: null, ratio: null}` for `no_match`.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "second_size": { "description": "Social proof (D19 key): the second size, or nulls.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "primary_system": { "description": "Social proof (D19 key): the size system of the names, `{name: \"EU\"}`; null without a chart.", "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, { "type": "null" } ] }, "sizing_chart_id": { "description": "Social proof (D19 key): the product's linked chart, or null when it has none.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ratio_high": { "description": "Social proof: the top ratio is above 0.6.", "type": "boolean" }, "social_proof_level": { "description": "Social proof: which rows gave the shares (the product, then fallbacks); null for `no_match`.", "anyOf": [ { "type": "string", "enum": ["product", "category_gender_body_part", "body_part_gender"] }, { "type": "null" } ] }, "social_proof_samples": { "description": "Social proof: how many similar shoppers were used (or found, for `no_match`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "morph_params": { "type": "array", "items": { "type": "number" } }, "found": { "description": "Usual size (D19 key): a size was found.", "type": "boolean" }, "name": { "description": "Usual size (D19 key): the size, as `recommended_size`.", "type": ["string", "null"] }, "size_order": { "description": "Usual size (D19 key): 0-based place in the chart.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_usual_size": { "description": "Usual size: lets the widget send `usual_size_add_to_cart`.", "type": "boolean", "const": true }, "offset_applied": { "description": "Usual size: sizes actually moved from the usual size. Classic with a product offset (T04.07.03): sizes the offset moved (0 at the chart's edge).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizing_adjustment": { "description": "Usual size, or classic with a product offset: the product's merchant offset that was used.", "type": "number" }, "precision": { "type": "null", "description": "Stays null until calibrated (S14.09)." }, "accuracy_validated": { "type": "boolean", "const": false }, "confidence_probability": { "type": "null" } }, "required": [ "comfort", "sizing_chart_info", "user_measurements", "size_conversions", "contract_version", "id", "engine_version", "chart_id", "chart_revision", "product_id", "mode", "input_source", "status", "recommended_size", "closest_size", "alternatives", "direction_hint", "available", "message_key", "missing_measurements", "fit_preference", "measurements_used", "candidates", "comforts", "primary_size_system", "precision", "accuracy_validated", "confidence_probability" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "comfort": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "comfort"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource, or a product with no reco (`product_not_eligible` with `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Values fail validation (`validation_failed`); `error.fields` names them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reco/usual_size": { "post": { "operationId": "postRecoUsualSize", "summary": "Usual-size recommendation: the shopper's usual size moved by fit feeling and desired fit (CONTRACTS §8)", "description": "From a shop page on an allowed domain of `client_id` (or a server with a `recommend` API key); anyone else gets `{eligible:false, reason:\"not_whitelisted\", comfort:[]}` (D39). Values outside the widget limits, unknown genders or shapes, unknown tape keys and a ± over 5 cm answer 422 `validation_failed` with `error.fields` (never the values). An unknown or not-eligible product, or a paused client, answers 404 `product_not_eligible` with its D50 `reason`. 60 calls a minute per `tracking_id` (429), on top of the client + IP limit. Answers are `no-store`; nothing the shopper sent is logged or stored. The database down answers 503. The usual size (one of `plugin_info.usual_size_list`, read in `size_system_id` or else the product's preferred system) moves by the fit answers: `narrow` and `oversize` +½ size, `comfy` and `slim` −½, plus the product's own offset, rounded away from zero, at most ±2 (D89). A `sizing_adjustment` sent here is ignored. Answers the §8 shape with `mode: usual_size` and the D19 keys `found`, `name`, `size_order`, `precision`, plus `is_usual_size` and `offset_applied`. A name outside the list, or an unknown `size_system_id`, is a 422 naming the field. Needs no predictor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "size_system_id": { "description": "A size system id of `GET /v1/sizes` (EU is 2). Default: the product's preferred system.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 32 } ] }, "usual_size_name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One of `plugin_info.usual_size_list`." }, "fit_feeling": { "type": "string", "enum": ["narrow", "perfect", "comfy"], "description": "How the usual size fits: `narrow`, `perfect` or `comfy`." }, "desired_fit": { "type": "string", "enum": ["slim", "regular", "oversize"], "description": "How this product should fit: `slim`, `regular` or `oversize`." }, "sizing_adjustment": { "description": "Ignored: the product's own offset is used (D89).", "type": "number", "minimum": -5, "maximum": 5 } }, "required": ["client_id", "product_id", "usual_size_name", "fit_feeling", "desired_fit"] }, "examples": { "example1": { "value": { "client_id": 1000, "product_id": "U640-066", "usual_size_name": "M", "fit_feeling": "perfect", "desired_fit": "regular", "available_sizes": ["S", "M", "L"] } }, "example2": { "value": { "client_id": 1000, "product_id": "W144-120", "size_system_id": 10, "usual_size_name": "40", "fit_feeling": "narrow", "desired_fit": "regular" } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$" } ], "description": "The client's numeric id (a number, as the D19 widget sends it, or digits)." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, exactly as in the feed." }, "tracking_id": { "description": "The device's tracking id; absent before analytics consent (D7). Never changes the size.", "type": "string", "minLength": 1, "maxLength": 128 }, "available_sizes": { "description": "The page's sizes (live stock). Only sets `available`; never changes the pick.", "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "shop_country": { "type": "string", "maxLength": 8 }, "channel": { "type": "string", "maxLength": 32 }, "language": { "type": "string", "maxLength": 16 }, "model": { "description": "The A/B \"Model Variation\" value.", "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "number" } ] }, { "type": "null" } ] }, "references": { "description": "Reference brands (used from S05.04).", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "brand_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 64 } ] }, "sizing_chart_slug": { "type": "string", "minLength": 1, "maxLength": 240 }, "size_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "size_system": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": ["size_name"] } }, "auto": { "description": "Auto-reco (T05.08.01): the widget asked silently at page load from the saved profile. Same answer; an incomplete profile answers `needs_measurements` instead of 422. Counted and logged apart.", "type": "boolean" }, "size_system_id": { "description": "A size system id of `GET /v1/sizes` (EU is 2). Default: the product's preferred system.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1, "maxLength": 32 } ] }, "usual_size_name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One of `plugin_info.usual_size_list`." }, "fit_feeling": { "type": "string", "enum": ["narrow", "perfect", "comfy"], "description": "How the usual size fits: `narrow`, `perfect` or `comfy`." }, "desired_fit": { "type": "string", "enum": ["slim", "regular", "oversize"], "description": "How this product should fit: `slim`, `regular` or `oversize`." }, "sizing_adjustment": { "description": "Ignored: the product's own offset is used (D89).", "type": "number", "minimum": -5, "maximum": 5 } }, "required": ["client_id", "product_id", "usual_size_name", "fit_feeling", "desired_fit"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "comfort": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comfort": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Chart measurement names (`Chest`, `ArmLength`…) → level." }, "comparison": { "type": "string", "enum": ["SMALLER", "BIGGER"] } }, "required": ["name", "size_order", "comfort"], "additionalProperties": false }, "description": "D19: best first; `comfort[0]` is the shown size. Empty when none." }, "sizing_chart_info": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_name": { "type": "string" }, "name": { "type": "string" }, "primary_system": { "type": "object", "properties": { "system": { "type": "string" } }, "required": ["system"] }, "primary_measurements": { "type": "array", "items": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "measurement_name": { "type": "string" }, "constraints": { "type": "array", "items": { "type": "object", "properties": { "relation": { "type": "string", "enum": ["=", "<", ">"] }, "value": { "type": "number" } }, "required": ["relation", "value"] } }, "systems": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_id": { "type": "number" }, "size_name": { "type": "string" }, "size_order": { "type": "number" } }, "required": ["size_id", "size_name", "size_order"] } } }, "required": ["measurement_name", "constraints", "systems"] } } }, "required": [ "id", "unique_name", "name", "primary_system", "primary_measurements", "measurements" ] }, { "type": "null" } ], "description": "D19: the full chart used." }, "user_measurements": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "D19: the estimated body under the chart measurement names; Height and Weight as given." }, "size_conversions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "size_name": { "type": "string" } }, "required": ["size_name"], "additionalProperties": false } }, "description": "D19, D89: every chart size (primary label) → its label in up to 3 other systems, the shop country's system first: `{M: {FR: {size_name: \"38\"}, UK: {size_name: \"10\"}}}`. Never the primary system; an empty entry for a size with no other label; present for every status.", "examples": [ { "S": { "FR": { "size_name": "36" }, "UK": { "size_name": "8" } }, "M": { "FR": { "size_name": "38" }, "UK": { "size_name": "10" } }, "XXL": {} } ] }, "contract_version": { "type": "number", "const": 2 }, "id": { "type": "string", "minLength": 1, "description": "Reco id, sent as `reco_id` in the reco event." }, "engine_version": { "type": "string" }, "body_model_version": { "type": "string" }, "predictor_version": { "type": "string" }, "chart_id": { "description": "The chart used; null for a social-proof answer on a product with no chart.", "type": ["string", "null"] }, "chart_revision": { "description": "The chart's content hash; null when `chart_id` is null.", "type": ["string", "null"] }, "product_id": { "type": "string" }, "mode": { "type": "string", "enum": ["classic", "social_proof", "usual_size", "shoes", "head"] }, "input_source": { "type": "string", "enum": ["questions", "measurements", "mixed", "usual_size", "profile"] }, "status": { "type": "string", "enum": ["recommended", "between_sizes", "needs_measurements", "no_match"] }, "recommended_size": { "type": ["string", "null"] }, "closest_size": { "type": ["string", "null"] }, "alternatives": { "type": "array", "items": { "type": "string" } }, "direction_hint": { "anyOf": [ { "type": "string", "enum": ["size_up_for_relaxed", "size_down_for_slim"] }, { "type": "null" } ] }, "deciding_measurement": { "description": "D98, T07.09.09 (additive, contract version unchanged): the predicted primary measurement (vocabulary id, e.g. `waist`) whose tape value would most raise the chance of the right size; `null` when the gain is under the engine threshold, when every primary value is entered, for `needs_measurements` and single-size answers. Absent on usual-size, social-proof, shoe and head answers.", "type": ["string", "null"] }, "available": { "type": ["boolean", "null"] }, "message_key": { "type": "string", "enum": [ "RESULT_RECOMMENDED", "RESULT_BETWEEN_SIZES", "RESULT_NEEDS_MEASUREMENTS", "RESULT_NO_MATCH", "RESULT_NOT_AVAILABLE", "PRODUCT_UNIQUE_SIZE", "EDGE_OF_CHART", "SORRY_SOCIAL_PROOF" ] }, "missing_measurements": { "type": "array", "items": { "type": "string" } }, "fit_preference": { "type": "string", "enum": ["slim", "regular", "relaxed", "brand"] }, "measurements_used": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value_cm": { "type": "number" }, "sd_cm": { "type": "number", "minimum": 0 }, "source": { "type": "string", "enum": ["entered", "predicted"] } }, "required": ["value_cm", "sd_cm", "source"], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "size": { "type": "string" }, "size_order": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "available": { "type": ["boolean", "null"] }, "ranking_score": { "type": "number", "description": "Deterministic cost, lower is better; not a probability." }, "within_chart": { "type": "boolean" }, "robust_to_uncertainty": { "type": "boolean" }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Vocabulary id (`chest`, `hipsMax`…), or `weight`." }, "body_cm": { "type": "number" }, "body_range_cm": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 2, "maxItems": 2 }, "relation": { "type": "string", "enum": ["below_range", "within_range", "above_range"] }, "outside_by_cm": { "type": "number", "minimum": 0 }, "uncertainty_outside_by_cm": { "type": "number", "minimum": 0 }, "comfort": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "comfort_alt": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "garment_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "dimension", "body_cm", "body_range_cm", "relation", "outside_by_cm", "uncertainty_outside_by_cm", "comfort" ], "additionalProperties": false } } }, "required": [ "size", "size_order", "available", "ranking_score", "within_chart", "robust_to_uncertainty", "comparisons" ], "additionalProperties": false } }, "comforts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": ["TOO_TIGHT", "TIGHT", "ADJUSTED", "LOOSE", "TOO_LOOSE"] }, "description": "Vocabulary id → level of the shown size." }, "primary_size_system": { "type": "string" }, "incoherent_references": { "description": "S05.04: references that contradict the body data or each other (D91), by their place in the request. On every classic answer (empty when none is flagged); a flag never blocks the size.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The reference's place in the request's `references` as sent." }, "reason": { "type": "string", "enum": [ "INCOHERERANCE_WARNING_REFERENCES", "INCOHERERANCE_WARNING_FOOT_LENGTH_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_FOOT_LENGTH_MULTIPLE_REFERENCES", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_SINGLE_REFERENCE", "INCOHERERANCE_WARNING_HEAD_CIRCUMFERENCE_MULTIPLE_REFERENCES" ] } }, "required": ["index", "reason"], "additionalProperties": false } }, "social_proof_sizes": { "description": "Social proof (S05.05): each size's share among similar shoppers who kept the product, best first, ratios rounded to 2 decimals summing to 1; empty for `no_match`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratio": { "type": "number" } }, "required": ["name", "ratio"] } }, "first_size": { "description": "Social proof (D19 key): the top size and its ratio; `{name: null, ratio: null}` for `no_match`.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "second_size": { "description": "Social proof (D19 key): the second size, or nulls.", "type": "object", "properties": { "name": { "type": ["string", "null"] }, "ratio": { "type": ["number", "null"] } }, "required": ["name", "ratio"], "additionalProperties": false }, "primary_system": { "description": "Social proof (D19 key): the size system of the names, `{name: \"EU\"}`; null without a chart.", "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, { "type": "null" } ] }, "sizing_chart_id": { "description": "Social proof (D19 key): the product's linked chart, or null when it has none.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ratio_high": { "description": "Social proof: the top ratio is above 0.6.", "type": "boolean" }, "social_proof_level": { "description": "Social proof: which rows gave the shares (the product, then fallbacks); null for `no_match`.", "anyOf": [ { "type": "string", "enum": ["product", "category_gender_body_part", "body_part_gender"] }, { "type": "null" } ] }, "social_proof_samples": { "description": "Social proof: how many similar shoppers were used (or found, for `no_match`).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "morph_params": { "type": "array", "items": { "type": "number" } }, "found": { "description": "Usual size (D19 key): a size was found.", "type": "boolean" }, "name": { "description": "Usual size (D19 key): the size, as `recommended_size`.", "type": ["string", "null"] }, "size_order": { "description": "Usual size (D19 key): 0-based place in the chart.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_usual_size": { "description": "Usual size: lets the widget send `usual_size_add_to_cart`.", "type": "boolean", "const": true }, "offset_applied": { "description": "Usual size: sizes actually moved from the usual size. Classic with a product offset (T04.07.03): sizes the offset moved (0 at the chart's edge).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizing_adjustment": { "description": "Usual size, or classic with a product offset: the product's merchant offset that was used.", "type": "number" }, "precision": { "type": "null", "description": "Stays null until calibrated (S14.09)." }, "accuracy_validated": { "type": "boolean", "const": false }, "confidence_probability": { "type": "null" } }, "required": [ "comfort", "sizing_chart_info", "user_measurements", "size_conversions", "contract_version", "id", "engine_version", "chart_id", "chart_revision", "product_id", "mode", "input_source", "status", "recommended_size", "closest_size", "alternatives", "direction_hint", "available", "message_key", "missing_measurements", "fit_preference", "measurements_used", "candidates", "comforts", "primary_size_system", "precision", "accuracy_validated", "confidence_probability" ], "additionalProperties": false }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "not_whitelisted" }, "comfort": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "comfort"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource, or a product with no reco (`product_not_eligible` with `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Values fail validation (`validation_failed`); `error.fields` names them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cross_sell_products": { "get": { "operationId": "getCrossSellProducts", "summary": "Suggested products for one cross-sell tab, with the shopper's size (compatible query)", "description": "One tab of suggested products for the product page (S07.12, D125), at most 12, each with the size the reco engine gives this profile on that product (null when it has no chart or the engine cannot decide). Latest releases: the same gender (and unisex) and body part, newest first. You might like: the same feed category, the same size chart first. Bought by people like you: kept by at least 5 shoppers close in gender, age, height and weight (training rows of S05.05), most kept first. Bought together: kept in at least 2 of the same orders, most shared orders first; full returns do not count. Only published products still in the feed, with a size in stock and an `https` page on an allowed domain of the client; never the current product. The cross-sell flag off or no match answers an empty list. An unknown product or chart answers `{eligible:false, reason:\"unknown_product\"}` like `plugin_info`; from a domain the client does not allow, or without `Origin`, `{eligible:false, reason:\"not_whitelisted\", products:[]}` (D39). A bad tab or value answers 422 `validation_failed` with `error.fields`. Answers are `no-store`; body values are never logged. The GET form is kept for compatibility; the widget sends the POST form, so body values never travel in a URL.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } }, { "name": "client_product_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product page's product id (merchant id)." } }, { "name": "cross_sell_products_type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["recentProducts", "similarProducts", "boughtBySimilarPeopleProducts", "boughtTogetherProducts"], "description": "The tab: `recentProducts` (latest releases), `similarProducts` (you might like), `boughtBySimilarPeopleProducts` (bought by people like you), `boughtTogetherProducts` (bought together)." } }, { "name": "sizing_chart_slug", "in": "query", "required": false, "schema": { "description": "The product's chart; an unknown one answers not found.", "type": "string", "maxLength": 240 } }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] } }, { "name": "age", "in": "query", "required": false, "schema": { "description": "Years, a whole number 0–120.", "type": "string" } }, { "name": "height", "in": "query", "required": false, "schema": { "description": "cm, 40–250.", "type": "string" } }, { "name": "weight", "in": "query", "required": false, "schema": { "description": "kg, 2–300.", "type": "string" } }, { "name": "foot_length", "in": "query", "required": false, "schema": { "description": "cm, 10–34 (shoe sizes).", "type": "string" } }, { "name": "client_host_name", "in": "query", "required": false, "schema": { "description": "Accepted and ignored.", "type": "string", "maxLength": 255 } }, { "name": "client_base_uri", "in": "query", "required": false, "schema": { "description": "Accepted and ignored.", "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "eligible": { "type": "boolean", "const": true }, "type": { "type": "string", "enum": [ "recentProducts", "similarProducts", "boughtBySimilarPeopleProducts", "boughtTogetherProducts" ] }, "products": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The merchant's product id." }, "name": { "type": "string" }, "image": { "type": "string", "format": "uri", "description": "Absolute `https` image address." }, "url": { "type": "string", "format": "uri", "description": "Absolute `https` product page, on one of the client's allowed domains." }, "price": { "description": "Null when the catalogue has no price.", "type": ["number", "null"] }, "currency": { "description": "ISO 4217 code, upper case.", "type": ["string", "null"] }, "size": { "description": "The size the reco engine gives this profile on that product, or null.", "type": ["string", "null"] } }, "required": ["id", "name", "image", "url", "price", "currency", "size"] } } }, "required": ["eligible", "type", "products"] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": ["not_whitelisted", "unknown_product", "client_inactive"] }, "products": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "products"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is missing or invalid (`error.fields` names it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postCrossSellProducts", "summary": "Suggested products for one cross-sell tab, with the shopper's size (JSON body)", "description": "One tab of suggested products for the product page (S07.12, D125), at most 12, each with the size the reco engine gives this profile on that product (null when it has no chart or the engine cannot decide). Latest releases: the same gender (and unisex) and body part, newest first. You might like: the same feed category, the same size chart first. Bought by people like you: kept by at least 5 shoppers close in gender, age, height and weight (training rows of S05.05), most kept first. Bought together: kept in at least 2 of the same orders, most shared orders first; full returns do not count. Only published products still in the feed, with a size in stock and an `https` page on an allowed domain of the client; never the current product. The cross-sell flag off or no match answers an empty list. An unknown product or chart answers `{eligible:false, reason:\"unknown_product\"}` like `plugin_info`; from a domain the client does not allow, or without `Origin`, `{eligible:false, reason:\"not_whitelisted\", products:[]}` (D39). A bad tab or value answers 422 `validation_failed` with `error.fields`. Answers are `no-store`; body values are never logged. The same names as the GET query, as a JSON body; numbers as numbers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } ] }, "client_product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product page's product id (merchant id)." }, "cross_sell_products_type": { "type": "string", "enum": [ "recentProducts", "similarProducts", "boughtBySimilarPeopleProducts", "boughtTogetherProducts" ], "description": "The tab: `recentProducts` (latest releases), `similarProducts` (you might like), `boughtBySimilarPeopleProducts` (bought by people like you), `boughtTogetherProducts` (bought together)." }, "sizing_chart_slug": { "description": "The product's chart; an unknown one answers not found.", "type": "string", "maxLength": 240 }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number", "minimum": 40, "maximum": 250 }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number", "minimum": 2, "maximum": 300 }, { "type": "null" } ] }, "foot_length": { "anyOf": [ { "type": "number", "minimum": 10, "maximum": 34 }, { "type": "null" } ] }, "client_host_name": { "description": "Accepted and ignored.", "type": "string", "maxLength": 255 }, "client_base_uri": { "description": "Accepted and ignored.", "type": "string", "maxLength": 2048 } }, "required": ["client_id", "client_product_id", "cross_sell_products_type"] }, "examples": { "example1": { "value": { "client_id": 9998, "client_product_id": "U510-054", "cross_sell_products_type": "recentProducts", "gender": "male", "age": 34, "height": 180, "weight": 78 } } } }, "text/plain": { "schema": { "type": "object", "properties": { "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } ] }, "client_product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product page's product id (merchant id)." }, "cross_sell_products_type": { "type": "string", "enum": [ "recentProducts", "similarProducts", "boughtBySimilarPeopleProducts", "boughtTogetherProducts" ], "description": "The tab: `recentProducts` (latest releases), `similarProducts` (you might like), `boughtBySimilarPeopleProducts` (bought by people like you), `boughtTogetherProducts` (bought together)." }, "sizing_chart_slug": { "description": "The product's chart; an unknown one answers not found.", "type": "string", "maxLength": 240 }, "gender": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies"] }, "age": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120 }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number", "minimum": 40, "maximum": 250 }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number", "minimum": 2, "maximum": 300 }, { "type": "null" } ] }, "foot_length": { "anyOf": [ { "type": "number", "minimum": 10, "maximum": 34 }, { "type": "null" } ] }, "client_host_name": { "description": "Accepted and ignored.", "type": "string", "maxLength": 255 }, "client_base_uri": { "description": "Accepted and ignored.", "type": "string", "maxLength": 2048 } }, "required": ["client_id", "client_product_id", "cross_sell_products_type"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "eligible": { "type": "boolean", "const": true }, "type": { "type": "string", "enum": [ "recentProducts", "similarProducts", "boughtBySimilarPeopleProducts", "boughtTogetherProducts" ] }, "products": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The merchant's product id." }, "name": { "type": "string" }, "image": { "type": "string", "format": "uri", "description": "Absolute `https` image address." }, "url": { "type": "string", "format": "uri", "description": "Absolute `https` product page, on one of the client's allowed domains." }, "price": { "description": "Null when the catalogue has no price.", "type": ["number", "null"] }, "currency": { "description": "ISO 4217 code, upper case.", "type": ["string", "null"] }, "size": { "description": "The size the reco engine gives this profile on that product, or null.", "type": ["string", "null"] } }, "required": ["id", "name", "image", "url", "price", "currency", "size"] } } }, "required": ["eligible", "type", "products"] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": ["not_whitelisted", "unknown_product", "client_inactive"] }, "products": { "maxItems": 0, "type": "array", "items": { "not": {} } } }, "required": ["eligible", "reason", "products"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is missing or invalid (`error.fields` names it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/retail/{client_id}/profile": { "get": { "operationId": "getRetailProfile", "summary": "The retail app's brand, colour, languages and unit system for one client", "description": "What the retail home screen shows (T10.05.02): the brand name, the logo (null until clients have one), the published widget colour, the enabled and default languages (lower-case codes) and the unit system (`auto` with a US shop country is answered as `imperial`). A client with the retail app off answers `{eligible:false, reason:\"retail_disabled\"}`; an unknown, paused or churned client 404. Browsers keep it 5 minutes (`private, max-age=300`, with an `ETag`); the CDN never. Browsers may call it only from the retail app's origins (`https://retail.fitmytype.com` and its staging twin); any other `Origin` answers 403 `not_whitelisted`.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (the retail URL's first segment)." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "eligible": { "type": "boolean", "const": true }, "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "brand_name": { "type": "string" }, "logo_url": { "type": ["string", "null"] }, "primary_color": { "type": "string" }, "enabled_languages": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "default_unit_system": { "type": "string", "enum": ["auto", "metric", "imperial"] } }, "required": [ "eligible", "client_id", "brand_name", "logo_url", "primary_color", "enabled_languages", "default_language", "default_unit_system" ] }, { "type": "object", "properties": { "eligible": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "retail_disabled" } }, "required": ["eligible", "reason"] } ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/retail/{client_id}/products/by_barcode/{code}": { "get": { "operationId": "getRetailProductByBarcode", "summary": "The product a scanned or typed barcode belongs to", "description": "Looks the code up on the client's products and on their sizes (a size, or variant, code maps to its product, T10.05.03). Spaces and dashes in a numeric code are dropped; a 12-digit UPC-A, the 13-digit EAN with a leading zero and the 14-digit GTIN find each other. When two products share the code, the one that can open the size flow wins, then the active one with a size chart, then the lowest id (D133 5). A product that cannot open the size flow is still returned, with `eligible:false` and its `reason`. An unknown code, another client's code or a client that is unknown, paused, churned or has the retail app off (`retail_enabled`) answers 404 `not_found`, the same as an unknown product. A code over 64 characters, or with characters a Code-128 code cannot hold, answers 422 `validation_failed` naming `code`. Never cached. Browsers may call it only from the retail app's origins (`https://retail.fitmytype.com` and its staging twin); any other `Origin` answers 403 `not_whitelisted`.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (the retail URL's first segment)." } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "EAN-13, EAN-8, UPC-A, GTIN-14 or Code-128 text, URL-encoded." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "barcode": { "type": "string", "maxLength": 64 }, "matched_on": { "type": "string", "enum": ["product", "size"] }, "size": { "type": ["string", "null"] }, "product": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "category_label": { "type": ["string", "null"] }, "gender": { "anyOf": [ { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies", "child"] }, { "type": "null" } ] }, "body_part": { "anyOf": [ { "type": "string", "enum": ["bosom", "top", "bottom", "feet", "full", "head"] }, { "type": "null" } ] }, "sizes": { "type": "array", "items": { "type": "string" } }, "eligible": { "type": "boolean" }, "reason": { "type": ["string", "null"] } }, "required": [ "product_id", "name", "image_url", "category", "category_label", "gender", "body_part", "sizes", "eligible", "reason" ] } }, "required": ["barcode", "matched_on", "size", "product"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown code, another client's code, or the retail app is off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The code is too long or not Code-128 text (`error.fields` names `code`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/retail/{client_id}/products": { "get": { "operationId": "getRetailCatalogue", "summary": "One page of the client's products that can open the size flow", "description": "The retail catalogue (T10.05.04): only active, validated products with a published size chart that are still in the feed, by name. `q` matches part of the name ignoring case, accents and extra spaces, cut at 100 characters; `gender` and `category` (a value of `facets.categories`) filter; `page` starts at 1. A client that is unknown, paused, churned or has the retail app off (`retail_enabled`) answers 404 `not_found`, the same as an unknown product. A bad value answers 422 `validation_failed` naming the field. Never cached. Browsers may call it only from the retail app's origins (`https://retail.fitmytype.com` and its staging twin); any other `Origin` answers 403 `not_whitelisted`.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (the retail URL's first segment)." } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Part of the product name.", "type": "string" } }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies", "child"] } }, { "name": "category", "in": "query", "required": false, "schema": { "description": "The feed category, as listed in `facets.categories`.", "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "description": "From 1 (default 1).", "type": "string", "pattern": "^\\d+$" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "description": "1 to 48 (default 24).", "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "category_label": { "type": ["string", "null"] }, "gender": { "anyOf": [ { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies", "child"] }, { "type": "null" } ] }, "body_part": { "anyOf": [ { "type": "string", "enum": ["bosom", "top", "bottom", "feet", "full", "head"] }, { "type": "null" } ] }, "sizes": { "type": "array", "items": { "type": "string" } }, "eligible": { "type": "boolean" }, "reason": { "type": ["string", "null"] } }, "required": [ "product_id", "name", "image_url", "category", "category_label", "gender", "body_part", "sizes", "eligible", "reason" ] } }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "page_size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total_pages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "q": { "type": ["string", "null"] }, "facets": { "type": "object", "properties": { "genders": { "type": "array", "items": { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies", "child"] } }, "categories": { "type": "array", "items": { "type": "string" } } }, "required": ["genders", "categories"] } }, "required": ["items", "page", "page_size", "total", "total_pages", "q", "facets"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown client, or the retail app is off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A query field is invalid (`error.fields` names it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/retail/{client_id}/products/{product_id}": { "get": { "operationId": "getRetailProduct", "summary": "One product of the client, with its sizes in order", "description": "The retail product screen (T10.05.04): the product by the merchant's id, with `eligible` and `reason` (a product that cannot open the size flow shows \"Size help is not available\"). Another client's product or an unknown id answers 404, as does a client whose retail app is off. Never cached. Browsers may call it only from the retail app's origins (`https://retail.fitmytype.com` and its staging twin); any other `Origin` answers 403 `not_whitelisted`.", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id (the retail URL's first segment)." } }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The merchant's product id, URL-encoded." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "category_label": { "type": ["string", "null"] }, "gender": { "anyOf": [ { "type": "string", "enum": ["male", "female", "unisex", "boys", "girls", "babies", "child"] }, { "type": "null" } ] }, "body_part": { "anyOf": [ { "type": "string", "enum": ["bosom", "top", "bottom", "feet", "full", "head"] }, { "type": "null" } ] }, "sizes": { "type": "array", "items": { "type": "string" } }, "eligible": { "type": "boolean" }, "reason": { "type": ["string", "null"] } }, "required": [ "product_id", "name", "image_url", "category", "category_label", "gender", "body_part", "sizes", "eligible", "reason" ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown product, another client's product, or the retail app is off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/setup-requests": { "post": { "operationId": "postShopifySetupRequest", "summary": "Ask FitMyType to set up the Shopify app through collaborator access", "description": "The docs site's white-glove form (T12.01.06). Browser calls only from the docs origin. One open ops ticket per shop: a second request adds to it. Limited to 5 requests per hour per IP, 5 per day per shop and 200 per day in total (429 with `Retry-After`). A bad address or code answers 422 `validation_failed` with `fields` and a top-level `field_errors` map of plain messages. The code is never sent back.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shop_domain": { "type": "string", "description": "The shop's `xxx.myshopify.com` address; a pasted admin URL is accepted." }, "request_code": { "type": "string", "description": "Shopify's collaborator request code (Settings → Users → Security)." } }, "required": ["shop_domain", "request_code"] } }, "text/plain": { "schema": { "type": "object", "properties": { "shop_domain": { "type": "string", "description": "The shop's `xxx.myshopify.com` address; a pasted admin URL is accepted." }, "request_code": { "type": "string", "description": "Shopify's collaborator request code (Settings → Users → Security)." } }, "required": ["shop_domain", "request_code"] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "shop_domain": { "type": "string" }, "status": { "type": "string", "enum": ["open", "closed"] }, "added_to_existing": { "type": "boolean", "description": "True when the shop already had an open request: this one was added to it." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": ["id", "shop_domain", "status", "added_to_existing", "created_at"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid shop address or request code (`validation_failed`, with `field_errors`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/integration_check": { "get": { "operationId": "getIntegrationCheck", "summary": "Counts of the integration events seen in the last 15 minutes", "description": "The docs snippet generator's Verify button (T12.08.04). Counts of `product`, `cart` and `transaction_end` events this client sent in the last 15 minutes, with test and invalid events counted apart; never any event data. Browser calls only from the docs origin. Answers are `no-store`: poll every 5 s. Limited to 30 calls a minute per IP (429 with `Retry-After`). A missing or non-numeric `client_id` answers 422 `validation_failed` with `error.fields`; an unknown client answers 404 `not_found`.", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The client's numeric id." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "window_minutes": { "type": "number", "const": 15, "description": "The events counted are from this many minutes back." }, "poll_seconds": { "type": "number", "const": 5, "description": "Poll at this interval; the answer is never cached." }, "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "events": { "type": "object", "properties": { "product": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events, not test events." }, "test": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events sent with `testEvent: true`." }, "invalid": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events stored as invalid (tracking debug says why)." } }, "required": ["count", "test", "invalid"] }, "cart": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events, not test events." }, "test": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events sent with `testEvent: true`." }, "invalid": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events stored as invalid (tracking debug says why)." } }, "required": ["count", "test", "invalid"] }, "transaction_end": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events, not test events." }, "test": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valid events sent with `testEvent: true`." }, "invalid": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Events stored as invalid (tracking debug says why)." } }, "required": ["count", "test", "invalid"] } }, "required": ["product", "cart", "transaction_end"] } }, "required": ["client_id", "window_minutes", "poll_seconds", "checked_at", "events"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No client has this id (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`client_id` is missing or not a whole positive number (`validation_failed`, with `error.fields`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tracking/{tracking_id}": { "delete": { "operationId": "deleteTracking", "summary": "Forget my data: delete what is stored for one device at one shop", "description": "The size tool's \"Forget my data\" (T13.01.03). Deletes, at this client only, everything stored for the device: raw events, daily visitor facts, latest and daily profile, order ledger lines and their returns, and the social-proof rows built from them. From the call on, every event carrying this `tracking_id` at this client is dropped (a hashed list kept 25 months). The delete job runs within 1 hour, and the call is entered in the data-subject register with requester \"shopper (widget)\". The answer is the same 202 whether or not the device had data, and for a second call. Browser calls only, from a shop page allowed for the client (the size tool's iframe names it with `X-Fmt-Parent-Origin`); a call from another origin or without `Origin` answers 403. Limited to 10 calls a minute per client and IP (429 with `Retry-After`).", "parameters": [ { "name": "tracking_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The device's tracking id (`fmt_device_id`)." } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,9}$", "description": "The client's numeric id." } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletion_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "A random id for this delete request; it says nothing about the device." } }, "required": ["deletion_id"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The call does not come from a shop page allowed for this client, or has no `Origin` (`not_whitelisted`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No client has this id (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`tracking_id` is not a UUID, or `client_id` is missing (`validation_failed`, with `error.fields`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 calls a minute from this IP for this client (`rate_limited`, with `Retry-After`).", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The delete cannot be queued right now; retry (`service_unavailable`, with `Retry-After`).", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/legal/subprocessor-subscriptions": { "post": { "operationId": "postSubprocessorSubscription", "summary": "Subscribe an email address to sub-processor changes", "description": "The sub-processor page's form (T13.04.02, D130 2). Sends a confirm email; the address gets change emails only after its link is clicked (valid 7 days). The answer is the same for a new, pending or already subscribed address and never names the address. Browser calls only from the docs origin. Limited to 5 requests per hour per IP, 3 per day per address and 500 per day in total (429 with `Retry-After`). A bad address answers 422 `validation_failed` with `error.fields` and `field_errors`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to notify." } }, "required": ["email"] } }, "text/plain": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to notify." } }, "required": ["email"] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "pending" } }, "required": ["status"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a valid email address (`validation_failed`, with `field_errors`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/legal/subprocessor-subscriptions/confirm": { "post": { "operationId": "confirmSubprocessorSubscription", "summary": "Confirm a sub-processor change subscription", "description": "The confirm link of the email (T13.04.02-TC11). Docs origin only for browsers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from the email link." } }, "required": ["token"] } }, "text/plain": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from the email link." } }, "required": ["token"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "confirmed" } }, "required": ["status"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The link is unknown, already used or older than 7 days (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/legal/subprocessor-subscriptions/unsubscribe": { "post": { "operationId": "unsubscribeSubprocessorChanges", "summary": "Stop sub-processor change emails and delete the address", "description": "The one-click unsubscribe link of every change email (T13.04.02-TC12). The address is deleted at once. Docs origin only for browsers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from the email link." } }, "required": ["token"] } }, "text/plain": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from the email link." } }, "required": ["token"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "unsubscribed" } }, "required": ["status"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The link is unknown or the address is already removed (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/app": { "get": { "operationId": "getShopifyAppHome", "summary": "The Shopify app's embedded home page (the app's application_url)", "description": "HTML page Shopify frames in the admin (T12.01.05). Only `https://` and `https://admin.shopify.com` may frame it (`Content-Security-Policy: frame-ancestors`); without a valid `shop` nobody may. It holds no shop data: it loads App Bridge, then the checklist from `GET /v1/shopify/home/status`.", "parameters": [ { "name": "shop", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "embedded", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/html": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A sent API or ingest key is not valid (`invalid_api_key`, `invalid_ingest_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/home/status": { "get": { "operationId": "getShopifyHomeStatus", "summary": "The app home's five setup checks for the shop of the session token", "description": "Store connected, products imported (count, pending validation, order history backfill), size button added (published theme's product template), tracking connected (web pixel), first events received (`product`, `cart`, `transaction_end` in the last 24 h). The shop comes only from the session token: a `shop` naming another shop answers 404. Shopify's theme and pixel checks run at most once a minute per shop. `Accept: text/html` answers the checklist as an HTML fragment. A missing or invalid token answers 401 with `X-Shopify-Retry-Invalid-Session-Request: 1`.", "parameters": [ { "name": "shop", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "shop": { "type": "string" }, "state": { "type": "string", "enum": ["installed", "waiting_for_ops", "not_connected"] }, "steps": { "minItems": 5, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "store_connected", "products_imported", "size_button", "tracking_connected", "first_events" ] }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["done", "todo", "failed", "waiting"] }, "detail": { "type": "string" }, "note": { "type": ["string", "null"] }, "action": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" }, "kind": { "type": "string", "enum": ["editor", "admin", "docs", "support"] } }, "required": ["label", "url", "kind"] }, { "type": "null" } ] }, "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": ["id", "title", "status", "detail", "note", "action", "checked_at"] } }, "done": { "type": "integer", "minimum": 0, "maximum": 5 }, "total": { "type": "number", "const": 5 }, "missing_scopes": { "type": "array", "items": { "type": "string" } }, "approve_url": { "type": "string" }, "dashboard_url": { "type": "string" }, "support_email": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "shop", "state", "steps", "done", "total", "missing_scopes", "approve_url", "dashboard_url", "support_email", "checked_at" ] } }, "text/html": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid Shopify session token (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/home/dashboard-link": { "post": { "operationId": "postShopifyDashboardLink", "summary": "The app home's \"Open dashboard\": a one-time back-office sign-in link", "description": "With the Shopify session token, Shopify is asked who the admin user is (online token exchange; the token is not kept). When a back-office member of the shop's client has that verified email (not staff, no two-factor sign-in), the answer is `{kind: sso, url}` with a code in the URL fragment, valid 60 s and usable once (`POST /bo/v1/auth/shopify-sso`); otherwise `{kind: login, url}` (the sign-in page).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["sso", "login"] }, "url": { "type": "string" } }, "required": ["kind", "url"] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid Shopify session token (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/session": { "post": { "operationId": "postShopifySession", "summary": "The Shopify app opens: install on the first open, then the shop's state", "description": "Called by the embedded app home with `Authorization: Bearer ` (T12.01.01). The first open exchanges the session token for an expiring offline token (sealed, never returned), links the shop to the one client that has its domain, writes the `fitmytype_app.client_id` metafield, connects the web pixel and starts the first import. A shop no client has, or two clients have, waits for ops (`waiting_for_ops`). A missing or invalid token answers 401 with `X-Shopify-Retry-Invalid-Session-Request: 1`; 503 when the app is not set up on this server.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "shop": { "type": "string" }, "state": { "type": "string", "enum": ["installed", "waiting_for_ops", "uninstalled", "redacted"] }, "client_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "message": { "description": "What the merchant reads while ops links the shop; null otherwise.", "type": ["string", "null"] }, "missing_scopes": { "type": "array", "items": { "type": "string" } }, "metafield": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": ["string", "null"] } }, "required": ["ok", "error"] }, { "type": "null" } ] }, "pixel": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "error": { "type": ["string", "null"] } }, "required": ["ok", "status", "error"] }, { "type": "null" } ] }, "import": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["running", "failed", "done"] }, "label": { "type": "string" }, "reason": { "type": ["string", "null"] }, "finished_at": { "type": ["string", "null"] } }, "required": ["status", "label", "reason"] }, { "type": "null" } ] } }, "required": [ "shop", "state", "client_id", "source_id", "message", "missing_scopes", "metafield", "pixel", "import" ] } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid Shopify session token (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shopify/webhooks": { "post": { "operationId": "postShopifyWebhook", "summary": "Shopify's webhooks to the app (uninstall, scope changes, GDPR)", "description": "Only Shopify calls this. `X-Shopify-Hmac-SHA256` (HMAC-SHA256 of the raw body, keyed by the app's credentials) is checked before the body is read: wrong or missing answers 401 with an empty body; a valid one answers 200 with an empty body (never the D38 error format). Topics: `app/uninstalled`, `app/scopes_update`, `customers/data_request`, `customers/redact`, `shop/redact`; repeats are dropped by `X-Shopify-Webhook-Id`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "text/plain": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Malformed request or `client_id` (`bad_request`, `invalid_json`, `invalid_client_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Wrong or missing HMAC signature (empty body).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Preflight from an origin the client does not allow (`not_whitelisted`), or a key without the scope or of another client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource (`not_found`, `brand_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over the route's limit (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy or a dependency is down (`capacity_busy`, `rate_limit_unavailable`, …); retry after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "request_id"], "properties": { "code": { "type": "string", "description": "Stable error code (see the API README)." }, "message": { "type": "string" }, "request_id": { "type": "string", "description": "Same as the `X-Request-Id` header." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "With `validation_failed` (422): the invalid fields, by name only." } } } } } } } }