Справочник API

Приём событий, профили, сегменты, цепочки и рассылки — спецификация OpenAPI 3.1.

Общие сведения

Описания методов и полей — на английском, как в спецификации.

Public API v1: event ingestion (write keys) and project management (secret keys with permissions). Errors are {"message": "..."}; validation errors add errors by field path. Lists use cursor pagination (limit 1-200, cursor from next_cursor). POST requests accept an Idempotency-Key header: a repeat with the same key and body returns the stored response for 24 hours. Rate limits: 6000 requests/min per write key, 1200 requests/min per secret key (429). Error messages follow Accept-Language (en, ru, de, es, fr, it, pt, tr, uz, zh), otherwise the platform default language.

Базовый адрес: https://cdp.onetrace.pro/api/v1

Ключи

writeKeyhttp bearer
cdp_wk_…: ingestion only. Also accepted as Basic auth user or writeKey body field.
secretKeyhttp bearer
cdp_sk_…: server-side only, permissions chosen when the key is created.

Ingest

Track an event

post/track

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

typestring
значения: "track", "identify", "page", "alias"
messageIdstring
длина: ≤ 100
anonymousIdstring | integer
userIdstring | integer
previousIdstring | integer
eventstring
длина: ≤ 200
namestring
propertiesobject
traitsobject
contextobject
consentsobject[]
identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.
элементов: ≤ 20
- channelstringобязательно
  шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"
- topicstring
  Subscription 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",
  "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
- acceptedinteger
- duplicatesinteger
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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

typestring
значения: "track", "identify", "page", "alias"
messageIdstring
длина: ≤ 100
anonymousIdstring | integer
userIdstring | integer
previousIdstring | integer
eventstring
длина: ≤ 200
namestring
propertiesobject
traitsobject
contextobject
consentsobject[]
identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.
элементов: ≤ 20
- channelstringобязательно
  шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"
- topicstring
  Subscription 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",
  "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
- acceptedinteger
- duplicatesinteger
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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

typestring
значения: "track", "identify", "page", "alias"
messageIdstring
длина: ≤ 100
anonymousIdstring | integer
userIdstring | integer
previousIdstring | integer
eventstring
длина: ≤ 200
namestring
propertiesobject
traitsobject
contextobject
consentsobject[]
identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.
элементов: ≤ 20
- channelstringобязательно
  шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"
- topicstring
  Subscription 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",
  "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
- acceptedinteger
- duplicatesinteger
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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

typestring
значения: "track", "identify", "page", "alias"
messageIdstring
длина: ≤ 100
anonymousIdstring | integer
userIdstring | integer
previousIdstring | integer
eventstring
длина: ≤ 200
namestring
propertiesobject
traitsobject
contextobject
consentsobject[]
identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.
элементов: ≤ 20
- channelstringобязательно
  шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"
- topicstring
  Subscription 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",
  "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
- acceptedinteger
- duplicatesinteger
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

Ключ: writeKey или secretKey

Тело запросаобязательно

batchMessage[]обязательно
элементов: ≤ 500

Пример тела запроса

{
  "batch": [
    {
      "type": "track",
      "messageId": "string",
      "anonymousId": "string",
      "userId": "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
- acceptedinteger
- duplicatesinteger
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

Key type, project and permissions. Accepts any active key (write or secret); use it for a "Test connection" button.

Ключ: writeKey или secretKey

Ответы

200OK
- typestringобязательно
  значения: "write", "secret"
- namestringобязательно
- projectobjectобязательно
  - uidstring
  - namestring
  - timezonestring
- 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

Push

VAPID public key for PushManager.subscribe()

get/push/config

Ключ: writeKey или secretKey

Ответы

200Public key of the project's Web Push integration
- public_keystringобязательно
  base64url, 65-byte uncompressed P-256 point
401Missing, invalid or revoked key · Error
404Not found in the key's project · Error
429Rate limit or monthly event quota exceeded · Error

Store a browser push subscription and link it to the visitor

post/push/subscriptions

Ключ: writeKey или secretKey

Тело запросаобязательно

anonymousIdstring
Required without userId
длина: ≤ 255
userIdstring
длина: ≤ 255
publicKeystring
VAPID key the subscription was created with
subscriptionobjectобязательно
PushSubscription.toJSON(); the endpoint must belong to a browser push service
- endpointstring (uri)обязательно
- expirationTimeinteger | null
- keysobjectобязательно
  - p256dhstringобязательно
  - authstringобязательно

Пример тела запроса

{
  "anonymousId": "string",
  "userId": "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

Ключ: writeKey или secretKey

Тело запросаобязательно

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

Recommendations

Product recommendations for the site

get/recommendations

Write key (tracker). Personal and recently viewed recommendations use the profile of 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).

Ключ: writeKey или secretKey

Параметры

typeв строке запросаstringобязательно
значения: "personal", "popular", "trending", "viewed_with", "bought_with", "similar", "recently_viewed", "replenish"
limitв строке запросаinteger
по умолчанию: 8 · диапазон: 1–24
itemв строке запросаstring
Context product id (or item[] for a cart) for viewed_with, bought_with, similar.
categoryв строке запросаstring
Category id for popular and trending.
exclude[]в строке запросаstring[]
anonymousIdв строке запросаstring
image_widthв строке запросаinteger
Card image width (image), px. Variants for are in srcset when imgproxy is configured (ADR-047).
по умолчанию: 480 · диапазон: 64–1200
languageв строке запросаstring
Visitor 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
- typestring
- request_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}

Write key (tracker renders

, ADR-048). Returns the widget settings and its products in one request; a paused widget returns no items. Personal recommendations use the profile of anonymousId only.

Ключ: writeKey или secretKey

Параметры

uidв путиstringобязательно
шаблон: ^[a-z0-9]{1,16}$
item[]в строке запросаstring[]
Context product ids (data-item): page product or cart items.
categoryв строке запросаstring
Category id (data-category); overrides the widget category.
exclude[]в строке запросаstring[]
anonymousIdв строке запросаstring
languageв строке запросаstring
Visitor language (BCP 47, as in context.locale): the heading, the button and product names come in their translation for the closest language (ADR-078, ADR-080).
длина: ≤ 35

Ответы

200Widget and products
- widgetobject
  - uidstring
  - typestring
  - statusstring
    значения: "active", "paused"
  - settingsobject
    titlestring
    layoutstring
    значения: "grid", "carousel"
    columnsinteger
    accentstring | null
    radiusinteger
    buttonstring
    showPriceboolean
- request_idstring | null
- itemsProductCard[]
401Invalid key
403Request origin is not one of the key website domains
404Widget not found in the project

Profiles

Get a profile by any identifier

get/profiles/{type}/{value}

Traits and identifiers are masked unless the key has profiles.pii.

Ключ: secretKey · Права: profiles.read

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

200OK
Profile
- idinteger
- traitsobject
- identitiesobject
- first_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}

Ключ: secretKey · Права: profiles.delete

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

204Erased
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

Profile events, newest first, 50 per page

get/profiles/{type}/{value}/events

Ключ: secretKey · Права: profiles.read

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).
beforeв строке запросаstring (date-time)
Cursor: next_before of the previous page.
nameв строке запросаstring

Ответы

200OK
- dataEvent[]
- next_beforestring (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

Subscribe or unsubscribe a profile

put/profiles/{type}/{value}/consents

Ключ: secretKey · Права: profiles.write

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).

Тело запросаобязательно

channelstringобязательно
пример: "email"
topicstring
Omit 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

Ключ: secretKey · Права: profiles.write

Тело запросаобязательно

identityIdentityRefобязательно
integrationstring
Integration uid when the project has several bots.

Пример тела запроса

{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "integration": "string"
}

Ответы

200OK
- urlstring
- tokenstring
- integrationstring
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

Ключ: secretKey · Права: profiles.write

Тело запросаобязательно

identityIdentityRefобязательно
integrationstring
Integration uid when the project has several Viber bots.

Пример тела запроса

{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "integration": "string"
}

Ответы

200OK
- urlstring
- tokenstring
- integrationstring
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

Products

Create or update products and categories

post/products

Ключ: secretKey · Права: products.write

Тело запросаобязательно

itemsProductInput[]обязательно
элементов: ≤ 1000
categoriesobject[]
элементов: ≤ 1000
- idstringобязательно
- namestringобязательно
- parent_idstring | null
- translationsobject
  Category 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",
      "params": {},
      "translations": {}
    }
  ],
  "categories": [
    {
      "id": "string",
      "name": "string",
      "parent_id": "string",
      "translations": {}
    }
  ]
}

Ответы

200Saved
- savedinteger
- categoriesinteger
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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

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

Ключ: secretKey · Права: events.read

Ответы

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

Ключ: secretKey · Права: events.read

Ответы

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

Segments

List segments

get/segments

Ключ: secretKey · Права: segments.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataSegment[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Create a segment

post/segments

Dynamic segments are computed asynchronously; poll status. Rules use the same DSL as the segment builder (docs/architecture/segmentation.md).

Ключ: secretKey · Права: segments.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

SegmentInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
typestringобязательно
значения: "dynamic", "static"
realtimeboolean
schedule_minutesinteger
значения: 15, 30, 60, 180, 360, 720, 1440
rulesobject

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "type": "dynamic",
  "realtime": true,
  "schedule_minutes": 15,
  "rules": {}
}

Ответы

201Created
SegmentDetail
Все поля Segment:
- rulesobject | null
  Rule tree: {"op": "and|or", "children": [...]}
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}

Ключ: secretKey · Права: segments.read

Параметры

segmentв путиintegerобязательно

Ответы

200OK
SegmentDetail
Все поля Segment:
- rulesobject | null
  Rule tree: {"op": "and|or", "children": [...]}
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 segment (partial)

patch/segments/{segment}

Changing rules of a dynamic segment queues a recomputation.

Ключ: secretKey · Права: segments.write

Параметры

segmentв путиintegerобязательно

Тело запросаобязательно

SegmentPatch

namestring
длина: ≤ 120
descriptionstring | null
realtimeboolean
schedule_minutesinteger
rulesobject

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "realtime": true,
  "schedule_minutes": 0,
  "rules": {}
}

Ответы

200OK
SegmentDetail
Все поля Segment:
- rulesobject | null
  Rule tree: {"op": "and|or", "children": [...]}
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}

Fails with 422 while other segments reference it.

Ключ: secretKey · Права: segments.write

Параметры

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

Ключ: secretKey · Права: segments.write

Параметры

segmentв путиintegerобязательно

Ответы

202Queued
- queuedboolean
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
422The request cannot be applied in the current state · Error
429Rate limit or monthly event quota exceeded · Error

Segment members, latest entered first

