Data schemas
Request and response objects. The types in method tables link here.
#Money
A monetary amount.
| Field | Type | Description |
|---|---|---|
amount | string required | Amount as a STRING (never a float), for example "123.45". |
currency | string required | ISO 4217 currency code: RUB (RU), GBP (EN), IDR (ID). |
#FieldError
A validation error for one field.
| Field | Type | Description |
|---|---|---|
field | string required | Path to the request field as a JSON Pointer (RFC 6901): "/limit", "/events/0". |
code | string required | Machine-readable reason: out_of_range, required, invalid_format… |
message | string required | Human-readable explanation. |
#Problem
An error in application/problem+json (RFC 9457).
| Field | Type | Description |
|---|---|---|
type | string required | Link to the code description: https://<cell domain>/developers/errors#<code>. |
title | string required | Short title, the same for a given code. |
status | integer required | HTTP status. |
code | string required | Stable machine-readable code. Branch on it, not on the text. Values: invalid_api_key wrong_cell integration_inactive tenant_inactive scope_missing ip_not_allowed feature_not_in_plan pii_transfer_not_allowed not_found method_not_allowed bad_request idempotency_key_required idempotency_conflict operation_in_progress invalid_state precondition_failed precondition_required payload_too_large validation_failed rate_limited spend_limit_reached insufficient_funds wallet_suspended internal_error service_unavailable upstream_unavailable |
detail | string required | Explanation of this particular case. Do not parse this text. |
request_id | string required | Request id (equals the X-Request-Id header). Quote it when contacting support. |
errors | array<FieldError> optional | Per-field errors (validation_failed only). |
correct_base_url | string optional | wrong_cell only: the base URL of the cell the key was issued in. |
topup_url | string optional | wallet_suspended only: the dashboard address where the wallet is topped up. |
balance | Money optional, may be null | wallet_suspended only: the wallet balance at the time of the refusal. |
#Usage
The cost of a paid operation.
| Field | Type | Description |
|---|---|---|
cost | Money required | |
model | string required | The model that performed the operation. |
#Operation
An asynchronous operation (one envelope for all modules).
| Field | Type | Description |
|---|---|---|
id | string required | Operation id. |
type | string required | Operation type, for example "article.generation". |
status | string required | Operation state. Values: queued running succeeded failed canceled |
created_at | string required | Creation time, ISO 8601 UTC. |
completed_at | string optional | Completion time; only for succeeded, failed, canceled. |
resource | object optional | The resource the operation relates to; read the result through it. |
resource.type | string required | |
resource.id | string required | |
error | object optional | failed only: a code from the error catalog or the operation-specific reason code. |
error.code | string required | |
error.message | string required | |
usage | Usage optional | Paid operations only. |
#OperationEnvelope
The 202 response to a creating request.
| Field | Type | Description |
|---|---|---|
operation | Operation required |
#Me
Who you are: tenant, integration, key, limits, wallet.
| Field | Type | Description |
|---|---|---|
tenant | object required | The tenant that owns the key. |
tenant.id | string required | |
tenant.name | string required | |
cell | string required | Platform cell: ru, en or id. Values: ru en id |
base_url | string required | Base URL of this cell API. |
integration | object required | The integration (service account) that owns the key. |
integration.id | string required | |
integration.name | string required | |
channel_id | string required, may be null | The integration "api" channel; null — the channel is not created yet. |
key | object required | |
key.key_id | string required | Public key id (not a secret). |
key.mode | string required | Values: live test |
key.scopes | array<string> required | Effective scopes: integration scopes ∩ the owner current permissions ∩ the licence. Values: conversations:read conversations:write ai_seller:invoke leads:read leads:write leads:score analytics:read analytics:write dashboards:read articles:read articles:write articles:generate strategist:read strategist:write strategist:chat webhooks:manage |
key.expires_at | string required | Key expiry, ISO 8601 UTC. |
key.ip_allowlist | array<string> required, may be null | Allowed addresses and networks (CIDR); null — any address. |
limits | object required | Request rate limits. |
limits.read_per_min | integer required | |
limits.write_per_min | integer required | |
limits.paid_per_min | integer required | |
limits.paid_concurrency | integer required | Concurrent paid operations per tenant. |
wallet | object required | The tenant wallet (AI operations). |
wallet.balance | Money required, may be null | The wallet balance in roubles; null — the state is unknown or the tenant is not billed. |
wallet.state | string required | ok — fine; low — running low; negative — the balance is below zero; blocked — the wallet is blocked; unknown — the state could not be obtained. Details: GET /wallet. Values: ok low negative blocked unknown |
wallet.exchange | string required | suspended for negative and blocked: every route except /me and /wallet answers 402 wallet_suspended. Values: active suspended |
wallet.topup_url | string required | The dashboard address where the wallet is topped up. |
wallet.daily_spend | object required | |
wallet.daily_spend.limit | Money required, may be null | The integration daily spend limit; null — not set. |
wallet.daily_spend.used | Money required | |
crm_mode | string required | The tenant CRM mode: "internal" (our CRM) or an external system. |
#Webhook
An event subscription. The secret is not returned in such responses.
| Field | Type | Description |
|---|---|---|
id | string required | Subscription id. |
url | string required | Receiving URL: https, port 443, a host name (not an IP), no redirects. |
events | array<string> required | Event types: an exact type or a family pattern "family.*". Available types: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean required | Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false. |
description | string required, may be null | A note for yourself, up to 200 characters. |
status | string required | active — deliveries flow; paused — suspended. Values: active paused |
created_at | string required | ISO 8601 UTC. |
updated_at | string required | ISO 8601 UTC. |
secret_rotated_at | string required, may be null | Time of the last secret rotation; null — never rotated. |
previous_secret_expires_at | string required, may be null | While the rotation window (24 hours) is open — when the previous secret stops working; otherwise null. |
#WebhookWithSecret
The subscription together with its secret: the creation and rotation response.
| Field | Type | Description |
|---|---|---|
id | string required | Subscription id. |
url | string required | Receiving URL: https, port 443, a host name (not an IP), no redirects. |
events | array<string> required | Event types: an exact type or a family pattern "family.*". Available types: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean required | Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false. |
description | string required, may be null | A note for yourself, up to 200 characters. |
status | string required | active — deliveries flow; paused — suspended. Values: active paused |
created_at | string required | ISO 8601 UTC. |
updated_at | string required | ISO 8601 UTC. |
secret_rotated_at | string required, may be null | Time of the last secret rotation; null — never rotated. |
previous_secret_expires_at | string required, may be null | While the rotation window (24 hours) is open — when the previous secret stops working; otherwise null. |
secret | string required, may be null | The signing secret: shown ONCE, in the creation or rotation response. On an idempotent replay of the request — null: keep the secret from the first response. |
#WebhookCreate
The subscription creation body.
| Field | Type | Description |
|---|---|---|
url | string required | Receiving URL: https, port 443, a host name (not an IP), no redirects. |
events | array<string> required | Event types: an exact type or a family pattern "family.*". Available types: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean optional | Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false. |
description | string optional, may be null | A note for yourself, up to 200 characters. |
#WebhookUpdate
The update body: pass at least one field.
| Field | Type | Description |
|---|---|---|
url | string optional | Receiving URL: https, port 443, a host name (not an IP), no redirects. |
events | array<string> optional | Event types: an exact type or a family pattern "family.*". Available types: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean optional | Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false. |
description | string optional, may be null | A note for yourself, up to 200 characters. |
status | string optional | Pause or resume deliveries. Values: active paused |
#WebhookPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<Webhook> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#WebhookTestResult
The 202 response to a test delivery. The event body arrives at your URL with livemode: false.
| Field | Type | Description |
|---|---|---|
event_id | string required, may be null | The test event id. |
type | string required | |
status | string required | The event is queued; it goes out on the next delivery run (within a minute). |
#WebhookDelivery
A delivery log entry (kept for 30 days).
| Field | Type | Description |
|---|---|---|
id | string required | Delivery id. |
event_id | string required | Event id. |
state | string required | pending — waiting for an attempt; delivered — delivered; failed — an attempt failed, a retry follows; dead — retries exhausted. Values: pending delivered failed dead |
attempt | integer required | Number of the last attempt (0 — none yet). |
status_code | integer required, may be null | HTTP status of the subscriber response; null if there was none. |
duration_ms | integer required, may be null | Attempt duration, ms. |
error | string required, may be null | Failure reason: timeout, connection or certificate error, a 3xx response. |
next_attempt_at | string required, may be null | Time of the next attempt; null if no more attempts follow. |
delivered_at | string required, may be null | Time of successful delivery. |
created_at | string required |
#WebhookDeliveryPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<WebhookDelivery> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#Wallet
The state of the tenant wallet and of data exchange.
| Field | Type | Description |
|---|---|---|
balance | Money required, may be null | The wallet balance in roubles (the wallet is kept in RUB on every cell); null — the state is unknown or the tenant is not billed. |
state | string required | ok — fine; low — running low (exchange continues); negative — the balance is below zero; blocked — the wallet is blocked; unknown — the state could not be obtained. Values: ok low negative blocked unknown |
exchange | string required | suspended for negative and blocked: every route except /me and /wallet answers 402 wallet_suspended and webhooks are postponed. With unknown it stays active: free reads proceed with the Sapport-Wallet-State: unknown header, paid operations are closed (503). Values: active suspended |
topup_url | string required | The dashboard address where the wallet is topped up (a staff member with the top-up permission must sign in). |
daily_spend | object required, may be null | The integration daily spend; null while spend is not tracked per integration. |
daily_spend.limit | Money required, may be null | The integration daily spend limit; null — not set. |
daily_spend.used | Money required |
#TimeseriesItem
One time series.
| Field | Type | Description |
|---|---|---|
metric | string required | Values: sessions pageviews visitors bounce_rate impressions clicks ctr position ai_referrals bot_hits leads deals_won revenue |
from | string required | Date YYYY-MM-DD. |
to | string required | Date YYYY-MM-DD. |
granularity | string required | Values: day week |
agg | string required | How the series is folded over the period. Values: sum avg |
engine | string required, may be null | The search engine of the series; null for metrics not tied to search. Values: google yandex bing |
availability | string required | Values: ok no_data no_source |
reason | string required, may be null | Reason code when availability is not ok. |
series | array<object> required | The series; days without data are filled with zeros. With the weekly step date is the first day of the week. |
comparison | object required | |
comparison.current | object required, may be null | |
comparison.prev | object required, may be null | |
comparison.delta_pct | number required, may be null | Change in percent; null if there is nothing to compare with or the base is zero. |
comparison.data_through | string required, may be null | The last date the data is complete. |
summary | object required, may be null | |
summary.total | object required, may be null | |
summary.latest | object required, may be null | |
summary.non_zero_days | integer required | |
cluster_applied | boolean required | |
data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
#TimeseriesResponse
One series (a single metric) or items in request order (several metrics).
| Field | Type | Description |
|---|---|---|
data | object required |
#TrafficSourceRow
A first-visit source over the period.
| Field | Type | Description |
|---|---|---|
source | string required | Values: google yandex bing chatgpt perplexity ai_other social ads direct other |
kind | string required | Values: search ai_assistant social ads direct other |
sessions | integer required | |
visitors | integer required, may be null | Daily unique visitors summed over the period; null when they cannot be counted (anonymous beacon). |
leads | integer required | |
series | array<object> optional | Only with include=series. |
#TrafficSourcesResponse
Traffic sources, most sessions first.
| Field | Type | Description |
|---|---|---|
data | array<TrafficSourceRow> required | |
data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
#FunnelStep
A funnel step with its own availability and date.
| Field | Type | Description |
|---|---|---|
key | string required | Values: impressions clicks sessions leads deals_created deals_won revenue |
availability | string required | Values: ok no_data no_source |
sources | array<string> required | |
unit | string required | Values: count money |
current | object required, may be null | |
prev | object required, may be null | |
delta_pct | number required, may be null | |
data_through | string required, may be null |
#FunnelResponse
The funnel impressions → clicks → sessions → leads → deals → revenue.
| Field | Type | Description |
|---|---|---|
data | object required | |
data.engine | string required | Values: yandex google both |
data.from | string required | Date YYYY-MM-DD. |
data.to | string required | Date YYYY-MM-DD. |
data.steps | array<FunnelStep> required | |
data.by_channel | array<object> required | |
data.search_by_engine | array<object> optional | Only engine=both: the engines separately. |
data.by_product | array<object> required | |
data.crm | object required | |
data.crm.availability | string required | Values: ok no_data |
data.crm.reason | string optional | |
data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
#VisibilityResponse
Visibility: five independent sections.
| Field | Type | Description |
|---|---|---|
data | object required | |
data.from | string required | Date YYYY-MM-DD. |
data.to | string required | Date YYYY-MM-DD. |
data.engine | string required | Values: yandex google both |
data.share | object required | |
data.share.availability | string required | |
data.share.reason | string optional | |
data.share.source | string required | |
data.share.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.share.data | object required | |
data.distribution | object required | |
data.distribution.availability | string required | |
data.distribution.reason | string optional | |
data.distribution.source | string required | |
data.distribution.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.distribution.data | object required | |
data.sov | object required | |
data.sov.availability | string required | |
data.sov.reason | string optional | |
data.sov.source | string required | |
data.sov.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.sov.data | object required | |
data.aeo | object required | |
data.aeo.availability | string required | |
data.aeo.reason | string optional | |
data.aeo.source | string required | |
data.aeo.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.aeo.data | object required | |
data.regions | object required | |
data.regions.availability | string required | |
data.regions.reason | string optional | |
data.regions.source | string required | |
data.regions.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.regions.data | object required |
#OverviewResponse
A slice of the Overview screen: the requested blocks in screen order.
| Field | Type | Description |
|---|---|---|
data | object required | |
data.from | string required | Date YYYY-MM-DD. |
data.to | string required | Date YYYY-MM-DD. |
data.blocks | object required | |
data.blocks.strategist | object optional | |
data.blocks.strategist.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.strategist.reason | string optional | |
data.blocks.strategist.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.kpi | object optional | |
data.blocks.kpi.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.kpi.reason | string optional | |
data.blocks.kpi.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.funnel | object optional | |
data.blocks.funnel.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.funnel.reason | string optional | |
data.blocks.funnel.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.attention | object optional | |
data.blocks.attention.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.attention.reason | string optional | |
data.blocks.attention.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.ads | object optional | |
data.blocks.ads.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.ads.reason | string optional | |
data.blocks.ads.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.ai_assistants | object optional | |
data.blocks.ai_assistants.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.ai_assistants.reason | string optional | |
data.blocks.ai_assistants.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.popular_pages | object optional | |
data.blocks.popular_pages.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.popular_pages.reason | string optional | |
data.blocks.popular_pages.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.clusters | object optional | |
data.blocks.clusters.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.clusters.reason | string optional | |
data.blocks.clusters.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.data_trust | object optional | |
data.blocks.data_trust.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.data_trust.reason | string optional | |
data.blocks.data_trust.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.sitemap_health | object optional | |
data.blocks.sitemap_health.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.sitemap_health.reason | string optional | |
data.blocks.sitemap_health.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
data.blocks.status | object optional | |
data.blocks.status.availability | string required | Values: ok no_data no_source not_connected |
data.blocks.status.reason | string optional | |
data.blocks.status.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
#PulseAlert
A Pulse finding: a demand topic that started to grow.
| Field | Type | Description |
|---|---|---|
id | string required | |
topic_id | string required | |
topic_name | string required, may be null | |
keyword | string required | |
horizon | string required | |
status | string required | |
episode_start | string required, may be null | |
last_seen | string required, may be null | |
score | number required, may be null | |
volume | number required, may be null | |
growth | number required, may be null | |
sources | array<object> required | |
strategist_topic | object required, may be null | The linked strategist queue topic. |
strategist_topic.id | string required | |
strategist_topic.status | string required |
#PulseResponse
A slice of the Pulse screen.
| Field | Type | Description |
|---|---|---|
data | object required | |
data.period | object required | |
data.period.from | string required | Date YYYY-MM-DD. |
data.period.to | string required | Date YYYY-MM-DD. |
data.new_7d | integer required | |
data.truncated | boolean required | |
data.alerts | array<PulseAlert> required | |
data.data_as_of | object required | Source → the date up to which its data is complete. A source with no data is not listed. |
#ArticleSummary
A tenant article without its content (a list item).
| Field | Type | Description |
|---|---|---|
id | string required | Article id. |
title | string required | |
slug | string required, may be null | |
status | string required | draft — a draft; review — in review; approved — approved; published — published; rejected — rejected; transferred — moved to the blog; external — external. |
locale | string required, may be null | Article language (ru, en, id). |
keyword | string required, may be null | The main query of the article. |
meta_title | string required, may be null | |
meta_description | string required, may be null | |
cover_image_url | string required, may be null | |
word_count | integer required | |
created_at | string required, may be null | ISO 8601 UTC. |
updated_at | string required, may be null | ISO 8601 UTC. |
published_at | string required, may be null | ISO 8601 UTC. |
#ArticlePublication
The state of the latest publication of the article through the site module.
| Field | Type | Description |
|---|---|---|
target | string required | Where it is published: the module on your site. |
state | string required | queued — in the queue or handed to the module; applied — applied on the site; skipped — skipped; conflict — the site edit is newer; failed — an error. Values: queued applied skipped conflict failed |
published_url | string required, may be null | The article URL on your site once applied. |
error | string required, may be null | The failure reason, up to 200 characters. |
#Article
A tenant article with its content.
| Field | Type | Description |
|---|---|---|
id | string required | Article id. |
title | string required | |
slug | string required, may be null | |
status | string required | draft — a draft; review — in review; approved — approved; published — published; rejected — rejected; transferred — moved to the blog; external — external. |
locale | string required, may be null | Article language (ru, en, id). |
keyword | string required, may be null | The main query of the article. |
meta_title | string required, may be null | |
meta_description | string required, may be null | |
cover_image_url | string required, may be null | |
word_count | integer required | |
created_at | string required, may be null | ISO 8601 UTC. |
updated_at | string required, may be null | ISO 8601 UTC. |
published_at | string required, may be null | ISO 8601 UTC. |
content | object required | The article body in the requested format: html and markdown — a string; blocks — an array of {type, html} blocks. The HTML is stripped of scripts, dangerous links and event handlers. For an article whose body moved to the platform blog the content is empty. |
publication | ArticlePublication required, may be null | null — the article has not been published through the site module yet. |
#ArticlePage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<ArticleSummary> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#StrategistReportSummary
A strategist report header (a list item).
| Field | Type | Description |
|---|---|---|
id | string required | Report id. |
report_date | string required | Report date, YYYY-MM-DD. |
report_type | string required | daily — daily, weekly — weekly. Values: daily weekly |
summary_text | string required | The short summary. |
actions_count | integer required | How many actions are recommended. |
data_as_of | object required | Data freshness: for each metric (key) the date of the latest data, YYYY-MM-DD; the snapshot key is the date of the analytics snapshot the report is built on. Empty if there is no snapshot. |
delivered_at | string required, may be null | When the report was delivered to the owner; null — not yet. ISO 8601 UTC. |
#StrategistReportAction
A recommended action.
| Field | Type | Description |
|---|---|---|
title | string required | |
priority | string required | Action priority (high, medium, low). |
rationale | string required | The rationale. Competitor names are hidden in it. |
target_ref | string required, may be null | A reference to the target (article, product, campaign); null if there is none or it is a competitor. |
expected_effect | object required, may be null | The expected effect; null if the strategist named none. |
expected_effect.metric | string required, may be null | |
expected_effect.delta | string required, may be null | |
expected_effect.horizon_days | integer required, may be null | |
check_after_days | integer required, may be null | In how many days to check the result. |
basis | string required | What the conclusion rests on: observed_pattern — observed elsewhere; own_measured — measured on your data; research — a study; hypothesis — a hypothesis. Values: observed_pattern own_measured research hypothesis |
#StrategistEvidence
Evidence per action. Verbatim competitor wording is not returned.
| Field | Type | Description |
|---|---|---|
actions | array<object> required | |
validation | object optional | The evidence check result. relevance_checked is always false: references and quotes are checked, not the meaning. |
validation.refs_valid | boolean required | |
validation.excerpts_valid | boolean required | |
validation.relevance_checked | boolean required | |
validation.limitations | array<string> required |
#StrategistReport
A full strategist report. The analytics snapshot, model and cost are not returned.
| Field | Type | Description |
|---|---|---|
id | string required | |
report_date | string required | |
report_type | string required | Values: daily weekly |
summary_text | string required | |
data_as_of | object required | Data freshness: for each metric (key) the date of the latest data, YYYY-MM-DD; the snapshot key is the date of the analytics snapshot the report is built on. Empty if there is no snapshot. |
highlights | array<object> required | What goes well. |
concerns | array<object> required | What is concerning. |
actions | array<StrategistReportAction> required | |
evidence | StrategistEvidence required |
#StrategistReportPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<StrategistReportSummary> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#StrategistTopic
A topic in the strategist queue.
| Field | Type | Description |
|---|---|---|
id | string required | |
title | string required, may be null | |
rationale | string required, may be null | Why the topic is proposed. For competitor-sourced topics domains are hidden. |
trend_score | number required, may be null | Trend score; null — not scored. |
source | string required | Where the topic comes from: planner, competitors, chat and others. |
status | string required | proposed — awaiting a decision; approved — approved; generating — the article is being created; generated — the article is created; rejected — rejected; duplicate — a duplicate; expired — expired. Values: proposed approved generating generated rejected duplicate expired |
cluster_id | string required, may be null | |
generated_article_id | string required, may be null | The id of the created article (GET /articles/{id}). |
proposed_at | string required, may be null | ISO 8601 UTC. |
decided_at | string required, may be null | ISO 8601 UTC. |
expires_at | string required, may be null | ISO 8601 UTC. |
#StrategistTopicPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<StrategistTopic> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#StrategistAction
A strategist action proposed in your session and awaiting a decision.
| Field | Type | Description |
|---|---|---|
id | string required | |
session_id | string required, may be null | The conversation session in which the action was proposed. |
type | string required | The action kind. In v1 only propose_topic. |
title | string required | The title of the proposed topic. |
status | string required | proposed — awaiting confirmation; confirmed — confirmed, running; executed — done; failed — failed; cancelled — cancelled; expired — expired (7 days). Values: proposed confirmed executed failed cancelled expired |
result | object required, may be null | The result of an executed action: the created topic. |
result.topic_id | string required | |
error | object required, may be null | The failure reason when status = failed. |
error.code | string required | |
error.message | string required | |
created_at | string required, may be null | ISO 8601 UTC. |
decided_at | string required, may be null | ISO 8601 UTC. |
expires_at | string required, may be null | When the wait ends: creation + 7 days. ISO 8601 UTC. |
#StrategistActionPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<StrategistAction> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#Conversation
A conversation. Contains personal data (external_customer_id).
| Field | Type | Description |
|---|---|---|
id | string required | Conversation id (uuid). |
channel | string required, may be null | Channel type: api, telegram, website … |
contact_id | string required, may be null | The Sapport contact (customer) id. |
external_customer_id | string required, may be null | The customer id in your system. Channel api only; null for other channels (the messenger external id is not disclosed). |
status | string required | Conversation state: open, handoff_pending, resolved, closed … The set may grow — do not treat the list as closed. |
mode | string required | Who handles the conversation: ai — the AI answers (modes auto and supervised), operator — a human answers (copilot and manual). Values: ai operator |
language | string required, may be null | Conversation language (ISO 639-1); null — not detected. |
created_at | string required, may be null | Conversation start, ISO 8601 UTC. |
updated_at | string required | Last change or message, ISO 8601 UTC. The walk order. The unread counter does not change it. |
#MessageAttachment
A message attachment.
| Field | Type | Description |
|---|---|---|
type | string required, may be null | Content kind: image, file, audio … |
url | string required | A temporary signed link to the file (download without the API key). Do not store the link: fetch the message again. |
expires_at | string required, may be null | When the link stops working, ISO 8601 UTC (about an hour); null — a permanent path. |
#Message
A conversation message. Contains customer personal data (text, attachments).
| Field | Type | Description |
|---|---|---|
id | string required | Message id (uuid). |
conversation_id | string required | The conversation. |
sender | string required | Sender: customer, ai, operator, system. Values: customer ai operator system |
content_type | string required | Content kind: text, image, file … |
content | string required, may be null | The text; null — no text (attachment only) or the message is deleted. |
attachments | array<MessageAttachment> required | Attachments (at most one for now). |
deleted | boolean required | true — the message is deleted (returned only with include_deleted=true; no text or attachments). |
created_at | string required | Message time, ISO 8601 UTC. |
#ConversationPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<Conversation> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#MessagePage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<Message> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |
#LeadFlags
AI flags from the conversation. true/false are set only when the model is confident.
| Field | Type | Description |
|---|---|---|
buy_intent | boolean required, may be null | Intent to buy; null — the model is not sure. |
support | boolean required, may be null | A support request rather than a purchase; null — not sure. |
supplier | boolean required, may be null | A supplier or advertiser, not a customer; true archives the lead (ai_not_client). |
#LeadScore
The lead score. null for a lead that has not been scored yet.
| Field | Type | Description |
|---|---|---|
score | integer required | Score 0–100. |
grade | string required | Grade: A — 75 and above, B — 50–74, C — 25–49, D — below 25. Values: A B C D |
reason | string required, may be null | Explanation of the score; null until recorded. |
flags | LeadFlags required, may be null | |
source | string required, may be null | Who scored: ai, external or manual; null — unknown. Values: ai external manual |
model | string required, may be null | The model that set the flags; null if the score is not AI. |
scored_at | string required, may be null | When the score was set. ISO 8601 UTC. |
#LeadContact
The lead contact. Holds personal data: every disclosure is recorded in the disclosure log.
| Field | Type | Description |
|---|---|---|
id | string required | Contact id. |
first_name | string required, may be null | |
last_name | string required, may be null | |
email | string required, may be null | Personal data. |
phone | string required, may be null | Personal data. |
tags | array<string> required | |
geo_country | string required, may be null | Country by IP (ISO 3166-1 alpha-2). |
geo_city | string required, may be null | City by IP. |
#LeadAttribution
Where the lead came from (first touch). null when there is no trace.
| Field | Type | Description |
|---|---|---|
utm_source | string required, may be null | |
utm_medium | string required, may be null | |
utm_campaign | string required, may be null | |
first_page | string required, may be null | The first-visit page. |
referrer | string required, may be null |
#Lead
A tenant lead.
| Field | Type | Description |
|---|---|---|
id | string required | Lead id. |
external_id | string required, may be null | The id in an external CRM; null until an external CRM is connected. |
external_url | string required, may be null | |
version | integer required, may be null | Version for If-Match; null while the database has no version column — use etag. |
etag | string required | The version tag (equals the ETag header of the card). |
status | string required | One of six canonical statuses. Archive is the archived flag, not a status. Values: new qualified proposal negotiation won lost |
archived | boolean required | The lead is archived. |
archived_reason | string required, may be null | Archive reason, for example ai_not_client. |
owner | string required | Where the lead lives: internal — in our CRM. Values: internal external |
title | string required, may be null | |
source | string required, may be null | |
assigned_to | string required, may be null | Id of the responsible employee. |
value | Money required, may be null | |
product_id | string required, may be null | |
course_slug | string required, may be null | |
contact | LeadContact required, may be null | |
conversation_id | string required, may be null | |
attribution | LeadAttribution required, may be null | |
score | LeadScore required, may be null | |
flags | LeadFlags required, may be null | |
intent | string required, may be null | |
ai_summary | string required, may be null | |
next_action | string required, may be null | |
next_action_at | string required, may be null | ISO 8601 UTC. |
lost_reason | string required, may be null | |
qualified_at | string required, may be null | ISO 8601 UTC. |
won_at | string required, may be null | ISO 8601 UTC. |
lost_at | string required, may be null | ISO 8601 UTC. |
last_activity_at | string required, may be null | ISO 8601 UTC. |
created_at | string required | Created. ISO 8601 UTC. |
updated_at | string required | Updated. ISO 8601 UTC. |
#LeadPage
A page of a list.
| Field | Type | Description |
|---|---|---|
data | array<Lead> required | |
next_cursor | string required, may be null | Cursor of the next page; null — the list is exhausted. Valid for 24 hours. |