Справочник API
Приём событий, профили, сегменты, цепочки и рассылки — спецификация OpenAPI 3.1.
Общие сведения
Описания методов и полей — на английском, как в спецификации.
{"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.Ключи
writeKeyhttp bearercdp_wk_…: ingestion only. Also accepted as Basic auth user orwriteKeybody field.secretKeyhttp bearercdp_sk_…: server-side only, permissions chosen when the key is created.
Ingest
Track an event
post/track
Тело запросаобязательно
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Пример тела запроса
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Identify a profile and update traits
post/identify
Тело запросаобязательно
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Пример тела запроса
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Track a page view
post/page
Тело запросаобязательно
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Пример тела запроса
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Track a mobile app screen view (event $screen, the screen name in properties.name)
post/screen
Тело запросаобязательно
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Пример тела запроса
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Link a previous identifier to a user
post/alias
Тело запросаобязательно
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Пример тела запроса
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Send up to 500 messages at once
post/batch
Тело запросаобязательно
элементов:
≤ 500
Пример тела запроса
{
"batch": [
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}
]
}Ответы
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 401Missing, invalid or revoked key · Error
- 413Body over 1 MB · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Check the API key
get/key
Ответы
200OK
typestringобязательнозначения:
"write", "secret"namestringобязательноprojectobjectобязательноuidstringnamestringtimezonestring
scopesstring[]обязательноPermissions of a secret key; empty for a write key.
- 401Missing, invalid or revoked key · Error
- 429Rate limit or monthly event quota exceeded · Error
Tracker module settings in one request
get/site/config
GET /chat/config, /feed/config, /forms, /search/widget and /products/questions/widget, which stay for older trackers. A part that fails or is not available on the plan comes back disabled.Параметры
languageв строке запросаstringVisitor language (BCP 47).длина:
≤ 35anonymousIdв строке запросаstringVisitor id: forms shown to segment members are filtered by the visitor's profile.длина:
≤ 255
Ответы
200Settings
chatobjectAsGET /chat/configfeedobjectAsGET /feed/configformsobjectAsGET /formssearchobjectAsGET /search/widget;enabled: falsewithout the product search featureaskobjectAsGET /products/questions/widget
- 401Missing, invalid or revoked key · Error
- 429Rate limit or monthly event quota exceeded · Error
Push
VAPID public key for PushManager.subscribe()
get/push/config
Ответы
Store a browser push subscription and link it to the visitor
post/push/subscriptions
Тело запросаобязательно
anonymousIdstringRequired without userIdдлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128publicKeystringVAPID key the subscription was created withsubscriptionobjectобязательноPushSubscription.toJSON(); the endpoint must belong to a browser push serviceendpointstring (uri)обязательноexpirationTimeinteger | nullkeysobjectобязательноp256dhstringобязательноauthstringобязательно
Пример тела запроса
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"publicKey": "string",
"subscription": {
"endpoint": "https://example.com",
"expirationTime": 0,
"keys": {
"p256dh": "string",
"auth": "string"
}
}
}Ответы
201Subscription stored; consent is recorded once the profile is processed
subscription_idstring
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Forget a browser push subscription
delete/push/subscriptions
Тело запросаобязательно
endpointstringобязательно
Пример тела запроса
{
"endpoint": "string"
}Ответы
200Whether a subscription was removed
deletedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Register a mobile app installation from the SDK: push token, notification permission and device details
post/devices
mobile_push identity and consent to the mobile_push channel; otherwise the identity is removed. A token registered by another installation moves here.Тело запросаобязательно
installationIdstringобязательноRandom id the SDK generates once per installationшаблон:
^[A-Za-z0-9_-]{8,64}$anonymousIdstringRequired without userIdдлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128appobjectобязательноidstringобязательноiOS bundle id or Android package nameversionstringbuildstring
osobjectобязательноnamestringобязательнозначения:
"ios", "android"versionstring
deviceobjectmanufacturerstringmodelstring
localestringдлина:
≤ 35timezonestringIANA time zoneдлина:
≤ 64pushobjectproviderstringзначения:
"fcm", "apns"tokenstringдлина:
≤ 4096enabledbooleanNotifications are allowed by the user
sdkobjectnamestringversionstring
Пример тела запроса
{
"installationId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"app": {
"id": "string",
"version": "string",
"build": "string"
},
"os": {
"name": "ios",
"version": "string"
},
"device": {
"manufacturer": "string",
"model": "string"
},
"locale": "string",
"timezone": "string",
"push": {
"provider": "fcm",
"token": "string",
"enabled": true
},
"sdk": {
"name": "string",
"version": "string"
}
}Ответы
200Installation stored
installation_idstringpushbooleanPush notifications can be sent to this installation
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Report that a mobile push was received by the app or opened by a tap
post/push/events
cdp_token from the notification data. opened with url records an open and a click on that link; received marks the message delivered. A token of another project or channel is ignored (recorded: false).Тело запросаобязательно
tokenstringобязательноcdp_token from the notification dataдлина:
≤ 100eventstringобязательнозначения:
"received", "opened"urlstringThe link opened by the tap (cdp_url)длина:
≤ 2000
Пример тела запроса
{
"token": "string",
"event": "received",
"url": "string"
}Ответы
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
In-app messages waiting to be shown on this installation
get/in-app/messages
in_app plan feature.Параметры
anonymousIdв строке запросаstringобязательнодлина:
≤ 255appIdв строке запросаstringобязательноBundle id or package nameplatformв строке запросаstringобязательнозначения:
"ios", "android"
Ответы
200Messages
dataobject[]tokenstringPass it back to /in-app/eventstrigger_eventstring | nullShow after the app tracks this event; null — on the next app openlayoutstringзначения:
"modal", "banner", "fullscreen"positionstringзначения:
"top", "bottom"titlestringbodystringimage_urlstringbutton_textstringbutton_urlstringclose_textstringbackground_colorstringtext_colorstringbutton_colorstringbutton_text_colorstring
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Report that an in-app message was shown, clicked or dismissed
post/in-app/events
shown marks the message delivered and opened and stops returning it; clicked with url records a click.Тело запросаобязательно
tokenstringобязательнодлина:
≤ 100eventstringобязательнозначения:
"shown", "clicked", "dismissed"urlstringдлина:
≤ 2000
Пример тела запроса
{
"token": "string",
"event": "shown",
"url": "string"
}Ответы
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Message feed of this visitor
get/feed
unread — cards not shown yet. Empty without the feed plan feature.Параметры
anonymousIdв строке запросаstringобязательнодлина:
≤ 255
Ответы
200Feed
dataobject[]tokenstringPass it back to /feed/eventslayoutstringclassic — image on the left, captioned — image on top, banner — image onlyзначения:
"classic", "captioned", "banner"titlestringbodystringimage_urlstringbutton_textstringAbsent — the whole card is the linkbutton_urlstringpinnedbooleanreadbooleanAlready shown in the feedcreated_atstring (date-time)expires_atstring (date-time)
unreadinteger
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Website widget settings of the message feed
get/feed/config
button (floating bell with a counter), element (an icon in every [data-cdp-feed] element) or chat (a tab in the chat window; becomes button while the chat is off). Disabled without the feed plan feature or a feed integration shown on the website.Ответы
Report that a feed card was shown, clicked or dismissed
post/feed/events
shown marks the card read, the message delivered and opened (once); clicked with url records a click; dismissed removes the card from the feed.Тело запросаобязательно
tokenstringобязательнодлина:
≤ 100eventstringобязательнозначения:
"shown", "clicked", "dismissed"urlstringдлина:
≤ 2000
Пример тела запроса
{
"token": "string",
"event": "shown",
"url": "string"
}Ответы
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Recommendations
Product recommendations for the site
get/recommendations
anonymousId only. Only available products are returned. replenish — products the visitor buys regularly whose repeat-purchase cycle has come (needs “Time to reorder” in the recommendation settings).Параметры
typeв строке запросаstringобязательнозначения:
"personal", "popular", "trending", "viewed_with", "bought_with", "similar", "recently_viewed", "replenish"limitв строке запросаintegerпо умолчанию:
8· диапазон:1–24itemв строке запросаstringContext product id (or item[] for a cart) for viewed_with, bought_with, similar.categoryв строке запросаstringCategory id for popular and trending.exclude[]в строке запросаstring[]anonymousIdв строке запросаstringimage_widthв строке запросаintegerCard image width (image), px. Variants forare in srcset when imgproxy is configured (ADR-047). по умолчанию:
480· диапазон:64–1200languageв строке запросаstringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).длина:
≤ 35
Ответы
200Recommended products
typestringrequest_idstring (uuid)itemsProductCard[]
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Website widget configured in the admin panel
get/widgets/{uid}
anonymousId only. A widget outside its display rules returns no items and hidden: true; variant is the A/B variant of the visitor (null — no variants).Параметры
uidв путиstringобязательношаблон:
^[a-z0-9]{1,16}$item[]в строке запросаstring[]Context product ids (data-item): page product or cart items.categoryв строке запросаstringCategory id (data-category); overrides the widget category.exclude[]в строке запросаstring[]anonymousIdв строке запросаstringlanguageв строке запросаstringVisitor 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).длина:
≤ 35urlв строке запросаstringPage address without the domain (path and query): display rules by pages (ADR-139).длина:
≤ 2000deviceв строке запросаstringVisitor device for the display rules (ADR-139).значения:
"desktop", "mobile"visitorв строке запросаstringNew (first session on the website) or returning visitor for the display rules (ADR-139).значения:
"new", "returning"previewв строке запросаstringSigned preview mark from the admin panel (cdp_previewin the page address, valid for 24 hours): the saved widget is shown in the chosen variant even if paused or outside the display rules; the response haspreview: trueand norequest_id, views and clicks are not tracked (ADR-139).длина:
≤ 200
Ответы
200Widget and products
widgetobjectuidstringtypestringstatusstringзначения:
"active", "paused"settingsobjecttitlestringlayoutstringзначения:
"grid", "carousel"columnsintegeraccentstring | nullradiusintegerbuttonstringshowPriceboolean
variantstring | nullpreviewboolean
request_idstring | nullitemsProductCard[]hiddenboolean
- 401Invalid key
- 403Request origin is not one of the key website domains
- 404Widget not found in the project
Personal block configured in the admin panel
get/blocks/{uid}
anonymousId belongs to (arm s1–s5), otherwise the default content or its A/B variant (arm a–d). A paused block or a block outside its display rules returns block: null and hidden: true. Requires the site_personalization plan feature (402 otherwise).Параметры
uidв путиstringобязательношаблон:
^[a-z0-9]{1,16}$anonymousIdв строке запросаstringlanguageв строке запросаstringVisitor language (BCP 47, as in context.locale): the banner texts and the HTML come in their translation for the closest language.длина:
≤ 35urlв строке запросаstringPage address without the domain (path and query): display rules by pages.длина:
≤ 2000deviceв строке запросаstringVisitor device for the display rules.значения:
"desktop", "mobile"visitorв строке запросаstringNew (first session on the website) or returning visitor for the display rules.значения:
"new", "returning"previewв строке запросаstringSigned preview mark from the admin panel (cdp_previewin the page address, valid for 24 hours): the saved block is shown in the chosen arm even if paused or outside the display rules; the response haspreview: true, views and clicks are not tracked.длина:
≤ 200
Ответы
200Block content
blockobject | nulluidstringarmstringa–d: default content and its variants; s1–s5: segment rowscontentobjectBanner (type: banner: layout, title, text, button_text, button_url, image_url, colours, radius) or sanitized HTML (type: html: html) and custom CSS for the shadow root.previewboolean
hiddenboolean
- 401Missing, invalid or revoked key · Error
- 402The plan has no `site_personalization` feature
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Meta
This OpenAPI specification
get/openapi.json
Ответы
200OK
object
Profiles
Get a profile by any identifier
get/profiles/{type}/{value}
profiles.pii.Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Ответы
200OK
idintegertraitsobjectidentitiesobjectfirst_seen_atstring (date-time)last_seen_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Erase a profile and all profiles merged into it (GDPR)
delete/profiles/{type}/{value}
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Ответы
Profile events, newest first, 50 per page
get/profiles/{type}/{value}/events
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).beforeв строке запросаstring (date-time)Cursor:next_beforeof the previous page.nameв строке запросаstring
Ответы
Subscribe or unsubscribe a profile
put/profiles/{type}/{value}/consents
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Тело запросаобязательно
channelstringобязательноChannel key, oradsfor the advertising consent: whether the profile's data may be sent to ad platforms (conversions, audiences);adsalways applies to the whole channel.пример:
"email"topicstringOmit for the whole channel (all).statusstringобязательнозначения:
"subscribed", "unsubscribed"
Пример тела запроса
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}Ответы
200OK
object
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create a Telegram deep link for a profile
post/telegram/link
Тело запросаобязательно
integrationstringIntegration uid when the project has several bots.
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Ответы
200OK
urlstringtokenstringintegrationstring
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create a Viber bot deep link for a profile
post/viber/link
Тело запросаобязательно
integrationstringIntegration uid when the project has several Viber bots.
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Ответы
200OK
urlstringtokenstringintegrationstring
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create a MAX bot deep link for a profile
post/max/link
https://max.ru/{bot}?start={token}: opening the bot with it links the MAX user to the profile.Тело запросаобязательно
integrationstringIntegration uid when the project has several MAX bots.
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Ответы
200OK
urlstringtokenstringintegrationstring
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create a VK community link for a profile
post/vk/link
https://vk.me/{community}?ref={token}: the first message to the community from this link links the VK user to the profile. The same token can be passed as the key of the VK "Allow messages" widget for community group_id.Тело запросаобязательно
integrationstringIntegration uid when the project has several VK communities.
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Ответы
200OK
urlstringtokenstringgroup_idintegerintegrationstring
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create an Instagram Direct link for a profile
post/instagram/link
https://ig.me/m/{account}?ref={token}: opening the conversation from this link links the Instagram user to the profile.Тело запросаобязательно
integrationstringIntegration uid when the project has several Instagram accounts.
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Ответы
200OK
urlstringtokenstringintegrationstring
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Subscription preferences of a profile
get/profiles/{type}/{value}/preferences
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).languageв строке запросаstringLanguage of topic names; the project default when omitted.
Ответы
200OK
profile_idintegerlanguagestringLanguage of topic names.пример:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringпример:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.пример:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringпример:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.значения:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing messages are paused until this time.preferences_urlstring (uri)Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.preferences_url_expires_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Change subscription preferences of a profile
put/profiles/{type}/{value}/preferences
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Тело запросаобязательно
topicsobjectTopic key → channel key → subscribed. Only the given topics and channels change.пример:
{"news":{"email":true},"offers":{"email":false}}frequencystring | nullOmit to keep.значения:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullPause marketing messages until this time (within a year);nullresumes; omit to keep.unsubscribe_allbooleanUnsubscribe from all marketing messages in every channel, including channels connected or addressable later; other fields are ignored. Subscribing to a channel afterwards (here, byPUT /profiles/{type}/{value}/consentsor by a push permission) opens only that channel.languagestringLanguage of topic names in the response.adsbooleanAdvertising consent: allow (true) or deny (false) sending the profile data to ad platforms. Applies only when the project has an ad platform connected (adsin the response is not null).
Пример тела запроса
{
"topics": {
"news": {
"email": true
},
"offers": {
"email": false
}
},
"frequency": "weekly",
"paused_until": "2026-01-01T10:00:00Z",
"unsubscribe_all": true,
"language": "string",
"ads": true
}Ответы
200OK
profile_idintegerlanguagestringLanguage of topic names.пример:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringпример:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.пример:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringпример:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.значения:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing messages are paused until this time.preferences_urlstring (uri)Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.preferences_url_expires_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Wallet card link of a profile
get/profiles/{type}/{value}/wallet
wallet_url is null when the project has no Wallet cards (no wallet integration or the plan has no wallet feature).Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).languageв строке запросаstringLanguage of topic names; the project default when omitted.
Ответы
200OK
wallet_urlstring (uri) | nullwallet_url_expires_atstring (date-time) | nullplatformsstring[]passesobject[]platformstringзначения:
"apple", "google"card_numberstringinstalledbooleaninstalled_atstring (date-time) | nullremoved_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Subscription topics of the project
get/subscription-topics
Ответы
Products
Create or update products and categories
post/products
Тело запросаобязательно
элементов:
≤ 1000categoriesobject[]элементов:
≤ 1000idstringобязательноnamestringобязательноparent_idstring | nulltranslationsobjectCategory name by language (BCP 47 tag → {name}).ключей:
≤ 20
Пример тела запроса
{
"items": [
{
"id": "string",
"name": "string",
"url": "https://example.com",
"image": "https://example.com",
"price": 0,
"old_price": 0,
"currency": "string",
"available": true,
"stock": 0,
"category_ids": [
"string"
],
"brand": "string",
"description": "string",
"params": {},
"translations": {}
}
],
"categories": [
{
"id": "string",
"name": "string",
"parent_id": "string",
"translations": {}
}
]
}Ответы
200Saved
savedintegercategoriesinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete products
delete/products
Тело запросаобязательно
idsstring[]обязательноэлементов:
1–1000
Пример тела запроса
{
"ids": [
"string"
]
}Ответы
200Deleted
deletedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Published reviews of a product
get/reviews
rating and count — over all published reviews of the product, distribution — number of reviews per score. product gives the name and link for schema.org markup. Cached for 1 minute. Needs the “Product reviews” tariff feature.Параметры
productв строке запросаstringобязательноProduct id from the catalog.длина:
≤ 128pageв строке запросаintegerпо умолчанию:
1· диапазон:1–1000languageв строке запросаstringLanguage of the product name.длина:
≤ 35
Ответы
200Reviews
productobjectidstringnamestringurlstring | nullimagestring | null
ratingnumber | nullAverage score,nullwithout reviews.countintegerdistributionobjectScore (5…1) → number of reviews.reviewsobject[]idintegerratingintegerдиапазон:
1–5titlestring | nulltextstring | nullauthorstring | nulllanguagestring | nullpublished_atstring (date-time) | null
pageintegermoreboolean
- 401Missing, invalid or revoked key · Error
- 402The tariff has no product reviews
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Add a product review
post/reviews
Тело запросаобязательно
productstringобязательноProduct id from the catalog.длина:
≤ 128ratingintegerобязательнодиапазон:
1–5titlestringдлина:
≤ 120textstringдлина:
≤ 2000authorstringName shown with the review.длина:
≤ 60languagestringдлина:
≤ 35publishbooleanпо умолчанию:
falsedatestring (date-time)Date of a moved review (withpublish).
Пример тела запроса
{
"product": "string",
"identity": {
"type": "user_id",
"value": "string"
},
"rating": 1,
"title": "string",
"text": "string",
"author": "string",
"language": "string",
"publish": false,
"date": "2026-01-01T10:00:00Z"
}Ответы
201Saved
idintegerstatusstringзначения:
"pending", "published"
- 401Missing, invalid or revoked key · Error
- 402The tariff has no product reviews
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Ask AI about a product
post/products/questions
Answers a shopper's question about one product from its card (name, description, characteristics, industry attributes, price, stock) and the shop knowledge base, in the language of the question (ADR-132). Charged to the project balance by tokens like AI in chat; the same question about an unchanged product in the same language is answered from a cache for a day without charge. Limited per visitor (5 a minute, 50 a day). Records the event $product_question for the visitor.
Used by the product question widget of the tracker; not part of the SDKs.
With async: true an answer from the cache comes at once (200); otherwise the model answers in the background and the response is 202 with id — get the result with GET /products/questions/result. Without it the answer comes in the same request.
Тело запросаобязательно
product_idstringобязательноProduct id in the catalog (id from the feed or the products API)длина:
≤ 128questionstringобязательнодлина:
≤ 500anonymousIdstringобязательнодлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128languagestringLanguage of the page (BCP 47); the answer follows the language of the questionдлина:
≤ 35asyncbooleanAnswer in the background: 202 withidinstead of waiting for the model (the tracker widget does so)
Пример тела запроса
{
"product_id": "string",
"question": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"language": "string",
"async": true
}Ответы
200Answer
answerstringansweredbooleanfalse — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staffsourcesobject[]titlestringurlstring | null
202Accepted with `async: true`: the model answers in the background
pendingbooleanidstringToken of the result for GET /products/questions/result, kept for 10 minutes
402AI is not available for the project: no paid plan, no balance, spend limit reached (`reason`)
messagestringreasonstring
404No such product
messagestringreasonstring
429Too many questions from this visitor
messagestringreasonstring
502The AI model did not answer
messagestringreasonstring
503AI is not configured on the platform
messagestringreasonstring
Result of a product question answered in the background
get/products/questions/result
Result of POST /products/questions with async: true (ADR-132): 202 while the model is answering, then the answer as for a question answered at once. The token is kept for 10 minutes.
Used by the product question widget of the tracker; not part of the SDKs.
Параметры
idв строке запросаstringобязательнодлина:
40–40
Ответы
200Answer
answerstringansweredbooleanfalse — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staffsourcesobject[]titlestringurlstring | null
202The model is still answering
pendingboolean
402AI is not available for the project (`reason`)
messagestringreasonstring
404No such result: unknown or expired token
messagestringreasonstring
502The AI model did not answer
messagestringreasonstring
503AI is turned off or not configured on the platform (`reason`)
messagestringreasonstring
Suggested questions about a product
get/products/questions/suggested
Three short typical shopper questions for products of the category, in the language of the page (ADR-132). Generated by AI once per category and language and kept for 30 days; empty when AI is not available.
Used by the product question widget of the tracker; not part of the SDKs.
Параметры
product_idв строке запросаstringобязательнодлина:
≤ 128languageв строке запросаstringдлина:
≤ 35
Ответы
200Questions
questionsstring[]
404No such product
messagestringreasonstring
Product question widget settings
get/products/questions/widget
Settings of the product question widget for the tracker (ADR-132): mode, suggestions, appearance and texts in the visitor's language. enabled: false when the widget is off in the site settings, AI is not configured or not paid for — the tracker then does not load the widget. Cached for 5 minutes when off, 1 minute when on.
Used by the tracker; not part of the SDKs.
Параметры
languageв строке запросаstringдлина:
≤ 35
Ответы
200Widget settings
enabledbooleanобязательноmodestringзначения:
"block", "chat"chatbooleanOnline chat is on: the block offers to ask the staffsuggestionsbooleanaccentstringпример:
"#4f46e5"radiusintegerдиапазон:
0–24textsobject
Stores
List stores
get/stores
Ответы
Create or update stores
post/stores
Тело запросаобязательно
элементов:
1–1000
Пример тела запроса
{
"items": [
{
"id": "string",
"name": "string",
"city": "string",
"address": "string"
}
]
}Ответы
200Saved
savedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete stores
delete/stores
Тело запросаобязательно
idsstring[]обязательноэлементов:
1–1000
Пример тела запроса
{
"ids": [
"string"
]
}Ответы
200Deleted
deletedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Catalog
Events seen in the project with their properties
get/catalog/events
Ответы
200OK
dataCatalogEvent[]
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Profile traits of the project
get/catalog/traits
Ответы
200OK
dataCatalogTrait[]
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Event schema of the project
get/event-schema
enabled — whether incoming events are checked against the schema.Ответы
200OK
enabledbooleanCheck incoming events against the schemaeventsobject[]элементов:
≤ 1000namestringобязательноEvent name (system$…events are not allowed)длина:
≤ 255labelstring | nullдлина:
≤ 255descriptionstring | nullдлина:
≤ 1000propertiesobject[]элементов:
≤ 200keystringобязательнодлина:
≤ 255typestringобязательнозначения:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleanпо умолчанию:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)элементов:
≤ 100Один из вариантов:
descriptionstring | nullдлина:
≤ 1000
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Replace the event schema
put/event-schema
events only enabled changes. label is changed only when present. Events that break the schema are still accepted: violations are counted for 7 days (GET /event-schema/violations) and start over after every change. Requires the event_schema plan feature (402 otherwise).Тело запросаобязательно
enabledbooleanCheck incoming events against the schemaeventsobject[]элементов:
≤ 1000namestringобязательноEvent name (system$…events are not allowed)длина:
≤ 255labelstring | nullдлина:
≤ 255descriptionstring | nullдлина:
≤ 1000propertiesobject[]элементов:
≤ 200keystringобязательнодлина:
≤ 255typestringобязательнозначения:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleanпо умолчанию:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)элементов:
≤ 100Один из вариантов:
descriptionstring | nullдлина:
≤ 1000
Пример тела запроса
{
"enabled": true,
"events": [
{
"name": "string",
"label": "string",
"description": "string",
"properties": [
{
"key": "string",
"type": "string",
"required": false,
"values": [
"string"
],
"description": "string"
}
]
}
]
}Ответы
200Saved
enabledbooleanCheck incoming events against the schemaeventsobject[]элементов:
≤ 1000namestringобязательноEvent name (system$…events are not allowed)длина:
≤ 255labelstring | nullдлина:
≤ 255descriptionstring | nullдлина:
≤ 1000propertiesobject[]элементов:
≤ 200keystringобязательнодлина:
≤ 255typestringобязательнозначения:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleanпо умолчанию:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)элементов:
≤ 100Один из вариантов:
descriptionstring | nullдлина:
≤ 1000
- 401Missing, invalid or revoked key · Error
- 402The tariff has no event schema
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Event schema violations for 7 days
get/event-schema/violations
unexpected_value; masked without the profiles.pii permission). Empty while the check is off.Ответы
Segments
List segments
get/segments
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
Create a segment
post/segments
status. Rules use the same DSL as the segment builder (docs/architecture/segmentation.md).Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120descriptionstring | nulltypestringобязательнозначения:
"dynamic", "static"realtimebooleanschedule_minutesintegerзначения:
15, 30, 60, 180, 360, 720, 1440rulesobject
Пример тела запроса
{
"name": "string",
"description": "string",
"type": "dynamic",
"realtime": true,
"schedule_minutes": 15,
"rules": {}
}Ответы
201Created
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a segment with its rules
get/segments/{segment}
Параметры
segmentв путиintegerобязательно
Ответы
Update a segment (partial)
patch/segments/{segment}
Параметры
segmentв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120descriptionstring | nullrealtimebooleanschedule_minutesintegerrulesobject
Пример тела запроса
{
"name": "string",
"description": "string",
"realtime": true,
"schedule_minutes": 0,
"rules": {}
}Ответы
200OK
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a segment
delete/segments/{segment}
Параметры
segmentв путиintegerобязательно
Ответы
- 204Deleted
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Queue a recomputation of a dynamic segment
post/segments/{segment}/compute
Параметры
segmentв путиintegerобязательно
Ответы
Segment members, latest entered first
get/segments/{segment}/members
Параметры
segmentв путиintegerобязательноlimitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
200OK
dataobject[]обязательноprofile_idintegerentered_atstring (date-time)
next_cursorstring | nullобязательноPass ascursorto get the next page; null on the last page.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Add profiles to a static segment
post/segments/{segment}/members
Параметры
segmentв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
элементов:
1–1000
Пример тела запроса
{
"identities": [
{
"type": "user_id",
"value": "string"
}
]
}Ответы
200OK
addedintegerunknownIdentityRef[]
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Remove profiles from a static segment
delete/segments/{segment}/members
Параметры
segmentв путиintegerобязательно
Тело запросаобязательно
элементов:
1–1000
Пример тела запроса
{
"identities": [
{
"type": "user_id",
"value": "string"
}
]
}Ответы
200OK
removedintegerunknownIdentityRef[]
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Whether a profile is a member
get/segments/{segment}/members/{type}/{value}
Параметры
segmentв путиintegerобязательноtypeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Ответы
Journeys
List journeys
get/journeys
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstringstatusв строке запросаstringзначения:
"draft", "active", "paused", "archived"
Ответы
Create a journey draft
post/journeys
Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120descriptionstring | nullgraphobjectnodesarrayэлементов:
≤ 200edgesarrayэлементов:
≤ 400
entryobject
Пример тела запроса
{
"name": "string",
"description": "string",
"graph": {
"nodes": [],
"edges": []
},
"entry": {}
}Ответы
201Created
Все поля Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a journey with its draft and published version
get/journeys/{journey}
Параметры
journeyв путиintegerобязательно
Ответы
200OK
Все поля Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update the draft (partial)
patch/journeys/{journey}
Параметры
journeyв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120descriptionstring | nullgraphobjectentryobject
Пример тела запроса
{
"name": "string",
"description": "string",
"graph": {},
"entry": {}
}Ответы
200OK
Все поля Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Validate the draft without publishing
post/journeys/{journey}/validate
graph.nodes.2.data.template_id.Параметры
journeyв путиintegerобязательно
Ответы
200OK
validboolean
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Launch readiness of the draft
get/journeys/{journey}/readiness
Параметры
journeyв путиintegerобязательно
Ответы
200OK
readybooleanобязательноNo errors: the launch will pass.clearbooleanобязательноNo errors and no warnings.checksobject[]обязательноkeystringобязательноconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringобязательнозначения:
"error", "warning", "info"messagestringобязательноText in the language of the requestpathstringField of a config error, e.g.variants.0.template_id
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Publish the draft as a new version
post/journeys/{journey}/publish
Параметры
journeyв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
Все поля Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Pause: no new entries, participants stay
post/journeys/{journey}/pause
{"exit_all": true} also exits all participants. Only active journeys.Параметры
journeyв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запроса
exit_allboolean
Пример тела запроса
{
"exit_all": true
}Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Resume a paused journey
post/journeys/{journey}/resume
Параметры
journeyв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Archive: all participants exit
post/journeys/{journey}/archive
Параметры
journeyв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Submit a journey for approval
post/journeys/{journey}/approval/request
comment.Параметры
journeyв путиintegerобязательно
Тело запроса
commentstringдлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Approve a journey
post/journeys/{journey}/approval/approve
Параметры
journeyв путиintegerобязательно
Тело запроса
commentstringдлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Return a journey for changes
post/journeys/{journey}/approval/return
comment is required.Параметры
journeyв путиintegerобязательно
Тело запросаобязательно
commentstringобязательнодлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Journey participations, newest first
get/journeys/{journey}/enrollments
Параметры
journeyв путиintegerобязательноlimitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstringstatusв строке запросаstringзначения:
"active", "waiting", "completed", "exited", "failed"
Ответы
200OK
next_cursorstring | nullобязательноPass ascursorto get the next page; null on the last page.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Funnel, goals and A/B branches for a period
get/journeys/{journey}/report
Параметры
journeyв путиintegerобязательноperiodв строке запросаintegerзначения:
7, 30, 90· по умолчанию:30
Ответы
Enroll a profile into a journey with the API trigger
post/journeys/{journey}/enroll
Параметры
journeyв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
dataobjectAvailable in templates ascontext.data.idempotency_keystringдлина:
≤ 150
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"data": {},
"idempotency_key": "string"
}Ответы
200Not enrolled (repeat key, re-entry policy, audience or limit)
enrolledbooleanenrollment_idinteger | nullprofile_idinteger
201Enrolled
enrolledbooleanenrollment_idinteger | nullprofile_idinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 409The request cannot be applied in the current state · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Templates
List message templates
get/templates
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstringchannelв строке запросаstringOnly templates of this channel.
Ответы
Create a message template
post/templates
Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120channel_keystringобязательноChannel of the template; cannot be changed later.topicstringпо умолчанию:
"marketing"· длина:≤ 64· шаблон:^[a-z0-9_-]+$transactionalbooleanпо умолчанию:
falselanguagestringMain language ofcontent; the project default language if omitted.длина:
≤ 16· пример:"de"contentobjectобязательноFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.ключей:
≤ 50
Пример тела запроса
{
"name": "string",
"channel_key": "string",
"topic": "marketing",
"transactional": false,
"language": "de",
"content": {},
"translations": {}
}Ответы
201Created
idintegernamestringchannelstringпример:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.длина:
≤ 16· пример:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a message template
get/templates/{template}
Параметры
templateв путиintegerобязательно
Ответы
200OK
idintegernamestringchannelstringпример:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.длина:
≤ 16· пример:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a message template (partial)
patch/templates/{template}
Параметры
templateв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120topicstringпо умолчанию:
"marketing"· длина:≤ 64· шаблон:^[a-z0-9_-]+$transactionalbooleanпо умолчанию:
falselanguagestringMain language ofcontent; the project default language if omitted.длина:
≤ 16· пример:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.ключей:
≤ 50
Пример тела запроса
{
"name": "string",
"topic": "marketing",
"transactional": false,
"language": "de",
"content": {},
"translations": {}
}Ответы
200OK
idintegernamestringchannelstringпример:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.длина:
≤ 16· пример:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a message template
delete/templates/{template}
Параметры
templateв путиintegerобязательно
Ответы
Campaigns
List campaigns
get/campaigns
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
Create a campaign draft
post/campaigns
Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.элементов:
1–5rate_per_minuteinteger | nullдиапазон:
10–100000goalCampaignGoal
Пример тела запроса
{
"name": "string",
"description": "string",
"integration_id": 0,
"audience": {
"segment_ids": [
0
],
"exclude_segment_ids": [
0
],
"ignore_control_group": true
},
"variants": [
{
"key": "string",
"template_id": 0,
"percent": 1
}
],
"ab": {
"mode": "test",
"test_percent": 5,
"metric": "opened",
"wait": {
"amount": 1,
"unit": "hour"
}
},
"schedule": {
"type": "now",
"at": "2026-11-01T10:00",
"repeat": "daily",
"time": "10:00",
"weekdays": [
1
],
"day_of_month": 1,
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"local_time": true,
"best_time": true
},
"rate_per_minute": 10,
"goal": {
"event": "string",
"within": {
"amount": 1,
"unit": "hour"
}
}
}Ответы
201Created
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a campaign
get/campaigns/{campaign}
Параметры
campaignв путиintegerобязательно
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a campaign (partial)
patch/campaigns/{campaign}
Параметры
campaignв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.audienceCampaignAudiencevariantsCampaignVariant[]элементов:
1–5scheduleCampaignSchedulerate_per_minuteinteger | nullдиапазон:
10–100000goalCampaignGoal
Пример тела запроса
{
"name": "string",
"description": "string",
"integration_id": 0,
"audience": {
"segment_ids": [
0
],
"exclude_segment_ids": [
0
],
"ignore_control_group": true
},
"variants": [
{
"key": "string",
"template_id": 0,
"percent": 1
}
],
"ab": {
"mode": "test",
"test_percent": 5,
"metric": "opened",
"wait": {
"amount": 1,
"unit": "hour"
}
},
"schedule": {
"type": "now",
"at": "2026-11-01T10:00",
"repeat": "daily",
"time": "10:00",
"weekdays": [
1
],
"day_of_month": 1,
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"local_time": true,
"best_time": true
},
"rate_per_minute": 10,
"goal": {
"event": "string",
"within": {
"amount": 1,
"unit": "hour"
}
}
}Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a campaign
delete/campaigns/{campaign}
Параметры
campaignв путиintegerобязательно
Ответы
- 204Deleted
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Campaign report: last runs with per-variant stats
get/campaigns/{campaign}/report
Параметры
campaignв путиintegerобязательно
Ответы
Launch readiness of the campaign
get/campaigns/{campaign}/readiness
Параметры
campaignв путиintegerобязательно
Ответы
200OK
readybooleanобязательноNo errors: the launch will pass.clearbooleanобязательноNo errors and no warnings.checksobject[]обязательноkeystringобязательноconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringобязательнозначения:
"error", "warning", "info"messagestringобязательноText in the language of the requestpathstringField of a config error, e.g.variants.0.template_id
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Schedule (or launch) a campaign
post/campaigns/{campaign}/schedule
now starts within a minute.Параметры
campaignв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Pause a campaign
post/campaigns/{campaign}/pause
Параметры
campaignв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Resume a paused campaign
post/campaigns/{campaign}/resume
Параметры
campaignв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Cancel a campaign
post/campaigns/{campaign}/cancel
Параметры
campaignв путиintegerобязательноIdempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Ответы
200OK
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Submit a campaign for approval
post/campaigns/{campaign}/approval/request
comment.Параметры
campaignв путиintegerобязательно
Тело запроса
commentstringдлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Approve a campaign
post/campaigns/{campaign}/approval/approve
Параметры
campaignв путиintegerобязательно
Тело запроса
commentstringдлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Return a campaign for changes
post/campaigns/{campaign}/approval/return
comment is required.Параметры
campaignв путиintegerобязательно
Тело запросаобязательно
commentstringобязательнодлина:
≤ 1000
Пример тела запроса
{
"comment": "string"
}Ответы
Chat
Website chat widget settings
get/chat/config
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.
Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.
Параметры
languageв строке запросаstringдлина:
≤ 35
Ответы
200Settings; only enabled: false when the chat is off
enabledbooleanonlinebooleancolorstringpositionstringзначения:
"right", "left"launcherbooleanСтандартная кнопка чата; false — чат открывает своя кнопка сайта (cdp.openChat() или data-cdp-chat).prechatbooleanname_fieldstringИмя в анкете: не спрашивать, необязательно, обязательно (обязательное проверяется у первого сообщения нового диалога).значения:
"hidden", "optional", "required"email_fieldstringEmail в анкете: не спрашивать, необязательно, обязательно.значения:
"hidden", "optional", "required"offline_emailbooleanТребовать email, когда чат не на связи (проверяет виджет).previewbooleanOperators see what the visitor is typing: send text with POST /chat/typing (stage 97)textsobjecttitlestringgreetingstringofflinestring
departmentsobject[]Departments the visitor can choose before the first message (stage 97); the widget shows the choice when there are at least two. online: the department works now (its or the chat's working hours) and one of its operators is online.idintegernamestringonlineboolean
filesobjectDocuments the visitor may attach (stage 97)extensionsstring[]max_mbinteger
fieldsobject[]Pre-chat fields (stage 97) with the label in the visitor languagekeystringtypestringзначения:
"text", "phone", "select"requiredbooleanoptionsstring[]labelstring
surveyobject | nullPost-chat survey (stage 97): questions and texts in the visitor languagekeystringquestionsobject[]textsobject
Messages of the visitor conversation
get/chat/messages
/conversations.Параметры
conversationв строке запросаstring (uuid)обязательноtokenв строке запросаstringобязательнодлина:
≤ 64afterв строке запросаintegerдиапазон:
≥ 0readв строке запросаbooleanMark operator replies as read by the visitorпо умолчанию:
true
Ответы
200Messages visible to the visitor
conversationChatVisitorConversationmessagesChatVisitorMessage[]
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
Send a visitor message
post/chat/messages
Finds the visitor profile by anonymousId (creates it if needed; userId, name and email go through the same rules as identify with a write key) and adds the message to its open website conversation or starts a new one. An open conversation continues only with its token or from the browser that started it.
Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.
Тело запросаобязательно
anonymousIdstringобязательнодлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128conversationstring (uuid)Conversation id from POST /chat/messagestokenstringVisitor token of the conversation from POST /chat/messagesдлина:
≤ 64bodystringMessage text. Required unless the message carries images (multipart/form-data).длина:
≤ 4000namestringдлина:
≤ 100emailstring (email)длина:
≤ 255pagestringPage URL (http/https)длина:
≤ 2000languagestringдлина:
≤ 35customer_tokenstringToken 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.длина:
≤ 2000departmentintegerDepartment chosen by the visitor (GET /chat/config → departments) for a new conversation; a department hidden from visitors or of another project is ignored, and the department is then chosen by the page or channel.invitationintegerAutomatic invitation the visitor replies to (stage 97): its text becomes the first operator message of the new conversationfieldsobjectPre-chat fields set in the chat settings (stage 97): field key → value; unknown keys and select values outside the options are dropped
Пример тела запроса
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"body": "string",
"name": "string",
"email": "string",
"page": "string",
"language": "string",
"customer_token": "string",
"department": 0,
"invitation": 0,
"fields": {}
}Ответы
201Message stored
conversationChatVisitorConversationmessageChatVisitorMessage
- 403The visitor is blocked (code: blocked)
- 404The website chat is turned off
- 409The open conversation of this customer was started in another browser (code `conversation_elsewhere`)
- 429Too many requests: messages of this browser (20 per minute), new conversations from this IP (5 per minute) or in this project (60 per minute), documents of this browser (20 per hour), or document bytes from this IP (50 MB per hour) or in this project (500 MB per hour); wait for Retry-After seconds
The visitor is typing
post/chat/typing
/conversations. Shares the presence rate limit, separate from event ingestion (ADR-253).Тело запросаобязательно
conversationstring (uuid)обязательноConversation id from POST /chat/messagestokenstringобязательноVisitor token of the conversation from POST /chat/messagesдлина:
≤ 64textstring | nullText the visitor is still typing (stage 97), sent when the chat config has preview: true. Operators see the first 500 characters; it is not stored.длина:
≤ 4000
Пример тела запроса
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"text": "string"
}Ответы
- 200Shown to operators of the open conversation
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
The visitor is on the site
post/chat/presence
Тело запросаобязательно
anonymousIdstringобязательнодлина:
≤ 255pagestringCurrent page URL (http or https). Only the path and utm_* parameters are kept: the fragment and other parameters are droppedдлина:
≤ 2000titlestringдлина:
≤ 300referrerstringSite the visit came from; only its scheme and host are keptдлина:
≤ 2000sourcestringutm_source of the first page or the referring hostдлина:
≤ 100started_atintegerStart of the visit, Unix time in millisecondspagesintegerPages viewed in the visitдиапазон:
≥ 1languagestringдлина:
≤ 35conversationstring (uuid)Conversation the widget already knowsinvitationsbooleanReturn the automatic invitations for this visitor
Пример тела запроса
{
"anonymousId": "string",
"page": "string",
"title": "string",
"referrer": "string",
"source": "string",
"started_at": 0,
"pages": 1,
"language": "string",
"conversation": "00000000-0000-0000-0000-000000000000",
"invitations": true
}Ответы
200The visitor is shown to operators as online for 90 seconds
nextintegerSeconds until the next presence call: 30 while operators are online or the visitor list is open, 180 otherwise (ADR-253)invitationsobject[]Enabled invitations for the visitor segments, text in the visitor language; the widget checks the page rules (stage 97)idintegertextstringsenderstring | nullrulesobject
conversationChatVisitorConversationConversation an operator started with this browser; contains the visitor tokenВсе поля ChatVisitorConversation
- 403The visitor is blocked (code: blocked)
- 404The chat is disabled
- 429Too many requests: presence calls of this browser or new browsers from this IP; wait for Retry-After seconds
Answer the post-chat survey
post/chat/survey
Тело запросаобязательно
conversationstring (uuid)обязательноtokenstringобязательнодлина:
≤ 64answersobjectобязательноQuestion id → answer (scale number, option or list of options, text)languagestringдлина:
≤ 35
Пример тела запроса
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"answers": {},
"language": "string"
}Ответы
- 200Recorded; a repeated answer updates the same survey response
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation, wrong token or no active post-chat survey
- 422The answers do not fit the questions
- 429More than 5 calls per hour for this conversation
Rate the conversation
post/chat/rating
/conversations.Тело запросаобязательно
conversationstring (uuid)обязательноConversation id from POST /chat/messagestokenstringобязательноVisitor token of the conversation from POST /chat/messagesдлина:
≤ 64ratingintegerобязательнодиапазон:
1–5commentstringдлина:
≤ 1000
Пример тела запроса
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"rating": 1,
"comment": "string"
}Ответы
200Rating stored
conversationChatVisitorConversation
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
- 422The conversation has never been closed (code rating_open), or the rating is not 1–5
- 429More than 5 calls per hour for this conversation
Ask for a human operator
post/chat/handoff
/conversations.Тело запросаобязательно
conversationstring (uuid)обязательноConversation id from POST /chat/messagestokenstringобязательноVisitor token of the conversation from POST /chat/messagesдлина:
≤ 64
Пример тела запроса
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string"
}Ответы
200The bot handed the conversation over to the operators
conversationChatVisitorConversation
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
Realtime tokens of the visitor conversation
post/chat/realtime
Centrifugo connection token (anonymous) and subscription token for the channel of this conversation only.
Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.
Тело запросаобязательно
conversationstring (uuid)обязательноConversation id from POST /chat/messagestokenstringобязательноVisitor token of the conversation from POST /chat/messagesдлина:
≤ 64
Пример тела запроса
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string"
}Ответы
200Tokens
urlstringchannelstringconnection_tokenstringsubscription_tokenstring
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
Search
Product search for the site
get/search
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.
Every request (and every suggestion request) counts towards the monthly search requests of the plan.
Параметры
qв строке запросаstringQuery text; empty — the whole catalog.длина:
≤ 200categoryв строке запросаstringCategory id; products of its subcategories too.brand[]в строке запросаstring[]элементов:
≤ 20price_minв строке запросаnumberдиапазон:
≥ 0price_maxв строке запросаnumberдиапазон:
≥ 0attrв строке запросаobjectFilters 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 — fromfacets.attributes.ключей:
≤ 20sortв строке запросаstringзначения:
"relevance", "popular", "price_asc", "price_desc"· по умолчанию:"relevance"pageв строке запросаintegerпо умолчанию:
1· диапазон:1–100per_pageв строке запросаintegerпо умолчанию:
24· диапазон:1–48allв строке запросаbooleanInclude products that are not available.по умолчанию:
falseanonymousIdв строке запросаstringTracker visitor id for the personal order.image_widthв строке запросаintegerпо умолчанию:
480· диапазон:64–1200languageв строке запросаstringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).длина:
≤ 35correctв строке запросаbooleanCorrect typos of a query that finds nothing (default true); false searches exactly the typed text.по умолчанию:
trueignore[]в строке запросаstring[]What not to recognize in the query text: price, brand or a characteristic key (the visitor removed the chip of a recognized filter).элементов:
≤ 20
Ответы
200Found products
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]Все поля ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.
- 401Missing, invalid or revoked key · Error
402Product search is not in the plan (feature_unavailable) or the monthly search requests are used up beyond the 10% margin (quota_exceeded): fall back to the website's own search.
messagestringcodestringзначения:
"feature_unavailable", "quota_exceeded"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
AI search
post/search/ai
AI search (ADR-195): the shopper's query in plain words is parsed by AI into catalog filters — categories, brands, attributes, price, exclusions, sorting — and the results come with the chips of what AI understood and follow-up refinements. Used only when the AI search mode of the project wants it for the query (off, auto for descriptive queries, toggle, always); otherwise {ai: null} and the usual results stay. A parse from the cache comes at once; otherwise 202 with id — get the results with GET /search/ai/result. AI filters that find nothing are relaxed step by step. Charged to the project balance by tokens; limited per visitor (10 model parses a minute, 100 a day). Counts as a search request.
Used by the search widget of the tracker; not part of the SDKs.
Тело запросаобязательно
qstringобязательнодлина:
≤ 200previousobjectai.stateof the previous answer: the query refines it ("cheaper", "only Michelin")stateobjectai.stateto search by without the model (a removed chip of what AI understood, the next page); checked against the catalog like a model answeraskedbooleanThe shopper turned on "Ask AI" (toggle mode)sortstringSorting chosen by the shopper; relevance — the sorting AI understoodзначения:
"relevance", "popular", "price_asc", "price_desc"anonymousIdstringдлина:
≤ 255languagestringдлина:
≤ 35pageintegerдиапазон:
1–100per_pageintegerдиапазон:
≥ 1image_widthintegerдиапазон:
64–1200allboolean
Пример тела запроса
{
"q": "string",
"previous": {},
"state": {},
"asked": true,
"sort": "relevance",
"anonymousId": "string",
"language": "string",
"page": 1,
"per_page": 1,
"image_width": 64,
"all": true
}Ответы
200Results by the AI parse, or `{ai: null}`
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]Все поля ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.aiobjectWhat AI understood (null — usual results stay)understoodobject[]typestringзначения:
"category", "brand", "attribute", "exclude", "price"keystringlabelstring
refinementsstring[]Short follow-up queries for chipsrelaxedinteger0 — all AI filters applied; 1 — without attributes and exclusions; 2 — text and price; 3 — the original textcachedbooleanstateobjectParsed state; send it back aspreviouswith a follow-up query
reasonstringWhy AI was not used: plan, balance, spend_limit, disabled, not_configured, too_many, failed, expired
202The model is parsing the query
pendingbooleanidstring
402Search quota exceeded
messagestringreasonstring
Result of an AI search parsed in the background
get/search/ai/result
Results of POST /search/ai that answered 202: send id and the same q and result parameters. 202 while the model is parsing; then the results by the parse, or {ai: null, reason} if AI was not available or did not answer. The id is kept for 5 minutes.
Used by the search widget of the tracker; not part of the SDKs.
Параметры
idв строке запросаstringобязательнодлина:
40–40qв строке запросаstringобязательнодлина:
≤ 200languageв строке запросаstringдлина:
≤ 35anonymousIdв строке запросаstringдлина:
≤ 255per_pageв строке запросаintegerimage_widthв строке запросаinteger
Ответы
200Results by the AI parse, or `{ai: null}`
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]Все поля ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.aiobjectWhat AI understood (null — usual results stay)understoodobject[]typestringзначения:
"category", "brand", "attribute", "exclude", "price"keystringlabelstring
refinementsstring[]Short follow-up queries for chipsrelaxedinteger0 — all AI filters applied; 1 — without attributes and exclusions; 2 — text and price; 3 — the original textcachedbooleanstateobjectParsed state; send it back aspreviouswith a follow-up query
reasonstringWhy AI was not used: plan, balance, spend_limit, disabled, not_configured, too_many, failed, expired
202The model is still parsing
pendingboolean
Short AI answer written so far
get/search/ai/answer
Text of the answer started with POST /search/ai/answer so far: done: false — still being written. The id is kept for 5 minutes.
Used by the search widget of the tracker; not part of the SDKs.
Параметры
idв строке запросаstringобязательнодлина:
40–40
Ответы
200Text so far
answerstringText so far; null — no answer (off, AI not available, too many requests)donebooleanreasonstring
Short AI answer above search results
post/search/ai/answer
One or two sentences about the products found for the query (ADR-195): what fits best, the price range or the key difference — only from the product cards; a sentence with a number the cards do not have is dropped. Off when the AI search mode is off or the project turned the answer off ({answer: null}). A cached answer comes at once; otherwise 202 with id — the text is written in the background and read with GET /search/ai/answer as it grows. Charged to the project balance by tokens; limited per visitor.
Used by the search widget of the tracker; not part of the SDKs.
Тело запросаобязательно
qstringобязательнодлина:
≤ 200productsstring[]обязательноIds of the products found, in the order of the resultsэлементов:
≤ 6languagestringдлина:
≤ 35anonymousIdstringдлина:
≤ 255
Пример тела запроса
{
"q": "string",
"products": [
"string"
],
"language": "string",
"anonymousId": "string"
}Ответы
200The answer or `{answer: null}`
answerstringText so far; null — no answer (off, AI not available, too many requests)donebooleanreasonstring
202The model is writing the answer
pendingbooleanidstring
Search suggestions while typing
get/search/suggest
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.
widget=1 is used by the search layer of the tracker: the answer also has brands and pages (website pages of the knowledge base), and an empty q returns trending queries and products for the visitor (anonymousId; personal recommendations, popular products without history; without the recommendations feature of the plan or computed recommendations — popular catalog products in stock).
Параметры
qв строке запросаstringдлина:
≤ 100limitв строке запросаintegerProducts in the suggestion.по умолчанию:
6· диапазон:1–10image_widthв строке запросаintegerпо умолчанию:
480· диапазон:64–1200languageв строке запросаstringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).длина:
≤ 35widgetв строке запросаbooleanAnswer for the search layer of the tracker: brands, website pages, and for an empty query trending queries and products for the visitor.по умолчанию:
falseanonymousIdв строке запросаstringVisitor of the tracker: products for an empty query with widget=1.длина:
≤ 255
Ответы
200Suggestions
productsProductCard[]Все поля ProductCard:
availableboolean
categoriesobject[]idstringnamestring
queriesstring[]redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.brandsobject[]With widget=1: brands of products in stock starting with the query.namestring
pagesobject[]With widget=1: website pages of the knowledge base matching the query (3 characters or more).titlestringurlstring (uri)
correctedstring | nullThe corrected query when products were found only for it.
- 401Missing, invalid or revoked key · Error
402Product search is not in the plan (feature_unavailable) or the monthly search requests are used up beyond the 10% margin (quota_exceeded): fall back to the website's own search.
messagestringcodestringзначения:
"feature_unavailable", "quota_exceeded"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Website search layer settings
get/search/widget
input[data-cdp-search], the results, category and add-to-cart addresses ({query}, {id}), the blocks to show, the look and texts in the visitor language, and the empty field (blank): the store's own queries and banner in the visitor language. A store whose search page shows <div data-cdp-search-results data-cart-url="…"> instead of its own results checks enabled first.Параметры
languageв строке запросаstringдлина:
≤ 35
Ответы
200Settings; enabled: false when the search layer is off — then also ai and the texts of the AI block when AI search is on (the AI block above the results of the store's own search)
enabledbooleanselectorstring | nullresults_urlstring | nullResults page with {query}; null — the form of the search field.category_urlstring | nullCategory page with {id}; null — categories are not shown.cart_urlstring | nullAdd-to-cart address with {id} — the catalog product id; the “Add to cart” button of the results widget sends POST to it (quantity, form_key from the cookie if present) and expects JSON: {"ok": true} or {"redirect": "…"} for a product that needs options. null — no button unless the page container sets data-cart-url.sectionsobjecthistorybooleantrendingbooleanproductsbooleancategoriesbooleanbrandsbooleanpagesboolean
textsobjectaccentstringAccent color, #rrggbb.radiusintegercolumnsintegerColumns of the results grid; 0 — by the width.ratiostringзначения:
"square", "portrait"voicebooleanaiobject | nullAI search mode of the project (null — off): when the results widget asks POST /search/ai, shows "Ask AI" and the short answermodestringзначения:
"auto", "toggle", "always"answerboolean
blankobjectEmpty search field in the visitor language (the project language closest to it, otherwise the default one): own queries shown first among trending ones (even with the trending block off) and a banner above the products.queriesstring[]элементов:
≤ 8bannerobject | nullimagestringhttps image address.urlstring | nullWebsite address or path; null — the banner is not a link.altstring
Analytics
Run an event report
post/analytics/reports
definition and the result — the same as the analytics pages.Тело запросаобязательно
seriesobject[]обязательноэлементов:
1–5eventstring | nullmetricstringзначения:
"count", "profiles", "per_profile", "sum", "avg"propertystring | nullfiltersPropertyFilter[]
profilesProfileRulesbreakdownBreakdownintervalAnalyticsIntervalperiodAnalyticsPeriodcompareboolean
Пример тела запроса
{
"series": [
{
"event": "string",
"metric": "count",
"property": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
}
],
"profiles": {},
"breakdown": {
"source": "property",
"key": "string",
"limit": 10
},
"interval": "day",
"period": {
"last": 7
},
"compare": true
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
bucketsstring (date)[]обязательноseriesobject[]обязательноPer series: index, total, values per bucket, previous period, breakdown
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a funnel
post/analytics/funnels
definition and the result — the same as the analytics pages.Тело запросаобязательно
stepsobject[]обязательноэлементов:
2–10eventstringобязательноfiltersPropertyFilter[]
windowobjectConversion window from the first step, up to 90 daysamountintegerдиапазон:
≥ 1unitstringзначения:
"minute", "hour", "day"
orderstringзначения:
"sequential", "strict"profilesProfileRulesbreakdownBreakdownperiodAnalyticsPeriod
Пример тела запроса
{
"steps": [
{
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
}
],
"window": {
"amount": 1,
"unit": "minute"
},
"order": "sequential",
"profiles": {},
"breakdown": {
"source": "property",
"key": "string",
"limit": 10
},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
stepsobject[]обязательноPer step: event, reached, from_start, from_previous, median_seconds, avg_secondsbreakdownobject[]обязательноPer breakdown value: value, steps (reached per step)time_samplenumberShare of profiles used for time between steps
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a retention report
post/analytics/retention
definition and the result — the same as the analytics pages.Тело запросаобязательно
startobjectобязательноeventstring | nullfiltersPropertyFilter[]
returnobjecteventstring | nullfiltersPropertyFilter[]
cohortstringзначения:
"first", "period"intervalAnalyticsIntervalperiodsintegerUp to 30 days, 12 weeks or 12 monthsдиапазон:
1–30returnsstringзначения:
"exact", "rolling"profilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"start": {
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
},
"return": {
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
},
"cohort": "first",
"interval": "day",
"periods": 1,
"returns": "exact",
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
cohortsobject[]обязательноPer cohort: date, size, values (returned per period, null — not yet), open (period still running)averageobject[]обязательноPer period: period, rate, profiles
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a paths report
post/analytics/paths
definition and the result — the same as the analytics pages.Тело запросаобязательно
eventstringобязательноfiltersPropertyFilter[]directionstringзначения:
"after", "before"stepsintegerдиапазон:
1–5gap_minutesintegerдиапазон:
1–1440excludestring[]элементов:
≤ 20profilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
],
"direction": "after",
"steps": 1,
"gap_minutes": 1,
"exclude": [
"string"
],
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
totalintegerобязательноnodesobject[]обязательноlinksobject[]обязательноpathsobject[]обязательноMost frequent paths: events, profilestruncatedboolean
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a revenue report
post/analytics/revenue
definition and the result — the same as the analytics pages.Тело запросаобязательно
eventstringPurchase event; by default from the prediction settingsamountstringNumeric order amount propertyproduct_propertystringintervalAnalyticsIntervalltv_intervalstringзначения:
"week", "month"ltv_periodsintegerдиапазон:
1–12profilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"event": "string",
"amount": "string",
"product_property": "string",
"interval": "day",
"ltv_interval": "week",
"ltv_periods": 1,
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullother_currency_ordersintegersummaryobjectобязательноseriesobjectобязательноltvobjectобязательноproductsobject[]обязательноcategoriesobject[]обязательно
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a traffic sources report
post/analytics/traffic
definition and the result — the same as the analytics pages.Тело запросаобязательно
dimensionstringзначения:
"channel", "source", "source_medium", "campaign", "referrer", "landing"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"dimension": "channel",
"interval": "day",
"event": "string",
"amount": "string",
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullpurchasesbooleansummaryobjectобязательноrowsobject[]обязательноrow_countintegerchartobjectобязательно
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a revenue attribution report
post/analytics/attribution
definition and the result — the same as the analytics pages.Тело запросаобязательно
window_daysintegerзначения:
1, 3, 7, 14, 30modelstringзначения:
"last", "first", "linear"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"window_days": 1,
"model": "last",
"interval": "day",
"event": "string",
"amount": "string",
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullsummaryobjectобязательноchannelsobject[]обязательноPer channel: channel, clicks, touched_orders, revenue and orders by modelitemsobject[]обязательноPer campaign, journey, message channel or widgetchartobject
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a ROPO report (research online, purchase offline)
post/analytics/ropo
/stores) preceded by an online touch of the same customer within the window: website visits by traffic channel, product views, message clicks; customers with and without online touches, touch sources, stores, products viewed online and bought in store, days to purchase and reverse ROPO (online orders after an in-store purchase). Small projects are calculated right away (results cached for 5 minutes). A project with more than 5 million events in the period plus the window is calculated in the queue: the response is 202 with pending: true and Retry-After — repeat the same request. Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.Тело запросаобязательно
window_daysintegerOnline touches no earlier than this many days before the in-store check (default 30)значения:
1, 3, 7, 14, 30, 60, 90touchesstring[]Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)intervalAnalyticsIntervaleventstringPurchase event (default — from the project settings)amountstringNumeric amount property of the purchase eventproduct_propertystringProduct id property in products[] lines (default — from the recommendation settings)profilesProfileRulesperiodAnalyticsPeriod
Пример тела запроса
{
"window_days": 1,
"touches": [
"visit"
],
"interval": "day",
"event": "string",
"amount": "string",
"product_property": "string",
"profiles": {},
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, ropo_revenue, other_offline_revenue, showroom_revenue
202The report is being calculated in the queue: repeat the request after Retry-After seconds
definitionobjectобязательноNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, ropo_revenue, other_offline_revenue, showroom_revenue
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
- 503The queued calculation failed; the next request starts it again
Run an AI assistants report
post/analytics/assistants
utm_medium=ai_assistant), purchases (orders tagged with the assistant by the store module, or a purchase within 30 days after the last visit from an assistant), frequent search queries and popular products. Results are 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 — the same as the analytics pages.Тело запросаобязательно
intervalAnalyticsIntervaleventstringPurchase event; defaults to the purchase event of the project settings. Without it the report has no purchasesamountstringNumeric property with the order amountperiodAnalyticsPeriod
Пример тела запроса
{
"interval": "day",
"event": "string",
"amount": "string",
"period": {
"last": 7
}
}Ответы
200OK
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullpurchasesbooleanattribution_daysintegersummaryobjectобязательноcurrentandpreviousperiod: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenueassistantsobject[]обязательноchartobjectобязательноbucketsand per assistantrequestsandvisitsby bucketqueriesobject[]обязательноquerystringcountintegeremptyintegerSearches without results
productsobject[]обязательноidstringnamestring | nullrequestsintegerclicksinteger
- 401Missing, invalid or revoked key · Error
- 402AI assistants are not in the plan of the project (code feature_unavailable, feature ai_shopping)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
List saved reports
get/analytics/saved-reports
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
Save a report
post/analytics/saved-reports
definition.* paths.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120definitionobjectобязательноDefinition of the report type — see the run operationsviewobject
Пример тела запроса
{
"name": "string",
"type": "report",
"definition": {},
"view": {}
}Ответы
201Created
Все поля SavedReport:
definitionobjectобязательноviewobjectобязательноPage view settings: chart type, metric
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a saved report
get/analytics/saved-reports/{report}
Параметры
reportв путиintegerобязательно
Ответы
200OK
Все поля SavedReport:
definitionobjectобязательноviewobjectобязательноPage view settings: chart type, metric
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a saved report
patch/analytics/saved-reports/{report}
Параметры
reportв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120definitionobjectviewobject
Пример тела запроса
{
"name": "string",
"definition": {},
"view": {}
}Ответы
200OK
Все поля SavedReport:
definitionobjectобязательноviewobjectобязательноPage view settings: chart type, metric
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a saved report
delete/analytics/saved-reports/{report}
Параметры
reportв путиintegerобязательно
Ответы
Run a saved report
post/analytics/saved-reports/{report}/result
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 — the same as the analytics pages.Параметры
reportв путиintegerобязательно
Тело запросаобязательно
periodAnalyticsPeriod
Пример тела запроса
{
"period": {
"last": 7
}
}Ответы
200OK
Объект с произвольными ключами.
- 202A ROPO report of a large project is being calculated in the queue (`pending: true`): repeat the request after Retry-After seconds
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
- 503The queued calculation failed; the next request starts it again
List dashboards
get/analytics/dashboards
Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
Create a dashboard
post/analytics/dashboards
Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
namestringобязательнодлина:
≤ 120layoutobject[]элементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Пример тела запроса
{
"name": "string",
"layout": [
{
"report_id": 0,
"size": "half"
}
],
"period": {
"last": 7
},
"main": true
}Ответы
201Created
idintegerобязательноnamestringобязательноlayoutobject[]обязательноэлементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
mainbooleanобязательноThe main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.created_atstring (date-time)обязательноupdated_atstring (date-time)обязательно
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a dashboard
get/analytics/dashboards/{dashboard}
Параметры
dashboardв путиintegerобязательно
Ответы
200OK
idintegerобязательноnamestringобязательноlayoutobject[]обязательноэлементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
mainbooleanобязательноThe main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.created_atstring (date-time)обязательноupdated_atstring (date-time)обязательно
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a dashboard
patch/analytics/dashboards/{dashboard}
layout replaces the whole layout.Параметры
dashboardв путиintegerобязательно
Тело запросаобязательно
namestringдлина:
≤ 120layoutobject[]элементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Пример тела запроса
{
"name": "string",
"layout": [
{
"report_id": 0,
"size": "half"
}
],
"period": {
"last": 7
},
"main": true
}Ответы
200OK
idintegerобязательноnamestringобязательноlayoutobject[]обязательноэлементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
mainbooleanобязательноThe main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.created_atstring (date-time)обязательноupdated_atstring (date-time)обязательно
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a dashboard
delete/analytics/dashboards/{dashboard}
Параметры
dashboardв путиintegerобязательно
Ответы
List periods of the global control group
get/control-group/periods
ended_at: null. The control group is turned on, resized and turned off only in the project settings, not through the API.Параметры
limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
200OK
next_cursorstring | nullобязательноPass ascursorto get the next page; null on the last page.
- 401Missing, invalid or revoked key · Error
- 402The control group is not in the plan of the project (code feature_unavailable, feature control_group)
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Effect of communications by the control group period
get/control-group/periods/{period}/report
Параметры
periodв путиintegerобязательно
Ответы
200OK
periodControlGroupPerioduntilstring (date-time)End of the calculation: the end of the period or the next full hour for the active onecurrencystring | nulleventstringPurchase event from the revenue settings of the projectgroupsobjectcontrol— profiles of the control group,target— everyone elsecontrolControlGroupSidetargetControlGroupSide
conversionAbStatsrevenue_per_profileobject | nullWelch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a groupcontrolnumberMean revenue per profile of the control grouptreatmentnumberMean revenue per profile of everyone elsedifferencenumbercinumber[]95 % interval of the differenceэлементов:
2–2liftnumber | nullp_valuenumbersignificantboolean
incrementalobjectEffect of the communications: (target per profile − control per profile) × target profilesrevenuenumberrevenue_cinumber[] | nullэлементов:
2–2ordersintegerbuyersinteger
other_currency_ordersintegerOrders in another currency, not countedheld_messagesintegerMarketing messages not sent to the control group in the periodseriesobjectCumulative incremental revenue by day (by week for periods longer than 120 days)intervalstringзначения:
"day", "week"bucketsstring (date)[]incremental_revenuenumber[]controlnumber[]Cumulative revenue per profiletargetnumber[]
exemptobjectCampaigns and journeys of the period with «send to the control group too»: the effect is understatedcampaignsobject[]idintegernamestring
journeysobject[]idintegernamestring
- 401Missing, invalid or revoked key · Error
- 402The control group is not in the plan of the project (code feature_unavailable, feature control_group)
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422The project has no purchase event in the revenue settings (code no_purchase_event)
- 429Rate limit or monthly event quota exceeded · Error
Loyalty
Calculate points for a cart
post/loyalty/calculate
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 — they depend on the order).Тело запросаобязательно
amountnumberобязательноCart amount in the project currencyдиапазон:
≥ 0
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
},
"amount": 0
}Ответы
200OK
memberbooleanbalanceintegertierstring | nullmax_pointsintegermax_discountnumberearn_pointsintegerpoint_valuenumbercurrencystring | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Loyalty account of a profile
get/loyalty/profiles/{type}/{value}
member: false.Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Ответы
200OK
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Point history of a profile
get/loyalty/profiles/{type}/{value}/transactions
earn, cancel, expire, adjust, redeem (a hold or a redemption), refund (points returned). Cursor pages.Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
Join the program
post/loyalty/members
enrollment: explicit). Returns 200 if the profile is already a member.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
}
}Ответы
201Created
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Apply a friend's referral code
post/loyalty/referrals
code: referrals off, unknown code, own code, existing customer.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
codestringобязательнодлина:
≤ 16
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
},
"code": "string"
}Ответы
200Counted before
statusstringpending— waiting for the friend's first order.значения:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe friend has received the reward.expires_atstring (date-time)The first order of the friend rewards the member until this moment.
201Counted
statusstringpending— waiting for the friend's first order.значения:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe friend has received the reward.expires_atstring (date-time)The first order of the friend rewards the member until this moment.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Hold points for a cart
post/loyalty/redemptions
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.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
pointsintegerобязательнодиапазон:
≥ 1cart_idstringобязательнодлина:
≤ 255amountnumberдиапазон:
≥ 0
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
},
"points": 1,
"cart_id": "string",
"amount": 0
}Ответы
201Created
idstringstatusstringзначения:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_untilstring (date-time)confirmed_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Confirm a redemption
post/loyalty/redemptions/{redemption}/confirm
order_refunded, order_cancelled) return the points proportionally. Repeating with the same order changes nothing; an expired or cancelled hold — 422.Параметры
redemptionв путиstringобязательноRedemption id from the hold response.Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
order_idstringобязательнодлина:
≤ 255
Пример тела запроса
{
"order_id": "string"
}Ответы
200OK
idstringstatusstringзначения:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_untilstring (date-time)confirmed_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Cancel a redemption
post/loyalty/redemptions/{redemption}/cancel
Параметры
redemptionв путиstringобязательноRedemption id from the hold response.
Ответы
200OK
idstringstatusstringзначения:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_untilstring (date-time)confirmed_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Adjust points manually
post/loyalty/adjustments
Idempotency-Key to make retries safe.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
pointsintegerобязательноPositive — add, negative — take offreasonstringобязательнодлина:
≤ 500
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
},
"points": 0,
"reason": "string"
}Ответы
200OK
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Promo
List promo code pools
get/promo/pools
Ответы
200OK
dataPromoPool[]
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Get a pool
get/promo/pools/{key}
Параметры
keyв путиstringобязательноPool key — the name used in templates:{{ promo_code('summer') }}.шаблон:
^[a-z0-9_]{1,64}$
Ответы
200OK
keystringобязательноnamestringобязательноtypestringобязательноshared— one code for everyone;unique— a separate code for every profile.значения:
"shared", "unique"statusstringобязательнозначения:
"active", "paused"activebooleanобязательноActive now: not paused and within the promotion period.discountstring | nullDiscount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.starts_atstring (date-time) | nullends_atstring (date-time) | nullEnd of the promotion (exclusive).validity_daysinteger | nullA code is valid for this many days after it is issued (not longer than the promotion).per_profileintegerобязательноHow many codes of the pool one profile can receive.statsobjectобязательноtotalintegeravailableintegerissuedintegerusedintegerusesintegerrevenuenumberSum of the orders with codes of the pool.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Codes of a pool (sync)
get/promo/pools/{key}/codes
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.Параметры
keyв путиstringобязательноPool key — the name used in templates:{{ promo_code('summer') }}.шаблон:
^[a-z0-9_]{1,64}$sinceв строке запросаstringCursor from the previous response.limitв строке запросаintegerпо умолчанию:
500· диапазон:1–1000
Ответы
200OK
dataPromoCode[]nextstring | nullCursor for the next call.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Add codes to a pool
post/promo/pools/{key}/codes
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.Параметры
keyв путиstringобязательноPool key — the name used in templates:{{ promo_code('summer') }}.шаблон:
^[a-z0-9_]{1,64}$Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
countintegerдиапазон:
1–50000codesstring[]элементов:
≤ 100000
Пример тела запроса
{
"count": 1,
"codes": [
"string"
]
}Ответы
201Created
addedintegerskippedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Issue a code to a profile
post/promo/pools/{key}/issue
$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).Параметры
keyв путиstringобязательноPool key — the name used in templates:{{ promo_code('summer') }}.шаблон:
^[a-z0-9_]{1,64}$Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
Пример тела запроса
{
"profile": {
"type": "user_id",
"value": "string"
}
}Ответы
200Already issued
poolstringPool key.codestringобязательноstatusstringобязательнозначения:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_atstring (date-time) | null
201Issued
poolstringPool key.codestringобязательноstatusstringобязательнозначения:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
409Not issued
messagestringreasonstringзначения:
"inactive", "limit", "exhausted"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Check a code
get/promo/codes/{code}
Параметры
codeв путиstringобязательноPromo code, case-insensitive.длина:
≤ 64
Ответы
200OK
Все поля PromoCode:
activebooleanIssued (or shared), not used, not expired, the pool is active.usesinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Codes of a profile
get/promo/profiles/{type}/{value}/codes
Параметры
typeв путиstringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valueв путиstringобязательноNormalized like at ingestion (lower-case email, E.164 phone).
Ответы
200OK
dataPromoCode[]Все поля PromoCode:
activeboolean
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Messages
Send one message now
post/messages
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 — poll GET /messages/cascades/{cascade}; the per-recipient limit counts a cascade once; without the cascades plan feature the answer is 402.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
- The recipient. A profile with this identity is created if there is none.
traitsobjectTraits written to the profile before sending, available in the template astraits.*.ключей:
≤ 100template_idintegerMessage 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_idinteger | nullChannel integration of the template's channel; may be omitted when the channel has exactly one active integration.dataobjectPer-message data, available in the template ascontext.data.*(order number, confirmation code).stepsCascadeStep[]Cascade (plans with thecascadesfeature): channels tried in order — 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.элементов:
2–5
Пример тела запроса
{
"identity": {
"type": "user_id",
"value": "string"
},
"traits": {},
"template_id": 0,
"integration_id": 0,
"data": {},
"steps": [
{
"integration_id": 0,
"template_id": 0,
"wait_for": "sent",
"timeout": {
"amount": 1,
"unit": "minute"
}
}
]
}Ответы
202Queued: a message, or a cascade when `steps` are given
Один из вариантов:
- 401Missing, invalid or revoked key · Error
- 402The request cannot be applied in the current state · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Send a store email
post/emails
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.Параметры
Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
tostring (email)обязательноRecipient address. The profile is found by this email or created.длина:
≤ 254subjectstringRequired unless an order template is enabled forkindandorderis given.длина:
≤ 998htmlstringReady HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled forkindandorderis given.длина:
≤ 1000000textstring | nullPlain-text part; built from the HTML when empty.длина:
≤ 1000000reply_tostring (email) | nullOverrides the Reply-To of the email integration.from_namestring | nullOverrides the sender name of the email integration; the sender address is always the integration's.длина:
≤ 100kindstringобязательно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… 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. Fororder_placed,order_paid,order_shipped,order_delivered,order_cancelled,order_refundedwithorder, an enabled OneTrace template builds the email instead ofhtml(seeGET /emails/settings).шаблон:
^[a-z0-9_]{1,40}$languagestring | nullCustomer language tag: picks the language version of an order template; for history and reports otherwise.длина:
≤ 20integration_idinteger | nullEmail integration; may be omitted when the project has exactly one active.traitsobject | nullProfile traits to update before sending (name, phone).attachmentsobject[]Up to 5 files, 5 MB in total.элементов:
≤ 5namestringобязательнодлина:
≤ 200typestringобязательнозначения:
"application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"contentstring (byte)обязательноFile contents in base64.
orderStoreOrder
Пример тела запроса
{
"to": "string",
"subject": "string",
"html": "string",
"text": "string",
"reply_to": "string",
"from_name": "string",
"kind": "string",
"language": "string",
"integration_id": 0,
"traits": {},
"attachments": [
{
"name": "string",
"type": "application/pdf",
"content": "string"
}
],
"order": {
"order_id": "string",
"number": "string",
"url": "https://example.com",
"created_at": "2026-01-01T10:00:00Z",
"currency": "string",
"amount": 0,
"subtotal": 0,
"discount": 0,
"shipping": 0,
"tax": 0,
"refund_amount": 0,
"coupon": "string",
"payment_method": "string",
"shipping_method": "string",
"carrier": "string",
"tracking_number": "string",
"tracking_url": "https://example.com",
"estimated_delivery": "2026-01-01",
"reason": "string",
"note": "string",
"payment_instructions": "string",
"products": [
{
"product_id": "string",
"variant_id": "string",
"sku": "string",
"product_name": "string",
"quantity": 0,
"price": 0,
"total": 0,
"image_url": "https://example.com",
"url": "https://example.com",
"options": "string"
}
],
"shipping_address": {
"name": "string",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"region": "string",
"postcode": "string",
"country": "string",
"phone": "string"
},
"billing_address": {
"name": "string",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"region": "string",
"postcode": "string",
"country": "string",
"phone": "string"
}
}
}Ответы
202Queued
Все поля MessageStatus:
kindstring | nulltemplatebooleanThe email is built from a OneTrace order template.
- 401Missing, invalid or revoked key · Error
- 402The request cannot be applied in the current state · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Store email settings
get/emails/settings
Ответы
200Settings
relaybooleanSend all store emails through OneTrace (store emails section).integration_idinteger | nulltemplatesobjectOrder email kinds built from OneTrace templates: the store does not send its own email for them and passesorderinstead.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
Get the state of a cascade
get/messages/cascades/{cascade}
POST /messages and the messages of its steps.Параметры
cascadeв путиstring (uuid)обязательноCascadeid(UUID) from the send response.
Ответы
200OK
idstring (uuid)statusstringreached— a step succeeded;failed— no channel reached the profile.значения:
"running", "reached", "failed"stepintegerCurrent step, from 0.reached_channelstring | nullprofile_idintegeroriginstring | nullcreated_atstring (date-time) | nullfinished_atstring (date-time) | nullmessagesMessageStatus[]Messages of the steps tried so far.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Get the status of a message
get/messages/{message}
POST /messages (or any message of the project by its id).Параметры
messageв путиstring (uuid)обязательноMessageid(UUID) from the send response.
Ответы
200OK
idstring (uuid)statusstringqueued→sent→delivered;scheduled— waiting (quiet hours, warm-up);skipped— not sent, seereason;failed/bounced— seereasonanderror.значения:
"queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"reasonstring | nullWhy 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…errorstring | nullchannelstringtemplate_idinteger | nullintegration_idinteger | nullprofile_idintegertransactionalbooleanoriginstring | nullapifor messages sent withmessages.send,storefor store emails (emails.send).created_atstring (date-time) | nullscheduled_forstring (date-time) | nullsent_atstring (date-time) | nulldelivered_atstring (date-time) | nullopened_atstring (date-time) | nullclicked_atstring (date-time) | nullfailed_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Conversations
List chat conversations
get/conversations
Параметры
statusв строке запросаstringopen— waiting for an answer.значения:
"open", "waiting", "closed"channelв строке запросаstringзначения:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"profile_typeв строке запросаstringIdentity type of the customer; together withprofile_value.значения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"profile_valueв строке запросаstringIdentity value of the customer; together withprofile_type.длина:
≤ 255limitв строке запросаintegerпо умолчанию:
50· диапазон:1–200cursorв строке запросаstring
Ответы
200OK
next_cursorstring | nullобязательноPass ascursorto get the next page; null on the last page.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a conversation with messages
get/conversations/{conversation}
Параметры
conversationв путиstring (uuid)обязательноConversationid(UUID).limitв строке запросаintegerHow many latest messages to return.по умолчанию:
100· диапазон:1–500
Ответы
200OK
Все поля Conversation:
- The latest messages, oldest first.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Answer in a conversation
post/conversations/{conversation}/messages
Параметры
conversationв путиstring (uuid)обязательноConversationid(UUID).Idempotency-KeyзаголовокstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.длина:
≤ 255
Тело запросаобязательно
bodystringPlain text of the answer. Optional when products are given (stage 97).длина:
1–4000buttonsstring[]Quick reply buttons (stage 97): the website widget, Telegram and Viber show buttons, WhatsApp up to three buttons of up to 20 characters, other channels a numbered list; a press arrives as the customer message with the label. Need body.элементов:
≤ 10productsstring[]Catalog product ids for product cards (stage 97): a card with the image, name, price and link; in messengers — a separate message.элементов:
≤ 4
Пример тела запроса
{
"body": "string",
"buttons": [
"string"
],
"products": [
"string"
]
}Ответы
201Created
idintegerобязательноauthorstringобязательноvisitor— the customer;operator— an answer from the inbox or the API;system— assignment, closing and reopening (seeaction).значения:
"visitor", "operator", "system"viastring | nullWhere an answer or action came from: the operator inbox or the API.значения:
"inbox", "api", nullapi_keystring | nullName of the API key that answered or closed the conversation.bodystringобязательноMessage text; empty for system messages except notesactionstring | nullAction of a system message; note — an internal note for operators (body is its text), never shown to the customerзначения:
"assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", nullproduct_idstring | nullProduct the customer asked about with this message, id in the catalogstatusstring | nullDelivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.created_atstring (date-time)обязательноimagesobject[]Customer images (stage 85, ADR-179). url is an absolute signed link valid for about 24 hours, only for status ready. pending — an image from a messenger is still being downloaded; failed — it could not be downloaded or is not a JPEG, PNG or WebP picture; expired — deleted after the storage period.idstring (uuid)statusstringзначения:
"ready", "pending", "failed", "expired"urlstring (uri) | nullwidthinteger | nullheightinteger | null
filesobject[]Documents of the message (stage 97); url is valid for 24 hours, the file is downloaded as an attachment. A customer document is firstpending(downloading from the messenger) orchecking(stored, checked for active content and by the antivirus in the background) without url, thenreadyorfailed; themessage.createdwebhook carries the first state.idstringstatusstringзначения:
"pending", "checking", "ready", "failed", "expired"namestringmimestring | nullsizeinteger | nullurlstring | null
buttonsstring[]Quick reply buttons of the reply (stage 97)productsobject[]Product cards of the reply (stage 97)idstringnamestringurlstring | nullpricenumber | nullcurrencystring | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Close a conversation
post/conversations/{conversation}/close
Параметры
conversationв путиstring (uuid)обязательноConversationid(UUID).
Ответы
200OK
idstring (uuid)обязательноprofile_idintegerобязательноchannelstringобязательноweb— the website chat; messengers need thechat_messengersplan feature.значения:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"statusstringобязательноopen— the customer wrote last and waits for an answer;waiting— answered, waiting for the customer;closed.значения:
"open", "waiting", "closed"assignedbooleanобязательноAn operator is responsible for the conversation.unread_countintegerобязательноCustomer messages operators have not read yet.languagestring | nullproduct_idstring | nullLast product the customer asked about from the site (product question widget or a product page), id in the catalogtagsstring[]Tag names from the project tag dictionary, set by operators (stage 97)ratinginteger | nullCustomer rating after the conversation.диапазон:
1–5rating_commentstring | nulllast_message_atstring (date-time) | nulllast_message_authorstring | nullзначения:
"visitor", "operator", "system", nullfirst_reply_atstring (date-time) | nullcreated_atstring (date-time)обязательноclosed_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Connect the store MCP server to the AI bot
put/chat/store-mcp
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.Тело запросаобязательно
urlstring (uri)обязательноHTTPS address of the store MCP serverдлина:
≤ 2048keystringобязательноBearer key the platform sends to the storeдлина:
32–500namestringдлина:
≤ 120platformstringзначения:
"woocommerce", "magento", "bitrix", "sdk", "custom"
Пример тела запроса
{
"url": "https://example.com",
"key": "string",
"name": "string",
"platform": "woocommerce"
}Ответы
200Updated
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this serverзначения:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_atstring (date-time) | null
201Connected
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this serverзначения:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_atstring (date-time) | null
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Disconnect the store MCP server
delete/chat/store-mcp
Тело запросаобязательно
urlstringобязательнодлина:
≤ 2048
Пример тела запроса
{
"url": "string"
}Ответы
- 204Disconnected
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
Forms
Submit a website form
post/forms/{uid}/submissions
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.
Used by the website forms of the tracker; not part of the SDKs.
Параметры
uidв путиstringобязательноFormuidfrom the site code.длина:
≤ 16
Тело запросаобязательно
anonymousIdstringобязательнодлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128valuesobjectобязательноForm fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).languagestringдлина:
≤ 35pagestringдлина:
≤ 2000websitestringHidden trap field: must stay empty.variantstringA/B variant of the form the visitor saw.значения:
"a", "b", "c", "d"playstringGame forms with the play-first order (stage 81): theplaytoken fromPOST /forms/{uid}/plays. The submission claims that draw; without it the server draws the prize now.длина:
≤ 32
Пример тела запроса
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"values": {},
"language": "string",
"page": "string",
"website": "string",
"variant": "a",
"play": "string"
}Ответы
201Accepted
statusstringобязательноpending— waiting for the confirmation link;accepted— applied to the profile.значения:
"pending", "accepted"messagestringобязательноText for the visitor in their language.promo_codestring | nullPromo code of the form (or of the game prize) when the submission is accepted at once.prizeobject | nullGame forms (stage 81): the prize of the draw.index— the wheel sector or scratch card prize in the order ofgame.prizesof the form config;null— no prize could be drawn.keystring | nullindexinteger | nullkindstringзначения:
"promo", "text", "none"labelstringtextstring
playedbooleanGame forms: this contact or visitor has already played this form, so there is no second prize.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Play a game form
post/forms/{uid}/plays
A visitor spins the wheel or scratches the card of a game form with the play-first order (stage 81, ADR-175). The server draws the prize by the probabilities of the form; the promo code is not revealed — the visitor claims the prize with a submission that carries the play token. One draw per form for a visitor: a repeat returns the same result.
Used by the website forms of the tracker; not part of the SDKs.
Параметры
uidв путиstringобязательноFormuidfrom the site code.длина:
≤ 16
Тело запросаобязательно
anonymousIdstringобязательнодлина:
≤ 255userIdstringдлина:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128languagestringдлина:
≤ 35
Пример тела запроса
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"language": "string"
}Ответы
201Drawn
playstring | nullToken for the submission;nullwhen this draw has already been claimed.prizeobject | nullобязательноGame forms (stage 81): the prize of the draw.index— the wheel sector or scratch card prize in the order ofgame.prizesof the form config;null— no prize could be drawn.keystring | nullindexinteger | nullkindstringзначения:
"promo", "text", "none"labelstringtextstring
playedbooleanобязательноThe draw has already been claimed by a submission of this visitor.
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Active website forms
get/forms
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.
Used by the website forms of the tracker; not part of the SDKs.
Параметры
languageв строке запросаstringVisitor language (BCP 47).длина:
≤ 35anonymousIdв строке запросаstringVisitor id: forms shown to segment members are filtered by the visitor's profile.длина:
≤ 255
Ответы
200OK
formsobject[]обязательноuidstringkindstringзначения:
"popup", "flyout", "embedded", "bar"double_opt_inbooleansettingsobjectrulesobjecttextsobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Схемы
Error
messagestringобязательно
ValidationError
messagestringобязательноerrorsobjectобязательно
IdentityRef
typestringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"valuestringобязательнодлина:
≤ 255
IdentitiesInput
элементов:
1–1000
Message
typestringзначения:
"track", "identify", "page", "screen", "alias"messageIdstringдлина:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.длина:
≤ 128previousIdstring | integereventstringдлина:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.элементов:
≤ 20channelstringобязательношаблон:
^[a-z0-9_]{1,64}$· пример:"email"topicstringSubscription topic; the whole channel if omitted.шаблон:
^[a-z0-9_-]{1,64}$statusstringобязательнозначения:
"subscribed", "unsubscribed"
timestampstring (date-time)
Profile
idintegertraitsobjectidentitiesobjectfirst_seen_atstring (date-time)last_seen_atstring (date-time)
Event
event_idstringtypestringnamestringpropertiesobjectcontextobjectoccurred_atstring (date-time)
CatalogEvent
namestringlabelstring | nullvolumeintegerfirst_seen_atstring (date-time) | nulllast_seen_atstring (date-time) | nullpropertiesobject[]keystringdata_typestring
CatalogTrait
keystringlabelstring | nulldata_typestringpiibooleansystemboolean
Segment
idintegernamestringdescriptionstring | nulltypestringзначения:
"dynamic", "static"realtimebooleanschedule_minutesinteger | nullstatusstringзначения:
"pending", "computing", "ready", "failed"sizeintegerlast_computed_atstring (date-time) | nullcreated_atstring (date-time)updated_atstring (date-time)
SegmentDetail
Все поля Segment:
rulesobject | nullRule tree: {"op": "and|or", "children": [...]}
SegmentInput
namestringобязательнодлина:
≤ 120descriptionstring | nulltypestringобязательнозначения:
"dynamic", "static"realtimebooleanschedule_minutesintegerзначения:
15, 30, 60, 180, 360, 720, 1440rulesobject
SegmentPatch
namestringдлина:
≤ 120descriptionstring | nullrealtimebooleanschedule_minutesintegerrulesobject
Journey
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
JourneyDetail
Все поля Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
JourneyInput
namestringобязательнодлина:
≤ 120descriptionstring | nullgraphobjectnodesarrayэлементов:
≤ 200edgesarrayэлементов:
≤ 400
entryobject
JourneyPatch
namestringдлина:
≤ 120descriptionstring | nullgraphobjectentryobject
Enrollment
idintegerprofile_idintegerversion_idintegerstatusstringcurrent_node_idstring | nullexit_reasonstring | nullentered_atstring (date-time)finished_atstring (date-time) | nullgoal_reached_atstring (date-time) | null
EnrollResult
enrolledbooleanenrollment_idinteger | nullprofile_idinteger
CampaignAudience
segment_idsinteger[]обязательноMembers of any of these segments get the campaign.элементов:
≤ 10exclude_segment_idsinteger[]Members of these segments are excluded.элементов:
≤ 10ignore_control_groupbooleanSend to the global control group too (ADR-167). By default profiles of the control group get no marketing messages.
CampaignVariant
keystringобязательношаблон:
^[a-z0-9_]{1,32}$template_idinteger | nullMessage template of the campaign channel.percentintegerобязательноShare of the audience (or of the A/B test share); all variants add up to 100.диапазон:
1–100
CampaignAb
mode: test (default) — test_percent of the audience is split between variants, after wait the rest gets the winner by metric (test_percent and wait required). mode: auto — recurring campaigns only, tariff feature auto_optimize: each run splits the audience by shares learned from previous runs by metric (ADR-171); test_percent and wait are ignored.modestringзначения:
"test", "auto"· по умолчанию:"test"test_percentintegerдиапазон:
5–50metricstringобязательнозначения:
"opened", "clicked", "goal"waitobjectamountintegerдиапазон:
1–72unitstringзначения:
"hour", "day"
CampaignSchedule
local_time — in each recipient's timezone trait; with best_time — at each recipient's best hour within 24 hours of the start.typestringобязательнозначения:
"now", "at", "recurring"atstringForat: Y-m-d\TH:i.пример:
"2026-11-01T10:00"repeatstringзначения:
"daily", "weekly", "monthly"timestringпример:
"10:00"weekdaysinteger[]ISO weekdays forweekly(1 = Monday).day_of_monthintegerдиапазон:
1–28start_datestring (date) | nullend_datestring (date) | nulllocal_timebooleanbest_timebooleanSend to each recipient at theirbest_send_hourtrait (predictions) within 24 hours of the start; without it — at the project best hour, otherwise right away. Requires predictions in the plan; not combined withlocal_time.
CampaignGoal
eventstringобязательноwithinobjectобязательноamountintegerдиапазон:
1–90unitstringзначения:
"hour", "day"
Campaign
idintegernamestringdescriptionstring | nullstatusstringзначения:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
CampaignInput
namestringобязательнодлина:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.элементов:
1–5rate_per_minuteinteger | nullдиапазон:
10–100000goalCampaignGoal
CampaignVariantStats
queuedintegersentintegerdeliveredintegeropenedintegerclickedintegerbouncedintegerfailedintegerskippedintegerunsubscribedintegerconvertedinteger | nullRecipients with the goal event in the window; null without a goal.
CampaignRun
idintegerstatusstringзначения:
"preparing", "sending", "testing", "completed", "paused", "cancelled", "failed"scheduled_atstring (date-time)started_atstring (date-time) | nullfinished_atstring (date-time) | nullaudience_sizeintegerRecipients without the control group.held_outintegerRecipients in the global control group: no message was sent to them.controlobject | nullRecipients of the run in the control group: no message,$message_skippedwith reasoncontrol_groupat the time the message would have been sent; goal conversion within the same window. null — no control group in the run.profilesintegerconvertedinteger | nullnull — the campaign has no goalstatsAbStatsGoal conversion: armcontrolagainst armcampaign(sent messages)
queuedintegerwinnerstring | nullwinner_atstring (date-time) | nullerrorstring | nullauto_pausedobject | nullSet while the run is paused automatically: the complaint or bounce rate of the run exceeded the limit. After resuming, the rates are counted again from the messages queued after the resume. null — the run was not paused automatically.atstring (date-time)sentintegercomplaint_ratenumberPercentbounce_ratenumberPercentexceededstring[]limitsobjectcomplaint_ratenumberbounce_ratenumber
variantsobjecttotalCampaignVariantStatsmetricstringзначения:
"opened", "clicked", "goal"statsAbStatsab_resultobject | nullTest result saved when the A/B winner was picked.metricstringdecided_atstring (date-time)statsAbStats
languagesobjectResults per language of the sent template version.
AbStats
verdictstringзначения:
"winner", "no_difference", "insufficient_data"winnerstring | nullSet only when the best variant is significantly better than every other one.beststringrequired_per_arminteger | nullalphanumberarmsobject[]keystringtrialsintegersuccessesintegerratenumbercinumber[]Wilson 95 % intervalэлементов:
2–2liftnumber | nullRelative to the first variantp_valuenumber | nullHolm-adjusted p-value against the best variantprobability_bestnumber
ProductCard
idstringnamestringurlstring | nullimagestring | nullJPEG up to image_width via imgproxy; without imgproxy — a direct link (CDN copy or feed URL).image_originalstring | nullDirect link: the platform CDN copy if the feed mirrors images, otherwise the feed URL.srcsetobject | nullVariants for: AVIF and WebP srcset (240–960 px); null without imgproxy. avifstringwebpstring
pricenumber | nullold_pricenumber | nullcurrencystring | nullbrandstring | nullcategory_idstring | nullmin_quantityinteger | nullThe product is sold as a set (tires by 4): how many to add to the cart; null — one.ratingnumber | nullAverage score of published reviews;nullwithout reviews.reviews_countintegerNumber of published reviews.
ProductInput
idstringобязательноProduct id on the site: product_id in events.длина:
≤ 128namestringобязательнодлина:
≤ 500urlstring (uri)imagestring (uri)pricenumberдиапазон:
≥ 0old_pricenumberдиапазон:
≥ 0currencystringдлина:
3–3availablebooleanпо умолчанию:
truestockintegerUnits 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.диапазон:
≥ 0category_idsstring[]Leaf category first.элементов:
≤ 10brandstringдлина:
≤ 200descriptionstringProduct description, plain text or HTML (ADR-132). HTML is turned into text and the result is cut to 5000 characters; the AI answers shoppers' questions about the product from it.длина:
≤ 65535paramsobjecttranslationsobjectTranslations by language (BCP 47 tag → 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.ключей:
≤ 20
MessageTemplate
idintegernamestringchannelstringпример:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.длина:
≤ 16· пример:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_atstring (date-time) | null
MessageTemplateInput
namestringобязательнодлина:
≤ 120channel_keystringобязательноChannel of the template; cannot be changed later.topicstringпо умолчанию:
"marketing"· длина:≤ 64· шаблон:^[a-z0-9_-]+$transactionalbooleanпо умолчанию:
falselanguagestringMain language ofcontent; the project default language if omitted.длина:
≤ 16· пример:"de"contentobjectобязательноFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.ключей:
≤ 50
AnalyticsReportType
string
значения: "report", "funnel", "retention", "paths", "revenue", "traffic", "attribution", "ropo", "assistants"
AnalyticsPeriod
Один из вариантов:
lastintegerобязательноLast N days including today, in the project timezoneзначения:
7, 14, 30, 90, 180, 365
fromstring (date)обязательноtostring (date)обязательно
Dates in the project timezone, up to 731 days
PropertyFilter
keystringобязательноProperty key from the event catalogoperatorstringобязательноOperator of the property type, as in segment rulesvalueanyValue for the operator; absent for is_set / is_not_set
ProfileRules
Объект с произвольными ключами.
Breakdown
sourcestringобязательнозначения:
"property", "context"keystringобязательноEvent property, or a page field: page.path, page.referrer, campaign.source, campaign.medium, campaign.name, localelimitintegerEvent reports only: how many values are shown separately, the rest go to $other. Funnels always show 10.значения:
5, 10· по умолчанию:10
AnalyticsInterval
string
значения: "day", "week", "month"
ReportQuery
seriesobject[]обязательноэлементов:
1–5eventstring | nullmetricstringзначения:
"count", "profiles", "per_profile", "sum", "avg"propertystring | nullfiltersPropertyFilter[]
profilesProfileRulesbreakdownBreakdownintervalAnalyticsIntervalperiodAnalyticsPeriodcompareboolean
FunnelQuery
stepsobject[]обязательноэлементов:
2–10eventstringобязательноfiltersPropertyFilter[]
windowobjectConversion window from the first step, up to 90 daysamountintegerдиапазон:
≥ 1unitstringзначения:
"minute", "hour", "day"
orderstringзначения:
"sequential", "strict"profilesProfileRulesbreakdownBreakdownperiodAnalyticsPeriod
RetentionQuery
startobjectобязательноeventstring | nullfiltersPropertyFilter[]
returnobjecteventstring | nullfiltersPropertyFilter[]
cohortstringзначения:
"first", "period"intervalAnalyticsIntervalperiodsintegerUp to 30 days, 12 weeks or 12 monthsдиапазон:
1–30returnsstringзначения:
"exact", "rolling"profilesProfileRulesperiodAnalyticsPeriod
PathQuery
eventstringобязательноfiltersPropertyFilter[]directionstringзначения:
"after", "before"stepsintegerдиапазон:
1–5gap_minutesintegerдиапазон:
1–1440excludestring[]элементов:
≤ 20profilesProfileRulesperiodAnalyticsPeriod
RevenueQuery
eventstringPurchase event; by default from the prediction settingsamountstringNumeric order amount propertyproduct_propertystringintervalAnalyticsIntervalltv_intervalstringзначения:
"week", "month"ltv_periodsintegerдиапазон:
1–12profilesProfileRulesperiodAnalyticsPeriod
TrafficQuery
dimensionstringзначения:
"channel", "source", "source_medium", "campaign", "referrer", "landing"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
AttributionQuery
window_daysintegerзначения:
1, 3, 7, 14, 30modelstringзначения:
"last", "first", "linear"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
ReportResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
bucketsstring (date)[]обязательноseriesobject[]обязательноPer series: index, total, values per bucket, previous period, breakdown
FunnelResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
stepsobject[]обязательноPer step: event, reached, from_start, from_previous, median_seconds, avg_secondsbreakdownobject[]обязательноPer breakdown value: value, steps (reached per step)time_samplenumberShare of profiles used for time between steps
RetentionResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
cohortsobject[]обязательноPer cohort: date, size, values (returned per period, null — not yet), open (period still running)averageobject[]обязательноPer period: period, rate, profiles
PathResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
totalintegerобязательноnodesobject[]обязательноlinksobject[]обязательноpathsobject[]обязательноMost frequent paths: events, profilestruncatedboolean
RevenueResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullother_currency_ordersintegersummaryobjectобязательноseriesobjectобязательноltvobjectобязательноproductsobject[]обязательноcategoriesobject[]обязательно
TrafficResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullpurchasesbooleansummaryobjectобязательноrowsobject[]обязательноrow_countintegerchartobjectобязательно
AttributionResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullsummaryobjectобязательноchannelsobject[]обязательноPer channel: channel, clicks, touched_orders, revenue and orders by modelitemsobject[]обязательноPer campaign, journey, message channel or widgetchartobject
SavedReport
idintegerобязательноnamestringобязательноcreated_atstring (date-time)обязательноupdated_atstring (date-time)обязательно
SavedReportDetail
Все поля SavedReport:
definitionobjectобязательноviewobjectобязательноPage view settings: chart type, metric
SavedReportInput
namestringобязательнодлина:
≤ 120definitionobjectобязательноDefinition of the report type — see the run operationsviewobject
SavedReportPatch
namestringдлина:
≤ 120definitionobjectviewobject
Dashboard
idintegerобязательноnamestringобязательноlayoutobject[]обязательноэлементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
mainbooleanобязательноThe main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.created_atstring (date-time)обязательноupdated_atstring (date-time)обязательно
DashboardInput
namestringобязательнодлина:
≤ 120layoutobject[]элементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
DashboardPatch
namestringдлина:
≤ 120layoutobject[]элементов:
≤ 24report_idintegerобязательноsizestringзначения:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
LoyaltyProfileRef
typestringобязательнозначения:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"valuestringобязательно
LoyaltyAccount
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
LoyaltyCalculation
memberbooleanbalanceintegertierstring | nullmax_pointsintegermax_discountnumberearn_pointsintegerpoint_valuenumbercurrencystring | null
LoyaltyRedemption
idstringstatusstringзначения:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_untilstring (date-time)confirmed_atstring (date-time) | null
LoyaltyTransaction
idintegertypestringзначения:
"earn", "cancel", "expire", "adjust", "redeem", "refund"pointsintegerreferencestring | nullreasonstring | nullrulestring | nullcreated_atstring (date-time)referralstring | nullReferral reward:friend— for joining by invitation,referrer— for the first order of a friend.значения:
"friend", "referrer", null
PromoPool
keystringобязательноnamestringобязательноtypestringобязательноshared— one code for everyone;unique— a separate code for every profile.значения:
"shared", "unique"statusstringобязательнозначения:
"active", "paused"activebooleanобязательноActive now: not paused and within the promotion period.discountstring | nullDiscount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.starts_atstring (date-time) | nullends_atstring (date-time) | nullEnd of the promotion (exclusive).validity_daysinteger | nullA code is valid for this many days after it is issued (not longer than the promotion).per_profileintegerобязательноHow many codes of the pool one profile can receive.statsobjectобязательноtotalintegeravailableintegerissuedintegerusedintegerusesintegerrevenuenumberSum of the orders with codes of the pool.
PromoCode
poolstringPool key.codestringобязательноstatusstringобязательнозначения:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_atstring (date-time) | null
LoyaltyReferral
statusstringpending— waiting for the friend's first order.значения:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe friend has received the reward.expires_atstring (date-time)The first order of the friend rewards the member until this moment.
MessageSendInput
template_id (and integration_id if needed) for one message, or steps for a cascade — not both.- The recipient. A profile with this identity is created if there is none.
traitsobjectTraits written to the profile before sending, available in the template astraits.*.ключей:
≤ 100template_idintegerMessage 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_idinteger | nullChannel integration of the template's channel; may be omitted when the channel has exactly one active integration.dataobjectPer-message data, available in the template ascontext.data.*(order number, confirmation code).stepsCascadeStep[]Cascade (plans with thecascadesfeature): channels tried in order — 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.элементов:
2–5
MessageStatus
idstring (uuid)statusstringqueued→sent→delivered;scheduled— waiting (quiet hours, warm-up);skipped— not sent, seereason;failed/bounced— seereasonanderror.значения:
"queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"reasonstring | nullWhy 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…errorstring | nullchannelstringtemplate_idinteger | nullintegration_idinteger | nullprofile_idintegertransactionalbooleanoriginstring | nullapifor messages sent withmessages.send,storefor store emails (emails.send).created_atstring (date-time) | nullscheduled_forstring (date-time) | nullsent_atstring (date-time) | nulldelivered_atstring (date-time) | nullopened_atstring (date-time) | nullclicked_atstring (date-time) | nullfailed_atstring (date-time) | null
CascadeStep
integration_idintegerобязательноtemplate_idintegerобязательноTemplate of the integration's channel.wait_forstringWhat counts as success.deliveredneeds an integration that reports delivery (not email through own SMTP),opened— a channel that reports reading (email, WhatsApp, Viber).значения:
"sent", "delivered", "opened"· по умолчанию:"sent"timeoutobjectHow long to wait fordeliveredoropenedafter sending; 15 minutes by default.amountintegerдиапазон:
1–3650unitstringзначения:
"minute", "hour", "day", "week"
CascadeStatus
idstring (uuid)statusstringreached— a step succeeded;failed— no channel reached the profile.значения:
"running", "reached", "failed"stepintegerCurrent step, from 0.reached_channelstring | nullprofile_idintegeroriginstring | nullcreated_atstring (date-time) | nullfinished_atstring (date-time) | nullmessagesMessageStatus[]Messages of the steps tried so far.
ChatVisitorMessage
idintegerauthorstringзначения:
"visitor", "operator", "system"bodystringoperatorstring | nullFirst name of the operatoractionstring | nullclosed — the conversation was closedcreated_atstring (date-time)botbooleanReply of the AI bot; operator holds the bot nameimagesobject[]Images of the message (stage 85). url is a signed path valid for about 24 hours: prepend the platform host. Without url: status expired (deleted after the storage period, 180 days by default).urlstring | nullwidthinteger | nullheightinteger | nullstatusstringзначения:
"ready", "pending", "failed", "expired"
filesobject[]Documents of the message (stage 97); url is a signed path valid for about 24 hours: prepend the platform host. The file is downloaded as an attachment. A document of the visitor is firstchecking(no url) and thenreadyorfailed; the change comes as the realtime eventmessage.updatedwith the whole message.namestringsizeinteger | nullurlstring | nullstatusstringзначения:
"pending", "checking", "ready", "failed", "expired"errorstring | nullWhy afaileddocument was not accepted:unsafe(macros, scripts, embedded objects or external links),infected(the antivirus found a threat),scan(the antivirus stayed unavailable),type,quota,download
buttonsstring[]Quick reply buttons of an operator message (stage 97): a press sends the label as the visitor messageproductsobject[]Catalog product cards of an operator message (stage 97)idstringnamestringurlstring | nullimagestring | nullpricenumber | nullcurrencystring | nullavailableboolean
ChatVisitorConversation
idstring (uuid)statusstringзначения:
"open", "waiting", "closed"ratinginteger | nulltokenstringReturned for a new conversation or when the request had no valid token; store itbotbooleanThe AI bot leads the conversation: the widget offers to call an operator (POST /chat/handoff)queueinteger | nullPlace in the operators' queue (1 — next) while the conversation waits for an operator with automatic routing; null otherwise
Conversation
idstring (uuid)обязательноprofile_idintegerобязательноchannelstringобязательноweb— the website chat; messengers need thechat_messengersplan feature.значения:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"statusstringобязательноopen— the customer wrote last and waits for an answer;waiting— answered, waiting for the customer;closed.значения:
"open", "waiting", "closed"assignedbooleanобязательноAn operator is responsible for the conversation.unread_countintegerобязательноCustomer messages operators have not read yet.languagestring | nullproduct_idstring | nullLast product the customer asked about from the site (product question widget or a product page), id in the catalogtagsstring[]Tag names from the project tag dictionary, set by operators (stage 97)ratinginteger | nullCustomer rating after the conversation.диапазон:
1–5rating_commentstring | nulllast_message_atstring (date-time) | nulllast_message_authorstring | nullзначения:
"visitor", "operator", "system", nullfirst_reply_atstring (date-time) | nullcreated_atstring (date-time)обязательноclosed_atstring (date-time) | null
ConversationMessage
idintegerобязательноauthorstringобязательноvisitor— the customer;operator— an answer from the inbox or the API;system— assignment, closing and reopening (seeaction).значения:
"visitor", "operator", "system"viastring | nullWhere an answer or action came from: the operator inbox or the API.значения:
"inbox", "api", nullapi_keystring | nullName of the API key that answered or closed the conversation.bodystringобязательноMessage text; empty for system messages except notesactionstring | nullAction of a system message; note — an internal note for operators (body is its text), never shown to the customerзначения:
"assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", nullproduct_idstring | nullProduct the customer asked about with this message, id in the catalogstatusstring | nullDelivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.created_atstring (date-time)обязательноimagesobject[]Customer images (stage 85, ADR-179). url is an absolute signed link valid for about 24 hours, only for status ready. pending — an image from a messenger is still being downloaded; failed — it could not be downloaded or is not a JPEG, PNG or WebP picture; expired — deleted after the storage period.idstring (uuid)statusstringзначения:
"ready", "pending", "failed", "expired"urlstring (uri) | nullwidthinteger | nullheightinteger | null
filesobject[]Documents of the message (stage 97); url is valid for 24 hours, the file is downloaded as an attachment. A customer document is firstpending(downloading from the messenger) orchecking(stored, checked for active content and by the antivirus in the background) without url, thenreadyorfailed; themessage.createdwebhook carries the first state.idstringstatusstringзначения:
"pending", "checking", "ready", "failed", "expired"namestringmimestring | nullsizeinteger | nullurlstring | null
buttonsstring[]Quick reply buttons of the reply (stage 97)productsobject[]Product cards of the reply (stage 97)idstringnamestringurlstring | nullpricenumber | nullcurrencystring | null
ConversationDetail
Все поля Conversation:
- The latest messages, oldest first.
StoreEmailInput
tostring (email)обязательноRecipient address. The profile is found by this email or created.длина:
≤ 254subjectstringRequired unless an order template is enabled forkindandorderis given.длина:
≤ 998htmlstringReady HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled forkindandorderis given.длина:
≤ 1000000textstring | nullPlain-text part; built from the HTML when empty.длина:
≤ 1000000reply_tostring (email) | nullOverrides the Reply-To of the email integration.from_namestring | nullOverrides the sender name of the email integration; the sender address is always the integration's.длина:
≤ 100kindstringобязательно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… 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. Fororder_placed,order_paid,order_shipped,order_delivered,order_cancelled,order_refundedwithorder, an enabled OneTrace template builds the email instead ofhtml(seeGET /emails/settings).шаблон:
^[a-z0-9_]{1,40}$languagestring | nullCustomer language tag: picks the language version of an order template; for history and reports otherwise.длина:
≤ 20integration_idinteger | nullEmail integration; may be omitted when the project has exactly one active.traitsobject | nullProfile traits to update before sending (name, phone).attachmentsobject[]Up to 5 files, 5 MB in total.элементов:
≤ 5namestringобязательнодлина:
≤ 200typestringобязательнозначения:
"application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"contentstring (byte)обязательноFile contents in base64.
orderStoreOrder
StoreEmailStatus
Все поля MessageStatus:
kindstring | nulltemplatebooleanThe email is built from a OneTrace order template.
StoreOrder
order template variable.order_idstringобязательнодлина:
≤ 100numberstring | nullNumber shown to the customer;order_idwhen empty.длина:
≤ 100urlstring (uri) | nullOrder page for the customer.created_atstring (date-time) | nullcurrencystringобязательношаблон:
^[A-Za-z]{3}$amountnumberобязательноOrder total.subtotalnumber | nulldiscountnumber | nullshippingnumber | nulltaxnumber | nullrefund_amountnumber | nullcouponstring | nullpayment_methodstring | nullshipping_methodstring | nullcarrierstring | nulltracking_numberstring | nulltracking_urlstring (uri) | nullestimated_deliverystring (date) | nullreasonstring | nullCancellation or refund reason.notestring | nullpayment_instructionsstring | nullBank transfer details and similar instructions.productsobject[]элементов:
≤ 100product_idstring | nullvariant_idstring | nullskustring | nullproduct_namestringобязательнодлина:
≤ 300quantitynumberобязательноpricenumberобязательноtotalnumber | nullLine total; price × quantity when empty.image_urlstring (uri) | nullurlstring (uri) | nulloptionsstring | nullVariant options as text: «Size: M, colour: white».длина:
≤ 500
shipping_addressobject | nullnamestring | nullдлина:
≤ 200companystring | nullдлина:
≤ 200address1string | nullдлина:
≤ 200address2string | nullдлина:
≤ 200citystring | nullдлина:
≤ 200regionstring | nullдлина:
≤ 200postcodestring | nullдлина:
≤ 200countrystring | nullдлина:
≤ 200phonestring | nullдлина:
≤ 200
billing_addressobject | nullnamestring | nullдлина:
≤ 200companystring | nullдлина:
≤ 200address1string | nullдлина:
≤ 200address2string | nullдлина:
≤ 200citystring | nullдлина:
≤ 200regionstring | nullдлина:
≤ 200postcodestring | nullдлина:
≤ 200countrystring | nullдлина:
≤ 200phonestring | nullдлина:
≤ 200
StoreEmailSettings
relaybooleanSend all store emails through OneTrace (store emails section).integration_idinteger | nulltemplatesobjectOrder email kinds built from OneTrace templates: the store does not send its own email for them and passesorderinstead.
StoreMcpServer
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this serverзначения:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_atstring (date-time) | null
ProfilePreferences
profile_idintegerlanguagestringLanguage of topic names.пример:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringпример:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.пример:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringпример:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.значения:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing messages are paused until this time.preferences_urlstring (uri)Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.preferences_url_expires_atstring (date-time)
Store
idstringобязательноStore id — the value ofstore_idin offline checks.длина:
≤ 128namestringобязательнодлина:
≤ 200citystring | nullдлина:
≤ 120addressstring | nullдлина:
≤ 300
RopoQuery
window_daysintegerOnline touches no earlier than this many days before the in-store check (default 30)значения:
1, 3, 7, 14, 30, 60, 90touchesstring[]Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)intervalAnalyticsIntervaleventstringPurchase event (default — from the project settings)amountstringNumeric amount property of the purchase eventproduct_propertystringProduct id property in products[] lines (default — from the recommendation settings)profilesProfileRulesperiodAnalyticsPeriod
RopoResult
definitionobjectобязательноNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, ropo_revenue, other_offline_revenue, showroom_revenue
ControlGroupPeriod
idintegerpercentintegerShare of profiles in the control group, %диапазон:
1–50started_atstring (date-time)ended_atstring (date-time) | nullnull for the active period
ControlGroupSide
profilesintegerbuyersintegerordersintegerrevenuenumberconversionnumber | nullBuyers / profilesrevenue_per_profilenumber | nullaovnumber | nullAverage order value
ControlGroupReport
periodControlGroupPerioduntilstring (date-time)End of the calculation: the end of the period or the next full hour for the active onecurrencystring | nulleventstringPurchase event from the revenue settings of the projectgroupsobjectcontrol— profiles of the control group,target— everyone elsecontrolControlGroupSidetargetControlGroupSide
conversionAbStatsrevenue_per_profileobject | nullWelch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a groupcontrolnumberMean revenue per profile of the control grouptreatmentnumberMean revenue per profile of everyone elsedifferencenumbercinumber[]95 % interval of the differenceэлементов:
2–2liftnumber | nullp_valuenumbersignificantboolean
incrementalobjectEffect of the communications: (target per profile − control per profile) × target profilesrevenuenumberrevenue_cinumber[] | nullэлементов:
2–2ordersintegerbuyersinteger
other_currency_ordersintegerOrders in another currency, not countedheld_messagesintegerMarketing messages not sent to the control group in the periodseriesobjectCumulative incremental revenue by day (by week for periods longer than 120 days)intervalstringзначения:
"day", "week"bucketsstring (date)[]incremental_revenuenumber[]controlnumber[]Cumulative revenue per profiletargetnumber[]
exemptobjectCampaigns and journeys of the period with «send to the control group too»: the effect is understatedcampaignsobject[]idintegernamestring
journeysobject[]idintegernamestring
LaunchReadiness
readybooleanобязательноNo errors: the launch will pass.clearbooleanобязательноNo errors and no warnings.checksobject[]обязательноkeystringобязательноconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringобязательнозначения:
"error", "warning", "info"messagestringобязательноText in the language of the requestpathstringField of a config error, e.g.variants.0.template_id
EventSchema
enabledbooleanCheck incoming events against the schemaeventsobject[]элементов:
≤ 1000namestringобязательноEvent name (system$…events are not allowed)длина:
≤ 255labelstring | nullдлина:
≤ 255descriptionstring | nullдлина:
≤ 1000propertiesobject[]элементов:
≤ 200keystringобязательнодлина:
≤ 255typestringобязательнозначения:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleanпо умолчанию:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)элементов:
≤ 100Один из вариантов:
descriptionstring | nullдлина:
≤ 1000
EventSchemaViolation
kindstringзначения:
"unplanned_event", "unplanned_property", "missing_property", "wrong_type", "unexpected_value"eventstringpropertystring | nullcountintegerlast_atstring (date-time)examplestring | null
Approval
requiredbooleanThe project requires approval before launch.statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.значения:
"pending", "approved", "returned"approved_bystringapproved_atstring (date-time)changedbooleanApproved, but changed since approval: launch will send it back to review.historyobject[]actionstringзначения:
"requested", "approved", "returned", "changed"commentstringuserstringvia_apibooleanatstring (date-time)
AssistantsQuery
intervalAnalyticsIntervaleventstringPurchase event; defaults to the purchase event of the project settings. Without it the report has no purchasesamountstringNumeric property with the order amountperiodAnalyticsPeriod
AssistantsResult
definitionobjectобязательноNormalized definitionperiodobjectобязательноfromstring (date)tostring (date)
currencystring | nullpurchasesbooleanattribution_daysintegersummaryobjectобязательноcurrentandpreviousperiod: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenueassistantsobject[]обязательноchartobjectобязательноbucketsand per assistantrequestsandvisitsby bucketqueriesobject[]обязательноquerystringcountintegeremptyintegerSearches without results
productsobject[]обязательноidstringnamestring | nullrequestsintegerclicksinteger