get/segments/{segment}/members

Ключ: secretKey · Права: segments.read

Параметры

segmentв путиintegerобязательно
limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataobject[]обязательно
  - profile_idinteger
  - entered_atstring (date-time)
- next_cursorstring | nullобязательно
  Pass as cursor to 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

Ключ: secretKey · Права: segments.write

Параметры

segmentв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

IdentitiesInput

identitiesIdentityRef[]обязательно
элементов: 1–1000

Пример тела запроса

{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Ответы

200OK
- addedinteger
- unknownIdentityRef[]
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

Ключ: secretKey · Права: segments.write

Параметры

segmentв путиintegerобязательно

Тело запросаобязательно

IdentitiesInput

identitiesIdentityRef[]обязательно
элементов: 1–1000

Пример тела запроса

{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Ответы

200OK
- removedinteger
- unknownIdentityRef[]
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}

Ключ: secretKey · Права: segments.read

Параметры

segmentв путиintegerобязательно
typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

200OK
- profile_idinteger
- memberboolean
- entered_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

Journeys

List journeys

get/journeys

Ключ: secretKey · Права: journeys.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring
statusв строке запросаstring
значения: "draft", "active", "paused", "archived"

Ответы

200OK
- dataJourney[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Create a journey draft

post/journeys

The draft may be incomplete; it is validated on publish. Graph and entry use the editor format (docs/architecture/journeys.md).

Ключ: secretKey · Права: journeys.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

JourneyInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
graphobject
- nodesarray
  элементов: ≤ 200
- edgesarray
  элементов: ≤ 400
entryobject

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "graph": {
    "nodes": [],
    "edges": []
  },
  "entry": {}
}

Ответы

201Created
JourneyDetail
Все поля Journey:
- draftobject
  - graphobject
  - entryobject
- publishedobject | null
  - graphobject
  - entryobject
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}

Ключ: secretKey · Права: journeys.read

Параметры

journeyв путиintegerобязательно

Ответы

200OK
JourneyDetail
Все поля Journey:
- draftobject
  - graphobject
  - entryobject
- publishedobject | null
  - graphobject
  - entryobject
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}

Ключ: secretKey · Права: journeys.write

Параметры

journeyв путиintegerобязательно

Тело запросаобязательно

JourneyPatch

namestring
длина: ≤ 120
descriptionstring | null
graphobject
entryobject

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "graph": {},
  "entry": {}
}

Ответы

200OK
JourneyDetail
Все поля Journey:
- draftobject
  - graphobject
  - entryobject
- publishedobject | null
  - graphobject
  - entryobject
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

422 lists errors by path, e.g. graph.nodes.2.data.template_id.

Ключ: secretKey · Права: journeys.read

Параметры

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

Publish the draft as a new version

post/journeys/{journey}/publish

First publish activates the journey and counts towards the plan's active journeys limit.

Ключ: secretKey · Права: journeys.publish

Параметры

journeyв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
JourneyDetail
Все поля Journey:
- draftobject
  - graphobject
  - entryobject
- publishedobject | null
  - graphobject
  - entryobject
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

Body {"exit_all": true} also exits all participants. Only active journeys.

Ключ: secretKey · Права: journeys.publish

Параметры

journeyв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запроса

exit_allboolean

Пример тела запроса

{
  "exit_all": true
}

Ответы

200OK
Journey
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "active", "paused", "archived"
- versioninteger | null
- next_run_atstring (date-time) | null
- 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

Counts towards the active journeys limit.

Ключ: secretKey · Права: journeys.publish

Параметры

journeyв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Journey
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "active", "paused", "archived"
- versioninteger | null
- next_run_atstring (date-time) | null
- 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

Irreversible.

Ключ: secretKey · Права: journeys.publish

Параметры

journeyв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Journey
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "active", "paused", "archived"
- versioninteger | null
- next_run_atstring (date-time) | null
- 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

Journey participations, newest first

get/journeys/{journey}/enrollments

Ключ: secretKey · Права: journeys.read

Параметры

journeyв путиintegerобязательно
limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring
statusв строке запросаstring
значения: "active", "waiting", "completed", "exited", "failed"

Ответы

200OK
- dataEnrollment[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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

Ключ: secretKey · Права: journeys.read, analytics.read

Параметры

journeyв путиintegerобязательно
periodв строке запросаinteger
значения: 7, 30, 90 · по умолчанию: 30

Ответы

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
429Rate limit or monthly event quota exceeded · Error

Enroll a profile into a journey with the API trigger

post/journeys/{journey}/enroll

Ключ: secretKey · Права: journeys.write

Параметры

journeyв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

identityIdentityRefобязательно
dataobject
Available in templates as context.data.
idempotency_keystring
длина: ≤ 150

Пример тела запроса

{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "data": {},
  "idempotency_key": "string"
}

Ответы

200Not enrolled (repeat key, re-entry policy, audience or limit)
EnrollResult
- enrolledboolean
- enrollment_idinteger | null
- profile_idinteger
201Enrolled
EnrollResult
- enrolledboolean
- enrollment_idinteger | null
- profile_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

Ключ: secretKey · Права: templates.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring
channelв строке запросаstring
Only templates of this channel.

Ответы

200OK
- dataMessageTemplate[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Create a message template

post/templates

Every language version is checked against the channel schema and the Twig sandbox.

Ключ: secretKey · Права: templates.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

MessageTemplateInput

namestringобязательно
длина: ≤ 120
channel_keystringобязательно
Channel of the template; cannot be changed later.
topicstring
по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$
transactionalboolean
по умолчанию: false
languagestring
Main language of content; the project default language if omitted.
длина: ≤ 16 · пример: "de"
contentobjectобязательно
Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
translationsobject
Other language versions; each is validated like content. 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
MessageTemplate
- idinteger
- namestring
- channelstring
  пример: "email"
- topicstring
  Subscription topic the message belongs to.
- transactionalboolean
- languagestring
  Main language of content: recipients whose profile language has no version get it.
  длина: ≤ 16 · пример: "de"
- contentobject
  Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
- translationsobject
  Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
- versioninteger
  Grows when any language version changes.
- created_atstring (date-time) | null
- updated_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}

Ключ: secretKey · Права: templates.read

Параметры

templateв путиintegerобязательно

Ответы

200OK
MessageTemplate
- idinteger
- namestring
- channelstring
  пример: "email"
- topicstring
  Subscription topic the message belongs to.
- transactionalboolean
- languagestring
  Main language of content: recipients whose profile language has no version get it.
  длина: ≤ 16 · пример: "de"
- contentobject
  Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
- translationsobject
  Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
- versioninteger
  Grows when any language version changes.
- created_atstring (date-time) | null
- updated_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}

Journeys and campaigns that use the template send the new content from the next message on.

Ключ: secretKey · Права: templates.write

Параметры

templateв путиintegerобязательно

Тело запросаобязательно

namestring
длина: ≤ 120
topicstring
по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$
transactionalboolean
по умолчанию: false
languagestring
Main language of content; the project default language if omitted.
длина: ≤ 16 · пример: "de"
contentobject
Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
translationsobject
Other language versions; each is validated like content. Omit to keep the stored versions, pass {} to delete them.
ключей: ≤ 50

Пример тела запроса

{
  "name": "string",
  "topic": "marketing",
  "transactional": false,
  "language": "de",
  "content": {},
  "translations": {}
}

Ответы

200OK
MessageTemplate
- idinteger
- namestring
- channelstring
  пример: "email"
- topicstring
  Subscription topic the message belongs to.
- transactionalboolean
- languagestring
  Main language of content: recipients whose profile language has no version get it.
  длина: ≤ 16 · пример: "de"
- contentobject
  Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
- translationsobject
  Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
- versioninteger
  Grows when any language version changes.
- created_atstring (date-time) | null
- updated_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}

Messages already sent keep their content; journey steps and campaign variants that use the template stop being valid.

Ключ: secretKey · Права: templates.write

Параметры

templateв пути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
429Rate limit or monthly event quota exceeded · Error

Campaigns

List campaigns

get/campaigns

Ключ: secretKey · Права: campaigns.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataCampaign[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Create a campaign draft

post/campaigns

The draft may be incomplete; readiness is checked on schedule.

Ключ: secretKey · Права: campaigns.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

CampaignInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
integration_idinteger | null
Channel integration; the template of every variant must belong to its channel.
audienceCampaignAudienceобязательно
variantsCampaignVariant[]обязательно
элементов: 1–5
abCampaignAb
scheduleCampaignScheduleобязательно
rate_per_minuteinteger | null
диапазон: 10–100000
goalCampaignGoal

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "integration_id": 0,
  "audience": {
    "segment_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ]
  },
  "variants": [
    {
      "key": "string",
      "template_id": 0,
      "percent": 1
    }
  ],
  "ab": {
    "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
  },
  "rate_per_minute": 10,
  "goal": {
    "event": "string",
    "within": {
      "amount": 1,
      "unit": "hour"
    }
  }
}

Ответы

201Created
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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}

Ключ: secretKey · Права: campaigns.read

Параметры

campaignв путиintegerобязательно

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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}

Only draft, scheduled or paused campaigns; a scheduled campaign is re-checked and its next run recomputed.

Ключ: secretKey · Права: campaigns.write

Параметры

campaignв путиintegerобязательно

Тело запросаобязательно

namestring
длина: ≤ 120
descriptionstring | null
integration_idinteger | null
Channel integration; the template of every variant must belong to its channel.
audienceCampaignAudience
variantsCampaignVariant[]
элементов: 1–5
abCampaignAb
scheduleCampaignSchedule
rate_per_minuteinteger | null
диапазон: 10–100000
goalCampaignGoal

Пример тела запроса

{
  "name": "string",
  "description": "string",
  "integration_id": 0,
  "audience": {
    "segment_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ]
  },
  "variants": [
    {
      "key": "string",
      "template_id": 0,
      "percent": 1
    }
  ],
  "ab": {
    "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
  },
  "rate_per_minute": 10,
  "goal": {
    "event": "string",
    "within": {
      "amount": 1,
      "unit": "hour"
    }
  }
}

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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}

Fails with 422 while scheduled or sending: cancel it first.

Ключ: secretKey · Права: campaigns.write

Параметры

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

Ключ: secretKey · Права: campaigns.read

Параметры

campaignв путиintegerобязательно

Ответы

200OK
- campaignCampaign
- runsCampaignRun[]
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

Draft or paused campaign without a paused run. Checks readiness (channel, templates, audience, goal, schedule); now starts within a minute.

Ключ: secretKey · Права: campaigns.send

Параметры

campaignв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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

The current run stops queueing messages; next runs do not start.

Ключ: secretKey · Права: campaigns.send

Параметры

campaignв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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

