{ "openapi": "3.1.0", "info": { "title": "Sapport public API", "version": "1.0.0", "description": "The platform public API: integration keys, access scopes, one error format application/problem+json. Three independent cells (RU, EN, ID): a key works only in its own cell." }, "servers": [ { "url": "https://formula-cream.pro/api/public/v1", "description": "Cell RU" }, { "url": "https://wfacademy.org/api/public/v1", "description": "Cell EN" }, { "url": "https://wfacademy.id/api/public/v1", "description": "Cell ID" } ], "tags": [ { "name": "account", "description": "Account" }, { "name": "conversations", "description": "Conversations" }, { "name": "analytics", "description": "Analytics" }, { "name": "dashboards", "description": "Dashboards" }, { "name": "leads", "description": "Leads" }, { "name": "articles", "description": "Articles" }, { "name": "strategist", "description": "Strategist" }, { "name": "webhooks", "description": "Webhooks" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "account" ], "summary": "Who am I", "description": "Returns the tenant, the integration, the key with its effective scopes, the rate limits and the wallet state. No scope is required: a valid key is enough. Handy for a connectivity check and for picking the cell.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The key and account description.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "service_unavailable", "internal_error" ] } }, "/wallet": { "get": { "operationId": "getWallet", "tags": [ "account" ], "summary": "Wallet and exchange state", "description": "Returns the tenant wallet balance, its state (ok, low, negative, blocked, unknown), whether data exchange is suspended and the top-up address. No scope is required and it works even while exchange is suspended: this is where you see why the other routes answer 402 wallet_suspended. A balance below zero or a blocked wallet suspends exchange; after a top-up it resumes by itself within 30 seconds.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The wallet state.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "service_unavailable", "internal_error" ] } }, "/conversations": { "get": { "operationId": "listConversations", "tags": [ "conversations" ], "summary": "List conversations", "description": "Tenant conversations in ascending updated_at order, paged by cursor: to pick up changes, keep the updated_at of the last one you saw and pass it as updated_after. Conversations have no soft deletion, so include_deleted adds nothing for now. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned.", "security": [ { "bearerAuth": [ "conversations:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Channel type: api, telegram, website …" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Conversation state, for example open." } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ai", "operator" ], "description": "ai — handled by the AI, operator — handled by a human." } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Conversations changed strictly after the moment. ISO 8601 with a zone." } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "default": false, "description": "Accepted for uniformity; changes nothing for now.", "type": "boolean" } } ], "responses": { "200": { "description": "A page of conversations.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "validation_failed" ] } }, "/conversations/{id}": { "get": { "operationId": "getConversation", "tags": [ "conversations" ], "summary": "Get a conversation", "description": "One conversation. A foreign, missing or non-public conversation all answer not_found alike. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned.", "security": [ { "bearerAuth": [ "conversations:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation id (uuid)." } } ], "responses": { "200": { "description": "The conversation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "not_found" ] } }, "/conversations/{id}/messages": { "get": { "operationId": "listConversationMessages", "tags": [ "conversations" ], "summary": "Conversation messages", "description": "Conversation messages from oldest to newest, paged by cursor (created_at, id). Operator internal notes are not returned. Attachments are temporary signed links; external messenger file addresses are not disclosed. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned.", "security": [ { "bearerAuth": [ "conversations:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation id (uuid)." } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "default": false, "description": "true — also return deleted messages as tombstones (deleted: true, no text).", "type": "boolean" } } ], "responses": { "200": { "description": "A page of messages.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "not_found", "validation_failed" ] } }, "/analytics/timeseries": { "get": { "operationId": "getAnalyticsTimeseries", "tags": [ "analytics" ], "summary": "Time series", "description": "Series for one to eight metrics by day or week with a summary and a comparison with the previous period. Each series carries its own availability and data-completeness date; days without data are filled with zeros.", "security": [ { "bearerAuth": [ "analytics:read" ] } ], "parameters": [ { "name": "metric", "in": "query", "required": true, "schema": { "type": "string", "description": "From 1 to 8 unique metrics, comma-separated: sessions, pageviews, visitors, bounce_rate, impressions, clicks, ctr, position, ai_referrals, bot_hits, leads, deals_won, revenue." } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day", "week" ], "description": "The series step; day by default." } }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "google", "yandex", "bing" ], "description": "The search engine for impressions, clicks, ctr, position; the cell market default if omitted." } }, { "name": "cluster", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "A query cluster id; a foreign or missing one gives not_found." } } ], "responses": { "200": { "description": "One series or items in request order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeseriesResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed", "not_found" ] } }, "/analytics/traffic-sources": { "get": { "operationId": "getAnalyticsTrafficSources", "tags": [ "analytics" ], "summary": "Traffic sources", "description": "First-visit sources over the period: sessions, visitors and leads. Aggregates by day and source only; no visit rows, IPs or hashes.", "security": [ { "bearerAuth": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "series" ], "description": "series adds a daily series to every source." } } ], "responses": { "200": { "description": "Sources, most sessions first.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficSourcesResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/analytics/funnel": { "get": { "operationId": "getAnalyticsFunnel", "tags": [ "analytics" ], "summary": "Funnel", "description": "The path from search impressions to revenue: steps with their own availability and date, channels and products. The calculation is shared with the cabinet. engine=both shows the engines separately and does not add them up.", "security": [ { "bearerAuth": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "yandex", "google", "both" ], "description": "The market search engine by default; both is not available in every market." } } ], "responses": { "200": { "description": "The funnel of the period.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/analytics/visibility": { "get": { "operationId": "getAnalyticsVisibility", "tags": [ "analytics" ], "summary": "Visibility", "description": "Visibility share, position distribution, share of voice (always without competitor names), AI citation and regions. Each section is independent: its own availability, source and date.", "security": [ { "bearerAuth": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Add a comparison with the previous period; false by default." } }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "yandex", "google", "both" ], "description": "The market search engine by default." } }, { "name": "cluster", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "A query cluster id; a foreign or missing one gives not_found." } } ], "responses": { "200": { "description": "Five visibility sections.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed", "not_found" ] } }, "/dashboards/overview": { "get": { "operationId": "getDashboardOverview", "tags": [ "dashboards" ], "summary": "The Overview dashboard", "description": "A slice of the Overview screen: up to eleven blocks, each with its own availability (ok, no_data, no_source, not_connected) and data date. A source failure never becomes an empty block: the answer is 503.", "security": [ { "bearerAuth": [ "dashboards:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } }, { "name": "blocks", "in": "query", "required": false, "schema": { "type": "string", "description": "Blocks, comma-separated; all by default: strategist, kpi, funnel, attention, ads, ai_assistants, popular_pages, clusters, data_trust, sitemap_health, status." } } ], "responses": { "200": { "description": "The requested blocks in screen order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/dashboards/pulse": { "get": { "operationId": "getDashboardPulse", "tags": [ "dashboards" ], "summary": "The Pulse dashboard", "description": "Pulse findings: demand topics that started to grow, with signal sources and the linked strategist queue topic.", "security": [ { "bearerAuth": [ "dashboards:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Start of the period, inclusive. Format YYYY-MM-DD.", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "End of the period, inclusive; not later than the last full day (a later value is clamped and echoed in the response). Format YYYY-MM-DD.", "example": "2026-09-30" } } ], "responses": { "200": { "description": "Findings of the period.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PulseResponse" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/leads": { "get": { "operationId": "listLeads", "tags": [ "leads" ], "summary": "List leads", "description": "Tenant leads in ascending updated_at order, paged by cursor. Archived leads are not returned by default. include_deleted=true currently returns 422 not_supported: deleted leads (tombstones) are not stored. The response contains the contact personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed).", "security": [ { "bearerAuth": [ "leads:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "qualified", "proposal", "negotiation", "won", "lost" ], "description": "Canonical status." } }, { "name": "archived", "in": "query", "required": false, "schema": { "default": false, "description": "true — archived only; default false — non-archived only.", "type": "boolean" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "description": "Leads updated at or after this moment. ISO 8601: a date or a date-time with a zone." } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "description": "The same, strictly after the moment (for walking on from the last seen one). Not together with updated_since." } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "description": "Exact lead source value." } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "default": false, "description": "true — also return tombstones {id, deleted_at} of deleted records (kept for 30 days).", "type": "boolean" } } ], "responses": { "200": { "description": "A page of leads.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "validation_failed" ] } }, "/leads/{id}": { "get": { "operationId": "getLead", "tags": [ "leads" ], "summary": "Get a lead", "description": "A lead card: contact, attribution, score (value, grade A–D, reason, flags), version. The ETag header equals the etag field. The response contains the contact personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed).", "security": [ { "bearerAuth": [ "leads:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Lead id (uuid)." } } ], "responses": { "200": { "description": "The lead.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "not_found" ] } }, "/articles": { "get": { "operationId": "listArticles", "tags": [ "articles" ], "summary": "List articles", "description": "Articles of your tenant (the SEO section) without their content, by descending updated_at. Articles of the shared platform blog are not included. include_deleted=true returns 422 not_supported: deleted articles are not stored.", "security": [ { "bearerAuth": [ "articles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "review", "approved", "published", "rejected", "transferred", "external" ], "description": "Article status." } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "description": "Only articles updated strictly after the moment. ISO 8601: a date or a date-time." } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "default": false, "description": "true — also return tombstones {id, deleted_at} of deleted records (kept for 30 days).", "type": "boolean" } } ], "responses": { "200": { "description": "A page of articles.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticlePage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/articles/{id}": { "get": { "operationId": "getArticle", "tags": [ "articles" ], "summary": "Get an article", "description": "An article with its content as html (default), markdown or blocks, and its publication state (publication). The HTML is stripped of scripts; a body over 2,000,000 bytes returns 422.", "security": [ { "bearerAuth": [ "articles:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Article id." } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "html", "description": "Content format.", "type": "string", "enum": [ "html", "markdown", "blocks" ] } } ], "responses": { "200": { "description": "The article.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found", "validation_failed" ] } }, "/strategist/reports": { "get": { "operationId": "listStrategistReports", "tags": [ "strategist" ], "summary": "List strategist reports", "description": "Headers of daily and weekly reports, newest first; each has data_as_of, the data freshness. Creative runs are not returned.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "report_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "daily", "weekly" ], "description": "Report type." } } ], "responses": { "200": { "description": "A page of reports.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistReportPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/strategist/reports/{id}": { "get": { "operationId": "getStrategistReport", "tags": [ "strategist" ], "summary": "Get a strategist report", "description": "The full report: conclusions, actions with rationale, and evidence. Competitor names are hidden; the analytics snapshot, model and cost are not returned.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Report id." } } ], "responses": { "200": { "description": "The report.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistReport" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found" ] } }, "/strategist/topics": { "get": { "operationId": "listStrategistTopics", "tags": [ "strategist" ], "summary": "List topics", "description": "Article topics proposed by the strategist, by descending trend score. include_deleted=true returns 422 not_supported: deleted topics are not stored.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "proposed", "approved", "generating", "generated", "rejected", "duplicate", "expired" ], "description": "Topic state." } }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "default": false, "description": "true — also return tombstones {id, deleted_at} of deleted records (kept for 30 days).", "type": "boolean" } } ], "responses": { "200": { "description": "A page of topics.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistTopicPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/strategist/topics/{id}": { "get": { "operationId": "getStrategistTopic", "tags": [ "strategist" ], "summary": "Get a topic", "description": "A queue topic. If an article was created from it, its id is in generated_article_id.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Topic id." } } ], "responses": { "200": { "description": "The topic.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistTopic" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found" ] } }, "/strategist/actions": { "get": { "operationId": "listStrategistActions", "tags": [ "strategist" ], "summary": "List strategist actions of your sessions", "description": "Actions the strategist proposed in sessions of THIS integration, newest first. Actions of staff in the cabinet and of other integrations are not visible. A proposal lives 7 days and then becomes expired.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "proposed", "confirmed", "executed", "failed", "cancelled", "expired" ], "description": "Action state." } }, { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the actions of this session (uuid)." } } ], "responses": { "200": { "description": "A page of actions.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistActionPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "validation_failed" ] } }, "/strategist/actions/{id}": { "get": { "operationId": "getStrategistAction", "tags": [ "strategist" ], "summary": "Get a strategist action", "description": "An action from your session: state, result (the created topic) or the failure reason. Another integration action returns 404.", "security": [ { "bearerAuth": [ "strategist:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Action id." } } ], "responses": { "200": { "description": "The action.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategistAction" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found" ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "webhooks" ], "summary": "List subscriptions", "description": "The subscriptions of this integration (at most 10). The signing secret is not returned.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "A page of subscriptions.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing" ] }, "post": { "operationId": "createWebhook", "tags": [ "webhooks" ], "summary": "Create a subscription", "description": "Creates an event subscription. The signing secret is shown once, in this response. The URL goes through SSRF protection; include_pii: true is allowed only for lead.*, contact.* and conversation.* events.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A unique string (usually a UUID v4), new for every new operation. A retry with the same key and body yields the same result." } } ], "requestBody": { "required": true, "description": "Subscription parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "The subscription with its secret.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "description": "Possible codes: bad_request, idempotency_key_required. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Possible codes: idempotency_conflict, operation_in_progress, invalid_state. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Payload too large. The request body is larger than 256 KB.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "write", "x-idempotent": true, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "bad_request", "validation_failed", "payload_too_large", "idempotency_key_required", "idempotency_conflict", "operation_in_progress", "invalid_state" ] } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "webhooks" ], "summary": "Get a subscription", "description": "The subscription without its secret.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } } ], "responses": { "200": { "description": "The subscription.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found" ] }, "patch": { "operationId": "updateWebhook", "tags": [ "webhooks" ], "summary": "Update a subscription", "description": "Changes the URL, events, note, status (active or paused) and include_pii. Pass at least one field.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "The subscription after the update.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad request. The body is not JSON, or the Content-Type or a header is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing, pii_transfer_not_allowed. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Payload too large. The request body is larger than 256 KB.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "write", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "pii_transfer_not_allowed", "not_found", "bad_request", "validation_failed", "payload_too_large" ] }, "delete": { "operationId": "deleteWebhook", "tags": [ "webhooks" ], "summary": "Delete a subscription", "description": "Deletes the subscription together with its delivery log. Deleting again returns not_found.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } } ], "responses": { "204": { "description": "The subscription is deleted; no body.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "write", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found" ] } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "webhooks" ], "summary": "Rotate the secret", "description": "Issues a new secret (shown once). Both secrets are valid for 24 hours and every delivery is signed with both.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A unique string (usually a UUID v4), new for every new operation. A retry with the same key and body yields the same result." } } ], "responses": { "200": { "description": "The subscription with the new secret.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "description": "Idempotency-Key header is required. The Idempotency-Key header is required for this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Possible codes: idempotency_conflict, operation_in_progress. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "write", "x-idempotent": true, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found", "idempotency_key_required", "idempotency_conflict", "operation_in_progress" ] } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "webhooks" ], "summary": "Send a test event", "description": "Queues a webhook.test event (livemode: false) for this subscription only. The subscription must be active.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A unique string (usually a UUID v4), new for every new operation. A retry with the same key and body yields the same result." } } ], "responses": { "202": { "description": "The event is queued.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } }, "400": { "description": "Idempotency-Key header is required. The Idempotency-Key header is required for this request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Possible codes: invalid_state, idempotency_conflict, operation_in_progress. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "write", "x-idempotent": true, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found", "invalid_state", "idempotency_key_required", "idempotency_conflict", "operation_in_progress" ] } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "webhooks" ], "summary": "Delivery log", "description": "Delivery attempts of the subscription, newest first; kept for 30 days.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription id." } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size: 1 to 100, default 25.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous response. Valid for 24 hours; start over when filters change." } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "dead" ], "description": "Filter by delivery state." } } ], "responses": { "200": { "description": "A page of the log.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" } } } }, "401": { "description": "Possible codes: invalid_api_key, wrong_cell, integration_inactive. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "Wallet is suspended. Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Possible codes: tenant_inactive, ip_not_allowed, feature_not_in_plan, scope_missing. Details: /developers/errors.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found. The resource does not exist or belongs to another tenant (the same thing for a client).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed. Parameters failed validation; details are in errors[].", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. The request rate limit was exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal error. An internal platform error. No details are disclosed in the response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service unavailable. The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-rate-class": "read", "x-idempotent": false, "x-status": "available", "x-error-codes": [ "invalid_api_key", "wrong_cell", "integration_inactive", "tenant_inactive", "ip_not_allowed", "feature_not_in_plan", "rate_limited", "wallet_suspended", "service_unavailable", "internal_error", "scope_missing", "not_found", "validation_failed" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The integration key: Authorization: Bearer . Scope names are the permissions a route requires." } }, "headers": { "XRequestId": { "description": "Request id; quote it when contacting support.", "schema": { "type": "string" } } }, "schemas": { "Money": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount as a STRING (never a float), for example \"123.45\"." }, "currency": { "type": "string", "description": "ISO 4217 currency code: RUB (RU), GBP (EN), IDR (ID)." } }, "required": [ "amount", "currency" ], "description": "A monetary amount." }, "FieldError": { "type": "object", "properties": { "field": { "type": "string", "description": "Path to the request field as a JSON Pointer (RFC 6901): \"/limit\", \"/events/0\"." }, "code": { "type": "string", "description": "Machine-readable reason: out_of_range, required, invalid_format…" }, "message": { "type": "string", "description": "Human-readable explanation." } }, "required": [ "field", "code", "message" ], "description": "A validation error for one field." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "Link to the code description: https:///developers/errors#." }, "title": { "type": "string", "description": "Short title, the same for a given code." }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "HTTP status." }, "code": { "type": "string", "enum": [ "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" ], "description": "Stable machine-readable code. Branch on it, not on the text." }, "detail": { "type": "string", "description": "Explanation of this particular case. Do not parse this text." }, "request_id": { "type": "string", "description": "Request id (equals the X-Request-Id header). Quote it when contacting support." }, "errors": { "description": "Per-field errors (validation_failed only).", "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } }, "correct_base_url": { "description": "wrong_cell only: the base URL of the cell the key was issued in.", "type": "string" }, "topup_url": { "description": "wallet_suspended only: the dashboard address where the wallet is topped up.", "type": "string" }, "balance": { "description": "wallet_suspended only: the wallet balance at the time of the refusal.", "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "description": "An error in application/problem+json (RFC 9457)." }, "Usage": { "type": "object", "properties": { "cost": { "$ref": "#/components/schemas/Money" }, "model": { "type": "string", "description": "The model that performed the operation." } }, "required": [ "cost", "model" ], "description": "The cost of a paid operation." }, "Operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation id." }, "type": { "type": "string", "description": "Operation type, for example \"article.generation\"." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "canceled" ], "description": "Operation state." }, "created_at": { "type": "string", "description": "Creation time, ISO 8601 UTC." }, "completed_at": { "description": "Completion time; only for succeeded, failed, canceled.", "type": "string" }, "resource": { "description": "The resource the operation relates to; read the result through it.", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "error": { "description": "failed only: a code from the error catalog or the operation-specific reason code.", "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "usage": { "description": "Paid operations only.", "$ref": "#/components/schemas/Usage" } }, "required": [ "id", "type", "status", "created_at" ], "description": "An asynchronous operation (one envelope for all modules)." }, "OperationEnvelope": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "required": [ "operation" ], "description": "The 202 response to a creating request." }, "Me": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "The tenant that owns the key." }, "cell": { "type": "string", "enum": [ "ru", "en", "id" ], "description": "Platform cell: ru, en or id." }, "base_url": { "type": "string", "description": "Base URL of this cell API." }, "integration": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "The integration (service account) that owns the key." }, "channel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The integration \"api\" channel; null — the channel is not created yet." }, "key": { "type": "object", "properties": { "key_id": { "type": "string", "description": "Public key id (not a secret)." }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "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" ] }, "description": "Effective scopes: integration scopes ∩ the owner current permissions ∩ the licence." }, "expires_at": { "type": "string", "description": "Key expiry, ISO 8601 UTC." }, "ip_allowlist": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Allowed addresses and networks (CIDR); null — any address." } }, "required": [ "key_id", "mode", "scopes", "expires_at", "ip_allowlist" ] }, "limits": { "type": "object", "properties": { "read_per_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "write_per_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paid_per_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paid_concurrency": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Concurrent paid operations per tenant." } }, "required": [ "read_per_min", "write_per_min", "paid_per_min", "paid_concurrency" ], "description": "Request rate limits." }, "wallet": { "type": "object", "properties": { "balance": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The wallet balance in roubles; null — the state is unknown or the tenant is not billed." }, "state": { "type": "string", "enum": [ "ok", "low", "negative", "blocked", "unknown" ], "description": "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." }, "exchange": { "type": "string", "enum": [ "active", "suspended" ], "description": "suspended for negative and blocked: every route except /me and /wallet answers 402 wallet_suspended." }, "topup_url": { "type": "string", "description": "The dashboard address where the wallet is topped up." }, "daily_spend": { "type": "object", "properties": { "limit": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The integration daily spend limit; null — not set." }, "used": { "$ref": "#/components/schemas/Money" } }, "required": [ "limit", "used" ] } }, "required": [ "balance", "state", "exchange", "topup_url", "daily_spend" ], "description": "The tenant wallet (AI operations)." }, "crm_mode": { "type": "string", "description": "The tenant CRM mode: \"internal\" (our CRM) or an external system." } }, "required": [ "tenant", "cell", "base_url", "integration", "channel_id", "key", "limits", "wallet", "crm_mode" ], "description": "Who you are: tenant, integration, key, limits, wallet." }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Subscription id." }, "url": { "type": "string", "description": "Receiving URL: https, port 443, a host name (not an IP), no redirects." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false." }, "description": { "anyOf": [ { "type": "string", "maxLength": 200, "description": "A note for yourself, up to 200 characters." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "active — deliveries flow; paused — suspended." }, "created_at": { "type": "string", "description": "ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "ISO 8601 UTC." }, "secret_rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time of the last secret rotation; null — never rotated." }, "previous_secret_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "While the rotation window (24 hours) is open — when the previous secret stops working; otherwise null." } }, "required": [ "id", "url", "events", "include_pii", "description", "status", "created_at", "updated_at", "secret_rotated_at", "previous_secret_expires_at" ], "description": "An event subscription. The secret is not returned in such responses." }, "WebhookWithSecret": { "type": "object", "properties": { "id": { "type": "string", "description": "Subscription id." }, "url": { "type": "string", "description": "Receiving URL: https, port 443, a host name (not an IP), no redirects." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false." }, "description": { "anyOf": [ { "type": "string", "maxLength": 200, "description": "A note for yourself, up to 200 characters." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "active — deliveries flow; paused — suspended." }, "created_at": { "type": "string", "description": "ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "ISO 8601 UTC." }, "secret_rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time of the last secret rotation; null — never rotated." }, "previous_secret_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "While the rotation window (24 hours) is open — when the previous secret stops working; otherwise null." }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "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." } }, "required": [ "id", "url", "events", "include_pii", "description", "status", "created_at", "updated_at", "secret_rotated_at", "previous_secret_expires_at", "secret" ], "description": "The subscription together with its secret: the creation and rotation response." }, "WebhookCreate": { "type": "object", "properties": { "url": { "type": "string", "description": "Receiving URL: https, port 443, a host name (not an IP), no redirects." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false." }, "description": { "anyOf": [ { "type": "string", "maxLength": 200, "description": "A note for yourself, up to 200 characters." }, { "type": "null" } ] } }, "required": [ "url", "events" ], "description": "The subscription creation body." }, "WebhookUpdate": { "type": "object", "properties": { "url": { "type": "string", "description": "Receiving URL: https, port 443, a host name (not an IP), no redirects." }, "events": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "Full payload with personal data; only for lead.*, contact.* and conversation.* events. Default false." }, "description": { "anyOf": [ { "type": "string", "maxLength": 200, "description": "A note for yourself, up to 200 characters." }, { "type": "null" } ] }, "status": { "description": "Pause or resume deliveries.", "type": "string", "enum": [ "active", "paused" ] } }, "description": "The update body: pass at least one field." }, "WebhookPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "WebhookTestResult": { "type": "object", "properties": { "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The test event id." }, "type": { "type": "string", "const": "webhook.test" }, "status": { "type": "string", "const": "queued", "description": "The event is queued; it goes out on the next delivery run (within a minute)." } }, "required": [ "event_id", "type", "status" ], "description": "The 202 response to a test delivery. The event body arrives at your URL with livemode: false." }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery id." }, "event_id": { "type": "string", "description": "Event id." }, "state": { "type": "string", "enum": [ "pending", "delivered", "failed", "dead" ], "description": "pending — waiting for an attempt; delivered — delivered; failed — an attempt failed, a retry follows; dead — retries exhausted." }, "attempt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of the last attempt (0 — none yet)." }, "status_code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "HTTP status of the subscriber response; null if there was none." }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Attempt duration, ms." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason: timeout, connection or certificate error, a 3xx response." }, "next_attempt_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time of the next attempt; null if no more attempts follow." }, "delivered_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Time of successful delivery." }, "created_at": { "type": "string" } }, "required": [ "id", "event_id", "state", "attempt", "status_code", "duration_ms", "error", "next_attempt_at", "delivered_at", "created_at" ], "description": "A delivery log entry (kept for 30 days)." }, "WebhookDeliveryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "Wallet": { "type": "object", "properties": { "balance": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "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": { "type": "string", "enum": [ "ok", "low", "negative", "blocked", "unknown" ], "description": "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." }, "exchange": { "type": "string", "enum": [ "active", "suspended" ], "description": "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)." }, "topup_url": { "type": "string", "description": "The dashboard address where the wallet is topped up (a staff member with the top-up permission must sign in)." }, "daily_spend": { "anyOf": [ { "type": "object", "properties": { "limit": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The integration daily spend limit; null — not set." }, "used": { "$ref": "#/components/schemas/Money" } }, "required": [ "limit", "used" ] }, { "type": "null" } ], "description": "The integration daily spend; null while spend is not tracked per integration." } }, "required": [ "balance", "state", "exchange", "topup_url", "daily_spend" ], "description": "The state of the tenant wallet and of data exchange." }, "TimeseriesItem": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "sessions", "pageviews", "visitors", "bounce_rate", "impressions", "clicks", "ctr", "position", "ai_referrals", "bot_hits", "leads", "deals_won", "revenue" ] }, "from": { "type": "string", "description": "Date YYYY-MM-DD." }, "to": { "type": "string", "description": "Date YYYY-MM-DD." }, "granularity": { "type": "string", "enum": [ "day", "week" ] }, "agg": { "type": "string", "enum": [ "sum", "avg" ], "description": "How the series is folded over the period." }, "engine": { "anyOf": [ { "type": "string", "enum": [ "google", "yandex", "bing" ] }, { "type": "null" } ], "description": "The search engine of the series; null for metrics not tied to search." }, "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason code when availability is not ok." }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date YYYY-MM-DD." }, "value": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] } }, "required": [ "date", "value" ] }, "description": "The series; days without data are filled with zeros. With the weekly step date is the first day of the week." }, "comparison": { "type": "object", "properties": { "current": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "prev": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "delta_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in percent; null if there is nothing to compare with or the base is zero." }, "data_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last date the data is complete." } }, "required": [ "current", "prev", "delta_pct", "data_through" ] }, "summary": { "anyOf": [ { "type": "object", "properties": { "total": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "latest": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "non_zero_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "latest", "non_zero_days" ] }, { "type": "null" } ] }, "cluster_applied": { "type": "boolean" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "metric", "from", "to", "granularity", "agg", "engine", "availability", "reason", "series", "comparison", "summary", "cluster_applied", "data_as_of" ], "description": "One time series." }, "TimeseriesResponse": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/TimeseriesItem" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesItem" } } }, "required": [ "items" ] } ] } }, "required": [ "data" ], "description": "One series (a single metric) or items in request order (several metrics)." }, "TrafficSourceRow": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "google", "yandex", "bing", "chatgpt", "perplexity", "ai_other", "social", "ads", "direct", "other" ] }, "kind": { "type": "string", "enum": [ "search", "ai_assistant", "social", "ads", "direct", "other" ] }, "sessions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "visitors": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Daily unique visitors summed over the period; null when they cannot be counted (anonymous beacon)." }, "leads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "series": { "description": "Only with include=series.", "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date YYYY-MM-DD." }, "sessions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "visitors": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "leads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "date", "sessions", "visitors", "leads" ] } } }, "required": [ "source", "kind", "sessions", "visitors", "leads" ], "description": "A first-visit source over the period." }, "TrafficSourcesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficSourceRow" } }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "data", "data_as_of" ], "description": "Traffic sources, most sessions first." }, "FunnelStep": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "impressions", "clicks", "sessions", "leads", "deals_created", "deals_won", "revenue" ] }, "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source" ] }, "sources": { "type": "array", "items": { "type": "string" } }, "unit": { "type": "string", "enum": [ "count", "money" ] }, "current": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "prev": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "$ref": "#/components/schemas/Money" } ] }, { "type": "null" } ] }, "delta_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "data_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "availability", "sources", "unit", "current", "prev", "delta_pct", "data_through" ], "description": "A funnel step with its own availability and date." }, "FunnelResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "engine": { "type": "string", "enum": [ "yandex", "google", "both" ] }, "from": { "type": "string", "description": "Date YYYY-MM-DD." }, "to": { "type": "string", "description": "Date YYYY-MM-DD." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FunnelStep" } }, "by_channel": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "availability": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "clicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "leads": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "channel", "availability", "sources", "clicks", "cost", "leads" ] } }, "search_by_engine": { "description": "Only engine=both: the engines separately.", "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "by_product": { "type": "array", "items": { "type": "object", "properties": { "course_slug": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sales_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leads": { "type": "number" }, "leads_prev": { "type": "number" }, "deals_won": { "type": "number" }, "deals_won_prev": { "type": "number" } }, "required": [ "course_slug", "name", "sales_mode", "leads", "leads_prev", "deals_won", "deals_won_prev" ] } }, "crm": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data" ] }, "reason": { "type": "string" } }, "required": [ "availability" ] } }, "required": [ "engine", "from", "to", "steps", "by_channel", "by_product", "crm" ] }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "data", "data_as_of" ], "description": "The funnel impressions → clicks → sessions → leads → deals → revenue." }, "VisibilityResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string", "description": "Date YYYY-MM-DD." }, "to": { "type": "string", "description": "Date YYYY-MM-DD." }, "engine": { "type": "string", "enum": [ "yandex", "google", "both" ] }, "share": { "type": "object", "properties": { "availability": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "availability", "source", "data_as_of", "data" ] }, "distribution": { "type": "object", "properties": { "availability": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "availability", "source", "data_as_of", "data" ] }, "sov": { "type": "object", "properties": { "availability": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "availability", "source", "data_as_of", "data" ] }, "aeo": { "type": "object", "properties": { "availability": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "availability", "source", "data_as_of", "data" ] }, "regions": { "type": "object", "properties": { "availability": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "availability", "source", "data_as_of", "data" ] } }, "required": [ "from", "to", "engine", "share", "distribution", "sov", "aeo", "regions" ] } }, "required": [ "data" ], "description": "Visibility: five independent sections." }, "OverviewResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string", "description": "Date YYYY-MM-DD." }, "to": { "type": "string", "description": "Date YYYY-MM-DD." }, "blocks": { "type": "object", "properties": { "strategist": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "kpi": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "funnel": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "attention": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "ads": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "ai_assistants": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "popular_pages": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "clusters": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "data_trust": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "sitemap_health": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} }, "status": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "ok", "no_data", "no_source", "not_connected" ] }, "reason": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "availability", "data_as_of" ], "additionalProperties": {} } } } }, "required": [ "from", "to", "blocks" ] } }, "required": [ "data" ], "description": "A slice of the Overview screen: the requested blocks in screen order." }, "PulseAlert": { "type": "object", "properties": { "id": { "type": "string" }, "topic_id": { "type": "string" }, "topic_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keyword": { "type": "string" }, "horizon": { "type": "string" }, "status": { "type": "string" }, "episode_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "growth": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "outcome": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "code", "outcome", "value", "base" ] } }, "strategist_topic": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, { "type": "null" } ], "description": "The linked strategist queue topic." } }, "required": [ "id", "topic_id", "topic_name", "keyword", "horizon", "status", "episode_start", "last_seen", "score", "volume", "growth", "sources", "strategist_topic" ], "description": "A Pulse finding: a demand topic that started to grow." }, "PulseResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Date YYYY-MM-DD." }, "to": { "type": "string", "description": "Date YYYY-MM-DD." } }, "required": [ "from", "to" ] }, "new_7d": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/PulseAlert" } }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Source → the date up to which its data is complete. A source with no data is not listed." } }, "required": [ "period", "new_7d", "truncated", "alerts", "data_as_of" ] } }, "required": [ "data" ], "description": "A slice of the Pulse screen." }, "ArticleSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Article id." }, "title": { "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft — a draft; review — in review; approved — approved; published — published; rejected — rejected; transferred — moved to the blog; external — external." }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article language (ru, en, id)." }, "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The main query of the article." }, "meta_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meta_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cover_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "word_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." } }, "required": [ "id", "title", "slug", "status", "locale", "keyword", "meta_title", "meta_description", "cover_image_url", "word_count", "created_at", "updated_at", "published_at" ], "description": "A tenant article without its content (a list item)." }, "ArticlePublication": { "type": "object", "properties": { "target": { "type": "string", "const": "connector", "description": "Where it is published: the module on your site." }, "state": { "type": "string", "enum": [ "queued", "applied", "skipped", "conflict", "failed" ], "description": "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." }, "published_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The article URL on your site once applied." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The failure reason, up to 200 characters." } }, "required": [ "target", "state", "published_url", "error" ], "description": "The state of the latest publication of the article through the site module." }, "Article": { "type": "object", "properties": { "id": { "type": "string", "description": "Article id." }, "title": { "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft — a draft; review — in review; approved — approved; published — published; rejected — rejected; transferred — moved to the blog; external — external." }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article language (ru, en, id)." }, "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The main query of the article." }, "meta_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meta_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cover_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "word_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "html": { "type": "string" } }, "required": [ "type", "html" ] } } ], "description": "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": { "anyOf": [ { "$ref": "#/components/schemas/ArticlePublication" }, { "type": "null" } ], "description": "null — the article has not been published through the site module yet." } }, "required": [ "id", "title", "slug", "status", "locale", "keyword", "meta_title", "meta_description", "cover_image_url", "word_count", "created_at", "updated_at", "published_at", "content", "publication" ], "description": "A tenant article with its content." }, "ArticlePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleSummary" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "StrategistReportSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Report id." }, "report_date": { "type": "string", "description": "Report date, YYYY-MM-DD." }, "report_type": { "type": "string", "enum": [ "daily", "weekly" ], "description": "daily — daily, weekly — weekly." }, "summary_text": { "type": "string", "description": "The short summary." }, "actions_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many actions are recommended." }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "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": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the report was delivered to the owner; null — not yet. ISO 8601 UTC." } }, "required": [ "id", "report_date", "report_type", "summary_text", "actions_count", "data_as_of", "delivered_at" ], "description": "A strategist report header (a list item)." }, "StrategistReportAction": { "type": "object", "properties": { "title": { "type": "string" }, "priority": { "type": "string", "description": "Action priority (high, medium, low)." }, "rationale": { "type": "string", "description": "The rationale. Competitor names are hidden in it." }, "target_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A reference to the target (article, product, campaign); null if there is none or it is a competitor." }, "expected_effect": { "anyOf": [ { "type": "object", "properties": { "metric": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "delta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "horizon_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "metric", "delta", "horizon_days" ] }, { "type": "null" } ], "description": "The expected effect; null if the strategist named none." }, "check_after_days": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "In how many days to check the result." }, "basis": { "type": "string", "enum": [ "observed_pattern", "own_measured", "research", "hypothesis" ], "description": "What the conclusion rests on: observed_pattern — observed elsewhere; own_measured — measured on your data; research — a study; hypothesis — a hypothesis." } }, "required": [ "title", "priority", "rationale", "target_ref", "expected_effect", "check_after_days", "basis" ], "description": "A recommended action." }, "StrategistEvidence": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Index into actions (zero-based)." }, "status": { "type": "string", "description": "supported — supporting sources were found; unsupported — none." }, "basis": { "type": "string", "enum": [ "observed_pattern", "own_measured", "research", "hypothesis" ], "description": "What the conclusion rests on: observed_pattern — observed elsewhere; own_measured — measured on your data; research — a study; hypothesis — a hypothesis." }, "items": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string", "description": "The source label; foreign domains are replaced with a placeholder." }, "url": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "ref", "kind", "label" ] } } }, "required": [ "index", "status", "basis", "items" ] } }, "validation": { "description": "The evidence check result. relevance_checked is always false: references and quotes are checked, not the meaning.", "type": "object", "properties": { "refs_valid": { "type": "boolean" }, "excerpts_valid": { "type": "boolean" }, "relevance_checked": { "type": "boolean", "const": false }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "refs_valid", "excerpts_valid", "relevance_checked", "limitations" ] } }, "required": [ "actions" ], "description": "Evidence per action. Verbatim competitor wording is not returned." }, "StrategistReport": { "type": "object", "properties": { "id": { "type": "string" }, "report_date": { "type": "string" }, "report_type": { "type": "string", "enum": [ "daily", "weekly" ] }, "summary_text": { "type": "string" }, "data_as_of": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "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": { "type": "array", "items": {}, "description": "What goes well." }, "concerns": { "type": "array", "items": {}, "description": "What is concerning." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/StrategistReportAction" } }, "evidence": { "$ref": "#/components/schemas/StrategistEvidence" } }, "required": [ "id", "report_date", "report_type", "summary_text", "data_as_of", "highlights", "concerns", "actions", "evidence" ], "description": "A full strategist report. The analytics snapshot, model and cost are not returned." }, "StrategistReportPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategistReportSummary" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "StrategistTopic": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the topic is proposed. For competitor-sourced topics domains are hidden." }, "trend_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Trend score; null — not scored." }, "source": { "type": "string", "description": "Where the topic comes from: planner, competitors, chat and others." }, "status": { "type": "string", "enum": [ "proposed", "approved", "generating", "generated", "rejected", "duplicate", "expired" ], "description": "proposed — awaiting a decision; approved — approved; generating — the article is being created; generated — the article is created; rejected — rejected; duplicate — a duplicate; expired — expired." }, "cluster_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "generated_article_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The id of the created article (GET /articles/{id})." }, "proposed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "decided_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." } }, "required": [ "id", "title", "rationale", "trend_score", "source", "status", "cluster_id", "generated_article_id", "proposed_at", "decided_at", "expires_at" ], "description": "A topic in the strategist queue." }, "StrategistTopicPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategistTopic" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "StrategistAction": { "type": "object", "properties": { "id": { "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The conversation session in which the action was proposed." }, "type": { "type": "string", "const": "propose_topic", "description": "The action kind. In v1 only propose_topic." }, "title": { "type": "string", "description": "The title of the proposed topic." }, "status": { "type": "string", "enum": [ "proposed", "confirmed", "executed", "failed", "cancelled", "expired" ], "description": "proposed — awaiting confirmation; confirmed — confirmed, running; executed — done; failed — failed; cancelled — cancelled; expired — expired (7 days)." }, "result": { "anyOf": [ { "type": "object", "properties": { "topic_id": { "type": "string" } }, "required": [ "topic_id" ] }, { "type": "null" } ], "description": "The result of an executed action: the created topic." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, { "type": "null" } ], "description": "The failure reason when status = failed." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "decided_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the wait ends: creation + 7 days. ISO 8601 UTC." } }, "required": [ "id", "session_id", "type", "title", "status", "result", "error", "created_at", "decided_at", "expires_at" ], "description": "A strategist action proposed in your session and awaiting a decision." }, "StrategistActionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StrategistAction" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation id (uuid)." }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Channel type: api, telegram, website …" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Sapport contact (customer) id." }, "external_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The customer id in your system. Channel api only; null for other channels (the messenger external id is not disclosed)." }, "status": { "type": "string", "description": "Conversation state: open, handoff_pending, resolved, closed … The set may grow — do not treat the list as closed." }, "mode": { "type": "string", "enum": [ "ai", "operator" ], "description": "Who handles the conversation: ai — the AI answers (modes auto and supervised), operator — a human answers (copilot and manual)." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conversation language (ISO 639-1); null — not detected." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conversation start, ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "Last change or message, ISO 8601 UTC. The walk order. The unread counter does not change it." } }, "required": [ "id", "channel", "contact_id", "external_customer_id", "status", "mode", "language", "created_at", "updated_at" ], "description": "A conversation. Contains personal data (external_customer_id)." }, "MessageAttachment": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Content kind: image, file, audio …" }, "url": { "type": "string", "description": "A temporary signed link to the file (download without the API key). Do not store the link: fetch the message again." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the link stops working, ISO 8601 UTC (about an hour); null — a permanent path." } }, "required": [ "type", "url", "expires_at" ], "description": "A message attachment." }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message id (uuid)." }, "conversation_id": { "type": "string", "description": "The conversation." }, "sender": { "type": "string", "enum": [ "customer", "ai", "operator", "system" ], "description": "Sender: customer, ai, operator, system." }, "content_type": { "type": "string", "description": "Content kind: text, image, file …" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The text; null — no text (attachment only) or the message is deleted." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" }, "description": "Attachments (at most one for now)." }, "deleted": { "type": "boolean", "description": "true — the message is deleted (returned only with include_deleted=true; no text or attachments)." }, "created_at": { "type": "string", "description": "Message time, ISO 8601 UTC." } }, "required": [ "id", "conversation_id", "sender", "content_type", "content", "attachments", "deleted", "created_at" ], "description": "A conversation message. Contains customer personal data (text, attachments)." }, "ConversationPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "MessagePage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." }, "LeadFlags": { "type": "object", "properties": { "buy_intent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Intent to buy; null — the model is not sure." }, "support": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "A support request rather than a purchase; null — not sure." }, "supplier": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "A supplier or advertiser, not a customer; true archives the lead (ai_not_client)." } }, "required": [ "buy_intent", "support", "supplier" ], "description": "AI flags from the conversation. true/false are set only when the model is confident." }, "LeadScore": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Score 0–100." }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D" ], "description": "Grade: A — 75 and above, B — 50–74, C — 25–49, D — below 25." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the score; null until recorded." }, "flags": { "anyOf": [ { "$ref": "#/components/schemas/LeadFlags" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "ai", "external", "manual" ] }, { "type": "null" } ], "description": "Who scored: ai, external or manual; null — unknown." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The model that set the flags; null if the score is not AI." }, "scored_at": { "anyOf": [ { "type": "string", "description": "When the score was set. ISO 8601 UTC." }, { "type": "null" } ] } }, "required": [ "score", "grade", "reason", "flags", "source", "model", "scored_at" ], "description": "The lead score. null for a lead that has not been scored yet." }, "LeadContact": { "type": "object", "properties": { "id": { "type": "string", "description": "Contact id." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Personal data." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Personal data." }, "tags": { "type": "array", "items": { "type": "string" } }, "geo_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country by IP (ISO 3166-1 alpha-2)." }, "geo_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City by IP." } }, "required": [ "id", "first_name", "last_name", "email", "phone", "tags", "geo_country", "geo_city" ], "description": "The lead contact. Holds personal data: every disclosure is recorded in the disclosure log." }, "LeadAttribution": { "type": "object", "properties": { "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "first_page": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first-visit page." }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "utm_source", "utm_medium", "utm_campaign", "first_page", "referrer" ], "description": "Where the lead came from (first touch). null when there is no trace." }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "description": "Lead id." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The id in an external CRM; null until an external CRM is connected." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Version for If-Match; null while the database has no version column — use etag." }, "etag": { "type": "string", "description": "The version tag (equals the ETag header of the card)." }, "status": { "type": "string", "enum": [ "new", "qualified", "proposal", "negotiation", "won", "lost" ], "description": "One of six canonical statuses. Archive is the archived flag, not a status." }, "archived": { "type": "boolean", "description": "The lead is archived." }, "archived_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Archive reason, for example ai_not_client." }, "owner": { "type": "string", "enum": [ "internal", "external" ], "description": "Where the lead lives: internal — in our CRM." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the responsible employee." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "course_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "$ref": "#/components/schemas/LeadContact" }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution": { "anyOf": [ { "$ref": "#/components/schemas/LeadAttribution" }, { "type": "null" } ] }, "score": { "anyOf": [ { "$ref": "#/components/schemas/LeadScore" }, { "type": "null" } ] }, "flags": { "anyOf": [ { "$ref": "#/components/schemas/LeadFlags" }, { "type": "null" } ] }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ai_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_action_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "lost_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qualified_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "won_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "lost_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "last_activity_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "Created. ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "Updated. ISO 8601 UTC." } }, "required": [ "id", "external_id", "external_url", "version", "etag", "status", "archived", "archived_reason", "owner", "title", "source", "assigned_to", "value", "product_id", "course_slug", "contact", "conversation_id", "attribution", "score", "flags", "intent", "ai_summary", "next_action", "next_action_at", "lost_reason", "qualified_at", "won_at", "lost_at", "last_activity_at", "created_at", "updated_at" ], "description": "A tenant lead." }, "LeadPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor of the next page; null — the list is exhausted. Valid for 24 hours." } }, "required": [ "data", "next_cursor" ], "description": "A page of a list." } } }, "x-scopes": { "conversations:read": "Requires an owner permission: conversations.view.", "conversations:write": "Requires an owner permission: conversations.manage.", "ai_seller:invoke": "Requires an owner permission: conversations.manage.", "leads:read": "Requires an owner permission: crm.leads.view.", "leads:write": "Requires an owner permission: crm.leads.edit.", "leads:score": "Requires an owner permission: crm.leads.edit.", "analytics:read": "Requires an owner permission: analytics.view or seo.view.", "analytics:write": "Requires an owner permission: seo.manage.", "dashboards:read": "Requires an owner permission: analytics.view or seo.view.", "articles:read": "Requires an owner permission: seo.view.", "articles:write": "Requires an owner permission: seo.manage.", "articles:generate": "Requires an owner permission: seo.manage.", "strategist:read": "Requires an owner permission: seo.view.", "strategist:write": "Requires an owner permission: seo.manage.", "strategist:chat": "Requires an owner permission: seo.manage.", "webhooks:manage": "Requires an owner permission: settings.integrations." }, "x-page-limit": { "default": 25, "max": 100 }, "x-error-catalog": [ { "code": "bad_request", "status": 400, "title": "Bad request", "group": "request", "when": "The body is not JSON, or the Content-Type or a header is invalid.", "action": "Fix the request; a retry without changes is pointless." }, { "code": "idempotency_key_required", "status": 400, "title": "Idempotency-Key header is required", "group": "request", "when": "The Idempotency-Key header is required for this request.", "action": "Add the header with a value unique per operation." }, { "code": "integration_inactive", "status": 401, "title": "Integration is not active", "group": "auth", "when": "The integration is suspended or revoked, or its owner lost access. The key itself is fine.", "action": "Check the integration in the dashboard (Settings → API)." }, { "code": "invalid_api_key", "status": 401, "title": "Invalid API key", "group": "auth", "when": "The header is missing, or the key is unknown, revoked or expired. The response is deliberately identical in all cases: the platform does not confirm that such a key ever existed.", "action": "Check the key; its expiry is visible in GET /me (key.expires_at). Issue a new one if needed. Do not retry automatically." }, { "code": "wrong_cell", "status": 401, "title": "Key belongs to another cell", "group": "auth", "when": "The key was issued in another cell. The response carries the correct_base_url field.", "action": "Use the base URL from correct_base_url." }, { "code": "insufficient_funds", "status": 402, "title": "Insufficient funds", "group": "money", "when": "The wallet does not hold enough funds for a paid operation.", "action": "Top up the wallet." }, { "code": "spend_limit_reached", "status": 402, "title": "Spend limit reached", "group": "money", "when": "A spend limit (tenant or integration), the paid-concurrency limit or the per-operation cost cap was reached.", "action": "Wait for the window or raise the limit in the dashboard." }, { "code": "wallet_suspended", "status": 402, "title": "Wallet is suspended", "group": "money", "when": "Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance.", "action": "Top up the wallet at topup_url (a staff member with the top-up permission must sign in). Exchange resumes by itself within 30 seconds of the credit; the state is visible in GET /wallet. Events are not lost: webhooks are delivered after the top-up." }, { "code": "feature_not_in_plan", "status": 403, "title": "API is not included in the plan", "group": "auth", "when": "The licence or plan does not include the API (api_access) or the specific feature.", "action": "Change the plan or contact support." }, { "code": "ip_not_allowed", "status": 403, "title": "IP address is not allowed", "group": "auth", "when": "The request came from an address outside the integration allowlist.", "action": "Add the address to the list or call from an allowed one." }, { "code": "pii_transfer_not_allowed", "status": 403, "title": "Personal data transfer is not allowed", "group": "auth", "when": "Cell RU: a scope with personal data was requested, but the IP allowlist or the recipient country does not permit the transfer.", "action": "Host the receiving system in Russia, set an IP allowlist, or do not request personal-data scopes." }, { "code": "scope_missing", "status": 403, "title": "Scope is missing", "group": "auth", "when": "A required scope is missing, or it was cut by the integration role, the owner permissions or the plan.", "action": "Check the scopes in GET /me (key.scopes) and the owner permissions." }, { "code": "tenant_inactive", "status": 403, "title": "Account is not active", "group": "auth", "when": "The tenant account is not active.", "action": "Contact support." }, { "code": "not_found", "status": 404, "title": "Not found", "group": "request", "when": "The resource does not exist or belongs to another tenant (the same thing for a client).", "action": "Check the identifier." }, { "code": "method_not_allowed", "status": 405, "title": "Method not allowed", "group": "request", "when": "The method is not supported at this URL.", "action": "Check the reference." }, { "code": "idempotency_conflict", "status": 409, "title": "Idempotency key was used with a different request", "group": "request", "when": "The Idempotency-Key was already used with a different request body.", "action": "Use a new key for a new request or repeat the original request." }, { "code": "invalid_state", "status": 409, "title": "Invalid state", "group": "request", "when": "The action is not allowed in the current state of the resource.", "action": "Re-read the resource and check its state." }, { "code": "operation_in_progress", "status": 409, "title": "Operation is in progress", "group": "request", "when": "A parallel retry: the operation with this Idempotency-Key is still running.", "action": "Wait for Retry-After or poll the operation." }, { "code": "precondition_failed", "status": 412, "title": "Precondition failed", "group": "request", "when": "If-Match does not match the current version: the resource was modified.", "action": "Re-read the resource and apply the change to the current version." }, { "code": "payload_too_large", "status": 413, "title": "Payload too large", "group": "request", "when": "The request body is larger than 256 KB.", "action": "Make the body smaller." }, { "code": "validation_failed", "status": 422, "title": "Validation failed", "group": "request", "when": "Parameters failed validation; details are in errors[].", "action": "Fix the request following errors[]." }, { "code": "precondition_required", "status": 428, "title": "Precondition required", "group": "request", "when": "If-Match was not sent for the modification.", "action": "Send the version from the last read." }, { "code": "rate_limited", "status": 429, "title": "Too many requests", "group": "money", "when": "The request rate limit was exceeded.", "action": "Wait Retry-After seconds and retry with the same Idempotency-Key." }, { "code": "internal_error", "status": 500, "title": "Internal error", "group": "platform", "when": "An internal platform error. No details are disclosed in the response.", "action": "Retry with a pause; if it persists, send the request_id to support." }, { "code": "service_unavailable", "status": 503, "title": "Service unavailable", "group": "platform", "when": "The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely.", "action": "Retry with a pause and the same Idempotency-Key." }, { "code": "upstream_unavailable", "status": 503, "title": "Upstream service unavailable", "group": "platform", "when": "An external dependency, such as a language model, is unavailable.", "action": "Retry with a pause and the same Idempotency-Key." } ] }