{"openapi":"3.1.0","info":{"title":"OneTrace.pro API","version":"1.0.0","description":"Public API v1: event ingestion (write keys) and project management (secret keys with permissions). Errors are `{\"message\": \"...\"}`; validation errors add `errors` by field path. Lists use cursor pagination (`limit` 1-200, `cursor` from `next_cursor`). POST requests accept an `Idempotency-Key` header: a repeat with the same key and body returns the stored response for 24 hours. Rate limits: 6000 requests\/min per write key, 1200 requests\/min per secret key (`429`). Error messages follow `Accept-Language` (en, ru, de, es, fr, it, pt, tr, uz, zh), otherwise the platform default language."},"servers":[{"url":"https:\/\/cdp.onetrace.ru\/api\/v1"}],"paths":{"\/track":{"post":{"operationId":"ingest.track","summary":"Track an event","tags":["ingest"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Message"}}}},"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"202":{"description":"Accepted for asynchronous processing","content":{"application\/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"duplicates":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/identify":{"post":{"operationId":"ingest.identify","summary":"Identify a profile and update traits","tags":["ingest"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Message"}}}},"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"202":{"description":"Accepted for asynchronous processing","content":{"application\/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"duplicates":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/page":{"post":{"operationId":"ingest.page","summary":"Track a page view","tags":["ingest"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Message"}}}},"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"202":{"description":"Accepted for asynchronous processing","content":{"application\/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"duplicates":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/alias":{"post":{"operationId":"ingest.alias","summary":"Link a previous identifier to a user","tags":["ingest"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Message"}}}},"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"202":{"description":"Accepted for asynchronous processing","content":{"application\/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"duplicates":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/batch":{"post":{"operationId":"ingest.batch","summary":"Send up to 500 messages at once","tags":["ingest"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["batch"],"properties":{"batch":{"type":"array","maxItems":500,"items":{"$ref":"#\/components\/schemas\/Message"}}}}}}},"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"202":{"description":"Accepted for asynchronous processing","content":{"application\/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"duplicates":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"413":{"$ref":"#\/components\/responses\/PayloadTooLarge"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/key":{"get":{"operationId":"key.show","summary":"Check the API key","tags":["ingest"],"description":"Key type, project and permissions. Accepts any active key (write or secret); use it for a \"Test connection\" button.","security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["type","name","project","scopes"],"properties":{"type":{"type":"string","enum":["write","secret"]},"name":{"type":"string"},"project":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"}}},"scopes":{"type":"array","items":{"type":"string"},"description":"Permissions of a secret key; empty for a write key."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/push\/config":{"get":{"operationId":"push.config","summary":"VAPID public key for PushManager.subscribe()","tags":["push"],"security":[{"writeKey":[]},{"secretKey":[]}],"responses":{"200":{"description":"Public key of the project's Web Push integration","content":{"application\/json":{"schema":{"type":"object","required":["public_key"],"properties":{"public_key":{"type":"string","description":"base64url, 65-byte uncompressed P-256 point"}}}}}},"404":{"$ref":"#\/components\/responses\/NotFound"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/push\/subscriptions":{"post":{"operationId":"push.subscribe","summary":"Store a browser push subscription and link it to the visitor","tags":["push"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["subscription"],"properties":{"anonymousId":{"type":"string","maxLength":255,"description":"Required without userId"},"userId":{"type":"string","maxLength":255},"publicKey":{"type":"string","description":"VAPID key the subscription was created with"},"subscription":{"type":"object","required":["endpoint","keys"],"description":"PushSubscription.toJSON(); the endpoint must belong to a browser push service","properties":{"endpoint":{"type":"string","format":"uri"},"expirationTime":{"type":["integer","null"]},"keys":{"type":"object","required":["p256dh","auth"],"properties":{"p256dh":{"type":"string"},"auth":{"type":"string"}}}}}}}}}},"responses":{"201":{"description":"Subscription stored; consent is recorded once the profile is processed","content":{"application\/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"string"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"delete":{"operationId":"push.unsubscribe","summary":"Forget a browser push subscription","tags":["push"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["endpoint"],"properties":{"endpoint":{"type":"string"}}}}}},"responses":{"200":{"description":"Whether a subscription was removed","content":{"application\/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/recommendations":{"get":{"operationId":"recommendations.get","summary":"Product recommendations for the site","tags":["recommendations"],"description":"Write key (tracker). Personal and recently viewed recommendations use the profile of `anonymousId` only. Only available products are returned. `replenish` \u2014 products the visitor buys regularly whose repeat-purchase cycle has come (needs \u201cTime to reorder\u201d in the recommendation settings).","security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["personal","popular","trending","viewed_with","bought_with","similar","recently_viewed","replenish"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":24,"default":8}},{"name":"item","in":"query","description":"Context product id (or item[] for a cart) for viewed_with, bought_with, similar.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Category id for popular and trending.","schema":{"type":"string"}},{"name":"exclude[]","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"anonymousId","in":"query","schema":{"type":"string"}},{"name":"image_width","in":"query","description":"Card image width (image), px. Variants for <picture> are in srcset when imgproxy is configured (ADR-047).","schema":{"type":"integer","minimum":64,"maximum":1200,"default":480}},{"name":"language","in":"query","description":"Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Recommended products","content":{"application\/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#\/components\/schemas\/ProductCard"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/openapi.json":{"get":{"operationId":"meta.openapi","summary":"This OpenAPI specification","tags":["meta"],"security":[],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object"}}}}}}},"\/profiles\/{type}\/{value}":{"get":{"operationId":"profiles.show","summary":"Get a profile by any identifier","tags":["profiles"],"description":"Traits and identifiers are masked unless the key has `profiles.pii`.\n\nRequires key permission(s): `profiles.read`.","parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"security":[{"secretKey":[]}],"x-required-scopes":["profiles.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Profile"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"profiles.destroy","summary":"Erase a profile and all profiles merged into it (GDPR)","tags":["profiles"],"parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"security":[{"secretKey":[]}],"x-required-scopes":["profiles.delete"],"description":"Requires key permission(s): `profiles.delete`.","responses":{"204":{"description":"Erased"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/profiles\/{type}\/{value}\/events":{"get":{"operationId":"profiles.events","summary":"Profile events, newest first, 50 per page","tags":["profiles"],"parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Cursor: `next_before` of the previous page."},{"name":"name","in":"query","schema":{"type":"string"}}],"security":[{"secretKey":[]}],"x-required-scopes":["profiles.read"],"description":"Requires key permission(s): `profiles.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Event"}},"next_before":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/profiles\/{type}\/{value}\/consents":{"put":{"operationId":"profiles.consents","summary":"Subscribe or unsubscribe a profile","tags":["profiles"],"parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["channel","status"],"properties":{"channel":{"type":"string","example":"email"},"topic":{"type":"string","description":"Omit for the whole channel (`all`)."},"status":{"type":"string","enum":["subscribed","unsubscribed"]}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["profiles.write"],"description":"Requires key permission(s): `profiles.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/telegram\/link":{"post":{"operationId":"profiles.telegramLink","summary":"Create a Telegram deep link for a profile","tags":["profiles"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["identity"],"properties":{"identity":{"$ref":"#\/components\/schemas\/IdentityRef"},"integration":{"type":"string","description":"Integration uid when the project has several bots."}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["profiles.write"],"description":"Requires key permission(s): `profiles.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"token":{"type":"string"},"integration":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/viber\/link":{"post":{"operationId":"profiles.viberLink","summary":"Create a Viber bot deep link for a profile","tags":["profiles"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["identity"],"properties":{"identity":{"$ref":"#\/components\/schemas\/IdentityRef"},"integration":{"type":"string","description":"Integration uid when the project has several Viber bots."}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["profiles.write"],"description":"Requires key permission(s): `profiles.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"token":{"type":"string"},"integration":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/products":{"post":{"operationId":"products.upsert","summary":"Create or update products and categories","tags":["products"],"security":[{"secretKey":[]}],"x-required-scopes":["products.write"],"description":"Requires key permission(s): `products.write`. Up to 1000 items per request.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":1000,"items":{"$ref":"#\/components\/schemas\/ProductInput"}},"categories":{"type":"array","maxItems":1000,"items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"parent_id":{"type":["string","null"]},"translations":{"type":"object","maxProperties":20,"description":"Category name by language (BCP 47 tag \u2192 {name}).","additionalProperties":{"type":"object","properties":{"name":{"type":"string","maxLength":300}}}}}}}}}}}},"responses":{"200":{"description":"Saved","content":{"application\/json":{"schema":{"type":"object","properties":{"saved":{"type":"integer"},"categories":{"type":"integer"}}}}}},"403":{"$ref":"#\/components\/responses\/Forbidden"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"products.delete","summary":"Delete products","tags":["products"],"security":[{"secretKey":[]}],"x-required-scopes":["products.write"],"description":"Requires key permission(s): `products.write`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Deleted","content":{"application\/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"403":{"$ref":"#\/components\/responses\/Forbidden"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/catalog\/events":{"get":{"operationId":"catalog.events","summary":"Events seen in the project with their properties","tags":["catalog"],"security":[{"secretKey":[]}],"x-required-scopes":["events.read"],"description":"Requires key permission(s): `events.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/CatalogEvent"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/catalog\/traits":{"get":{"operationId":"catalog.traits","summary":"Profile traits of the project","tags":["catalog"],"security":[{"secretKey":[]}],"x-required-scopes":["events.read"],"description":"Requires key permission(s): `events.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/CatalogTrait"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/segments":{"get":{"operationId":"segments.index","summary":"List segments","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.read"],"description":"Requires key permission(s): `segments.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Segment"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"segments.store","summary":"Create a segment","tags":["segments"],"description":"Dynamic segments are computed asynchronously; poll `status`. Rules use the same DSL as the segment builder (docs\/architecture\/segmentation.md).\n\nRequires key permission(s): `segments.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SegmentInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SegmentDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/segments\/{segment}":{"get":{"operationId":"segments.show","summary":"Get a segment with its rules","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.read"],"description":"Requires key permission(s): `segments.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SegmentDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"segments.update","summary":"Update a segment (partial)","tags":["segments"],"description":"Changing rules of a dynamic segment queues a recomputation.\n\nRequires key permission(s): `segments.write`.","parameters":[{"$ref":"#\/components\/parameters\/SegmentId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SegmentPatch"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SegmentDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"segments.destroy","summary":"Delete a segment","tags":["segments"],"description":"Fails with 422 while other segments reference it.\n\nRequires key permission(s): `segments.write`.","parameters":[{"$ref":"#\/components\/parameters\/SegmentId"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/segments\/{segment}\/compute":{"post":{"operationId":"segments.compute","summary":"Queue a recomputation of a dynamic segment","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"description":"Requires key permission(s): `segments.write`.","responses":{"202":{"description":"Queued","content":{"application\/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/Error"}}}},"\/segments\/{segment}\/members":{"get":{"operationId":"segments.members","summary":"Segment members, latest entered first","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"},{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.read"],"description":"Requires key permission(s): `segments.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"profile_id":{"type":"integer"},"entered_at":{"type":"string","format":"date-time"}}}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"post":{"operationId":"segments.addMembers","summary":"Add profiles to a static segment","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/IdentitiesInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"description":"Requires key permission(s): `segments.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"unknown":{"type":"array","items":{"$ref":"#\/components\/schemas\/IdentityRef"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"segments.removeMembers","summary":"Remove profiles from a static segment","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/IdentitiesInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["segments.write"],"description":"Requires key permission(s): `segments.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"removed":{"type":"integer"},"unknown":{"type":"array","items":{"$ref":"#\/components\/schemas\/IdentityRef"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/segments\/{segment}\/members\/{type}\/{value}":{"get":{"operationId":"segments.membership","summary":"Whether a profile is a member","tags":["segments"],"parameters":[{"$ref":"#\/components\/parameters\/SegmentId"},{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"security":[{"secretKey":[]}],"x-required-scopes":["segments.read"],"description":"Requires key permission(s): `segments.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"profile_id":{"type":"integer"},"member":{"type":"boolean"},"entered_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/journeys":{"get":{"operationId":"journeys.index","summary":"List journeys","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused","archived"]}}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.read"],"description":"Requires key permission(s): `journeys.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Journey"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"journeys.store","summary":"Create a journey draft","tags":["journeys"],"description":"The draft may be incomplete; it is validated on publish. Graph and entry use the editor format (docs\/architecture\/journeys.md).\n\nRequires key permission(s): `journeys.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["journeys.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}":{"get":{"operationId":"journeys.show","summary":"Get a journey with its draft and published version","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/JourneyId"}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.read"],"description":"Requires key permission(s): `journeys.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"journeys.update","summary":"Update the draft (partial)","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/JourneyId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyPatch"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["journeys.write"],"description":"Requires key permission(s): `journeys.write`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/validate":{"post":{"operationId":"journeys.validate","summary":"Validate the draft without publishing","tags":["journeys"],"description":"422 lists errors by path, e.g. `graph.nodes.2.data.template_id`.\n\nRequires key permission(s): `journeys.read`.","parameters":[{"$ref":"#\/components\/parameters\/JourneyId"}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/publish":{"post":{"operationId":"journeys.publish","summary":"Publish the draft as a new version","tags":["journeys"],"description":"First publish activates the journey and counts towards the plan's active journeys limit.\n\nRequires key permission(s): `journeys.publish`.","parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.publish"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JourneyDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/pause":{"post":{"operationId":"journeys.pause","summary":"Pause: no new entries, participants stay","tags":["journeys"],"description":"Body `{\"exit_all\": true}` also exits all participants. Only active journeys.\n\nRequires key permission(s): `journeys.publish`.","parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"exit_all":{"type":"boolean"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["journeys.publish"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Journey"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/resume":{"post":{"operationId":"journeys.resume","summary":"Resume a paused journey","tags":["journeys"],"description":"Counts towards the active journeys limit.\n\nRequires key permission(s): `journeys.publish`.","parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.publish"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Journey"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/archive":{"post":{"operationId":"journeys.archive","summary":"Archive: all participants exit","tags":["journeys"],"description":"Irreversible.\n\nRequires key permission(s): `journeys.publish`.","parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.publish"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Journey"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/journeys\/{journey}\/enrollments":{"get":{"operationId":"journeys.enrollments","summary":"Journey participations, newest first","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","waiting","completed","exited","failed"]}}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.read"],"description":"Requires key permission(s): `journeys.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Enrollment"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/journeys\/{journey}\/report":{"get":{"operationId":"journeys.report","summary":"Funnel, goals and A\/B branches for a period","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"name":"period","in":"query","schema":{"type":"integer","enum":[7,30,90],"default":30}}],"security":[{"secretKey":[]}],"x-required-scopes":["journeys.read","analytics.read"],"description":"Requires key permission(s): `journeys.read`, `analytics.read`.","responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","description":"See docs\/architecture\/analytics.md#\u043e\u0442\u0447\u0451\u0442-\u043f\u043e-\u0446\u0435\u043f\u043e\u0447\u043a\u0435."}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/journeys\/{journey}\/enroll":{"post":{"operationId":"journeys.enroll","summary":"Enroll a profile into a journey with the API trigger","tags":["journeys"],"parameters":[{"$ref":"#\/components\/parameters\/JourneyId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["identity"],"properties":{"identity":{"$ref":"#\/components\/schemas\/IdentityRef"},"data":{"type":"object","description":"Available in templates as `context.data`."},"idempotency_key":{"type":"string","maxLength":150}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["journeys.write"],"description":"Requires key permission(s): `journeys.write`.","responses":{"201":{"description":"Enrolled","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EnrollResult"}}}},"200":{"description":"Not enrolled (repeat key, re-entry policy, audience or limit)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EnrollResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"409":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/templates":{"get":{"operationId":"templates.index","summary":"List message templates","tags":["templates"],"description":"Requires key permission(s): `templates.read`.","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"Only templates of this channel."}],"security":[{"secretKey":[]}],"x-required-scopes":["templates.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/MessageTemplate"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"templates.store","summary":"Create a message template","tags":["templates"],"description":"Every language version is checked against the channel schema and the Twig sandbox.\n\nRequires key permission(s): `templates.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageTemplateInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["templates.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageTemplate"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/templates\/{template}":{"get":{"operationId":"templates.show","summary":"Get a message template","tags":["templates"],"description":"Requires key permission(s): `templates.read`.","parameters":[{"$ref":"#\/components\/parameters\/TemplateId"}],"security":[{"secretKey":[]}],"x-required-scopes":["templates.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageTemplate"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"templates.update","summary":"Update a message template (partial)","tags":["templates"],"description":"Journeys and campaigns that use the template send the new content from the next message on.\n\nRequires key permission(s): `templates.write`.","parameters":[{"$ref":"#\/components\/parameters\/TemplateId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"topic":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$","default":"marketing"},"transactional":{"type":"boolean","default":false},"language":{"type":"string","maxLength":16,"description":"Main language of `content`; the project default language if omitted.","examples":["de"]},"content":{"type":"object","additionalProperties":true,"description":"Fields of the channel message schema, e.g. `subject`, `html` and `text` for email; string fields are Twig templates."},"translations":{"type":"object","maxProperties":50,"additionalProperties":{"type":"object","additionalProperties":true},"description":"Other language versions; each is validated like `content`. Omit to keep the stored versions, pass `{}` to delete them."}},"description":"Any subset of MessageTemplateInput fields except `channel_key`."}}}},"security":[{"secretKey":[]}],"x-required-scopes":["templates.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageTemplate"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"templates.destroy","summary":"Delete a message template","tags":["templates"],"description":"Messages already sent keep their content; journey steps and campaign variants that use the template stop being valid.\n\nRequires key permission(s): `templates.write`.","parameters":[{"$ref":"#\/components\/parameters\/TemplateId"}],"security":[{"secretKey":[]}],"x-required-scopes":["templates.write"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/campaigns":{"get":{"operationId":"campaigns.index","summary":"List campaigns","tags":["campaigns"],"description":"Requires key permission(s): `campaigns.read`.","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Campaign"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"campaigns.store","summary":"Create a campaign draft","tags":["campaigns"],"description":"The draft may be incomplete; readiness is checked on schedule.\n\nRequires key permission(s): `campaigns.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CampaignInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/campaigns\/{campaign}":{"get":{"operationId":"campaigns.show","summary":"Get a campaign","tags":["campaigns"],"description":"Requires key permission(s): `campaigns.read`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"campaigns.update","summary":"Update a campaign (partial)","tags":["campaigns"],"description":"Only draft, scheduled or paused campaigns; a scheduled campaign is re-checked and its next run recomputed.\n\nRequires key permission(s): `campaigns.write`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","description":"Any subset of CampaignInput fields.","properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"integration_id":{"type":["integer","null"],"description":"Channel integration; the template of every variant must belong to its channel."},"audience":{"$ref":"#\/components\/schemas\/CampaignAudience"},"variants":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#\/components\/schemas\/CampaignVariant"}},"ab":{"$ref":"#\/components\/schemas\/CampaignAb"},"schedule":{"$ref":"#\/components\/schemas\/CampaignSchedule"},"rate_per_minute":{"type":["integer","null"],"minimum":10,"maximum":100000},"goal":{"$ref":"#\/components\/schemas\/CampaignGoal"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"campaigns.destroy","summary":"Delete a campaign","tags":["campaigns"],"description":"Fails with 422 while scheduled or sending: cancel it first.\n\nRequires key permission(s): `campaigns.write`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.write"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/campaigns\/{campaign}\/report":{"get":{"operationId":"campaigns.report","summary":"Campaign report: last runs with per-variant stats","tags":["campaigns"],"description":"Requires key permission(s): `campaigns.read`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#\/components\/schemas\/Campaign"},"runs":{"type":"array","items":{"$ref":"#\/components\/schemas\/CampaignRun"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/campaigns\/{campaign}\/schedule":{"post":{"operationId":"campaigns.schedule","summary":"Schedule (or launch) a campaign","tags":["campaigns"],"description":"Draft or paused campaign without a paused run. Checks readiness (channel, templates, audience, goal, schedule); `now` starts within a minute.\n\nRequires key permission(s): `campaigns.send`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/campaigns\/{campaign}\/pause":{"post":{"operationId":"campaigns.pause","summary":"Pause a campaign","tags":["campaigns"],"description":"The current run stops queueing messages; next runs do not start.\n\nRequires key permission(s): `campaigns.send`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/campaigns\/{campaign}\/resume":{"post":{"operationId":"campaigns.resume","summary":"Resume a paused campaign","tags":["campaigns"],"description":"A paused run continues; otherwise the campaign is scheduled again.\n\nRequires key permission(s): `campaigns.send`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/campaigns\/{campaign}\/cancel":{"post":{"operationId":"campaigns.cancel","summary":"Cancel a campaign","tags":["campaigns"],"description":"Unsent recipients of the current run do not get the message; recurring runs stop.\n\nRequires key permission(s): `campaigns.send`.","parameters":[{"$ref":"#\/components\/parameters\/CampaignId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["campaigns.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Campaign"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/widgets\/{uid}":{"get":{"operationId":"widgets.get","summary":"Website widget configured in the admin panel","tags":["recommendations"],"description":"Write key (tracker renders <div data-cdp-widget=\"{uid}\">, ADR-048). Returns the widget settings and its products in one request; a paused widget returns no items. Personal recommendations use the profile of `anonymousId` only.","security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]{1,16}$"}},{"name":"item[]","in":"query","description":"Context product ids (data-item): page product or cart items.","schema":{"type":"array","items":{"type":"string"}}},{"name":"category","in":"query","description":"Category id (data-category); overrides the widget category.","schema":{"type":"string"}},{"name":"exclude[]","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"anonymousId","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","description":"Visitor language (BCP 47, as in context.locale): the heading, the button and product names come in their translation for the closest language (ADR-078, ADR-080).","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Widget and products","content":{"application\/json":{"schema":{"type":"object","properties":{"widget":{"type":"object","properties":{"uid":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"settings":{"type":"object","properties":{"title":{"type":"string"},"layout":{"type":"string","enum":["grid","carousel"]},"columns":{"type":"integer"},"accent":{"type":["string","null"]},"radius":{"type":"integer"},"button":{"type":"string"},"showPrice":{"type":"boolean"}}}}},"request_id":{"type":["string","null"]},"items":{"type":"array","items":{"$ref":"#\/components\/schemas\/ProductCard"}}}}}}},"401":{"description":"Invalid key"},"403":{"description":"Request origin is not one of the key website domains"},"404":{"description":"Widget not found in the project"}}}},"\/chat\/config":{"get":{"operationId":"chat.config","summary":"Website chat widget settings","description":"Used by the tracker: whether the chat is enabled, online state (working hours and operators online), color, position, pre-chat form and texts in the visitor language.\n\nUsed by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`.","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Settings; only enabled: false when the chat is off","content":{"application\/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"online":{"type":"boolean"},"color":{"type":"string"},"position":{"type":"string","enum":["right","left"]},"prechat":{"type":"boolean"},"texts":{"type":"object","properties":{"title":{"type":"string"},"greeting":{"type":"string"},"offline":{"type":"string"}}}}}}}}},"x-internal":true}},"\/chat\/messages":{"post":{"operationId":"chat.send","summary":"Send a visitor message","description":"Finds the visitor profile by userId or anonymousId (creates it if needed) and adds the message to its open website conversation or starts a new one.\n\nUsed by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`.","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["anonymousId","body"],"properties":{"anonymousId":{"type":"string","maxLength":255},"userId":{"type":"string","maxLength":255},"conversation":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"},"token":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"},"body":{"type":"string","maxLength":4000},"name":{"type":"string","maxLength":100},"email":{"type":"string","format":"email","maxLength":255},"page":{"type":"string","maxLength":2000,"description":"Page URL (http\/https)"},"language":{"type":"string","maxLength":35},"customer_token":{"type":"string","maxLength":2000,"description":"Token of the customer signed in to the store website, issued by the store (store MCP contract, docs\/api\/store-mcp.md#5). The store verifies it; the platform stores it encrypted."}}}}}},"responses":{"201":{"description":"Message stored","content":{"application\/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#\/components\/schemas\/ChatVisitorConversation"},"message":{"$ref":"#\/components\/schemas\/ChatVisitorMessage"}}}}}},"404":{"description":"The website chat is turned off"},"429":{"description":"Too many messages from the visitor"}},"x-internal":true},"get":{"operationId":"chat.messages","summary":"Messages of the visitor conversation","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"conversation","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"}},{"name":"token","in":"query","required":true,"schema":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"}},{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"read","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Mark operator replies as read by the visitor"}],"responses":{"200":{"description":"Messages visible to the visitor","content":{"application\/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#\/components\/schemas\/ChatVisitorConversation"},"messages":{"type":"array","items":{"$ref":"#\/components\/schemas\/ChatVisitorMessage"}}}}}}},"404":{"description":"Unknown conversation or wrong token"}},"x-internal":true,"description":"Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`."}},"\/chat\/typing":{"post":{"operationId":"chat.typing","summary":"The visitor is typing","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["conversation","token"],"properties":{"conversation":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"},"token":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"}}}}}},"responses":{"200":{"description":"Shown to operators of the open conversation"},"404":{"description":"Unknown conversation or wrong token"}},"x-internal":true,"description":"Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`."}},"\/chat\/rating":{"post":{"operationId":"chat.rate","summary":"Rate the conversation","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["conversation","token","rating"],"properties":{"conversation":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"},"token":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Rating stored","content":{"application\/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#\/components\/schemas\/ChatVisitorConversation"}}}}}},"404":{"description":"Unknown conversation or wrong token"}},"x-internal":true,"description":"Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`."}},"\/chat\/handoff":{"post":{"operationId":"chat.handoff","summary":"Ask for a human operator","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["conversation","token"],"properties":{"conversation":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"},"token":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"}}}}}},"responses":{"200":{"description":"The bot handed the conversation over to the operators","content":{"application\/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#\/components\/schemas\/ChatVisitorConversation"}}}}}},"404":{"description":"Unknown conversation or wrong token"}},"x-internal":true,"description":"The bot (AI in the chat) hands the conversation over to the queue of human operators. Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`."}},"\/chat\/realtime":{"post":{"operationId":"chat.realtime","summary":"Realtime tokens of the visitor conversation","description":"Centrifugo connection token (anonymous) and subscription token for the channel of this conversation only.\n\nUsed by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use `\/conversations`.","tags":["chat"],"security":[{"writeKey":[]},{"secretKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["conversation","token"],"properties":{"conversation":{"type":"string","format":"uuid","description":"Conversation id from POST \/chat\/messages"},"token":{"type":"string","maxLength":64,"description":"Visitor token of the conversation from POST \/chat\/messages"}}}}}},"responses":{"200":{"description":"Tokens","content":{"application\/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"channel":{"type":"string"},"connection_token":{"type":"string"},"subscription_token":{"type":"string"}}}}}},"404":{"description":"Unknown conversation or wrong token"}},"x-internal":true}},"\/search":{"get":{"operationId":"search.products","summary":"Product search for the site","tags":["search"],"description":"Write key (tracker, shop plugins), ADR-079. Word forms of the project languages, typos and a query typed in the wrong keyboard layout are understood; a query without results is retried with any of its words (`relaxed`). With `anonymousId` the first results are reordered by the categories and brands the visitor looked at (`personalized`). Facets are counted over the whole query, before the category, brand and price filters.","security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"q","in":"query","description":"Query text; empty \u2014 the whole catalog.","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","description":"Category id; products of its subcategories too.","schema":{"type":"string"}},{"name":"brand[]","in":"query","schema":{"type":"array","items":{"type":"string"},"maxItems":20}},{"name":"price_min","in":"query","schema":{"type":"number","minimum":0}},{"name":"price_max","in":"query","schema":{"type":"number","minimum":0}},{"name":"attr","in":"query","style":"deepObject","explode":true,"description":"Filters by product characteristics of the store industry (ADR-114), e.g. `attr[season]=winter&attr[rim_diameter][]=16&attr[rim_diameter][]=17`: any of the values of a key, all keys. Keys and values \u2014 from `facets.attributes`.","schema":{"type":"object","maxProperties":20,"additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","maxItems":20,"items":{"type":"string"}}]}}},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","popular","price_asc","price_desc"],"default":"relevance"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":48,"default":24}},{"name":"all","in":"query","description":"Include products that are not available.","schema":{"type":"boolean","default":false}},{"name":"anonymousId","in":"query","description":"Tracker visitor id for the personal order.","schema":{"type":"string"}},{"name":"image_width","in":"query","schema":{"type":"integer","minimum":64,"maximum":1200,"default":480}},{"name":"language","in":"query","description":"Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Found products","content":{"application\/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"query":{"type":"string"},"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"relaxed":{"type":"boolean","description":"Nothing matched all words: products matching any word."},"personalized":{"type":"boolean"},"items":{"type":"array","items":{"allOf":[{"$ref":"#\/components\/schemas\/ProductCard"},{"type":"object","properties":{"available":{"type":"boolean"}}}]}},"facets":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"}}}},"brands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}}}},"price":{"type":"object","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]}}},"attributes":{"type":"array","description":"Characteristics of the store industry with values and product counts; values go to `attr[key]`.","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"values":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"}}}}}}}}},"redirect":{"type":["string","null"],"format":"uri","description":"Redirect rule of the query (Site \u2192 Search): the page to open instead of the results, or null."},"filters":{"type":"object","description":"Sizes and parameters recognized in the query text and applied as filters (\u201c205\/55 r16 winter\u201d \u2192 tire_width, tire_profile, rim_diameter, season); empty when nothing was recognized or nothing matched them.","additionalProperties":{"type":["string","number","boolean"]}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Product search is not in the plan of the project (code feature_unavailable)"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/search\/suggest":{"get":{"operationId":"search.suggest","summary":"Search suggestions while typing","tags":["search"],"description":"Write key, ADR-079. Products by the beginning of words, categories by name, popular queries of the website (`search` events of the last 30 days). An empty query returns only the popular queries.","security":[{"writeKey":[]},{"secretKey":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"limit","in":"query","description":"Products in the suggestion.","schema":{"type":"integer","minimum":1,"maximum":10,"default":6}},{"name":"image_width","in":"query","schema":{"type":"integer","minimum":64,"maximum":1200,"default":480}},{"name":"language","in":"query","description":"Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Suggestions","content":{"application\/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"allOf":[{"$ref":"#\/components\/schemas\/ProductCard"},{"type":"object","properties":{"available":{"type":"boolean"}}}]}},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"queries":{"type":"array","items":{"type":"string"}},"redirect":{"type":["string","null"],"format":"uri","description":"Redirect rule of the query (Site \u2192 Search): the page to open instead of the results, or null."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Product search is not in the plan of the project (code feature_unavailable)"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/analytics\/reports":{"post":{"operationId":"analytics.reports","summary":"Run an event report","tags":["analytics"],"description":"Report builder: series of an event and a metric (count, unique profiles, per profile, sum or average of a numeric property) with property filters, profile filter, breakdown, interval, period and comparison with the previous period (docs\/architecture\/analytics.md#\u043a\u043e\u043d\u0441\u0442\u0440\u0443\u043a\u0442\u043e\u0440-\u043e\u0442\u0447\u0451\u0442\u043e\u0432). Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ReportQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ReportResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/funnels":{"post":{"operationId":"analytics.funnels","summary":"Run a funnel","tags":["analytics"],"description":"Steps of events with property filters, conversion window, order, profile filter, breakdown by the first step; conversion and time between steps. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FunnelQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FunnelResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/retention":{"post":{"operationId":"analytics.retention","summary":"Run a retention report","tags":["analytics"],"description":"Cohorts by the first start event and returns by the return event per day, week or month. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RetentionQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RetentionResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/paths":{"post":{"operationId":"analytics.paths","summary":"Run a paths report","tags":["analytics"],"description":"Frequent event sequences after or before the anchor event; nodes and links for a Sankey diagram and the most frequent paths. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PathQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PathResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/revenue":{"post":{"operationId":"analytics.revenue","summary":"Run a revenue report","tags":["analytics"],"description":"Revenue, orders, average order value, new and returning buyers, LTV by first purchase cohort, top products and categories in the project currency. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RevenueQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RevenueResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Revenue, traffic and attribution reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/traffic":{"post":{"operationId":"analytics.traffic","summary":"Run a traffic sources report","tags":["analytics"],"description":"Website visits by channel, source, campaign, referring site or landing page with new profiles, bounces, conversions and revenue. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TrafficQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TrafficResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Revenue, traffic and attribution reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/attribution":{"post":{"operationId":"analytics.attribution","summary":"Run a revenue attribution report","tags":["analytics"],"description":"Revenue attributed to platform clicks (campaigns, journeys, messages, recommendations, search) by the last click, first click and linear models. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AttributionQuery"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AttributionResult"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Revenue, traffic and attribution reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/saved-reports":{"get":{"operationId":"analytics.savedReports.index","summary":"List saved reports","tags":["analytics"],"description":"Requires key permission(s): `analytics.read`.","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"},{"name":"type","in":"query","required":false,"schema":{"$ref":"#\/components\/schemas\/AnalyticsReportType"}}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/SavedReport"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"analytics.savedReports.store","summary":"Save a report","tags":["analytics"],"description":"The definition is validated and normalized by the report type; errors come with `definition.*` paths.\n\nRequires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SavedReportInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SavedReportDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/saved-reports\/{report}":{"get":{"operationId":"analytics.savedReports.show","summary":"Get a saved report","tags":["analytics"],"description":"Requires key permission(s): `analytics.read`.","parameters":[{"$ref":"#\/components\/parameters\/SavedReportId"}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SavedReportDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"analytics.savedReports.update","summary":"Update a saved report","tags":["analytics"],"description":"The report type cannot be changed.\n\nRequires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/SavedReportId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SavedReportPatch"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SavedReportDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"analytics.savedReports.destroy","summary":"Delete a saved report","tags":["analytics"],"description":"Its cards are removed from dashboards; its email schedules are deleted.\n\nRequires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/SavedReportId"}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/analytics\/saved-reports\/{report}\/result":{"post":{"operationId":"analytics.savedReports.result","summary":"Run a saved report","tags":["analytics"],"description":"Optional `period` replaces the period of the saved definition. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized `definition` and the result \u2014 the same as the analytics pages.\n\nRequires key permission(s): `analytics.read`.","parameters":[{"$ref":"#\/components\/parameters\/SavedReportId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","description":"The result of the report type \u2014 see the corresponding run operation.","additionalProperties":true}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"description":"Revenue, traffic and attribution reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/dashboards":{"get":{"operationId":"analytics.dashboards.index","summary":"List dashboards","tags":["analytics"],"description":"Requires key permission(s): `analytics.read`.","parameters":[{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Dashboard"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"post":{"operationId":"analytics.dashboards.store","summary":"Create a dashboard","tags":["analytics"],"description":"Requires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DashboardInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Dashboard"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/analytics\/dashboards\/{dashboard}":{"get":{"operationId":"analytics.dashboards.show","summary":"Get a dashboard","tags":["analytics"],"description":"Requires key permission(s): `analytics.read`.","parameters":[{"$ref":"#\/components\/parameters\/DashboardId"}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Dashboard"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"patch":{"operationId":"analytics.dashboards.update","summary":"Update a dashboard","tags":["analytics"],"description":"Fields not sent stay unchanged; `layout` replaces the whole layout.\n\nRequires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/DashboardId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DashboardPatch"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Dashboard"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"delete":{"operationId":"analytics.dashboards.destroy","summary":"Delete a dashboard","tags":["analytics"],"description":"Saved reports stay; email schedules of the dashboard are deleted.\n\nRequires key permission(s): `analytics.write`.","parameters":[{"$ref":"#\/components\/parameters\/DashboardId"}],"security":[{"secretKey":[]}],"x-required-scopes":["analytics.write"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/loyalty\/calculate":{"post":{"operationId":"loyalty.calculate","summary":"Calculate points for a cart","tags":["loyalty"],"description":"How many points the profile can use for a cart of `amount` (at most `max_redeem_percent` of the amount and the balance), the discount in the project currency and an estimate of points the order will earn at the member's tier (rules are not included \u2014 they depend on the order).\n\nRequires key permission(s): `loyalty.read`.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile","amount"],"properties":{"profile":{"$ref":"#\/components\/schemas\/LoyaltyProfileRef"},"amount":{"type":"number","minimum":0,"description":"Cart amount in the project currency"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyCalculation"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/loyalty\/profiles\/{type}\/{value}":{"get":{"operationId":"loyalty.profiles.show","summary":"Loyalty account of a profile","tags":["loyalty"],"description":"Balance, points waiting for the return period, tier, purchase sum of the tier window and the nearest expiry. A profile that has not joined returns `member: false`.\n\nRequires key permission(s): `loyalty.read`.","parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyAccount"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/loyalty\/profiles\/{type}\/{value}\/transactions":{"get":{"operationId":"loyalty.profiles.transactions","summary":"Point history of a profile","tags":["loyalty"],"description":"Ledger operations from the newest: `earn`, `cancel`, `expire`, `adjust`, `redeem` (a hold or a redemption), `refund` (points returned). Cursor pages.\n\nRequires key permission(s): `loyalty.read`.","parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"},{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/LoyaltyTransaction"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/loyalty\/members":{"post":{"operationId":"loyalty.members.store","summary":"Join the program","tags":["loyalty"],"description":"Opens an account for an existing profile \u2014 for programs with explicit joining (`enrollment: explicit`). Returns 200 if the profile is already a member.\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"$ref":"#\/components\/schemas\/LoyaltyProfileRef"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyAccount"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/loyalty\/referrals":{"post":{"operationId":"loyalty.referrals.store","summary":"Apply a friend's referral code","tags":["loyalty"],"description":"For the registration form of a store: the profile came with the code of a member. The referral counts only for a new customer (no orders, not the member themselves); an identified profile joins the program and gets the friend reward at once (points and, if set, a promo code). 201 \u2014 counted now, 200 \u2014 counted before. 422 on `code`: referrals off, unknown code, own code, existing customer.\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile","code"],"properties":{"profile":{"$ref":"#\/components\/schemas\/LoyaltyProfileRef"},"code":{"type":"string","maxLength":16}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"201":{"description":"Counted","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyReferral"}}}},"200":{"description":"Counted before","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyReferral"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/loyalty\/redemptions":{"post":{"operationId":"loyalty.redemptions.store","summary":"Hold points for a cart","tags":["loyalty"],"description":"Takes points off the balance (earliest expiring first) and holds them for 30 minutes while the order is placed. A new hold for the same `cart_id` returns the previous one. With `amount`, points are limited to the payable share of the cart. Confirm with the order number or cancel; unconfirmed holds return automatically.\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile","points","cart_id"],"properties":{"profile":{"$ref":"#\/components\/schemas\/LoyaltyProfileRef"},"points":{"type":"integer","minimum":1},"cart_id":{"type":"string","maxLength":255},"amount":{"type":"number","minimum":0}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyRedemption"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/loyalty\/redemptions\/{redemption}\/confirm":{"post":{"operationId":"loyalty.redemptions.confirm","summary":"Confirm a redemption","tags":["loyalty"],"description":"Binds the held points to the order. Refunds and cancellations of the order (events `order_refunded`, `order_cancelled`) return the points proportionally. Repeating with the same order changes nothing; an expired or cancelled hold \u2014 422.\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/RedemptionId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["order_id"],"properties":{"order_id":{"type":"string","maxLength":255}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyRedemption"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/loyalty\/redemptions\/{redemption}\/cancel":{"post":{"operationId":"loyalty.redemptions.cancel","summary":"Cancel a redemption","tags":["loyalty"],"description":"Returns the points of a hold or a confirmed redemption to the balance (into their original lots while they have not expired).\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/RedemptionId"}],"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyRedemption"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/loyalty\/adjustments":{"post":{"operationId":"loyalty.adjustments.store","summary":"Adjust points manually","tags":["loyalty"],"description":"Adds points (a lot available at once, with the program lifetime) or takes them off the balance (not more than available), with a reason recorded in the history and the audit log. Send `Idempotency-Key` to make retries safe.\n\nRequires key permission(s): `loyalty.write`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile","points","reason"],"properties":{"profile":{"$ref":"#\/components\/schemas\/LoyaltyProfileRef"},"points":{"type":"integer","description":"Positive \u2014 add, negative \u2014 take off"},"reason":{"type":"string","maxLength":500}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["loyalty.write"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LoyaltyAccount"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/promo\/pools":{"get":{"operationId":"promo.pools.index","summary":"List promo code pools","tags":["promo"],"description":"Pools of the project with code counts by status, uses and the revenue of orders with codes.\n\nRequires key permission(s): `promo.read`.","security":[{"secretKey":[]}],"x-required-scopes":["promo.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/PromoPool"}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/promo\/pools\/{key}":{"get":{"operationId":"promo.pools.show","summary":"Get a pool","tags":["promo"],"description":"One pool with its statistics.\n\nRequires key permission(s): `promo.read`.","parameters":[{"$ref":"#\/components\/parameters\/PromoPoolKey"}],"security":[{"secretKey":[]}],"x-required-scopes":["promo.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PromoPool"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/promo\/pools\/{key}\/codes":{"get":{"operationId":"promo.codes.index","summary":"Codes of a pool (sync)","tags":["promo"],"description":"For store plugins: codes created or changed after the cursor, oldest first. Store `next` and pass it as `since` next time; an empty page returns the same cursor. Changes of the last 10 seconds come with the next call.\n\nRequires key permission(s): `promo.read`.","parameters":[{"$ref":"#\/components\/parameters\/PromoPoolKey"},{"name":"since","in":"query","schema":{"type":"string"},"description":"Cursor from the previous response."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}}],"security":[{"secretKey":[]}],"x-required-scopes":["promo.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/PromoCode"}},"next":{"type":["string","null"],"description":"Cursor for the next call."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"post":{"operationId":"promo.codes.store","summary":"Add codes to a pool","tags":["promo"],"description":"Generates `count` codes (prefix and length of the pool, up to 50 000) or uploads ready `codes` (up to 100 000, e.g. coupons exported from the store). Codes that already exist in the project are skipped. Only for `unique` pools.\n\nRequires key permission(s): `promo.write`.","parameters":[{"$ref":"#\/components\/parameters\/PromoPoolKey"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":50000},"codes":{"type":"array","maxItems":100000,"items":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{2,63}$"}}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["promo.write"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"skipped":{"type":"integer"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/promo\/pools\/{key}\/issue":{"post":{"operationId":"promo.codes.issue","summary":"Issue a code to a profile","tags":["promo"],"description":"A profile with an active code of the pool gets the same code (200); otherwise the next free code is issued (201, event `$promo_code_issued`). A `shared` pool returns its code. 409 with `reason`: `inactive` (paused or outside the period), `limit` (the profile received all its codes), `exhausted` (no free codes).\n\nRequires key permission(s): `promo.write`.","parameters":[{"$ref":"#\/components\/parameters\/PromoPoolKey"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"$ref":"#\/components\/schemas\/IdentityRef"}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["promo.write"],"responses":{"201":{"description":"Issued","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PromoCode"}}}},"200":{"description":"Already issued","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PromoCode"}}}},"409":{"description":"Not issued","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"reason":{"type":"string","enum":["inactive","limit","exhausted"]}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/promo\/codes\/{code}":{"get":{"operationId":"promo.codes.show","summary":"Check a code","tags":["promo"],"description":"Pool, status, validity and the number of orders with the code.\n\nRequires key permission(s): `promo.read`.","parameters":[{"$ref":"#\/components\/parameters\/PromoCode"}],"security":[{"secretKey":[]}],"x-required-scopes":["promo.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/PromoCode"},{"type":"object","properties":{"active":{"type":"boolean","description":"Issued (or shared), not used, not expired, the pool is active."},"uses":{"type":"integer"}}}]}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/promo\/profiles\/{type}\/{value}\/codes":{"get":{"operationId":"promo.profiles.codes","summary":"Codes of a profile","tags":["promo"],"description":"Codes issued to the profile, newest first (up to 100) \u2014 for the customer account of a store.\n\nRequires key permission(s): `promo.read`.","parameters":[{"$ref":"#\/components\/parameters\/IdentityType"},{"$ref":"#\/components\/parameters\/IdentityValue"}],"security":[{"secretKey":[]}],"x-required-scopes":["promo.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#\/components\/schemas\/PromoCode"},{"type":"object","properties":{"active":{"type":"boolean"}}}]}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/messages":{"post":{"operationId":"messages.send","summary":"Send one message now","tags":["messages"],"description":"Sends one message to one profile right away \u2014 an order confirmation, a password reset, a one-time code. The recipient profile is found by identity or created. Repeat the request with the same `Idempotency-Key` to retry safely: no second message is sent. No more than `MESSAGES_API_PER_RECIPIENT_PER_HOUR` (20 by default) messages per recipient per hour through the API. Poll `GET \/messages\/{message}` for the delivery status. With `steps`, the message goes as a cascade \u2014 poll `GET \/messages\/cascades\/{cascade}`; the per-recipient limit counts a cascade once; without the `cascades` plan feature the answer is `402`.\n\nRequires key permission(s): `messages.send`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageSendInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["messages.send"],"responses":{"202":{"description":"Queued: a message, or a cascade when `steps` are given","content":{"application\/json":{"schema":{"oneOf":[{"$ref":"#\/components\/schemas\/MessageStatus"},{"$ref":"#\/components\/schemas\/CascadeStatus"}]}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"402":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/emails":{"post":{"operationId":"emails.send","summary":"Send a store email","tags":["messages"],"description":"Sends a ready email of an online store \u2014 an order confirmation, an invoice, a password reset \u2014 through the project's email integration as is, without a template. The email goes to `to` as a transactional message: no marketing consent or frequency rules, but bounced and complained addresses are blocked. It is counted in the monthly message quota. The answer is fast: when it is not `202` (no email integration, quota exhausted, the service is unavailable), send the email yourself. Repeat the request with the same `Idempotency-Key` to retry safely. No more than `MESSAGES_STORE_EMAILS_PER_RECIPIENT_PER_HOUR` (30 by default) store emails per recipient per hour. Order emails (`order_*` kinds) with `order` are built from the OneTrace template enabled for the kind, in the customer `language`; without an enabled template `subject` and `html` are required. Poll `GET \/messages\/{message}` for the delivery status.\n\nRequires key permission(s): `messages.send`.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreEmailInput"}}}},"security":[{"secretKey":[]}],"x-required-scopes":["messages.send"],"responses":{"202":{"description":"Queued","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreEmailStatus"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"402":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/emails\/settings":{"get":{"operationId":"emails.settings","summary":"Store email settings","tags":["messages"],"description":"What the store plugin should do: relay store emails through OneTrace and which order emails are built from OneTrace templates. Cache for a few minutes.\n\nRequires key permission(s): `messages.send`.","security":[{"secretKey":[]}],"x-required-scopes":["messages.send"],"responses":{"200":{"description":"Settings","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreEmailSettings"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/messages\/cascades\/{cascade}":{"get":{"operationId":"messages.cascade","summary":"Get the state of a cascade","tags":["messages"],"description":"Status of a cascade sent with `POST \/messages` and the messages of its steps.\n\nRequires key permission(s): `messages.send`.","parameters":[{"$ref":"#\/components\/parameters\/CascadeId"}],"security":[{"secretKey":[]}],"x-required-scopes":["messages.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CascadeStatus"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/messages\/{message}":{"get":{"operationId":"messages.show","summary":"Get the status of a message","tags":["messages"],"description":"Status and timestamps of a message sent with `POST \/messages` (or any message of the project by its id).\n\nRequires key permission(s): `messages.send`.","parameters":[{"$ref":"#\/components\/parameters\/MessageId"}],"security":[{"secretKey":[]}],"x-required-scopes":["messages.send"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageStatus"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/conversations":{"get":{"operationId":"conversations.index","summary":"List chat conversations","tags":["conversations"],"description":"Conversations of the online chat (website and messengers), newest first. Filter by status, channel or customer.\n\nRequires key permission(s): `chats.read`.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","waiting","closed"]},"description":"`open` \u2014 waiting for an answer."},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["web","telegram","whatsapp","viber"]}},{"name":"profile_type","in":"query","required":false,"schema":{"type":"string","enum":["user_id","anonymous_id","email","phone","telegram_chat_id","viber_id","web_push"]},"description":"Identity type of the customer; together with `profile_value`."},{"name":"profile_value","in":"query","required":false,"schema":{"type":"string","maxLength":255},"description":"Identity value of the customer; together with `profile_type`."},{"$ref":"#\/components\/parameters\/Limit"},{"$ref":"#\/components\/parameters\/Cursor"}],"security":[{"secretKey":[]}],"x-required-scopes":["chats.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Conversation"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/conversations\/{conversation}":{"get":{"operationId":"conversations.show","summary":"Get a conversation with messages","tags":["conversations"],"description":"The conversation and its latest messages, oldest first.\n\nRequires key permission(s): `chats.read`.","parameters":[{"$ref":"#\/components\/parameters\/ConversationId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"How many latest messages to return."}],"security":[{"secretKey":[]}],"x-required-scopes":["chats.read"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversationDetail"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/conversations\/{conversation}\/messages":{"post":{"operationId":"conversations.messages.store","summary":"Answer in a conversation","tags":["conversations"],"description":"Sends an answer to the customer as the API key: a bot or an external helpdesk. It does not take an operator seat and is signed with the key name in the operator inbox. The website visitor sees it in the chat widget; a messenger answer goes through the messenger integration (WhatsApp allows free text only within 24 hours of the customer's last message). An answer to a closed conversation reopens it unless the customer already has a newer one.\n\nRequires key permission(s): `chats.reply`.","parameters":[{"$ref":"#\/components\/parameters\/ConversationId"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":4000,"description":"Plain text of the answer."}}}}}},"security":[{"secretKey":[]}],"x-required-scopes":["chats.reply"],"responses":{"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversationMessage"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/conversations\/{conversation}\/close":{"post":{"operationId":"conversations.close","summary":"Close a conversation","tags":["conversations"],"description":"Closes the conversation; the website visitor is asked to rate it. Closing a closed conversation changes nothing.\n\nRequires key permission(s): `chats.reply`.","parameters":[{"$ref":"#\/components\/parameters\/ConversationId"}],"security":[{"secretKey":[]}],"x-required-scopes":["chats.reply"],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Conversation"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/forms\/{uid}\/submissions":{"post":{"operationId":"forms.submit","summary":"Submit a website form","tags":["forms"],"description":"A visitor submits a signup form of the website (popup, flyout, embedded form or bar). With double opt-in the address gets a confirmation email and becomes part of the profile only after the visitor confirms it; otherwise the email or phone, the consent and the promo code of the form are applied at once.\n\nUsed by the website forms of the tracker; not part of the SDKs.","x-internal":true,"security":[{"writeKey":[]}],"parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string","maxLength":16},"description":"Form `uid` from the site code."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["anonymousId","values"],"properties":{"anonymousId":{"type":"string","maxLength":255},"userId":{"type":"string","maxLength":255},"values":{"type":"object","description":"Form fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).","additionalProperties":true},"language":{"type":"string","maxLength":35},"page":{"type":"string","maxLength":2000},"website":{"type":"string","description":"Hidden trap field: must stay empty."},"variant":{"type":"string","enum":["a","b","c","d"],"description":"A\/B variant of the form the visitor saw."}}}}}},"responses":{"201":{"description":"Accepted","content":{"application\/json":{"schema":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["pending","accepted"],"description":"`pending` \u2014 waiting for the confirmation link; `accepted` \u2014 applied to the profile."},"message":{"type":"string","description":"Text for the visitor in their language."},"promo_code":{"type":["string","null"],"description":"Promo code of the form when the submission is accepted at once."}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/forms":{"get":{"operationId":"forms.config","summary":"Active website forms","tags":["forms"],"description":"Active signup forms of the project for the tracker: type, fields, design, display rules and the texts in the visitor's language. The tracker loads its forms module only when there is at least one.\n\nUsed by the website forms of the tracker; not part of the SDKs.","x-internal":true,"security":[{"writeKey":[]}],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","maxLength":35},"description":"Visitor language (BCP 47)."},{"name":"anonymousId","in":"query","required":false,"schema":{"type":"string","maxLength":255},"description":"Visitor id: forms shown to segment members are filtered by the visitor's profile."}],"responses":{"200":{"description":"OK","content":{"application\/json":{"schema":{"type":"object","required":["forms"],"properties":{"forms":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"kind":{"type":"string","enum":["popup","flyout","embedded","bar"]},"double_opt_in":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true},"rules":{"type":"object","additionalProperties":true},"texts":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}}},"\/chat\/store-mcp":{"put":{"operationId":"chat.storeMcp.save","summary":"Connect the store MCP server to the AI bot","tags":["conversations"],"description":"A store plugin connects its MCP server (contract: docs\/api\/store-mcp.md) to the AI bot of the project: the platform checks the contract marker in `initialize`, reads `tools\/list` and keeps the contract tools the store owner allowed. One server per URL: calling again updates the key and re-reads the tools.\n\nRequires key permission(s): `chats.manage`.","security":[{"secretKey":[]}],"x-required-scopes":["chats.manage"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url","key"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS address of the store MCP server"},"key":{"type":"string","minLength":32,"maxLength":500,"description":"Bearer key the platform sends to the store"},"name":{"type":"string","maxLength":120},"platform":{"type":"string","enum":["woocommerce","magento","bitrix","sdk","custom"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreMcpServer"}}}},"201":{"description":"Connected","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StoreMcpServer"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"429":{"$ref":"#\/components\/responses\/TooManyRequests"}}},"delete":{"operationId":"chat.storeMcp.delete","summary":"Disconnect the store MCP server","tags":["conversations"],"description":"Removes the store MCP server with this URL from the AI bot of the project.\n\nRequires key permission(s): `chats.manage`.","security":[{"secretKey":[]}],"x-required-scopes":["chats.manage"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2048}}}}}},"responses":{"204":{"description":"Disconnected"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}}},"components":{"securitySchemes":{"writeKey":{"type":"http","scheme":"bearer","description":"`cdp_wk_\u2026`: ingestion only. Also accepted as Basic auth user or `writeKey` body field."},"secretKey":{"type":"http","scheme":"bearer","description":"`cdp_sk_\u2026`: server-side only, permissions chosen when the key is created."}},"parameters":{"IdentityType":{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["user_id","anonymous_id","email","phone","telegram_chat_id","viber_id","web_push"]}},"IdentityValue":{"name":"value","in":"path","required":true,"schema":{"type":"string"},"description":"Normalized like at ingestion (lower-case email, E.164 phone)."},"SegmentId":{"name":"segment","in":"path","required":true,"schema":{"type":"integer"}},"JourneyId":{"name":"journey","in":"path","required":true,"schema":{"type":"integer"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Repeat-safe retries: same key and body return the stored response (header `Idempotent-Replayed: true`); a different body gives 422; a request still in progress gives 409."},"CampaignId":{"name":"campaign","in":"path","required":true,"schema":{"type":"integer"}},"TemplateId":{"name":"template","in":"path","required":true,"schema":{"type":"integer"}},"SavedReportId":{"name":"report","in":"path","required":true,"schema":{"type":"integer"}},"DashboardId":{"name":"dashboard","in":"path","required":true,"schema":{"type":"integer"}},"RedemptionId":{"name":"redemption","in":"path","required":true,"schema":{"type":"string"},"description":"Redemption id from the hold response."},"PromoPoolKey":{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9_]{1,64}$"},"description":"Pool key \u2014 the name used in templates: `{{ promo_code('summer') }}`."},"PromoCode":{"name":"code","in":"path","required":true,"schema":{"type":"string","maxLength":64},"description":"Promo code, case-insensitive."},"MessageId":{"name":"message","in":"path","required":true,"description":"Message `id` (UUID) from the send response.","schema":{"type":"string","format":"uuid"}},"CascadeId":{"name":"cascade","in":"path","required":true,"description":"Cascade `id` (UUID) from the send response.","schema":{"type":"string","format":"uuid"}},"ConversationId":{"name":"conversation","in":"path","required":true,"description":"Conversation `id` (UUID).","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"Missing, invalid or revoked key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Forbidden":{"description":"The key lacks the required permission or the brand is suspended","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"NotFound":{"description":"Not found in the key's project","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"ValidationError":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"TooManyRequests":{"description":"Rate limit or monthly event quota exceeded","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"PayloadTooLarge":{"description":"Body over 1 MB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Error":{"description":"The request cannot be applied in the current state","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"Error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"IdentityRef":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["user_id","anonymous_id","email","phone","telegram_chat_id","viber_id","web_push"]},"value":{"type":"string","maxLength":255}}},"IdentitiesInput":{"type":"object","required":["identities"],"properties":{"identities":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#\/components\/schemas\/IdentityRef"}}}},"Message":{"type":"object","properties":{"type":{"type":"string","enum":["track","identify","page","alias"]},"messageId":{"type":"string","maxLength":100},"anonymousId":{"type":["string","integer"]},"userId":{"type":["string","integer"]},"previousId":{"type":["string","integer"]},"event":{"type":"string","maxLength":200},"name":{"type":"string"},"properties":{"type":"object"},"traits":{"type":"object"},"context":{"type":"object"},"consents":{"type":"array","maxItems":20,"description":"identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.","items":{"type":"object","required":["channel","status"],"properties":{"channel":{"type":"string","pattern":"^[a-z0-9_]{1,64}$","examples":["email"]},"topic":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$","description":"Subscription topic; the whole channel if omitted."},"status":{"type":"string","enum":["subscribed","unsubscribed"]}}}},"timestamp":{"type":"string","format":"date-time"}}},"Profile":{"type":"object","properties":{"id":{"type":"integer"},"traits":{"type":"object"},"identities":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"}}},"Event":{"type":"object","properties":{"event_id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"properties":{"type":"object"},"context":{"type":"object"},"occurred_at":{"type":"string","format":"date-time"}}},"CatalogEvent":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":["string","null"]},"volume":{"type":"integer"},"first_seen_at":{"type":["string","null"],"format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"},"properties":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"data_type":{"type":"string"}}}}}},"CatalogTrait":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":["string","null"]},"data_type":{"type":"string"},"pii":{"type":"boolean"},"system":{"type":"boolean"}}},"Segment":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["dynamic","static"]},"realtime":{"type":"boolean"},"schedule_minutes":{"type":["integer","null"]},"status":{"type":"string","enum":["pending","computing","ready","failed"]},"size":{"type":"integer"},"last_computed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SegmentDetail":{"allOf":[{"$ref":"#\/components\/schemas\/Segment"},{"type":"object","properties":{"rules":{"type":["object","null"],"description":"Rule tree: {\"op\": \"and|or\", \"children\": [...]}"}}}]},"SegmentInput":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"type":{"type":"string","enum":["dynamic","static"]},"realtime":{"type":"boolean"},"schedule_minutes":{"type":"integer","enum":[15,30,60,180,360,720,1440]},"rules":{"type":"object"}}},"SegmentPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"realtime":{"type":"boolean"},"schedule_minutes":{"type":"integer"},"rules":{"type":"object"}}},"Journey":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"version":{"type":["integer","null"]},"next_run_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"JourneyDetail":{"allOf":[{"$ref":"#\/components\/schemas\/Journey"},{"type":"object","properties":{"draft":{"type":"object","properties":{"graph":{"type":"object"},"entry":{"type":"object"}}},"published":{"type":["object","null"],"properties":{"graph":{"type":"object"},"entry":{"type":"object"}}}}}]},"JourneyInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"graph":{"type":"object","properties":{"nodes":{"type":"array","maxItems":200},"edges":{"type":"array","maxItems":400}}},"entry":{"type":"object"}}},"JourneyPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"graph":{"type":"object"},"entry":{"type":"object"}}},"Enrollment":{"type":"object","properties":{"id":{"type":"integer"},"profile_id":{"type":"integer"},"version_id":{"type":"integer"},"status":{"type":"string"},"current_node_id":{"type":["string","null"]},"exit_reason":{"type":["string","null"]},"entered_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"goal_reached_at":{"type":["string","null"],"format":"date-time"}}},"EnrollResult":{"type":"object","properties":{"enrolled":{"type":"boolean"},"enrollment_id":{"type":["integer","null"]},"profile_id":{"type":"integer"}}},"CampaignAudience":{"type":"object","required":["segment_ids"],"properties":{"segment_ids":{"type":"array","maxItems":10,"items":{"type":"integer"},"description":"Members of any of these segments get the campaign."},"exclude_segment_ids":{"type":"array","maxItems":10,"items":{"type":"integer"},"description":"Members of these segments are excluded."}}},"CampaignVariant":{"type":"object","required":["key","percent"],"properties":{"key":{"type":"string","pattern":"^[a-z0-9_]{1,32}$"},"template_id":{"type":["integer","null"],"description":"Message template of the campaign channel."},"percent":{"type":"integer","minimum":1,"maximum":100,"description":"Share of the audience (or of the A\/B test share); all variants add up to 100."}}},"CampaignAb":{"type":["object","null"],"required":["test_percent","metric","wait"],"description":"A\/B test: `test_percent` of the audience is split between variants; after `wait` the rest gets the winner by `metric`.","properties":{"test_percent":{"type":"integer","minimum":5,"maximum":50},"metric":{"type":"string","enum":["opened","clicked","goal"]},"wait":{"type":"object","properties":{"amount":{"type":"integer","minimum":1,"maximum":72},"unit":{"type":"string","enum":["hour","day"]}}}}},"CampaignSchedule":{"type":"object","required":["type"],"description":"Times are wall-clock in the project time zone; with `local_time` \u2014 in each recipient's `timezone` trait.","properties":{"type":{"type":"string","enum":["now","at","recurring"]},"at":{"type":"string","example":"2026-11-01T10:00","description":"For `at`: Y-m-d\\TH:i."},"repeat":{"type":"string","enum":["daily","weekly","monthly"]},"time":{"type":"string","example":"10:00"},"weekdays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7},"description":"ISO weekdays for `weekly` (1 = Monday)."},"day_of_month":{"type":"integer","minimum":1,"maximum":28},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"local_time":{"type":"boolean"}}},"CampaignGoal":{"type":["object","null"],"required":["event","within"],"description":"Conversion: the event from the recipient within the window after sending.","properties":{"event":{"type":"string"},"within":{"type":"object","properties":{"amount":{"type":"integer","minimum":1,"maximum":90},"unit":{"type":"string","enum":["hour","day"]}}}}},"Campaign":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","scheduled","sending","sent","paused","cancelled"]},"integration_id":{"type":["integer","null"]},"channel":{"type":["string","null"]},"audience":{"$ref":"#\/components\/schemas\/CampaignAudience"},"variants":{"type":"array","items":{"$ref":"#\/components\/schemas\/CampaignVariant"}},"ab":{"$ref":"#\/components\/schemas\/CampaignAb"},"schedule":{"$ref":"#\/components\/schemas\/CampaignSchedule"},"rate_per_minute":{"type":["integer","null"]},"goal":{"$ref":"#\/components\/schemas\/CampaignGoal"},"next_run_at":{"type":["string","null"],"format":"date-time"},"last_run_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CampaignInput":{"type":"object","required":["name","audience","variants","schedule"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"]},"integration_id":{"type":["integer","null"],"description":"Channel integration; the template of every variant must belong to its channel."},"audience":{"$ref":"#\/components\/schemas\/CampaignAudience"},"variants":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#\/components\/schemas\/CampaignVariant"}},"ab":{"$ref":"#\/components\/schemas\/CampaignAb"},"schedule":{"$ref":"#\/components\/schemas\/CampaignSchedule"},"rate_per_minute":{"type":["integer","null"],"minimum":10,"maximum":100000},"goal":{"$ref":"#\/components\/schemas\/CampaignGoal"}}},"CampaignVariantStats":{"type":"object","properties":{"queued":{"type":"integer"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"bounced":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"},"unsubscribed":{"type":"integer"},"converted":{"type":["integer","null"],"description":"Recipients with the goal event in the window; null without a goal."}}},"CampaignRun":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["preparing","sending","testing","completed","paused","cancelled","failed"]},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"audience_size":{"type":"integer"},"queued":{"type":"integer"},"winner":{"type":["string","null"]},"winner_at":{"type":["string","null"],"format":"date-time"},"error":{"type":["string","null"]},"variants":{"type":"object","additionalProperties":{"$ref":"#\/components\/schemas\/CampaignVariantStats"}},"total":{"$ref":"#\/components\/schemas\/CampaignVariantStats"},"metric":{"type":"string","enum":["opened","clicked","goal"]},"stats":{"$ref":"#\/components\/schemas\/AbStats"},"ab_result":{"type":["object","null"],"description":"Test result saved when the A\/B winner was picked.","properties":{"metric":{"type":"string"},"decided_at":{"type":"string","format":"date-time"},"stats":{"$ref":"#\/components\/schemas\/AbStats"}}},"languages":{"type":"object","description":"Results per language of the sent template version.","additionalProperties":{"type":"object","properties":{"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"unsubscribed":{"type":"integer"}}}}}},"AbStats":{"type":["object","null"],"description":"Significance of the difference between variants (docs\/architecture\/analytics.md#\u0437\u043d\u0430\u0447\u0438\u043c\u043e\u0441\u0442\u044c-ab); null with one variant.","properties":{"verdict":{"type":"string","enum":["winner","no_difference","insufficient_data"]},"winner":{"type":["string","null"],"description":"Set only when the best variant is significantly better than every other one."},"best":{"type":"string"},"required_per_arm":{"type":["integer","null"]},"alpha":{"type":"number"},"arms":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"trials":{"type":"integer"},"successes":{"type":"integer"},"rate":{"type":"number"},"ci":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"Wilson 95 % interval"},"lift":{"type":["number","null"],"description":"Relative to the first variant"},"p_value":{"type":["number","null"],"description":"Holm-adjusted p-value against the best variant"},"probability_best":{"type":"number"}}}}}},"ProductCard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":["string","null"]},"image":{"type":["string","null"],"description":"JPEG up to image_width via imgproxy; without imgproxy \u2014 a direct link (CDN copy or feed URL)."},"image_original":{"type":["string","null"],"description":"Direct link: the platform CDN copy if the feed mirrors images, otherwise the feed URL."},"srcset":{"type":["object","null"],"description":"Variants for <picture>: AVIF and WebP srcset (240\u2013960 px); null without imgproxy.","properties":{"avif":{"type":"string"},"webp":{"type":"string"}}},"price":{"type":["number","null"]},"old_price":{"type":["number","null"]},"currency":{"type":["string","null"]},"brand":{"type":["string","null"]},"category_id":{"type":["string","null"]},"min_quantity":{"type":["integer","null"],"description":"The product is sold as a set (tires by 4): how many to add to the cart; null \u2014 one."}}},"ProductInput":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","maxLength":128,"description":"Product id on the site: product_id in events."},"name":{"type":"string","maxLength":500},"url":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"price":{"type":"number","minimum":0},"old_price":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"available":{"type":"boolean","default":true},"stock":{"type":"integer","minimum":0,"description":"Units in stock. Used only when \"Use stock levels from the API and plugins\" is on in the catalog settings of the project: then the stock is saved, zero takes the product off sale, and the \"low stock\" journey trigger works. Otherwise it is ignored."},"category_ids":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Leaf category first."},"brand":{"type":"string","maxLength":200},"params":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"translations":{"type":"object","maxProperties":20,"description":"Translations by language (BCP 47 tag \u2192 text), ADR-080: name, url and params in that language; they are shown to visitors and in messages of the language. Languages sent before are kept, a new one is added.","additionalProperties":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"url":{"type":"string","format":"uri","maxLength":2000},"params":{"type":"object"}}}}}},"MessageTemplate":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"channel":{"type":"string","examples":["email"]},"topic":{"type":"string","description":"Subscription topic the message belongs to."},"transactional":{"type":"boolean"},"language":{"type":"string","maxLength":16,"description":"Main language of `content`: recipients whose profile language has no version get it.","examples":["de"]},"content":{"type":"object","additionalProperties":true,"description":"Fields of the channel message schema, e.g. `subject`, `html` and `text` for email; string fields are Twig templates."},"translations":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true},"description":"Other language versions: language tag \u2192 content. A recipient gets the version for the `language` profile trait (exact tag, then the base language, then another variant of it), otherwise `content`."},"version":{"type":"integer","description":"Grows when any language version changes."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"MessageTemplateInput":{"type":"object","required":["name","channel_key","content"],"properties":{"name":{"type":"string","maxLength":120},"channel_key":{"type":"string","description":"Channel of the template; cannot be changed later."},"topic":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$","default":"marketing"},"transactional":{"type":"boolean","default":false},"language":{"type":"string","maxLength":16,"description":"Main language of `content`; the project default language if omitted.","examples":["de"]},"content":{"type":"object","additionalProperties":true,"description":"Fields of the channel message schema, e.g. `subject`, `html` and `text` for email; string fields are Twig templates."},"translations":{"type":"object","maxProperties":50,"additionalProperties":{"type":"object","additionalProperties":true},"description":"Other language versions; each is validated like `content`. Omit to keep the stored versions, pass `{}` to delete them."}}},"AnalyticsReportType":{"type":"string","enum":["report","funnel","retention","paths","revenue","traffic","attribution"]},"AnalyticsPeriod":{"oneOf":[{"type":"object","required":["last"],"properties":{"last":{"type":"integer","enum":[7,14,30,90,180,365],"description":"Last N days including today, in the project timezone"}}},{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}},"description":"Dates in the project timezone, up to 731 days"}]},"PropertyFilter":{"type":"object","required":["key","operator"],"properties":{"key":{"type":"string","description":"Property key from the event catalog"},"operator":{"type":"string","description":"Operator of the property type, as in segment rules"},"value":{"description":"Value for the operator; absent for is_set \/ is_not_set"}}},"ProfileRules":{"type":["object","null"],"description":"Segment rules (docs\/architecture\/segmentation.md): only events of matching profiles are counted. Null or an empty group \u2014 all profiles.","additionalProperties":true},"Breakdown":{"type":["object","null"],"required":["source","key"],"properties":{"source":{"type":"string","enum":["property","context"]},"key":{"type":"string","description":"Event property, or a page field: page.path, page.referrer, campaign.source, campaign.medium, campaign.name, locale"}}},"AnalyticsInterval":{"type":"string","enum":["day","week","month"]},"ReportQuery":{"type":"object","required":["series"],"properties":{"series":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"object","properties":{"event":{"type":["string","null"]},"metric":{"type":"string","enum":["count","profiles","per_profile","sum","avg"]},"property":{"type":["string","null"]},"filters":{"type":"array","items":{"$ref":"#\/components\/schemas\/PropertyFilter"}}}}},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"breakdown":{"$ref":"#\/components\/schemas\/Breakdown"},"interval":{"$ref":"#\/components\/schemas\/AnalyticsInterval"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"},"compare":{"type":"boolean"}}},"FunnelQuery":{"type":"object","required":["steps"],"properties":{"steps":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"object","required":["event"],"properties":{"event":{"type":"string"},"filters":{"type":"array","items":{"$ref":"#\/components\/schemas\/PropertyFilter"}}}}},"window":{"type":"object","properties":{"amount":{"type":"integer","minimum":1},"unit":{"type":"string","enum":["minute","hour","day"]}},"description":"Conversion window from the first step, up to 90 days"},"order":{"type":"string","enum":["sequential","strict"]},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"breakdown":{"$ref":"#\/components\/schemas\/Breakdown"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"RetentionQuery":{"type":"object","required":["start"],"properties":{"start":{"type":"object","properties":{"event":{"type":["string","null"]},"filters":{"type":"array","items":{"$ref":"#\/components\/schemas\/PropertyFilter"}}}},"return":{"type":"object","properties":{"event":{"type":["string","null"]},"filters":{"type":"array","items":{"$ref":"#\/components\/schemas\/PropertyFilter"}}}},"cohort":{"type":"string","enum":["first","period"]},"interval":{"$ref":"#\/components\/schemas\/AnalyticsInterval"},"periods":{"type":"integer","minimum":1,"maximum":30,"description":"Up to 30 days, 12 weeks or 12 months"},"returns":{"type":"string","enum":["exact","rolling"]},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"PathQuery":{"type":"object","required":["event"],"properties":{"event":{"type":"string"},"filters":{"type":"array","items":{"$ref":"#\/components\/schemas\/PropertyFilter"}},"direction":{"type":"string","enum":["after","before"]},"steps":{"type":"integer","minimum":1,"maximum":5},"gap_minutes":{"type":"integer","minimum":1,"maximum":1440},"exclude":{"type":"array","maxItems":20,"items":{"type":"string"}},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"RevenueQuery":{"type":"object","properties":{"event":{"type":"string","description":"Purchase event; by default from the prediction settings"},"amount":{"type":"string","description":"Numeric order amount property"},"product_property":{"type":"string"},"interval":{"$ref":"#\/components\/schemas\/AnalyticsInterval"},"ltv_interval":{"type":"string","enum":["week","month"]},"ltv_periods":{"type":"integer","minimum":1,"maximum":12},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"TrafficQuery":{"type":"object","properties":{"dimension":{"type":"string","enum":["channel","source","source_medium","campaign","referrer","landing"]},"interval":{"$ref":"#\/components\/schemas\/AnalyticsInterval"},"event":{"type":"string"},"amount":{"type":"string"},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"AttributionQuery":{"type":"object","properties":{"window_days":{"type":"integer","enum":[1,3,7,14,30]},"model":{"type":"string","enum":["last","first","linear"]},"interval":{"$ref":"#\/components\/schemas\/AnalyticsInterval"},"event":{"type":"string"},"amount":{"type":"string"},"profiles":{"$ref":"#\/components\/schemas\/ProfileRules"},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"ReportResult":{"type":"object","required":["definition","period","buckets","series"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"buckets":{"type":"array","items":{"type":"string","format":"date"}},"series":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per series: index, total, values per bucket, previous period, breakdown"}},"additionalProperties":true},"FunnelResult":{"type":"object","required":["definition","period","steps","breakdown"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"steps":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds"},"breakdown":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per breakdown value: value, steps (reached per step)"},"time_sample":{"type":"number","description":"Share of profiles used for time between steps"}},"additionalProperties":true},"RetentionResult":{"type":"object","required":["definition","period","cohorts","average"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"cohorts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per cohort: date, size, values (returned per period, null \u2014 not yet), open (period still running)"},"average":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per period: period, rate, profiles"}},"additionalProperties":true},"PathResult":{"type":"object","required":["definition","period","total","nodes","links","paths"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"total":{"type":"integer"},"nodes":{"type":"array","items":{"type":"object","additionalProperties":true}},"links":{"type":"array","items":{"type":"object","additionalProperties":true}},"paths":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Most frequent paths: events, profiles"},"truncated":{"type":"boolean"}},"additionalProperties":true},"RevenueResult":{"type":"object","required":["definition","period","summary","series","ltv","products","categories"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"currency":{"type":["string","null"]},"other_currency_orders":{"type":"integer"},"summary":{"type":"object","additionalProperties":true},"series":{"type":"object","additionalProperties":true},"ltv":{"type":"object","additionalProperties":true},"products":{"type":"array","items":{"type":"object","additionalProperties":true}},"categories":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"TrafficResult":{"type":"object","required":["definition","period","summary","rows","chart"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"currency":{"type":["string","null"]},"purchases":{"type":"boolean"},"summary":{"type":"object","additionalProperties":true},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}},"row_count":{"type":"integer"},"chart":{"type":"object","additionalProperties":true}},"additionalProperties":true},"AttributionResult":{"type":"object","required":["definition","period","summary","channels","items"],"properties":{"definition":{"type":"object","description":"Normalized definition","additionalProperties":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"currency":{"type":["string","null"]},"summary":{"type":"object","additionalProperties":true},"channels":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per channel: channel, clicks, touched_orders, revenue and orders by model"},"items":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per campaign, journey, message channel or widget"},"chart":{"type":"object","additionalProperties":true}},"additionalProperties":true},"SavedReport":{"type":"object","required":["id","name","type","created_at","updated_at"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"$ref":"#\/components\/schemas\/AnalyticsReportType"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SavedReportDetail":{"allOf":[{"$ref":"#\/components\/schemas\/SavedReport"},{"type":"object","required":["definition","view"],"properties":{"definition":{"type":"object","additionalProperties":true},"view":{"type":"object","additionalProperties":true,"description":"Page view settings: chart type, metric"}}}]},"SavedReportInput":{"type":"object","required":["name","type","definition"],"properties":{"name":{"type":"string","maxLength":120},"type":{"$ref":"#\/components\/schemas\/AnalyticsReportType"},"definition":{"type":"object","description":"Definition of the report type \u2014 see the run operations","additionalProperties":true},"view":{"type":"object","additionalProperties":true}}},"SavedReportPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"definition":{"type":"object","additionalProperties":true},"view":{"type":"object","additionalProperties":true}}},"Dashboard":{"type":"object","required":["id","name","layout","period","created_at","updated_at"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"layout":{"type":"array","maxItems":24,"items":{"type":"object","required":["report_id"],"properties":{"report_id":{"type":"integer"},"size":{"type":"string","enum":["half","full"]}}}},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DashboardInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"layout":{"type":"array","maxItems":24,"items":{"type":"object","required":["report_id"],"properties":{"report_id":{"type":"integer"},"size":{"type":"string","enum":["half","full"]}}}},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"DashboardPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"layout":{"type":"array","maxItems":24,"items":{"type":"object","required":["report_id"],"properties":{"report_id":{"type":"integer"},"size":{"type":"string","enum":["half","full"]}}}},"period":{"$ref":"#\/components\/schemas\/AnalyticsPeriod"}}},"LoyaltyProfileRef":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["user_id","anonymous_id","email","phone","telegram_chat_id","viber_id","web_push"]},"value":{"type":"string"}}},"LoyaltyAccount":{"type":"object","properties":{"member":{"type":"boolean"},"balance":{"type":"integer","description":"Available points"},"pending":{"type":"integer","description":"Points waiting for the return period"},"tier":{"type":["string","null"]},"tier_spend":{"type":"number"},"expiring":{"type":"integer","description":"Points expiring within 30 days"},"expires_at":{"type":["string","null"],"format":"date-time"},"enrolled_at":{"type":["string","null"],"format":"date-time"},"referral_code":{"type":["string","null"],"description":"Code of the member for inviting friends."},"referral_url":{"type":["string","null"],"description":"Referral link (`?ref=` on the store page) when referrals are on."},"referrals":{"type":"object","properties":{"invited":{"type":"integer"},"rewarded":{"type":"integer"},"points":{"type":"integer"}},"description":"Friends who came with the code, of them rewarded, and points for them."}}},"LoyaltyCalculation":{"type":"object","properties":{"member":{"type":"boolean"},"balance":{"type":"integer"},"tier":{"type":["string","null"]},"max_points":{"type":"integer"},"max_discount":{"type":"number"},"earn_points":{"type":"integer"},"point_value":{"type":"number"},"currency":{"type":["string","null"]}}},"LoyaltyRedemption":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["held","confirmed","cancelled","expired"]},"points":{"type":"integer"},"returned":{"type":"integer"},"discount":{"type":"number"},"cart_id":{"type":"string"},"order_id":{"type":["string","null"]},"held_until":{"type":"string","format":"date-time"},"confirmed_at":{"type":["string","null"],"format":"date-time"}}},"LoyaltyTransaction":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","enum":["earn","cancel","expire","adjust","redeem","refund"]},"points":{"type":"integer"},"reference":{"type":["string","null"]},"reason":{"type":["string","null"]},"rule":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"referral":{"type":["string","null"],"enum":["friend","referrer",null],"description":"Referral reward: `friend` \u2014 for joining by invitation, `referrer` \u2014 for the first order of a friend."}}},"PromoPool":{"type":"object","required":["key","name","type","status","active","per_profile","stats"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["shared","unique"],"description":"`shared` \u2014 one code for everyone; `unique` \u2014 a separate code for every profile."},"status":{"type":"string","enum":["active","paused"]},"active":{"type":"boolean","description":"Active now: not paused and within the promotion period."},"discount":{"type":["string","null"],"description":"Discount text for messages, e.g. \u00ab\u221210 %\u00bb. The discount itself is a coupon rule of the store."},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time","description":"End of the promotion (exclusive)."},"validity_days":{"type":["integer","null"],"description":"A code is valid for this many days after it is issued (not longer than the promotion)."},"per_profile":{"type":"integer","description":"How many codes of the pool one profile can receive."},"stats":{"type":"object","properties":{"total":{"type":"integer"},"available":{"type":"integer"},"issued":{"type":"integer"},"used":{"type":"integer"},"uses":{"type":"integer"},"revenue":{"type":"number","description":"Sum of the orders with codes of the pool."}}}}},"PromoCode":{"type":"object","required":["code","status"],"properties":{"pool":{"type":"string","description":"Pool key."},"code":{"type":"string"},"status":{"type":"string","enum":["available","issued","used","shared"]},"issued_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"used_at":{"type":["string","null"],"format":"date-time"}}},"LoyaltyReferral":{"type":"object","properties":{"status":{"type":"string","enum":["pending","rewarded","expired","limit","cancelled"],"description":"`pending` \u2014 waiting for the friend's first order."},"code":{"type":"string"},"friend_points":{"type":"integer"},"friend_promo_code":{"type":["string","null"]},"rewarded":{"type":"boolean","description":"The friend has received the reward."},"expires_at":{"type":"string","format":"date-time","description":"The first order of the friend rewards the member until this moment."}}},"MessageSendInput":{"type":"object","required":["identity"],"properties":{"identity":{"$ref":"#\/components\/schemas\/IdentityRef","description":"The recipient. A profile with this identity is created if there is none."},"traits":{"type":"object","maxProperties":100,"description":"Traits written to the profile before sending, available in the template as `traits.*`."},"template_id":{"type":"integer","description":"Message template. A transactional template skips consents, frequency limits and quiet hours, but not hard blocks of the channel (address does not exist, bot blocked); other templates follow all messaging rules."},"integration_id":{"type":["integer","null"],"description":"Channel integration of the template's channel; may be omitted when the channel has exactly one active integration."},"data":{"type":"object","description":"Per-message data, available in the template as `context.data.*` (order number, confirmation code)."},"steps":{"type":"array","minItems":2,"maxItems":5,"items":{"$ref":"#\/components\/schemas\/CascadeStep"},"description":"Cascade (plans with the `cascades` feature): channels tried in order \u2014 the next one when the profile cannot be reached on the previous, or its message was not sent, not delivered or not read within the step time."}},"description":"Pass `template_id` (and `integration_id` if needed) for one message, or `steps` for a cascade \u2014 not both."},"MessageStatus":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","scheduled","sent","delivered","failed","skipped","bounced"],"description":"`queued` \u2192 `sent` \u2192 `delivered`; `scheduled` \u2014 waiting (quiet hours, warm-up); `skipped` \u2014 not sent, see `reason`; `failed`\/`bounced` \u2014 see `reason` and `error`."},"reason":{"type":["string","null"],"description":"Why it was skipped or failed: `no_recipient`, `unsubscribed`, `recipient_blocked`, `suppressed`, `frequency_limit`, `quota_exceeded`, `feature_unavailable`, `delivery_failed`, `recipient_unreachable`, `undelivered`, `template_error`, `integration_unavailable` \u2026"},"error":{"type":["string","null"]},"channel":{"type":"string"},"template_id":{"type":["integer","null"]},"integration_id":{"type":["integer","null"]},"profile_id":{"type":"integer"},"transactional":{"type":"boolean"},"origin":{"type":["string","null"],"description":"`api` for messages sent with `messages.send`, `store` for store emails (`emails.send`)."},"created_at":{"type":["string","null"],"format":"date-time"},"scheduled_for":{"type":["string","null"],"format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"opened_at":{"type":["string","null"],"format":"date-time"},"clicked_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"}}},"CascadeStep":{"type":"object","required":["integration_id","template_id"],"properties":{"integration_id":{"type":"integer"},"template_id":{"type":"integer","description":"Template of the integration's channel."},"wait_for":{"type":"string","enum":["sent","delivered","opened"],"default":"sent","description":"What counts as success. `delivered` needs an integration that reports delivery (not email through own SMTP), `opened` \u2014 a channel that reports reading (email, WhatsApp, Viber)."},"timeout":{"type":"object","description":"How long to wait for `delivered` or `opened` after sending; 15 minutes by default.","properties":{"amount":{"type":"integer","minimum":1,"maximum":3650},"unit":{"type":"string","enum":["minute","hour","day","week"]}}}}},"CascadeStatus":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["running","reached","failed"],"description":"`reached` \u2014 a step succeeded; `failed` \u2014 no channel reached the profile."},"step":{"type":"integer","description":"Current step, from 0."},"reached_channel":{"type":["string","null"]},"profile_id":{"type":"integer"},"origin":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"messages":{"type":"array","items":{"$ref":"#\/components\/schemas\/MessageStatus"},"description":"Messages of the steps tried so far."}}},"ChatVisitorMessage":{"type":"object","properties":{"id":{"type":"integer"},"author":{"type":"string","enum":["visitor","operator","system"]},"body":{"type":"string"},"operator":{"type":["string","null"],"description":"First name of the operator"},"action":{"type":["string","null"],"description":"closed \u2014 the conversation was closed"},"created_at":{"type":"string","format":"date-time"},"bot":{"type":"boolean","description":"Reply of the AI bot; operator holds the bot name"}}},"ChatVisitorConversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","waiting","closed"]},"rating":{"type":["integer","null"]},"token":{"type":"string","description":"Returned for a new conversation or when the request had no valid token; store it"},"bot":{"type":"boolean","description":"The AI bot leads the conversation: the widget offers to call an operator (POST \/chat\/handoff)"}}},"Conversation":{"type":"object","required":["id","profile_id","channel","status","assigned","unread_count","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"integer"},"channel":{"type":"string","enum":["web","telegram","whatsapp","viber"],"description":"`web` \u2014 the website chat; messengers need the `chat_messengers` plan feature."},"status":{"type":"string","enum":["open","waiting","closed"],"description":"`open` \u2014 the customer wrote last and waits for an answer; `waiting` \u2014 answered, waiting for the customer; `closed`."},"assigned":{"type":"boolean","description":"An operator is responsible for the conversation."},"unread_count":{"type":"integer","description":"Customer messages operators have not read yet."},"language":{"type":["string","null"]},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"Customer rating after the conversation."},"rating_comment":{"type":["string","null"]},"last_message_at":{"type":["string","null"],"format":"date-time"},"last_message_author":{"type":["string","null"],"enum":["visitor","operator","system",null]},"first_reply_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"}}},"ConversationMessage":{"type":"object","required":["id","author","body","created_at"],"properties":{"id":{"type":"integer"},"author":{"type":"string","enum":["visitor","operator","system"],"description":"`visitor` \u2014 the customer; `operator` \u2014 an answer from the inbox or the API; `system` \u2014 assignment, closing and reopening (see `action`)."},"via":{"type":["string","null"],"enum":["inbox","api",null],"description":"Where an answer or action came from: the operator inbox or the API."},"api_key":{"type":["string","null"],"description":"Name of the API key that answered or closed the conversation."},"body":{"type":"string"},"action":{"type":["string","null"],"enum":["assigned","unassigned","closed","reopened",null]},"status":{"type":["string","null"],"description":"Delivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced."},"created_at":{"type":"string","format":"date-time"}}},"ConversationDetail":{"allOf":[{"$ref":"#\/components\/schemas\/Conversation"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","description":"The latest messages, oldest first.","items":{"$ref":"#\/components\/schemas\/ConversationMessage"}}}}]},"StoreEmailInput":{"type":"object","required":["to","kind"],"properties":{"to":{"type":"string","format":"email","maxLength":254,"description":"Recipient address. The profile is found by this email or created."},"subject":{"type":"string","maxLength":998,"description":"Required unless an order template is enabled for `kind` and `order` is given."},"html":{"type":"string","maxLength":1000000,"description":"Ready HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled for `kind` and `order` is given."},"text":{"type":["string","null"],"maxLength":1000000,"description":"Plain-text part; built from the HTML when empty."},"reply_to":{"type":["string","null"],"format":"email","description":"Overrides the Reply-To of the email integration."},"from_name":{"type":["string","null"],"maxLength":100,"description":"Overrides the sender name of the email integration; the sender address is always the integration's."},"kind":{"type":"string","pattern":"^[a-z0-9_]{1,40}$","description":"What the email is: `order_placed`, `order_paid`, `order_shipped`, `order_delivered`, `order_cancelled`, `order_refunded`, `account_new`, `password_reset`, `email_verification`, `login_link`, `login_code`, `other` \u2026 Access-link kinds (`password_reset`, `account_new`, `email_verification`, `login_link`, `login_code`) go without click tracking, and only the subject is kept after sending. For `order_placed`, `order_paid`, `order_shipped`, `order_delivered`, `order_cancelled`, `order_refunded` with `order`, an enabled OneTrace template builds the email instead of `html` (see `GET \/emails\/settings`)."},"language":{"type":["string","null"],"maxLength":20,"description":"Customer language tag: picks the language version of an order template; for history and reports otherwise."},"integration_id":{"type":["integer","null"],"description":"Email integration; may be omitted when the project has exactly one active."},"traits":{"type":["object","null"],"additionalProperties":true,"description":"Profile traits to update before sending (name, phone)."},"attachments":{"type":"array","maxItems":5,"description":"Up to 5 files, 5 MB in total.","items":{"type":"object","required":["name","type","content"],"properties":{"name":{"type":"string","maxLength":200},"type":{"type":"string","enum":["application\/pdf","image\/png","image\/jpeg","image\/gif","text\/plain","text\/csv","text\/calendar"]},"content":{"type":"string","format":"byte","description":"File contents in base64."}}}},"order":{"$ref":"#\/components\/schemas\/StoreOrder"}}},"StoreEmailStatus":{"allOf":[{"$ref":"#\/components\/schemas\/MessageStatus"},{"type":"object","properties":{"kind":{"type":["string","null"]},"template":{"type":"boolean","description":"The email is built from a OneTrace order template."}}}]},"StoreOrder":{"type":"object","required":["order_id","currency","amount"],"description":"Order data for order email templates \u2014 the `order` template variable.","properties":{"order_id":{"type":"string","maxLength":100},"number":{"type":["string","null"],"maxLength":100,"description":"Number shown to the customer; `order_id` when empty."},"url":{"type":["string","null"],"format":"uri","description":"Order page for the customer."},"created_at":{"type":["string","null"],"format":"date-time"},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"amount":{"type":"number","description":"Order total."},"subtotal":{"type":["number","null"]},"discount":{"type":["number","null"]},"shipping":{"type":["number","null"]},"tax":{"type":["number","null"]},"refund_amount":{"type":["number","null"]},"coupon":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"shipping_method":{"type":["string","null"]},"carrier":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"tracking_url":{"type":["string","null"],"format":"uri"},"estimated_delivery":{"type":["string","null"],"format":"date"},"reason":{"type":["string","null"],"description":"Cancellation or refund reason."},"note":{"type":["string","null"]},"payment_instructions":{"type":["string","null"],"description":"Bank transfer details and similar instructions."},"products":{"type":"array","maxItems":100,"items":{"type":"object","required":["product_name","quantity","price"],"properties":{"product_id":{"type":["string","null"]},"variant_id":{"type":["string","null"]},"sku":{"type":["string","null"]},"product_name":{"type":"string","maxLength":300},"quantity":{"type":"number"},"price":{"type":"number"},"total":{"type":["number","null"],"description":"Line total; price \u00d7 quantity when empty."},"image_url":{"type":["string","null"],"format":"uri"},"url":{"type":["string","null"],"format":"uri"},"options":{"type":["string","null"],"maxLength":500,"description":"Variant options as text: \u00abSize: M, colour: white\u00bb."}}}},"shipping_address":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"maxLength":200},"company":{"type":["string","null"],"maxLength":200},"address1":{"type":["string","null"],"maxLength":200},"address2":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":200},"region":{"type":["string","null"],"maxLength":200},"postcode":{"type":["string","null"],"maxLength":200},"country":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"maxLength":200}}},"billing_address":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"maxLength":200},"company":{"type":["string","null"],"maxLength":200},"address1":{"type":["string","null"],"maxLength":200},"address2":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":200},"region":{"type":["string","null"],"maxLength":200},"postcode":{"type":["string","null"],"maxLength":200},"country":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"maxLength":200}}}}},"StoreEmailSettings":{"type":"object","properties":{"relay":{"type":"boolean","description":"Send all store emails through OneTrace (store emails section)."},"integration_id":{"type":["integer","null"]},"templates":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Order email kinds built from OneTrace templates: the store does not send its own email for them and passes `order` instead."}}},"StoreMcpServer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"status":{"type":"string","enum":["pending","ok","error"],"description":"`error` \u2014 see `error`; the bot works without this server"},"error":{"type":["string","null"]},"tools":{"type":"array","items":{"type":"string"},"description":"Contract tools the bot may use"},"checked_at":{"type":["string","null"],"format":"date-time"}}}}}}