A paused run continues; otherwise the campaign is scheduled again.

Ключ: secretKey · Права: campaigns.send

Параметры

campaignв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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

Unsent recipients of the current run do not get the message; recurring runs stop.

Ключ: secretKey · Права: campaigns.send

Параметры

campaignв путиintegerобязательно
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Ответы

200OK
Campaign
- idinteger
- namestring
- descriptionstring | null
- statusstring
  значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
- integration_idinteger | null
- channelstring | null
- audienceCampaignAudience
- variantsCampaignVariant[]
- abCampaignAb
- scheduleCampaignSchedule
- rate_per_minuteinteger | null
- goalCampaignGoal
- next_run_atstring (date-time) | null
- last_run_atstring (date-time) | null
- 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

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.

Ключ: writeKey или secretKey

Параметры

languageв строке запросаstring
длина: ≤ 35

Ответы

200Settings; only enabled: false when the chat is off
- enabledboolean
- onlineboolean
- colorstring
- positionstring
  значения: "right", "left"
- prechatboolean
- textsobject
  - titlestring
  - greetingstring
  - offlinestring

Messages of the visitor conversation

get/chat/messages

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Ключ: writeKey или secretKey

Параметры

conversationв строке запросаstring (uuid)обязательно
tokenв строке запросаstringобязательно
длина: ≤ 64
afterв строке запросаinteger
диапазон: ≥ 0
readв строке запросаboolean
Mark operator replies as read by the visitor
по умолчанию: true

Ответы

200Messages visible to the visitor
- conversationChatVisitorConversation
- messagesChatVisitorMessage[]
404Unknown conversation or wrong token

Send a visitor message

post/chat/messages

Finds the visitor profile by userId or anonymousId (creates it if needed) and adds the message to its open website conversation or starts a new one.

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Ключ: writeKey или secretKey

Тело запросаобязательно

anonymousIdstringобязательно
длина: ≤ 255
userIdstring
длина: ≤ 255
conversationstring (uuid)
Conversation id from POST /chat/messages
tokenstring
Visitor token of the conversation from POST /chat/messages
длина: ≤ 64
bodystringобязательно
длина: ≤ 4000
namestring
длина: ≤ 100
emailstring (email)
длина: ≤ 255
pagestring
Page URL (http/https)
длина: ≤ 2000
languagestring
длина: ≤ 35
customer_tokenstring
Token of the customer signed in to the store website, issued by the store (store MCP contract, docs/api/store-mcp.md#5). The store verifies it; the platform stores it encrypted.
длина: ≤ 2000

Пример тела запроса

{
  "anonymousId": "string",
  "userId": "string",
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "body": "string",
  "name": "string",
  "email": "string",
  "page": "string",
  "language": "string",
  "customer_token": "string"
}

Ответы

201Message stored
- conversationChatVisitorConversation
- messageChatVisitorMessage
404The website chat is turned off
429Too many messages from the visitor

The visitor is typing

post/chat/typing

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Ключ: writeKey или secretKey

Тело запросаобязательно

conversationstring (uuid)обязательно
Conversation id from POST /chat/messages
tokenstringобязательно
Visitor token of the conversation from POST /chat/messages
длина: ≤ 64

Пример тела запроса

{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Ответы

200Shown to operators of the open conversation
404Unknown conversation or wrong token

Rate the conversation

post/chat/rating

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Ключ: writeKey или secretKey

Тело запросаобязательно

conversationstring (uuid)обязательно
Conversation id from POST /chat/messages
tokenstringобязательно
Visitor token of the conversation from POST /chat/messages
длина: ≤ 64
ratingintegerобязательно
диапазон: 1–5
commentstring
длина: ≤ 1000

Пример тела запроса

{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "rating": 1,
  "comment": "string"
}

Ответы

200Rating stored
- conversationChatVisitorConversation
404Unknown conversation or wrong token

Ask for a human operator

post/chat/handoff

The bot (AI in the chat) hands the conversation over to the queue of human operators. Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Ключ: writeKey или secretKey

Тело запросаобязательно

conversationstring (uuid)обязательно
Conversation id from POST /chat/messages
tokenstringобязательно
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
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.

Ключ: writeKey или secretKey

Тело запросаобязательно

conversationstring (uuid)обязательно
Conversation id from POST /chat/messages
tokenstringобязательно
Visitor token of the conversation from POST /chat/messages
длина: ≤ 64

Пример тела запроса

{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Ответы

200Tokens
- urlstring
- channelstring
- connection_tokenstring
- subscription_tokenstring
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.

Ключ: writeKey или secretKey

Параметры

qв строке запросаstring
Query text; empty — the whole catalog.
длина: ≤ 200
categoryв строке запросаstring
Category id; products of its subcategories too.
brand[]в строке запросаstring[]
элементов: ≤ 20
price_minв строке запросаnumber
диапазон: ≥ 0
price_maxв строке запросаnumber
диапазон: ≥ 0
attrв строке запросаobject
Filters by product characteristics of the store industry (ADR-114), e.g. attr[season]=winter&attr[rim_diameter][]=16&attr[rim_diameter][]=17: any of the values of a key, all keys. Keys and values — from facets.attributes.
ключей: ≤ 20
sortв строке запросаstring
значения: "relevance", "popular", "price_asc", "price_desc" · по умолчанию: "relevance"
pageв строке запросаinteger
по умолчанию: 1 · диапазон: 1–100
per_pageв строке запросаinteger
по умолчанию: 24 · диапазон: 1–48
allв строке запросаboolean
Include products that are not available.
по умолчанию: false
anonymousIdв строке запросаstring
Tracker visitor id for the personal order.
image_widthв строке запросаinteger
по умолчанию: 480 · диапазон: 64–1200
languageв строке запросаstring
Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).
длина: ≤ 35

Ответы

200Found products
- request_idstring (uuid)
- querystring
- totalinteger
- pageinteger
- per_pageinteger
- relaxedboolean
  Nothing matched all words: products matching any word.
- personalizedboolean
- itemsProductCard[]
  Все поля ProductCard:
  - availableboolean
- facetsobject
  - categoriesobject[]
    idstring
    namestring
    countinteger
  - brandsobject[]
    namestring
    countinteger
  - priceobject
    minnumber | null
    maxnumber | null
  - attributesobject[]
    Characteristics of the store industry with values and product counts; values go to attr[key].
    keystring
    namestring
    valuesobject[]
    valuestring
    labelstring
    countinteger
- redirectstring (uri) | null
  Redirect rule of the query (Site → Search): the page to open instead of the results, or null.
- filtersobject
  Sizes and parameters recognized in the query text and applied as filters (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season); empty when nothing was recognized or nothing matched them.
401Missing, invalid or revoked key · Error
402Product search is not in the plan of the project (code feature_unavailable)
422Validation failed · ValidationError
429Rate limit or monthly event quota exceeded · Error

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.

Ключ: writeKey или secretKey

Параметры

qв строке запросаstring
длина: ≤ 100
limitв строке запросаinteger
Products in the suggestion.
по умолчанию: 6 · диапазон: 1–10
image_widthв строке запросаinteger
по умолчанию: 480 · диапазон: 64–1200
languageв строке запросаstring
Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).
длина: ≤ 35

Ответы

200Suggestions
- productsProductCard[]
  Все поля ProductCard:
  - availableboolean
- categoriesobject[]
  - idstring
  - namestring
- queriesstring[]
- redirectstring (uri) | null
  Redirect rule of the query (Site → Search): the page to open instead of the results, or null.
401Missing, invalid or revoked key · Error
402Product search is not in the plan of the project (code feature_unavailable)
422Validation failed · ValidationError
429Rate limit or monthly event quota exceeded · Error

Analytics

Run an event report

post/analytics/reports

Report builder: series of an event and a metric (count, unique profiles, per profile, sum or average of a numeric property) with property filters, profile filter, breakdown, interval, period and comparison with the previous period (docs/architecture/analytics.md#конструктор-отчётов). 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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

ReportQuery

seriesobject[]обязательно
элементов: 1–5
- eventstring | null
- metricstring
  значения: "count", "profiles", "per_profile", "sum", "avg"
- propertystring | null
- filtersPropertyFilter[]
profilesProfileRules
breakdownBreakdown
intervalAnalyticsInterval
periodAnalyticsPeriod
compareboolean

Пример тела запроса

{
  "series": [
    {
      "event": "string",
      "metric": "count",
      "property": "string",
      "filters": [
        {
          "key": "string",
          "operator": "string",
          "value": null
        }
      ]
    }
  ],
  "profiles": {},
  "breakdown": {
    "source": "property",
    "key": "string"
  },
  "interval": "day",
  "period": {
    "last": 7
  },
  "compare": true
}

Ответы

200OK
ReportResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - 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

Steps of events with property filters, conversion window, order, profile filter, breakdown by the first step; conversion and time between steps. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

FunnelQuery

stepsobject[]обязательно
элементов: 2–10
- eventstringобязательно
- filtersPropertyFilter[]
windowobject
Conversion window from the first step, up to 90 days
- amountinteger
  диапазон: ≥ 1
- unitstring
  значения: "minute", "hour", "day"
orderstring
значения: "sequential", "strict"
profilesProfileRules
breakdownBreakdown
periodAnalyticsPeriod

Пример тела запроса

{
  "steps": [
    {
      "event": "string",
      "filters": [
        {
          "key": "string",
          "operator": "string",
          "value": null
        }
      ]
    }
  ],
  "window": {
    "amount": 1,
    "unit": "minute"
  },
  "order": "sequential",
  "profiles": {},
  "breakdown": {
    "source": "property",
    "key": "string"
  },
  "period": {
    "last": 7
  }
}

Ответы

200OK
FunnelResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - fromstring (date)
  - tostring (date)
- stepsobject[]обязательно
  Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
- breakdownobject[]обязательно
  Per breakdown value: value, steps (reached per step)
- time_samplenumber
  Share 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

Cohorts by the first start event and returns by the return event per day, week or month. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

RetentionQuery

startobjectобязательно
- eventstring | null
- filtersPropertyFilter[]
returnobject
- eventstring | null
- filtersPropertyFilter[]
cohortstring
значения: "first", "period"
intervalAnalyticsInterval
periodsinteger
Up to 30 days, 12 weeks or 12 months
диапазон: 1–30
returnsstring
значения: "exact", "rolling"
profilesProfileRules
periodAnalyticsPeriod

Пример тела запроса

{
  "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
RetentionResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - 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

Frequent event sequences after or before the anchor event; nodes and links for a Sankey diagram and the most frequent paths. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

PathQuery

eventstringобязательно
filtersPropertyFilter[]
directionstring
значения: "after", "before"
stepsinteger
диапазон: 1–5
gap_minutesinteger
диапазон: 1–1440
excludestring[]
элементов: ≤ 20
profilesProfileRules
periodAnalyticsPeriod

Пример тела запроса

{
  "event": "string",
  "filters": [
    {
      "key": "string",
      "operator": "string",
      "value": null
    }
  ],
  "direction": "after",
  "steps": 1,
  "gap_minutes": 1,
  "exclude": [
    "string"
  ],
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

200OK
PathResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - fromstring (date)
  - tostring (date)
- totalintegerобязательно
- nodesobject[]обязательно
- linksobject[]обязательно
- pathsobject[]обязательно
  Most frequent paths: events, profiles
- truncatedboolean
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

Revenue, orders, average order value, new and returning buyers, LTV by first purchase cohort, top products and categories in the project currency. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

RevenueQuery

eventstring
Purchase event; by default from the prediction settings
amountstring
Numeric order amount property
product_propertystring
intervalAnalyticsInterval
ltv_intervalstring
значения: "week", "month"
ltv_periodsinteger
диапазон: 1–12
profilesProfileRules
periodAnalyticsPeriod

Пример тела запроса

{
  "event": "string",
  "amount": "string",
  "product_property": "string",
  "interval": "day",
  "ltv_interval": "week",
  "ltv_periods": 1,
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

200OK
RevenueResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - fromstring (date)
  - tostring (date)
- currencystring | null
- other_currency_ordersinteger
- summaryobjectобязательно
- seriesobjectобязательно
- ltvobjectобязательно
- productsobject[]обязательно
- categoriesobject[]обязательно
401Missing, invalid or revoked key · Error
402Revenue, traffic and attribution 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

Website visits by channel, source, campaign, referring site or landing page with new profiles, bounces, conversions and revenue. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

TrafficQuery

dimensionstring
значения: "channel", "source", "source_medium", "campaign", "referrer", "landing"
intervalAnalyticsInterval
eventstring
amountstring
profilesProfileRules
periodAnalyticsPeriod

Пример тела запроса

{
  "dimension": "channel",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

200OK
TrafficResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - fromstring (date)
  - tostring (date)
- currencystring | null
- purchasesboolean
- summaryobjectобязательно
- rowsobject[]обязательно
- row_countinteger
- chartobjectобязательно
401Missing, invalid or revoked key · Error
402Revenue, traffic and attribution 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

Revenue attributed to platform clicks (campaigns, journeys, messages, recommendations, search) by the last click, first click and linear models. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

AttributionQuery

window_daysinteger
значения: 1, 3, 7, 14, 30
modelstring
значения: "last", "first", "linear"
intervalAnalyticsInterval
eventstring
amountstring
profilesProfileRules
periodAnalyticsPeriod

Пример тела запроса

{
  "window_days": 1,
  "model": "last",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

200OK
AttributionResult
- definitionobjectобязательно
  Normalized definition
- periodobjectобязательно
  - fromstring (date)
  - tostring (date)
- currencystring | null
- summaryobjectобязательно
- channelsobject[]обязательно
  Per channel: channel, clicks, touched_orders, revenue and orders by model
- itemsobject[]обязательно
  Per campaign, journey, message channel or widget
- chartobject
401Missing, invalid or revoked key · Error
402Revenue, traffic and attribution 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

List saved reports

get/analytics/saved-reports

Ключ: secretKey · Права: analytics.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring
typeв строке запросаAnalyticsReportType

Ответы

200OK
- dataSavedReport[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Save a report

post/analytics/saved-reports

The definition is validated and normalized by the report type; errors come with definition.* paths.

Ключ: secretKey · Права: analytics.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

SavedReportInput

namestringобязательно
длина: ≤ 120
typeAnalyticsReportTypeобязательно
definitionobjectобязательно
Definition of the report type — see the run operations
viewobject

Пример тела запроса

{
  "name": "string",
  "type": "report",
  "definition": {},
  "view": {}
}

Ответы

201Created
SavedReportDetail
Все поля 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}

Ключ: secretKey · Права: analytics.read

Параметры

reportв путиintegerобязательно

Ответы

200OK
SavedReportDetail
Все поля 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}

The report type cannot be changed.

Ключ: secretKey · Права: analytics.write

Параметры

reportв путиintegerобязательно

Тело запросаобязательно

SavedReportPatch

namestring
длина: ≤ 120
definitionobject
viewobject

Пример тела запроса

{
  "name": "string",
  "definition": {},
  "view": {}
}

Ответы

200OK
SavedReportDetail
Все поля 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}

Its cards are removed from dashboards; its email schedules are deleted.

Ключ: secretKey · Права: analytics.write

Параметры

reportв пути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
429Rate limit or monthly event quota exceeded · Error

Run a saved report

post/analytics/saved-reports/{report}/result

Optional period replaces the period of the saved definition. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Ключ: secretKey · Права: analytics.read

Параметры

reportв путиintegerобязательно

Тело запросаобязательно

periodAnalyticsPeriod

Пример тела запроса

{
  "period": {
    "last": 7
  }
}

Ответы

200OK
Объект с произвольными ключами.
401Missing, invalid or revoked key · Error
402Revenue, traffic and attribution 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

List dashboards

get/analytics/dashboards

Ключ: secretKey · Права: analytics.read

Параметры

limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataDashboard[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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
429Rate limit or monthly event quota exceeded · Error

Create a dashboard

post/analytics/dashboards

Ключ: secretKey · Права: analytics.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

DashboardInput

namestringобязательно
длина: ≤ 120
layoutobject[]
элементов: ≤ 24
- report_idintegerобязательно
- sizestring
  значения: "half", "full"
periodAnalyticsPeriod

Пример тела запроса

{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  }
}

Ответы

201Created
Dashboard
- idintegerобязательно
- namestringобязательно
- layoutobject[]обязательно
  элементов: ≤ 24
  - report_idintegerобязательно
  - sizestring
    значения: "half", "full"
- periodAnalyticsPeriodобязательно
- 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}

Ключ: secretKey · Права: analytics.read

Параметры

dashboardв путиintegerобязательно

Ответы

200OK
Dashboard
- idintegerобязательно
- namestringобязательно
- layoutobject[]обязательно
  элементов: ≤ 24
  - report_idintegerобязательно
  - sizestring
    значения: "half", "full"
- periodAnalyticsPeriodобязательно
- 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}

Fields not sent stay unchanged; layout replaces the whole layout.

Ключ: secretKey · Права: analytics.write

Параметры

dashboardв путиintegerобязательно

Тело запросаобязательно

DashboardPatch

namestring
длина: ≤ 120
layoutobject[]
элементов: ≤ 24
- report_idintegerобязательно
- sizestring
  значения: "half", "full"
periodAnalyticsPeriod

Пример тела запроса

{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  }
}

Ответы

200OK
Dashboard
- idintegerобязательно
- namestringобязательно
- layoutobject[]обязательно
  элементов: ≤ 24
  - report_idintegerобязательно
  - sizestring
    значения: "half", "full"
- periodAnalyticsPeriodобязательно
- 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}

Saved reports stay; email schedules of the dashboard are deleted.

Ключ: secretKey · Права: analytics.write

Параметры

dashboardв пути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
429Rate limit or monthly event quota exceeded · Error

Loyalty

Calculate points for a cart

post/loyalty/calculate

How many points the profile can use for a cart of amount (at most max_redeem_percent of the amount and the balance), the discount in the project currency and an estimate of points the order will earn at the member's tier (rules are not included — they depend on the order).

Ключ: secretKey · Права: loyalty.read

Тело запросаобязательно

profileLoyaltyProfileRefобязательно
amountnumberобязательно
Cart amount in the project currency
диапазон: ≥ 0

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "amount": 0
}

Ответы

200OK
LoyaltyCalculation
- memberboolean
- balanceinteger
- tierstring | null
- max_pointsinteger
- max_discountnumber
- earn_pointsinteger
- point_valuenumber
- currencystring | 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}

Balance, points waiting for the return period, tier, purchase sum of the tier window and the nearest expiry. A profile that has not joined returns member: false.

Ключ: secretKey · Права: loyalty.read

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

200OK
LoyaltyAccount
- memberboolean
- balanceinteger
  Available points
- pendinginteger
  Points waiting for the return period
- tierstring | null
- tier_spendnumber
- expiringinteger
  Points expiring within 30 days
- expires_atstring (date-time) | null
- enrolled_atstring (date-time) | null
- referral_codestring | null
  Code of the member for inviting friends.
- referral_urlstring | null
  Referral link (?ref= on the store page) when referrals are on.
- referralsobject
  Friends who came with the code, of them rewarded, and points for them.
  - invitedinteger
  - rewardedinteger
  - pointsinteger
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

Ledger operations from the newest: earn, cancel, expire, adjust, redeem (a hold or a redemption), refund (points returned). Cursor pages.

Ключ: secretKey · Права: loyalty.read

Параметры

typeв путиstringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valueв путиstringобязательно
Normalized like at ingestion (lower-case email, E.164 phone).
limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataLoyaltyTransaction[]
- next_cursorstring | 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

Join the program

post/loyalty/members

Opens an account for an existing profile — for programs with explicit joining (enrollment: explicit). Returns 200 if the profile is already a member.

Ключ: secretKey · Права: loyalty.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

profileLoyaltyProfileRefобязательно

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Ответы

201Created
LoyaltyAccount
- memberboolean
- balanceinteger
  Available points
- pendinginteger
  Points waiting for the return period
- tierstring | null
- tier_spendnumber
- expiringinteger
  Points expiring within 30 days
- expires_atstring (date-time) | null
- enrolled_atstring (date-time) | null
- referral_codestring | null
  Code of the member for inviting friends.
- referral_urlstring | null
  Referral link (?ref= on the store page) when referrals are on.
- referralsobject
  Friends who came with the code, of them rewarded, and points for them.
  - invitedinteger
  - rewardedinteger
  - pointsinteger
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

For the registration form of a store: the profile came with the code of a member. The referral counts only for a new customer (no orders, not the member themselves); an identified profile joins the program and gets the friend reward at once (points and, if set, a promo code). 201 — counted now, 200 — counted before. 422 on code: referrals off, unknown code, own code, existing customer.

Ключ: secretKey · Права: loyalty.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

profileLoyaltyProfileRefобязательно
codestringобязательно
длина: ≤ 16

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "code": "string"
}

Ответы

200Counted before
LoyaltyReferral
- statusstring
  pending — waiting for the friend's first order.
  значения: "pending", "rewarded", "expired", "limit", "cancelled"
- codestring
- friend_pointsinteger
- friend_promo_codestring | null
- rewardedboolean
  The friend has received the reward.
- expires_atstring (date-time)
  The first order of the friend rewards the member until this moment.
201Counted
LoyaltyReferral
- statusstring
  pending — waiting for the friend's first order.
  значения: "pending", "rewarded", "expired", "limit", "cancelled"
- codestring
- friend_pointsinteger
- friend_promo_codestring | null
- rewardedboolean
  The 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

Takes points off the balance (earliest expiring first) and holds them for 30 minutes while the order is placed. A new hold for the same cart_id returns the previous one. With amount, points are limited to the payable share of the cart. Confirm with the order number or cancel; unconfirmed holds return automatically.

Ключ: secretKey · Права: loyalty.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

profileLoyaltyProfileRefобязательно
pointsintegerобязательно
диапазон: ≥ 1
cart_idstringобязательно
длина: ≤ 255
amountnumber
диапазон: ≥ 0

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 1,
  "cart_id": "string",
  "amount": 0
}

Ответы

201Created
LoyaltyRedemption
- idstring
- statusstring
  значения: "held", "confirmed", "cancelled", "expired"
- pointsinteger
- returnedinteger
- discountnumber
- cart_idstring
- order_idstring | null
- held_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

Binds the held points to the order. Refunds and cancellations of the order (events order_refunded, order_cancelled) return the points proportionally. Repeating with the same order changes nothing; an expired or cancelled hold — 422.

Ключ: secretKey · Права: loyalty.write

Параметры

redemptionв путиstringобязательно
Redemption id from the hold response.
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

order_idstringобязательно
длина: ≤ 255

Пример тела запроса

{
  "order_id": "string"
}

Ответы

200OK
LoyaltyRedemption
- idstring
- statusstring
  значения: "held", "confirmed", "cancelled", "expired"
- pointsinteger
- returnedinteger
- discountnumber
- cart_idstring
- order_idstring | null
- held_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

Returns the points of a hold or a confirmed redemption to the balance (into their original lots while they have not expired).

Ключ: secretKey · Права: loyalty.write

Параметры

redemptionв путиstringобязательно
Redemption id from the hold response.

Ответы

200OK
LoyaltyRedemption
- idstring
- statusstring
  значения: "held", "confirmed", "cancelled", "expired"
- pointsinteger
- returnedinteger
- discountnumber
- cart_idstring
- order_idstring | null
- held_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

Adds points (a lot available at once, with the program lifetime) or takes them off the balance (not more than available), with a reason recorded in the history and the audit log. Send Idempotency-Key to make retries safe.

Ключ: secretKey · Права: loyalty.write

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

profileLoyaltyProfileRefобязательно
pointsintegerобязательно
Positive — add, negative — take off
reasonstringобязательно
длина: ≤ 500

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 0,
  "reason": "string"
}

Ответы

200OK
LoyaltyAccount
- memberboolean
- balanceinteger
  Available points
- pendinginteger
  Points waiting for the return period
- tierstring | null
- tier_spendnumber
- expiringinteger
  Points expiring within 30 days
- expires_atstring (date-time) | null
- enrolled_atstring (date-time) | null
- referral_codestring | null
  Code of the member for inviting friends.
- referral_urlstring | null
  Referral link (?ref= on the store page) when referrals are on.
- referralsobject
  Friends who came with the code, of them rewarded, and points for them.
  - invitedinteger
  - rewardedinteger
  - pointsinteger
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

Add codes to a pool

post/promo/pools/{key}/codes

Generates count codes (prefix and length of the pool, up to 50 000) or uploads ready codes (up to 100 000, e.g. coupons exported from the store). Codes that already exist in the project are skipped. Only for unique pools.

Ключ: secretKey · Права: promo.write

Параметры

keyв путиstringобязательно
Pool key — the name used in templates: {{ promo_code('summer') }}.
шаблон: ^[a-z0-9_]{1,64}$
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

countinteger
диапазон: 1–50000
codesstring[]
элементов: ≤ 100000

Пример тела запроса

{
  "count": 1,
  "codes": [
    "string"
  ]
}

Ответы

201Created
- addedinteger
- skippedinteger
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

A profile with an active code of the pool gets the same code (200); otherwise the next free code is issued (201, event $promo_code_issued). A shared pool returns its code. 409 with reason: inactive (paused or outside the period), limit (the profile received all its codes), exhausted (no free codes).

Ключ: secretKey · Права: promo.write

Параметры

keyв путиstringобязательно
Pool key — the name used in templates: {{ promo_code('summer') }}.
шаблон: ^[a-z0-9_]{1,64}$
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

profileIdentityRefобязательно

Пример тела запроса

{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Ответы

200Already issued
PromoCode
- poolstring
  Pool key.
- codestringобязательно
- statusstringобязательно
  значения: "available", "issued", "used", "shared"
- issued_atstring (date-time) | null
- expires_atstring (date-time) | null
- used_atstring (date-time) | null
201Issued
PromoCode
- poolstring
  Pool key.
- codestringобязательно
- statusstringобязательно
  значения: "available", "issued", "used", "shared"
- issued_atstring (date-time) | null
- expires_atstring (date-time) | null
- used_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
- messagestring
- reasonstring
  значения: "inactive", "limit", "exhausted"
422Validation failed · ValidationError
429Rate limit or monthly event quota exceeded · Error

Messages

Send one message now

post/messages

Sends one message to one profile right away — an order confirmation, a password reset, a one-time code. The recipient profile is found by identity or created. Repeat the request with the same Idempotency-Key to retry safely: no second message is sent. No more than MESSAGES_API_PER_RECIPIENT_PER_HOUR (20 by default) messages per recipient per hour through the API. Poll GET /messages/{message} for the delivery status. With steps, the message goes as a cascade — poll GET /messages/cascades/{cascade}; the per-recipient limit counts a cascade once; without the cascades plan feature the answer is 402.

Ключ: secretKey · Права: messages.send

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

MessageSendInput

identityIdentityRefобязательно
The recipient. A profile with this identity is created if there is none.
traitsobject
Traits written to the profile before sending, available in the template as traits.*.
ключей: ≤ 100
template_idinteger
Message template. A transactional template skips consents, frequency limits and quiet hours, but not hard blocks of the channel (address does not exist, bot blocked); other templates follow all messaging rules.
integration_idinteger | null
Channel integration of the template's channel; may be omitted when the channel has exactly one active integration.
dataobject
Per-message data, available in the template as context.data.* (order number, confirmation code).
stepsCascadeStep[]
Cascade (plans with the cascades feature): 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
Один из вариантов:
- MessageStatus
- CascadeStatus
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

Sends a ready email of an online store — an order confirmation, an invoice, a password reset — through the project's email integration as is, without a template. The email goes to to as a transactional message: no marketing consent or frequency rules, but bounced and complained addresses are blocked. It is counted in the monthly message quota. The answer is fast: when it is not 202 (no email integration, quota exhausted, the service is unavailable), send the email yourself. Repeat the request with the same Idempotency-Key to retry safely. No more than MESSAGES_STORE_EMAILS_PER_RECIPIENT_PER_HOUR (30 by default) store emails per recipient per hour. Order emails (order_* kinds) with order are built from the OneTrace template enabled for the kind, in the customer language; without an enabled template subject and html are required. Poll GET /messages/{message} for the delivery status.

Ключ: secretKey · Права: messages.send

Параметры

Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

StoreEmailInput

tostring (email)обязательно
Recipient address. The profile is found by this email or created.
длина: ≤ 254
subjectstring
Required unless an order template is enabled for kind and order is given.
длина: ≤ 998
htmlstring
Ready HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled for kind and order is given.
длина: ≤ 1000000
textstring | null
Plain-text part; built from the HTML when empty.
длина: ≤ 1000000
reply_tostring (email) | null
Overrides the Reply-To of the email integration.
from_namestring | null
Overrides the sender name of the email integration; the sender address is always the integration's.
длина: ≤ 100
kindstringобязательно
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. For order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded with order, an enabled OneTrace template builds the email instead of html (see GET /emails/settings).
шаблон: ^[a-z0-9_]{1,40}$
languagestring | null
Customer language tag: picks the language version of an order template; for history and reports otherwise.
длина: ≤ 20
integration_idinteger | null
Email integration; may be omitted when the project has exactly one active.
traitsobject | null
Profile traits to update before sending (name, phone).
attachmentsobject[]
Up to 5 files, 5 MB in total.
элементов: ≤ 5
- namestringобязательно
  длина: ≤ 200
- typestringобязательно
  значения: "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
StoreEmailStatus
Все поля MessageStatus:
- kindstring | null
- templateboolean
  The 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

What the store plugin should do: relay store emails through OneTrace and which order emails are built from OneTrace templates. Cache for a few minutes.

Ключ: secretKey · Права: messages.send

Ответы

200Settings
StoreEmailSettings
- relayboolean
  Send all store emails through OneTrace (store emails section).
- integration_idinteger | null
- templatesobject
  Order email kinds built from OneTrace templates: the store does not send its own email for them and passes order instead.
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}

Status of a cascade sent with POST /messages and the messages of its steps.

Ключ: secretKey · Права: messages.send

Параметры

cascadeв путиstring (uuid)обязательно
Cascade id (UUID) from the send response.

Ответы

200OK
CascadeStatus
- idstring (uuid)
- statusstring
  reached — a step succeeded; failed — no channel reached the profile.
  значения: "running", "reached", "failed"
- stepinteger
  Current step, from 0.
- reached_channelstring | null
- profile_idinteger
- originstring | null
- created_atstring (date-time) | null
- finished_atstring (date-time) | null
- messagesMessageStatus[]
  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}

Status and timestamps of a message sent with POST /messages (or any message of the project by its id).

Ключ: secretKey · Права: messages.send

Параметры

messageв путиstring (uuid)обязательно
Message id (UUID) from the send response.

Ответы

200OK
MessageStatus
- idstring (uuid)
- statusstring
  queued → sent → delivered; scheduled — waiting (quiet hours, warm-up); skipped — not sent, see reason; failed/bounced — see reason and error.
  значения: "queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"
- reasonstring | null
  Why it was skipped or failed: no_recipient, unsubscribed, recipient_blocked, suppressed, frequency_limit, quota_exceeded, feature_unavailable, delivery_failed, recipient_unreachable, undelivered, template_error, integration_unavailable …
- errorstring | null
- channelstring
- template_idinteger | null
- integration_idinteger | null
- profile_idinteger
- transactionalboolean
- originstring | null
  api for messages sent with messages.send, store for store emails (emails.send).
- created_atstring (date-time) | null
- scheduled_forstring (date-time) | null
- sent_atstring (date-time) | null
- delivered_atstring (date-time) | null
- opened_atstring (date-time) | null
- clicked_atstring (date-time) | null
- failed_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

Conversations of the online chat (website and messengers), newest first. Filter by status, channel or customer.

Ключ: secretKey · Права: chats.read

Параметры

statusв строке запросаstring
open — waiting for an answer.
значения: "open", "waiting", "closed"
channelв строке запросаstring
значения: "web", "telegram", "whatsapp", "viber"
profile_typeв строке запросаstring
Identity type of the customer; together with profile_value.
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
profile_valueв строке запросаstring
Identity value of the customer; together with profile_type.
длина: ≤ 255
limitв строке запросаinteger
по умолчанию: 50 · диапазон: 1–200
cursorв строке запросаstring

Ответы

200OK
- dataConversation[]обязательно
- next_cursorstring | nullобязательно
  Pass as cursor to 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}

The conversation and its latest messages, oldest first.

Ключ: secretKey · Права: chats.read

Параметры

conversationв путиstring (uuid)обязательно
Conversation id (UUID).
limitв строке запросаinteger
How many latest messages to return.
по умолчанию: 100 · диапазон: 1–500

Ответы

200OK
ConversationDetail
Все поля Conversation:
- messagesConversationMessage[]обязательно
  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

Sends an answer to the customer as the API key: a bot or an external helpdesk. It does not take an operator seat and is signed with the key name in the operator inbox. The website visitor sees it in the chat widget; a messenger answer goes through the messenger integration (WhatsApp allows free text only within 24 hours of the customer's last message). An answer to a closed conversation reopens it unless the customer already has a newer one.

Ключ: secretKey · Права: chats.reply

Параметры

conversationв путиstring (uuid)обязательно
Conversation id (UUID).
Idempotency-Keyзаголовокstring
Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.
длина: ≤ 255

Тело запросаобязательно

bodystringобязательно
Plain text of the answer.
длина: 1–4000

Пример тела запроса

{
  "body": "string"
}

Ответы

201Created
ConversationMessage
- idintegerобязательно
- authorstringобязательно
  visitor — the customer; operator — an answer from the inbox or the API; system — assignment, closing and reopening (see action).
  значения: "visitor", "operator", "system"
- viastring | null
  Where an answer or action came from: the operator inbox or the API.
  значения: "inbox", "api", null
- api_keystring | null
  Name of the API key that answered or closed the conversation.
- bodystringобязательно
- actionstring | null
  значения: "assigned", "unassigned", "closed", "reopened", null
- statusstring | null
  Delivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.
- created_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

Close a conversation

post/conversations/{conversation}/close

Closes the conversation; the website visitor is asked to rate it. Closing a closed conversation changes nothing.

Ключ: secretKey · Права: chats.reply

Параметры

conversationв путиstring (uuid)обязательно
Conversation id (UUID).

Ответы

200OK
Conversation
- idstring (uuid)обязательно
- profile_idintegerобязательно
- channelstringобязательно
  web — the website chat; messengers need the chat_messengers plan feature.
  значения: "web", "telegram", "whatsapp", "viber"
- 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 | null
- ratinginteger | null
  Customer rating after the conversation.
  диапазон: 1–5
- rating_commentstring | null
- last_message_atstring (date-time) | null
- last_message_authorstring | null
  значения: "visitor", "operator", "system", null
- first_reply_atstring (date-time) | null
- created_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

A store plugin connects its MCP server (contract: docs/api/store-mcp.md) to the AI bot of the project: the platform checks the contract marker in initialize, reads tools/list and keeps the contract tools the store owner allowed. One server per URL: calling again updates the key and re-reads the tools.

Ключ: secretKey · Права: chats.manage

Тело запросаобязательно

urlstring (uri)обязательно
HTTPS address of the store MCP server
длина: ≤ 2048
keystringобязательно
Bearer key the platform sends to the store
длина: 32–500
namestring
длина: ≤ 120
platformstring
значения: "woocommerce", "magento", "bitrix", "sdk", "custom"

Пример тела запроса

{
  "url": "https://example.com",
  "key": "string",
  "name": "string",
  "platform": "woocommerce"
}

Ответы

200Updated
StoreMcpServer
- idstring (uuid)
- urlstring
- statusstring
  error — see error; the bot works without this server
  значения: "pending", "ok", "error"
- errorstring | null
- toolsstring[]
  Contract tools the bot may use
- checked_atstring (date-time) | null
201Connected
StoreMcpServer
- idstring (uuid)
- urlstring
- statusstring
  error — see error; the bot works without this server
  значения: "pending", "ok", "error"
- errorstring | null
- toolsstring[]
  Contract tools the bot may use
- checked_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

Removes the store MCP server with this URL from the AI bot of the project.

Ключ: secretKey · Права: chats.manage

Тело запросаобязательно

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.

Ключ: writeKey

Параметры

uidв путиstringобязательно
Form uid from the site code.
длина: ≤ 16

Тело запросаобязательно

anonymousIdstringобязательно
длина: ≤ 255
userIdstring
длина: ≤ 255
valuesobjectобязательно
Form fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).
languagestring
длина: ≤ 35
pagestring
длина: ≤ 2000
websitestring
Hidden trap field: must stay empty.
variantstring
A/B variant of the form the visitor saw.
значения: "a", "b", "c", "d"

Пример тела запроса

{
  "anonymousId": "string",
  "userId": "string",
  "values": {},
  "language": "string",
  "page": "string",
  "website": "string",
  "variant": "a"
}

Ответы

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 | null
  Promo code of the form when the submission is accepted at once.
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.

Ключ: writeKey

Параметры

languageв строке запросаstring
Visitor language (BCP 47).
длина: ≤ 35
anonymousIdв строке запросаstring
Visitor id: forms shown to segment members are filtered by the visitor's profile.
длина: ≤ 255

Ответы

200OK
- formsobject[]обязательно
  - uidstring
  - kindstring
    значения: "popup", "flyout", "embedded", "bar"
  - double_opt_inboolean
  - settingsobject
  - rulesobject
  - textsobject
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", "telegram_chat_id", "viber_id", "web_push"
valuestringобязательно
длина: ≤ 255

IdentitiesInput

identitiesIdentityRef[]обязательно
элементов: 1–1000

Message

typestring
значения: "track", "identify", "page", "alias"
messageIdstring
длина: ≤ 100
anonymousIdstring | integer
userIdstring | integer
previousIdstring | integer
eventstring
длина: ≤ 200
namestring
propertiesobject
traitsobject
contextobject
consentsobject[]
identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.
элементов: ≤ 20
- channelstringобязательно
  шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"
- topicstring
  Subscription topic; the whole channel if omitted.
  шаблон: ^[a-z0-9_-]{1,64}$
- statusstringобязательно
  значения: "subscribed", "unsubscribed"
timestampstring (date-time)

Profile

idinteger
traitsobject
identitiesobject
first_seen_atstring (date-time)
last_seen_atstring (date-time)

Event

event_idstring
typestring
namestring
propertiesobject
contextobject
occurred_atstring (date-time)

CatalogEvent

namestring
labelstring | null
volumeinteger
first_seen_atstring (date-time) | null
last_seen_atstring (date-time) | null
propertiesobject[]
- keystring
- data_typestring

CatalogTrait

keystring
labelstring | null
data_typestring
piiboolean
systemboolean

Segment

idinteger
namestring
descriptionstring | null
typestring
значения: "dynamic", "static"
realtimeboolean
schedule_minutesinteger | null
statusstring
значения: "pending", "computing", "ready", "failed"
sizeinteger
last_computed_atstring (date-time) | null
created_atstring (date-time)
updated_atstring (date-time)

SegmentDetail

Все поля Segment:

rulesobject | null
Rule tree: {"op": "and|or", "children": [...]}

SegmentInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
typestringобязательно
значения: "dynamic", "static"
realtimeboolean
schedule_minutesinteger
значения: 15, 30, 60, 180, 360, 720, 1440
rulesobject

SegmentPatch

namestring
длина: ≤ 120
descriptionstring | null
realtimeboolean
schedule_minutesinteger
rulesobject

Journey

idinteger
namestring
descriptionstring | null
statusstring
значения: "draft", "active", "paused", "archived"
versioninteger | null
next_run_atstring (date-time) | null
created_atstring (date-time)
updated_atstring (date-time)

JourneyDetail

Все поля Journey:

draftobject
- graphobject
- entryobject
publishedobject | null
- graphobject
- entryobject

JourneyInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
graphobject
- nodesarray
  элементов: ≤ 200
- edgesarray
  элементов: ≤ 400
entryobject

JourneyPatch

namestring
длина: ≤ 120
descriptionstring | null
graphobject
entryobject

Enrollment

idinteger
profile_idinteger
version_idinteger
statusstring
current_node_idstring | null
exit_reasonstring | null
entered_atstring (date-time)
finished_atstring (date-time) | null
goal_reached_atstring (date-time) | null

EnrollResult

enrolledboolean
enrollment_idinteger | null
profile_idinteger

CampaignAudience

segment_idsinteger[]обязательно
Members of any of these segments get the campaign.
элементов: ≤ 10
exclude_segment_idsinteger[]
Members of these segments are excluded.
элементов: ≤ 10

CampaignVariant

keystringобязательно
шаблон: ^[a-z0-9_]{1,32}$
template_idinteger | null
Message 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

A/B test: test_percent of the audience is split between variants; after wait the rest gets the winner by metric.

test_percentintegerобязательно
диапазон: 5–50
metricstringобязательно
значения: "opened", "clicked", "goal"
waitobjectобязательно
- amountinteger
  диапазон: 1–72
- unitstring
  значения: "hour", "day"

CampaignSchedule

Times are wall-clock in the project time zone; with local_time — in each recipient's timezone trait.

typestringобязательно
значения: "now", "at", "recurring"
atstring
For at: Y-m-d\TH:i.
пример: "2026-11-01T10:00"
repeatstring
значения: "daily", "weekly", "monthly"
timestring
пример: "10:00"
weekdaysinteger[]
ISO weekdays for weekly (1 = Monday).
day_of_monthinteger
диапазон: 1–28
start_datestring (date) | null
end_datestring (date) | null
local_timeboolean

CampaignGoal

Conversion: the event from the recipient within the window after sending.

eventstringобязательно
withinobjectобязательно
- amountinteger
  диапазон: 1–90
- unitstring
  значения: "hour", "day"

Campaign

idinteger
namestring
descriptionstring | null
statusstring
значения: "draft", "scheduled", "sending", "sent", "paused", "cancelled"
integration_idinteger | null
channelstring | null
audienceCampaignAudience
variantsCampaignVariant[]
abCampaignAb
scheduleCampaignSchedule
rate_per_minuteinteger | null
goalCampaignGoal
next_run_atstring (date-time) | null
last_run_atstring (date-time) | null
created_atstring (date-time)
updated_atstring (date-time)

CampaignInput

namestringобязательно
длина: ≤ 120
descriptionstring | null
integration_idinteger | null
Channel integration; the template of every variant must belong to its channel.
audienceCampaignAudienceобязательно
variantsCampaignVariant[]обязательно
элементов: 1–5
abCampaignAb
scheduleCampaignScheduleобязательно
rate_per_minuteinteger | null
диапазон: 10–100000
goalCampaignGoal

CampaignVariantStats

queuedinteger
sentinteger
deliveredinteger
openedinteger
clickedinteger
bouncedinteger
failedinteger
skippedinteger
unsubscribedinteger
convertedinteger | null
Recipients with the goal event in the window; null without a goal.

CampaignRun

idinteger
statusstring
значения: "preparing", "sending", "testing", "completed", "paused", "cancelled", "failed"
scheduled_atstring (date-time)
started_atstring (date-time) | null
finished_atstring (date-time) | null
audience_sizeinteger
queuedinteger
winnerstring | null
winner_atstring (date-time) | null
errorstring | null
variantsobject
totalCampaignVariantStats
metricstring
значения: "opened", "clicked", "goal"
statsAbStats
ab_resultobject | null
Test result saved when the A/B winner was picked.
- metricstring
- decided_atstring (date-time)
- statsAbStats
languagesobject
Results per language of the sent template version.

AbStats

Significance of the difference between variants (docs/architecture/analytics.md#значимость-ab); null with one variant.

verdictstring
значения: "winner", "no_difference", "insufficient_data"
winnerstring | null
Set only when the best variant is significantly better than every other one.
beststring
required_per_arminteger | null
alphanumber
armsobject[]
- keystring
- trialsinteger
- successesinteger
- ratenumber
- cinumber[]
  Wilson 95 % interval
  элементов: 2–2
- liftnumber | null
  Relative to the first variant
- p_valuenumber | null
  Holm-adjusted p-value against the best variant
- probability_bestnumber

ProductCard

idstring
namestring
urlstring | null
imagestring | null
JPEG up to image_width via imgproxy; without imgproxy — a direct link (CDN copy or feed URL).
image_originalstring | null
Direct link: the platform CDN copy if the feed mirrors images, otherwise the feed URL.
srcsetobject | null
Variants for : AVIF and WebP srcset (240–960 px); null without imgproxy.
- avifstring
- webpstring
pricenumber | null
old_pricenumber | null
currencystring | null
brandstring | null
category_idstring | null
min_quantityinteger | null
The product is sold as a set (tires by 4): how many to add to the cart; null — one.

ProductInput

idstringобязательно
Product id on the site: product_id in events.
длина: ≤ 128
namestringобязательно
длина: ≤ 500
urlstring (uri)
imagestring (uri)
pricenumber
диапазон: ≥ 0
old_pricenumber
диапазон: ≥ 0
currencystring
длина: 3–3
availableboolean
по умолчанию: true
stockinteger
Units in stock. Used only when "Use stock levels from the API and plugins" is on in the catalog settings of the project: then the stock is saved, zero takes the product off sale, and the "low stock" journey trigger works. Otherwise it is ignored.
диапазон: ≥ 0
category_idsstring[]
Leaf category first.
элементов: ≤ 10
brandstring
длина: ≤ 200
paramsobject
translationsobject
Translations 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

idinteger
namestring
channelstring
пример: "email"
topicstring
Subscription topic the message belongs to.
transactionalboolean
languagestring
Main language of content: recipients whose profile language has no version get it.
длина: ≤ 16 · пример: "de"
contentobject
Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
translationsobject
Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
versioninteger
Grows when any language version changes.
created_atstring (date-time) | null
updated_atstring (date-time) | null

MessageTemplateInput

namestringобязательно
длина: ≤ 120
channel_keystringобязательно
Channel of the template; cannot be changed later.
topicstring
по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$
transactionalboolean
по умолчанию: false
languagestring
Main language of content; the project default language if omitted.
длина: ≤ 16 · пример: "de"
contentobjectобязательно
Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
translationsobject
Other language versions; each is validated like content. Omit to keep the stored versions, pass {} to delete them.
ключей: ≤ 50

AnalyticsReportType

string

значения: "report", "funnel", "retention", "paths", "revenue", "traffic", "attribution"

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 catalog
operatorstringобязательно
Operator of the property type, as in segment rules
valueany
Value for the operator; absent for is_set / is_not_set

ProfileRules

Segment rules (docs/architecture/segmentation.md): only events of matching profiles are counted. Null or an empty group — all profiles.

Объект с произвольными ключами.

Breakdown

sourcestringобязательно
значения: "property", "context"
keystringобязательно
Event property, or a page field: page.path, page.referrer, campaign.source, campaign.medium, campaign.name, locale

AnalyticsInterval

string

значения: "day", "week", "month"

ReportQuery

seriesobject[]обязательно
элементов: 1–5
- eventstring | null
- metricstring
  значения: "count", "profiles", "per_profile", "sum", "avg"
- propertystring | null
- filtersPropertyFilter[]
profilesProfileRules
breakdownBreakdown
intervalAnalyticsInterval
periodAnalyticsPeriod
compareboolean

FunnelQuery

stepsobject[]обязательно
элементов: 2–10
- eventstringобязательно
- filtersPropertyFilter[]
windowobject
Conversion window from the first step, up to 90 days
- amountinteger
  диапазон: ≥ 1
- unitstring
  значения: "minute", "hour", "day"
orderstring
значения: "sequential", "strict"
profilesProfileRules
breakdownBreakdown
periodAnalyticsPeriod

RetentionQuery

startobjectобязательно
- eventstring | null
- filtersPropertyFilter[]
returnobject
- eventstring | null
- filtersPropertyFilter[]
cohortstring
значения: "first", "period"
intervalAnalyticsInterval
periodsinteger
Up to 30 days, 12 weeks or 12 months
диапазон: 1–30
returnsstring
значения: "exact", "rolling"
profilesProfileRules
periodAnalyticsPeriod

PathQuery

eventstringобязательно
filtersPropertyFilter[]
directionstring
значения: "after", "before"
stepsinteger
диапазон: 1–5
gap_minutesinteger
диапазон: 1–1440
excludestring[]
элементов: ≤ 20
profilesProfileRules
periodAnalyticsPeriod

RevenueQuery

eventstring
Purchase event; by default from the prediction settings
amountstring
Numeric order amount property
product_propertystring
intervalAnalyticsInterval
ltv_intervalstring
значения: "week", "month"
ltv_periodsinteger
диапазон: 1–12
profilesProfileRules
periodAnalyticsPeriod

TrafficQuery

dimensionstring
значения: "channel", "source", "source_medium", "campaign", "referrer", "landing"
intervalAnalyticsInterval
eventstring
amountstring
profilesProfileRules
periodAnalyticsPeriod

AttributionQuery

window_daysinteger
значения: 1, 3, 7, 14, 30
modelstring
значения: "last", "first", "linear"
intervalAnalyticsInterval
eventstring
amountstring
profilesProfileRules
periodAnalyticsPeriod

ReportResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
bucketsstring (date)[]обязательно
seriesobject[]обязательно
Per series: index, total, values per bucket, previous period, breakdown

FunnelResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
stepsobject[]обязательно
Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
breakdownobject[]обязательно
Per breakdown value: value, steps (reached per step)
time_samplenumber
Share of profiles used for time between steps

RetentionResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- 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 definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
totalintegerобязательно
nodesobject[]обязательно
linksobject[]обязательно
pathsobject[]обязательно
Most frequent paths: events, profiles
truncatedboolean

RevenueResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
currencystring | null
other_currency_ordersinteger
summaryobjectобязательно
seriesobjectобязательно
ltvobjectобязательно
productsobject[]обязательно
categoriesobject[]обязательно

TrafficResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
currencystring | null
purchasesboolean
summaryobjectобязательно
rowsobject[]обязательно
row_countinteger
chartobjectобязательно

AttributionResult

definitionobjectобязательно
Normalized definition
periodobjectобязательно
- fromstring (date)
- tostring (date)
currencystring | null
summaryobjectобязательно
channelsobject[]обязательно
Per channel: channel, clicks, touched_orders, revenue and orders by model
itemsobject[]обязательно
Per campaign, journey, message channel or widget
chartobject

SavedReport

idintegerобязательно
namestringобязательно
typeAnalyticsReportTypeобязательно
created_atstring (date-time)обязательно
updated_atstring (date-time)обязательно

SavedReportDetail

Все поля SavedReport:

definitionobjectобязательно
viewobjectобязательно
Page view settings: chart type, metric

SavedReportInput

namestringобязательно
длина: ≤ 120
typeAnalyticsReportTypeобязательно
definitionobjectобязательно
Definition of the report type — see the run operations
viewobject

SavedReportPatch

namestring
длина: ≤ 120
definitionobject
viewobject

Dashboard

idintegerобязательно
namestringобязательно
layoutobject[]обязательно
элементов: ≤ 24
- report_idintegerобязательно
- sizestring
  значения: "half", "full"
periodAnalyticsPeriodобязательно
created_atstring (date-time)обязательно
updated_atstring (date-time)обязательно

DashboardInput

namestringобязательно
длина: ≤ 120
layoutobject[]
элементов: ≤ 24
- report_idintegerобязательно
- sizestring
  значения: "half", "full"
periodAnalyticsPeriod

DashboardPatch

namestring
длина: ≤ 120
layoutobject[]
элементов: ≤ 24
- report_idintegerобязательно
- sizestring
  значения: "half", "full"
periodAnalyticsPeriod

LoyaltyProfileRef

typestringобязательно
значения: "user_id", "anonymous_id", "email", "phone", "telegram_chat_id", "viber_id", "web_push"
valuestringобязательно

LoyaltyAccount

memberboolean
balanceinteger
Available points
pendinginteger
Points waiting for the return period
tierstring | null
tier_spendnumber
expiringinteger
Points expiring within 30 days
expires_atstring (date-time) | null
enrolled_atstring (date-time) | null
referral_codestring | null
Code of the member for inviting friends.
referral_urlstring | null
Referral link (?ref= on the store page) when referrals are on.
referralsobject
Friends who came with the code, of them rewarded, and points for them.
- invitedinteger
- rewardedinteger
- pointsinteger

LoyaltyCalculation

memberboolean
balanceinteger
tierstring | null
max_pointsinteger
max_discountnumber
earn_pointsinteger
point_valuenumber
currencystring | null

LoyaltyRedemption

idstring
statusstring
значения: "held", "confirmed", "cancelled", "expired"
pointsinteger
returnedinteger
discountnumber
cart_idstring
order_idstring | null
held_untilstring (date-time)
confirmed_atstring (date-time) | null

LoyaltyTransaction

idinteger
typestring
значения: "earn", "cancel", "expire", "adjust", "redeem", "refund"
pointsinteger
referencestring | null
reasonstring | null
rulestring | null
created_atstring (date-time)
referralstring | null
Referral 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 | null
Discount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.
starts_atstring (date-time) | null
ends_atstring (date-time) | null
End of the promotion (exclusive).
validity_daysinteger | null
A 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обязательно
- totalinteger
- availableinteger
- issuedinteger
- usedinteger
- usesinteger
- revenuenumber
  Sum of the orders with codes of the pool.

PromoCode

poolstring
Pool key.
codestringобязательно
statusstringобязательно
значения: "available", "issued", "used", "shared"
issued_atstring (date-time) | null
expires_atstring (date-time) | null
used_atstring (date-time) | null

LoyaltyReferral

statusstring
pending — waiting for the friend's first order.
значения: "pending", "rewarded", "expired", "limit", "cancelled"
codestring
friend_pointsinteger
friend_promo_codestring | null
rewardedboolean
The friend has received the reward.
expires_atstring (date-time)
The first order of the friend rewards the member until this moment.

MessageSendInput

Pass template_id (and integration_id if needed) for one message, or steps for a cascade — not both.

identityIdentityRefобязательно
The recipient. A profile with this identity is created if there is none.
traitsobject
Traits written to the profile before sending, available in the template as traits.*.
ключей: ≤ 100
template_idinteger
Message template. A transactional template skips consents, frequency limits and quiet hours, but not hard blocks of the channel (address does not exist, bot blocked); other templates follow all messaging rules.
integration_idinteger | null
Channel integration of the template's channel; may be omitted when the channel has exactly one active integration.
dataobject
Per-message data, available in the template as context.data.* (order number, confirmation code).
stepsCascadeStep[]
Cascade (plans with the cascades feature): 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)
statusstring
queued → sent → delivered; scheduled — waiting (quiet hours, warm-up); skipped — not sent, see reason; failed/bounced — see reason and error.
значения: "queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"
reasonstring | null
Why it was skipped or failed: no_recipient, unsubscribed, recipient_blocked, suppressed, frequency_limit, quota_exceeded, feature_unavailable, delivery_failed, recipient_unreachable, undelivered, template_error, integration_unavailable …
errorstring | null
channelstring
template_idinteger | null
integration_idinteger | null
profile_idinteger
transactionalboolean
originstring | null
api for messages sent with messages.send, store for store emails (emails.send).
created_atstring (date-time) | null
scheduled_forstring (date-time) | null
sent_atstring (date-time) | null
delivered_atstring (date-time) | null
opened_atstring (date-time) | null
clicked_atstring (date-time) | null
failed_atstring (date-time) | null

CascadeStep

integration_idintegerобязательно
template_idintegerобязательно
Template of the integration's channel.
wait_forstring
What counts as success. delivered needs an integration that reports delivery (not email through own SMTP), opened — a channel that reports reading (email, WhatsApp, Viber).
значения: "sent", "delivered", "opened" · по умолчанию: "sent"
timeoutobject
How long to wait for delivered or opened after sending; 15 minutes by default.
- amountinteger
  диапазон: 1–3650
- unitstring
  значения: "minute", "hour", "day", "week"

CascadeStatus

idstring (uuid)
statusstring
reached — a step succeeded; failed — no channel reached the profile.
значения: "running", "reached", "failed"
stepinteger
Current step, from 0.
reached_channelstring | null
profile_idinteger
originstring | null
created_atstring (date-time) | null
finished_atstring (date-time) | null
messagesMessageStatus[]
Messages of the steps tried so far.

ChatVisitorMessage

idinteger
authorstring
значения: "visitor", "operator", "system"
bodystring
operatorstring | null
First name of the operator
actionstring | null
closed — the conversation was closed
created_atstring (date-time)
botboolean
Reply of the AI bot; operator holds the bot name

ChatVisitorConversation

idstring (uuid)
statusstring
значения: "open", "waiting", "closed"
ratinginteger | null
tokenstring
Returned for a new conversation or when the request had no valid token; store it
botboolean
The AI bot leads the conversation: the widget offers to call an operator (POST /chat/handoff)

Conversation

idstring (uuid)обязательно
profile_idintegerобязательно
channelstringобязательно
web — the website chat; messengers need the chat_messengers plan feature.
значения: "web", "telegram", "whatsapp", "viber"
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 | null
ratinginteger | null
Customer rating after the conversation.
диапазон: 1–5
rating_commentstring | null
last_message_atstring (date-time) | null
last_message_authorstring | null
значения: "visitor", "operator", "system", null
first_reply_atstring (date-time) | null
created_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 (see action).
значения: "visitor", "operator", "system"
viastring | null
Where an answer or action came from: the operator inbox or the API.
значения: "inbox", "api", null
api_keystring | null
Name of the API key that answered or closed the conversation.
bodystringобязательно
actionstring | null
значения: "assigned", "unassigned", "closed", "reopened", null
statusstring | null
Delivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.
created_atstring (date-time)обязательно

ConversationDetail

Все поля Conversation:

messagesConversationMessage[]обязательно
The latest messages, oldest first.

StoreEmailInput

tostring (email)обязательно
Recipient address. The profile is found by this email or created.
длина: ≤ 254
subjectstring
Required unless an order template is enabled for kind and order is given.
длина: ≤ 998
htmlstring
Ready HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled for kind and order is given.
длина: ≤ 1000000
textstring | null
Plain-text part; built from the HTML when empty.
длина: ≤ 1000000
reply_tostring (email) | null
Overrides the Reply-To of the email integration.
from_namestring | null
Overrides the sender name of the email integration; the sender address is always the integration's.
длина: ≤ 100
kindstringобязательно
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. For order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded with order, an enabled OneTrace template builds the email instead of html (see GET /emails/settings).
шаблон: ^[a-z0-9_]{1,40}$
languagestring | null
Customer language tag: picks the language version of an order template; for history and reports otherwise.
длина: ≤ 20
integration_idinteger | null
Email integration; may be omitted when the project has exactly one active.
traitsobject | null
Profile traits to update before sending (name, phone).
attachmentsobject[]
Up to 5 files, 5 MB in total.
элементов: ≤ 5
- namestringобязательно
  длина: ≤ 200
- typestringобязательно
  значения: "application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"
- contentstring (byte)обязательно
  File contents in base64.
orderStoreOrder

StoreEmailStatus

Все поля MessageStatus:

kindstring | null
templateboolean
The email is built from a OneTrace order template.

StoreOrder

Order data for order email templates — the order template variable.

order_idstringобязательно
длина: ≤ 100
numberstring | null
Number shown to the customer; order_id when empty.
длина: ≤ 100
urlstring (uri) | null
Order page for the customer.
created_atstring (date-time) | null
currencystringобязательно
шаблон: ^[A-Za-z]{3}$
amountnumberобязательно
Order total.
subtotalnumber | null
discountnumber | null
shippingnumber | null
taxnumber | null
refund_amountnumber | null
couponstring | null
payment_methodstring | null
shipping_methodstring | null
carrierstring | null
tracking_numberstring | null
tracking_urlstring (uri) | null
estimated_deliverystring (date) | null
reasonstring | null
Cancellation or refund reason.
notestring | null
payment_instructionsstring | null
Bank transfer details and similar instructions.
productsobject[]
элементов: ≤ 100
- product_idstring | null
- variant_idstring | null
- skustring | null
- product_namestringобязательно
  длина: ≤ 300
- quantitynumberобязательно
- pricenumberобязательно
- totalnumber | null
  Line total; price × quantity when empty.
- image_urlstring (uri) | null
- urlstring (uri) | null
- optionsstring | null
  Variant options as text: «Size: M, colour: white».
  длина: ≤ 500
shipping_addressobject | null
- namestring | null
  длина: ≤ 200
- companystring | null
  длина: ≤ 200
- address1string | null
  длина: ≤ 200
- address2string | null
  длина: ≤ 200
- citystring | null
  длина: ≤ 200
- regionstring | null
  длина: ≤ 200
- postcodestring | null
  длина: ≤ 200
- countrystring | null
  длина: ≤ 200
- phonestring | null
  длина: ≤ 200
billing_addressobject | null
- namestring | null
  длина: ≤ 200
- companystring | null
  длина: ≤ 200
- address1string | null
  длина: ≤ 200
- address2string | null
  длина: ≤ 200
- citystring | null
  длина: ≤ 200
- regionstring | null
  длина: ≤ 200
- postcodestring | null
  длина: ≤ 200
- countrystring | null
  длина: ≤ 200
- phonestring | null
  длина: ≤ 200

StoreEmailSettings

relayboolean
Send all store emails through OneTrace (store emails section).
integration_idinteger | null
templatesobject
Order email kinds built from OneTrace templates: the store does not send its own email for them and passes order instead.

StoreMcpServer

idstring (uuid)
urlstring
statusstring
error — see error; the bot works without this server
значения: "pending", "ok", "error"
errorstring | null
toolsstring[]
Contract tools the bot may use
checked_atstring (date-time) | null

Справочник API

Общие сведения

Ключи

Ingest

Track an event

Тело запросаобязательно

Ответы

Identify a profile and update traits

Тело запросаобязательно

Ответы

Track a page view

Тело запросаобязательно

Ответы

Link a previous identifier to a user

Тело запросаобязательно

Ответы

Send up to 500 messages at once

Тело запросаобязательно

Ответы

Check the API key

Ответы

Push

VAPID public key for PushManager.subscribe()

Ответы

Store a browser push subscription and link it to the visitor

Тело запросаобязательно

Ответы

Forget a browser push subscription

Тело запросаобязательно

Ответы

Recommendations

Product recommendations for the site

Параметры

Ответы

Website widget configured in the admin panel

Параметры

Ответы

Meta

This OpenAPI specification

Ответы

Profiles

Get a profile by any identifier

Параметры

Ответы

Erase a profile and all profiles merged into it (GDPR)

Параметры

Ответы

Profile events, newest first, 50 per page

Параметры

Ответы

Subscribe or unsubscribe a profile

Параметры

Тело запросаобязательно

Ответы

Create a Telegram deep link for a profile

Тело запросаобязательно

Ответы

Create a Viber bot deep link for a profile

Тело запросаобязательно

Ответы

Products

Create or update products and categories

Тело запросаобязательно

Ответы

Delete products

Тело запросаобязательно

Ответы

Catalog

Events seen in the project with their properties

Ответы

Profile traits of the project

Ответы

Segments

List segments

Параметры

Ответы

Create a segment

Параметры

Тело запросаобязательно

Ответы