{ "openapi": "3.1.0", "info": { "title": "Integrations 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" }, { "name": "channels", "description": "Channels" }, { "name": "cards", "description": "Product cards" } ], "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" ] } }, "/me/encryption-key": { "put": { "operationId": "putEncryptionKey", "tags": [ "account" ], "summary": "Public key for the JWE format", "description": "EN and ID cells only; 404 on RU. Registers or replaces the recipient public key (JWK) used to build personal-data field values in JWE format (RFC 7516). You create the key pair and keep the private key; private JWK members are rejected. EN: ECDH-ES+A256KW (P-256, P-384, X25519) or RSA-OAEP-256 (2048 bits or more). ID: ECDH-ES+A256KW (P-384, X25519) or RSA-OAEP-256 / RSA-OAEP-384 (3072 bits or more). enc is A256GCM. The same key again — changed: false. A new key applies at once; the previous one can still be requested with the Encryption-Key-Id header for 7 days. Registration turns mode off into optional; mode required is changed in the dashboard only.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "description": "The recipient public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PiiEncryptionKeyPut" } } } }, "responses": { "200": { "description": "The setting after registration.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PiiEncryptionKeyResult" } } } }, "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. 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": "Invalid state. The action is not allowed in the current state of the resource.", "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", "not_found", "bad_request", "validation_failed", "payload_too_large", "invalid_state" ], "x-cells": [ "en", "id" ] } }, "/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" ] } }, "/operations/{id}": { "get": { "operationId": "getOperation", "tags": [ "account" ], "summary": "Get an operation", "description": "Returns an asynchronous operation created by your integration (a 202 response with the operation envelope): the queued, running, succeeded, failed or canceled state, the result resource and the cost of paid operations. The route needs no scope of its own: it requires the same scope as the request that created the operation (for example, ai_seller:invoke for an AI seller reply). An operation of another integration or tenant is a 404. Instead of frequent polling, subscribe to the operation.completed event.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Operation id (uuid) from the operation envelope." } } ], "responses": { "200": { "description": "The operation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" } } } }, "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": { "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. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.", "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" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000, "description": "Comma-separated fields to return (id is always present). Without the parameter every field EXCEPT personal-data fields is returned; a personal-data field is returned only when named explicitly: top-level (title, content) or nested (contact.email, score.reason). An unknown name — 422. Only the returned fields are recorded in the disclosure log." } }, { "name": "Encryption-Key-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "EN and ID cells only: which registered key (kid) to build the JWE with — the active one or the previous one for 7 days after a change. The header enables the JWE format even in mode off." } } ], "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" } } } }, "409": { "description": "Encryption key is required. The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "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", "encryption_key_required" ] }, "post": { "operationId": "createConversation", "tags": [ "conversations" ], "summary": "Find or create a conversation", "description": "A conversation of your channel customer (the integration api channel) by the external id: an active one is returned (200), otherwise a new one is created (201) with a conversation.created event. The same external_customer_id of two integrations means two different customers. Name, email and phone are written into empty contact fields only. Connect the channel in the dashboard (Settings → API); without it — 409 channel_not_configured. A retry with the same Idempotency-Key returns the same conversation. 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:write" ] } ], "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": "Your channel customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCreate" } } } }, "responses": { "201": { "description": "The conversation (new — 201, existing — 200).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "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: channel_not_configured, 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", "validation_failed", "bad_request", "payload_too_large", "channel_not_configured", "idempotency_key_required", "idempotency_conflict", "operation_in_progress", "invalid_state" ] } }, "/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. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.", "security": [ { "bearerAuth": [ "conversations:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation id (uuid)." } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000, "description": "Comma-separated fields to return (id is always present). Without the parameter every field EXCEPT personal-data fields is returned; a personal-data field is returned only when named explicitly: top-level (title, content) or nested (contact.email, score.reason). An unknown name — 422. Only the returned fields are recorded in the disclosure log." } }, { "name": "Encryption-Key-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "EN and ID cells only: which registered key (kid) to build the JWE with — the active one or the previous one for 7 days after a change. The header enables the JWE format even in mode off." } } ], "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" } } } }, "409": { "description": "Encryption key is required. The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "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", "encryption_key_required" ] } }, "/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. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.", "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" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000, "description": "Comma-separated fields to return (id is always present). Without the parameter every field EXCEPT personal-data fields is returned; a personal-data field is returned only when named explicitly: top-level (title, content) or nested (contact.email, score.reason). An unknown name — 422. Only the returned fields are recorded in the disclosure log." } }, { "name": "Encryption-Key-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "EN and ID cells only: which registered key (kid) to build the JWE with — the active one or the previous one for 7 days after a change. The header enables the JWE format even in mode off." } } ], "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" } } } }, "409": { "description": "Encryption key is required. The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "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", "encryption_key_required" ] }, "post": { "operationId": "createConversationMessage", "tags": [ "conversations" ], "summary": "Customer message and AI reply", "description": "Saves a customer message into a conversation of the integration channel (conversations:write) and, with ai_reply=auto and the ai_seller:invoke scope, starts the AI seller reply asynchronously: 202 with message_id, ai_reply.status=queued and a conversation.ai_reply operation. ?wait=N (0–20 s) waits for the SAME job: in time — 200 with the result (ai_reply, reply.id, operation.usage.cost in the wallet currency), otherwise — 202. Without ai_seller:invoke or with ai_reply=none — 201, ai_reply.status=skipped, reason=not_requested; the AI is not called and nothing is charged. The AI reply text is not here — read GET /conversations/{id}/messages or wait for message.created. A retry with the same Idempotency-Key while running returns the same 202, afterwards the result; the message is never written or charged twice. Paid part: at most 5 concurrent operations per integration (429 concurrency_limit), the per-operation cost cap and the integration daily limit (402 spend_limit_reached) are checked before writing; a refusal writes nothing and frees the Idempotency-Key. A conversation of another channel or tenant — 404, a closed one — 409 invalid_state.", "security": [ { "bearerAuth": [ "conversations:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Conversation id (uuid)." } }, { "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." } }, { "name": "wait", "in": "query", "required": false, "schema": { "default": 0, "description": "Seconds to wait for the AI reply, 0–20. Not part of the idempotency key.", "type": "integer", "minimum": 0, "maximum": 20 } } ], "requestBody": { "required": true, "description": "The customer message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" } } } }, "responses": { "202": { "description": "Accepted; the AI reply is being prepared (202), ready within wait (200) or not requested (201).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageAccepted" } } } }, "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": "Possible codes: wallet_suspended, spend_limit_reached. 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, 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" } } } }, "409": { "description": "Possible codes: channel_not_configured, invalid_state, idempotency_conflict, operation_in_progress. 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": "Possible codes: rate_limited, concurrency_limit. Details: /developers/errors.", "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": "Possible codes: service_unavailable, upstream_unavailable. Details: /developers/errors.", "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", "validation_failed", "bad_request", "payload_too_large", "not_found", "channel_not_configured", "invalid_state", "idempotency_key_required", "idempotency_conflict", "operation_in_progress", "concurrency_limit", "spend_limit_reached", "upstream_unavailable" ] } }, "/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. Personal-data fields (contact.first_name, contact.last_name, contact.email, contact.phone, contact.geo_country, contact.geo_city, title, intent, ai_summary, score.reason, next_action, lost_reason) are returned only when named in fields=; 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). On the EN and ID cells these values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.", "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" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000, "description": "Comma-separated fields to return (id is always present). Without the parameter every field EXCEPT personal-data fields is returned; a personal-data field is returned only when named explicitly: top-level (title, content) or nested (contact.email, score.reason). An unknown name — 422. Only the returned fields are recorded in the disclosure log." } }, { "name": "Encryption-Key-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "EN and ID cells only: which registered key (kid) to build the JWE with — the active one or the previous one for 7 days after a change. The header enables the JWE format even in mode off." } } ], "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" } } } }, "409": { "description": "Encryption key is required. The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "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", "encryption_key_required" ] } }, "/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. Personal-data fields (contact.first_name, contact.last_name, contact.email, contact.phone, contact.geo_country, contact.geo_city, title, intent, ai_summary, score.reason, next_action, lost_reason) are returned only when named in fields=; 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). On the EN and ID cells these values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.", "security": [ { "bearerAuth": [ "leads:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Lead id (uuid)." } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2000, "description": "Comma-separated fields to return (id is always present). Without the parameter every field EXCEPT personal-data fields is returned; a personal-data field is returned only when named explicitly: top-level (title, content) or nested (contact.email, score.reason). An unknown name — 422. Only the returned fields are recorded in the disclosure log." } }, { "name": "Encryption-Key-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "EN and ID cells only: which registered key (kid) to build the JWE with — the active one or the previous one for 7 days after a change. The header enables the JWE format even in mode off." } } ], "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" } } } }, "409": { "description": "Encryption key is required. The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "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", "encryption_key_required" ] } }, "/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).", "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. A subscription has no secret: every delivery is signed with the platform key (JWS EdDSA with a detached payload; headers Webhook-Event-Id, Webhook-Timestamp, Webhook-Signature); verify it with the public key from GET /.well-known/jwks.json. 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.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "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.", "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}/test": { "post": { "operationId": "testWebhook", "tags": [ "webhooks" ], "summary": "Send a test event", "description": "Queues a webhook.test event (livemode: false) for this subscription only; it is signed exactly like live events. 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" ] } }, "/.well-known/jwks.json": { "get": { "operationId": "getWebhookJwks", "tags": [ "webhooks" ], "summary": "Webhook signing public keys", "description": "The cell public key set (JWKS) for verifying the Webhook-Signature header. No authentication; cacheable (Cache-Control: max-age=300); on an unknown kid, fetch the set again. The signed payload is the string \"..\"; the signature is a compact JWS with an empty middle part (RFC 7515, Appendix F). Reject deliveries whose Webhook-Timestamp is older than 5 minutes.", "security": [], "responses": { "200": { "description": "The key set.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookJwks" } } } }, "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": [ "service_unavailable", "internal_error" ] } }, "/channels/{id}/widget": { "get": { "operationId": "getChannelWidget", "tags": [ "channels" ], "summary": "Get chat widget settings", "description": "Appearance of the chat widget of your web_chat channel: assistant, operator queue, attribution, visitor files, color and more. A channel of another type or another account — not_found.", "security": [ { "bearerAuth": [ "channels:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The web_chat channel id." } } ], "responses": { "200": { "description": "Widget settings.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelWidget" } } } }, "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": "updateChannelWidget", "tags": [ "channels" ], "summary": "Update chat widget settings", "description": "The same checks as in the dashboard: color #rrggbb, image URLs https:// or a path on your site only, field lengths; a failure is validation_failed with field errors. The change is recorded in the audit log.", "security": [ { "bearerAuth": [ "channels:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The web_chat channel id." } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelWidgetUpdate" } } } }, "responses": { "200": { "description": "Settings after the update.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelWidget" } } } }, "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. 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", "not_found", "bad_request", "validation_failed", "payload_too_large" ] } }, "/cards": { "get": { "operationId": "listCards", "tags": [ "cards" ], "summary": "List cards", "description": "The account product cards ordered by sort, then by creation. ai_enabled=true|false — only cards available (or not) to the AI seller.", "security": [ { "bearerAuth": [ "cards:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "description": "Page size, 1–100, default 50.", "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": "ai_enabled", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter by availability to the AI seller." } } ], "responses": { "200": { "description": "A page of cards.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardPage" } } } }, "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" ] }, "post": { "operationId": "createCard", "tags": [ "cards" ], "summary": "Create a card", "description": "Creates a product with a card. A taken code — validation_failed on /code. URLs: https:// or a path on your site (\"/…\") only; javascript:, data:, http: and another account storage path are rejected (validation_failed).", "security": [ { "bearerAuth": [ "cards:write" ] } ], "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": "The card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCreate" } } } }, "responses": { "201": { "description": "The card.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "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. Details: /developers/errors.", "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" } } } }, "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", "bad_request", "validation_failed", "payload_too_large", "idempotency_key_required", "idempotency_conflict", "operation_in_progress" ] } }, "/cards/{code}": { "get": { "operationId": "getCard", "tags": [ "cards" ], "summary": "Get a card", "description": "A card by code. Another account card or a missing one — not_found.", "security": [ { "bearerAuth": [ "cards:read" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The card code." } } ], "responses": { "200": { "description": "The card.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "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": "updateCard", "tags": [ "cards" ], "summary": "Update a card", "description": "Changes the given fields; pass at least one. Messages already sent do not change — they hold a copy of the card. URLs: https:// or a path on your site (\"/…\") only; javascript:, data:, http: and another account storage path are rejected (validation_failed).", "security": [ { "bearerAuth": [ "cards:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The card code." } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdate" } } } }, "responses": { "200": { "description": "The card after the update.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "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. 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", "not_found", "bad_request", "validation_failed", "payload_too_large" ] }, "delete": { "operationId": "deleteCard", "tags": [ "cards" ], "summary": "Delete a card", "description": "Removes the card from the product (code, image, buttons, AI seller access); the product itself stays. A repeat — not_found.", "security": [ { "bearerAuth": [ "cards:write" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "description": "The card code." } } ], "responses": { "204": { "description": "The card is removed; 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" ] } }, "/conversations/{id}/cards": { "post": { "operationId": "sendConversationCards", "tags": [ "cards" ], "summary": "Send cards to a conversation", "description": "An operator message with the cards (a copy at the time of sending, URLs resolved). The integration channel gets a message.created event; the site widget shows the cards; Telegram, VK and Max — in their own format; other channels — as text. An unknown or inactive code — validation_failed on /codes. A conversation of another tenant, the student portal or a personal inbox — not_found. A retry with the same Idempotency-Key returns the same message.", "security": [ { "bearerAuth": [ "conversations:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The conversation 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." } } ], "requestBody": { "required": true, "description": "Card codes and a comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSend" } } } }, "responses": { "201": { "description": "The message is saved.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSendResult" } } } }, "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" } } } }, "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" } } } }, "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", "not_found", "bad_request", "validation_failed", "payload_too_large", "idempotency_key_required", "idempotency_conflict", "operation_in_progress" ] } } }, "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", "channel_not_configured", "encryption_key_required", "precondition_failed", "precondition_required", "payload_too_large", "validation_failed", "rate_limited", "concurrency_limit", "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." }, "PiiEncryption": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ], "description": "off — personal-data fields are returned as is; optional — in JWE format when a key is registered; required — only in JWE format (no key — 409 encryption_key_required). The mode is set in the dashboard." }, "key": { "anyOf": [ { "type": "object", "properties": { "kid": { "type": "string", "description": "Key id (from the JWK or the RFC 7638 thumbprint)." }, "alg": { "type": "string", "description": "Key management algorithm: ECDH-ES+A256KW, RSA-OAEP-256 or RSA-OAEP-384." }, "kty": { "type": "string", "enum": [ "EC", "OKP", "RSA" ] }, "crv": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Curve (EC/OKP); null for RSA." }, "rsa_bits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "RSA modulus length, bits; null for EC/OKP." }, "thumbprint": { "type": "string", "description": "Public key thumbprint (RFC 7638, SHA-256)." }, "created_at": { "type": "string", "description": "When the key was registered, ISO 8601 UTC." } }, "required": [ "kid", "alg", "kty", "crv", "rsa_bits", "thumbprint", "created_at" ] }, { "type": "null" } ], "description": "The active recipient public key; null — none registered." }, "previous_key": { "anyOf": [ { "type": "object", "properties": { "kid": { "type": "string", "description": "Key id (from the JWK or the RFC 7638 thumbprint)." }, "alg": { "type": "string", "description": "Key management algorithm: ECDH-ES+A256KW, RSA-OAEP-256 or RSA-OAEP-384." }, "kty": { "type": "string", "enum": [ "EC", "OKP", "RSA" ] }, "crv": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Curve (EC/OKP); null for RSA." }, "rsa_bits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "RSA modulus length, bits; null for EC/OKP." }, "thumbprint": { "type": "string", "description": "Public key thumbprint (RFC 7638, SHA-256)." }, "created_at": { "type": "string", "description": "When the key was registered, ISO 8601 UTC." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kid", "alg", "kty", "crv", "rsa_bits", "thumbprint", "created_at", "expires_at" ] }, { "type": "null" } ], "description": "The previous key after a change: it can still be requested with the Encryption-Key-Id header until expires_at (7 days)." }, "accepted": { "anyOf": [ { "type": "object", "properties": { "alg": { "type": "array", "items": { "type": "string" } }, "crv": { "type": "array", "items": { "type": "string" } }, "min_rsa_bits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enc": { "type": "string", "const": "A256GCM" } }, "required": [ "alg", "crv", "min_rsa_bits", "enc" ] }, { "type": "null" } ], "description": "Which keys this cell accepts." } }, "required": [ "mode", "key", "previous_key", "accepted" ], "description": "The JWE format (RFC 7516) of personal-data fields: EN and ID cells only. You create the key pair; only the public key is sent to the platform." }, "PiiEncryptionKeyPut": { "type": "object", "properties": { "jwk": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The recipient public key (JWK) with an alg member. Private members (d, p, q, dp, dq, qi, k) are rejected." } }, "required": [ "jwk" ], "description": "The key registration body." }, "PiiEncryptionKeyResult": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "optional", "required" ], "description": "off — personal-data fields are returned as is; optional — in JWE format when a key is registered; required — only in JWE format (no key — 409 encryption_key_required). The mode is set in the dashboard." }, "key": { "anyOf": [ { "type": "object", "properties": { "kid": { "type": "string", "description": "Key id (from the JWK or the RFC 7638 thumbprint)." }, "alg": { "type": "string", "description": "Key management algorithm: ECDH-ES+A256KW, RSA-OAEP-256 or RSA-OAEP-384." }, "kty": { "type": "string", "enum": [ "EC", "OKP", "RSA" ] }, "crv": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Curve (EC/OKP); null for RSA." }, "rsa_bits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "RSA modulus length, bits; null for EC/OKP." }, "thumbprint": { "type": "string", "description": "Public key thumbprint (RFC 7638, SHA-256)." }, "created_at": { "type": "string", "description": "When the key was registered, ISO 8601 UTC." } }, "required": [ "kid", "alg", "kty", "crv", "rsa_bits", "thumbprint", "created_at" ] }, { "type": "null" } ], "description": "The active recipient public key; null — none registered." }, "previous_key": { "anyOf": [ { "type": "object", "properties": { "kid": { "type": "string", "description": "Key id (from the JWK or the RFC 7638 thumbprint)." }, "alg": { "type": "string", "description": "Key management algorithm: ECDH-ES+A256KW, RSA-OAEP-256 or RSA-OAEP-384." }, "kty": { "type": "string", "enum": [ "EC", "OKP", "RSA" ] }, "crv": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Curve (EC/OKP); null for RSA." }, "rsa_bits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "RSA modulus length, bits; null for EC/OKP." }, "thumbprint": { "type": "string", "description": "Public key thumbprint (RFC 7638, SHA-256)." }, "created_at": { "type": "string", "description": "When the key was registered, ISO 8601 UTC." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kid", "alg", "kty", "crv", "rsa_bits", "thumbprint", "created_at", "expires_at" ] }, { "type": "null" } ], "description": "The previous key after a change: it can still be requested with the Encryption-Key-Id header until expires_at (7 days)." }, "accepted": { "anyOf": [ { "type": "object", "properties": { "alg": { "type": "array", "items": { "type": "string" } }, "crv": { "type": "array", "items": { "type": "string" } }, "min_rsa_bits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enc": { "type": "string", "const": "A256GCM" } }, "required": [ "alg", "crv", "min_rsa_bits", "enc" ] }, { "type": "null" } ], "description": "Which keys this cell accepts." }, "changed": { "type": "boolean", "description": "false — the same key was already registered." } }, "required": [ "mode", "key", "previous_key", "accepted", "changed" ], "description": "The setting after the key registration." }, "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", "channels:read", "channels:write", "cards:read", "cards:write" ] }, "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 AI operations per integration; beyond it — 429 concurrency_limit." }, "max_operation_cost": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The per-operation cost cap in the wallet currency (a higher estimate — 402 spend_limit_reached); null — could not be read." } }, "required": [ "read_per_min", "write_per_min", "paid_per_min", "paid_concurrency", "max_operation_cost" ], "description": "Request rate and paid-operation 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": { "anyOf": [ { "type": "object", "properties": { "limit": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The integration daily spend limit; null — not set." }, "used": { "description": "Charged for the integration paid operations since the start of the cell local day.", "$ref": "#/components/schemas/Money" } }, "required": [ "limit", "used" ] }, { "type": "null" } ], "description": "The integration daily spend; null — could not be computed." } }, "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." }, "pii_encryption": { "description": "EN and ID cells only: the JWE format of personal-data fields; null — the setting could not be read. Absent on the RU cell.", "anyOf": [ { "$ref": "#/components/schemas/PiiEncryption" }, { "type": "null" } ] } }, "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." } }, "required": [ "id", "url", "events", "include_pii", "description", "status", "created_at", "updated_at" ], "description": "An event subscription. A subscription has no secret: every delivery is signed with the platform key (JWS EdDSA, the Webhook-Signature header); the public keys are at GET /.well-known/jwks.json." }, "WebhookJwk": { "type": "object", "properties": { "kty": { "type": "string", "const": "OKP" }, "crv": { "type": "string", "const": "Ed25519" }, "x": { "type": "string", "description": "The public key, base64url." }, "kid": { "type": "string", "description": "Key id (RFC 7638 thumbprint); equals the kid in the signature header." }, "alg": { "type": "string", "const": "EdDSA" }, "use": { "type": "string", "const": "sig" } }, "required": [ "kty", "crv", "x", "kid", "alg", "use" ], "description": "A webhook signing public key." }, "WebhookJwks": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookJwk" }, "description": "The active key and keys still valid after a rotation." } }, "required": [ "keys" ], "description": "The cell webhook signing public key set (RFC 7517)." }, "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." }, "ChannelWidgetPoweredBy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "default", "custom", "hidden" ], "description": "default — the cell product name; custom — your text and link; hidden — no attribution." }, "text": { "description": "Attribution text for custom, up to 40 characters.", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "url": { "description": "Attribution link for custom: https:// only.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "mode" ], "description": "The attribution line at the bottom of the widget." }, "ChannelWidgetFiles": { "type": "object", "properties": { "visitor_upload": { "type": "boolean", "description": "Visitors may send files. Default true." }, "max_mb": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Per-file limit, MB (1–10)." } }, "required": [ "visitor_upload", "max_mb" ], "description": "Visitor files." }, "ChannelWidget": { "type": "object", "properties": { "channel_id": { "type": "string", "description": "The web_chat channel id." }, "name": { "type": "string", "description": "Channel name." }, "is_active": { "type": "boolean", "description": "The channel is active." }, "assistant_name": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Assistant name in the header; defaults to the channel name. Up to 60 characters." }, { "type": "null" } ] }, "assistant_subtitle": { "anyOf": [ { "type": "string", "maxLength": 80, "description": "Assistant subtitle. Up to 80 characters." }, { "type": "null" } ] }, "assistant_avatar_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Assistant icon (header and feed). Only https:// or a path on this cell starting with \"/\". Up to 500 characters." }, { "type": "null" } ] }, "queue_title": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Header title while the conversation waits for an operator. Up to 60 characters." }, { "type": "null" } ] }, "queue_subtitle": { "anyOf": [ { "type": "string", "maxLength": 80, "description": "Subtitle while waiting for an operator. Up to 80 characters." }, { "type": "null" } ] }, "queue_icon_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Icon while waiting for an operator. Only https:// or a path on this cell starting with \"/\". Up to 500 characters." }, { "type": "null" } ] }, "powered_by": { "$ref": "#/components/schemas/ChannelWidgetPoweredBy" }, "files": { "$ref": "#/components/schemas/ChannelWidgetFiles" }, "color": { "anyOf": [ { "type": "string", "description": "Widget color: #rrggbb." }, { "type": "null" } ] }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Greeting. Up to 500 characters." }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "string", "enum": [ "bottom-right", "bottom-left" ], "description": "Launcher corner." }, { "type": "null" } ] }, "theme": { "anyOf": [ { "type": "string", "enum": [ "light", "dark" ], "description": "Theme." }, { "type": "null" } ] }, "bubble_text": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Launcher hint text. Up to 60 characters." }, { "type": "null" } ] }, "delay": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120, "description": "Display delay, seconds." }, { "type": "null" } ] }, "consent_text": { "anyOf": [ { "type": "string", "maxLength": 600, "description": "Consent text before the first message. Up to 600 characters." }, { "type": "null" } ] }, "consent_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Link to the consent document: https:// only." }, { "type": "null" } ] } }, "required": [ "channel_id", "name", "is_active", "assistant_name", "assistant_subtitle", "assistant_avatar_url", "queue_title", "queue_subtitle", "queue_icon_url", "powered_by", "files", "color", "greeting", "position", "theme", "bubble_text", "delay", "consent_text", "consent_url" ], "description": "Chat widget settings of the channel. null — the default value." }, "ChannelWidgetUpdate": { "type": "object", "properties": { "assistant_name": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Assistant name in the header; defaults to the channel name. Up to 60 characters." }, { "type": "null" } ] }, "assistant_subtitle": { "anyOf": [ { "type": "string", "maxLength": 80, "description": "Assistant subtitle. Up to 80 characters." }, { "type": "null" } ] }, "assistant_avatar_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Assistant icon (header and feed). Only https:// or a path on this cell starting with \"/\". Up to 500 characters." }, { "type": "null" } ] }, "queue_title": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Header title while the conversation waits for an operator. Up to 60 characters." }, { "type": "null" } ] }, "queue_subtitle": { "anyOf": [ { "type": "string", "maxLength": 80, "description": "Subtitle while waiting for an operator. Up to 80 characters." }, { "type": "null" } ] }, "queue_icon_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Icon while waiting for an operator. Only https:// or a path on this cell starting with \"/\". Up to 500 characters." }, { "type": "null" } ] }, "powered_by": { "anyOf": [ { "$ref": "#/components/schemas/ChannelWidgetPoweredBy" }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": { "visitor_upload": { "type": "boolean", "description": "Visitors may send files. Default true." }, "max_mb": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Per-file limit, MB (1–10)." } } }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string", "description": "Widget color: #rrggbb." }, { "type": "null" } ] }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Greeting. Up to 500 characters." }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "string", "enum": [ "bottom-right", "bottom-left" ], "description": "Launcher corner." }, { "type": "null" } ] }, "theme": { "anyOf": [ { "type": "string", "enum": [ "light", "dark" ], "description": "Theme." }, { "type": "null" } ] }, "bubble_text": { "anyOf": [ { "type": "string", "maxLength": 60, "description": "Launcher hint text. Up to 60 characters." }, { "type": "null" } ] }, "delay": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120, "description": "Display delay, seconds." }, { "type": "null" } ] }, "consent_text": { "anyOf": [ { "type": "string", "maxLength": 600, "description": "Consent text before the first message. Up to 600 characters." }, { "type": "null" } ] }, "consent_url": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Link to the consent document: https:// only." }, { "type": "null" } ] } }, "description": "Update: pass at least one field. Omitted fields stay as they are, null restores the default; unknown fields are ignored." }, "CardButton": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 30, "description": "Label, up to 30 characters." }, "url": { "type": "string", "maxLength": 2000, "description": "Button URL. Only https:// or a path on your site starting with \"/\" (resolved against the account primary domain)." } }, "required": [ "label", "url" ], "description": "A card button." }, "Card": { "type": "object", "properties": { "id": { "type": "string", "description": "The product id." }, "code": { "type": "string", "maxLength": 40, "description": "The card code, unique in the account: lowercase latin letters, digits, \"_\" and \"-\", up to 40 characters. The AI seller puts the [CARD:code] marker into its reply." }, "name": { "type": "string", "maxLength": 120, "description": "Name. Up to 120 characters." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Description. Up to 500 characters." }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Image: https:// or the path of a file uploaded to your account storage." }, { "type": "null" } ] }, "price_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Price as text; when not set — from the product price and currency; null — no price." }, "badge": { "anyOf": [ { "type": "string", "maxLength": 30, "description": "Badge (\"Bestseller\"). Up to 30 characters." }, { "type": "null" } ] }, "page_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Product page. Only https:// or a path on your site starting with \"/\" (resolved against the account primary domain)." }, { "type": "null" } ] }, "buttons": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/CardButton" }, "description": "Up to 3 buttons. Empty — a single \"Learn more\" button to page_url." }, "ai_enabled": { "type": "boolean", "description": "The card is available to the AI seller: code, name and price go into its catalogue. Requires a code." }, "sort": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order in the AI seller catalogue and the operator picker (ascending)." }, "active": { "type": "boolean", "description": "The product is active; an inactive card cannot be sent." }, "created_at": { "type": "string", "description": "ISO 8601 UTC." }, "updated_at": { "type": "string", "description": "ISO 8601 UTC." } }, "required": [ "id", "code", "name", "description", "image_url", "price_text", "badge", "page_url", "buttons", "ai_enabled", "sort", "active", "created_at", "updated_at" ], "description": "A product card for chat: image, name, price and up to three buttons. Stored on the account product." }, "CardCreate": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 40, "description": "The card code, unique in the account: lowercase latin letters, digits, \"_\" and \"-\", up to 40 characters. The AI seller puts the [CARD:code] marker into its reply." }, "name": { "type": "string", "maxLength": 120, "description": "Name. Up to 120 characters." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Description. Up to 500 characters." }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Image: https:// or the path of a file uploaded to your account storage." }, { "type": "null" } ] }, "page_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Product page. Only https:// or a path on your site starting with \"/\" (resolved against the account primary domain)." }, { "type": "null" } ] }, "badge": { "anyOf": [ { "type": "string", "maxLength": 30, "description": "Badge (\"Bestseller\"). Up to 30 characters." }, { "type": "null" } ] }, "price_text": { "anyOf": [ { "type": "string", "maxLength": 40, "description": "Price as text. Up to 40 characters." }, { "type": "null" } ] }, "buttons": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/CardButton" }, "description": "Up to 3 buttons. Empty — a single \"Learn more\" button to page_url." }, "ai_enabled": { "type": "boolean", "description": "The card is available to the AI seller: code, name and price go into its catalogue. Requires a code." }, "sort": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order in the AI seller catalogue and the operator picker (ascending)." }, "active": { "type": "boolean", "description": "The product is active; an inactive card cannot be sent." } }, "required": [ "code", "name" ], "description": "The card creation body. Unknown fields — 422." }, "CardUpdate": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 40, "description": "The card code, unique in the account: lowercase latin letters, digits, \"_\" and \"-\", up to 40 characters. The AI seller puts the [CARD:code] marker into its reply." }, "name": { "type": "string", "maxLength": 120, "description": "Name. Up to 120 characters." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500, "description": "Description. Up to 500 characters." }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Image: https:// or the path of a file uploaded to your account storage." }, { "type": "null" } ] }, "page_url": { "anyOf": [ { "type": "string", "maxLength": 2000, "description": "Product page. Only https:// or a path on your site starting with \"/\" (resolved against the account primary domain)." }, { "type": "null" } ] }, "badge": { "anyOf": [ { "type": "string", "maxLength": 30, "description": "Badge (\"Bestseller\"). Up to 30 characters." }, { "type": "null" } ] }, "price_text": { "anyOf": [ { "type": "string", "maxLength": 40, "description": "Price as text. Up to 40 characters." }, { "type": "null" } ] }, "buttons": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/CardButton" }, "description": "Up to 3 buttons. Empty — a single \"Learn more\" button to page_url." }, "ai_enabled": { "type": "boolean", "description": "The card is available to the AI seller: code, name and price go into its catalogue. Requires a code." }, "sort": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order in the AI seller catalogue and the operator picker (ascending)." }, "active": { "type": "boolean", "description": "The product is active; an inactive card cannot be sent." } }, "description": "The update body: pass at least one field." }, "CardPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "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." }, "MessageCard": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 40, "description": "The card code, unique in the account: lowercase latin letters, digits, \"_\" and \"-\", up to 40 characters. The AI seller puts the [CARD:code] marker into its reply." }, "name": { "type": "string", "maxLength": 120, "description": "Name. Up to 120 characters." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full https image URL." }, "price_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "badge": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full https page URL; null — a path without an account domain." }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/CardButton" } } }, "required": [ "code", "name", "description", "image_url", "price_text", "badge", "page_url", "buttons" ], "description": "A copy of the card in the message at the time of sending (URLs resolved)." }, "CardSend": { "type": "object", "properties": { "codes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string" }, "description": "Card codes, 1–3." }, "comment": { "description": "Text above the cards, up to 1000 characters.", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "codes" ], "description": "The body for sending cards to a conversation." }, "CardSendResult": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The id of the message with the cards." }, "conversation_id": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 UTC." }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/MessageCard" } }, "delivery": { "type": "string", "enum": [ "metadata", "native", "text" ], "description": "How the cards reach the customer: metadata — the site widget and the integration channel (message.created event); native — Telegram, VK, Max in their own format; text — as \"name — price — link\" lines." }, "status": { "type": "string", "enum": [ "sent", "delivered", "failed" ], "description": "Channel delivery state." } }, "required": [ "message_id", "conversation_id", "created_at", "cards", "delivery", "status" ], "description": "The 201 response to sending cards." }, "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 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": { "description": "Charged since the start of the cell local day.", "$ref": "#/components/schemas/Money" } }, "required": [ "limit", "used" ] }, { "type": "null" } ], "description": "The integration daily spend: charges for its paid operations since the start of the cell local day; null — could not be computed." } }, "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 platform contact (customer) id." }, "external_customer_id": { "description": "The customer id in your system. Channel api only; null for other channels (the messenger external id is not disclosed). Personal data: on reads it is returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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." }, "_enc": { "description": "EN and ID cells only, when the JWE format is in effect: fields of this object whose values are replaced by a compact JWE string (the plaintext is the JSON of the original value).", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "channel", "contact_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." }, "name": { "description": "File name (attachments uploaded via the widget or by an operator).", "type": "string" }, "size": { "description": "Size, bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "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": { "description": "The text; null — no text (attachment only) or the message is deleted. Personal data: on reads it is returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attachments": { "description": "Attachments: up to five files per message. Personal data: on reads it is returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" } }, { "type": "string" } ] }, "cards": { "description": "Product cards of the message (up to three); no field — no cards. They contain no personal data.", "type": "array", "items": { "$ref": "#/components/schemas/MessageCard" } }, "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." }, "_enc": { "description": "EN and ID cells only, when the JWE format is in effect: fields of this object whose values are replaced by a compact JWE string (the plaintext is the JSON of the original value).", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "conversation_id", "sender", "content_type", "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." }, "ConversationCreate": { "type": "object", "properties": { "external_customer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A stable customer id in your system (not a phone or email). The platform finds or creates the contact and the conversation by it; ids of different integrations never mix." }, "name": { "description": "Customer name. Written only into an empty contact field.", "type": "string", "maxLength": 120 }, "email": { "description": "Customer email. Written only into an empty contact field.", "type": "string", "maxLength": 254 }, "phone": { "description": "Phone in international format (+…). Written only into an empty contact field.", "type": "string", "maxLength": 32 }, "language": { "description": "Language of a new conversation (ISO 639-1). The AI reply language is limited to the cell languages.", "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "external_customer_id" ], "description": "A conversation of your channel customer. Unknown fields — 422." }, "MessageCreate": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The customer message text, up to 4000 characters." }, "ai_reply": { "default": "auto", "description": "auto — request an AI seller reply (needs the ai_seller:invoke scope; without it the message is only saved); none — only save the message.", "type": "string", "enum": [ "auto", "none" ] } }, "required": [ "content", "ai_reply" ], "description": "A customer message. Attachments are not accepted in v1. Unknown fields — 422." }, "AiReply": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "replied", "queued", "queued_for_review", "skipped" ], "description": "replied — the AI answered (the reply is a separate conversation message); queued — the reply is being prepared (operation); queued_for_review — the AI reply became a draft awaiting an operator (supervised mode); skipped — the AI will not answer, see reason." }, "reason": { "description": "skipped only: operator_active, spam, flow_reply, ai_unavailable_handoff, no_agent, daily_limit, insufficient_funds, upstream_unavailable, quota_exceeded, not_requested. The list may grow.", "type": "string", "enum": [ "operator_active", "spam", "flow_reply", "ai_unavailable_handoff", "no_agent", "daily_limit", "insufficient_funds", "upstream_unavailable", "quota_exceeded", "not_requested" ] } }, "required": [ "status" ], "description": "What happened to the AI reply to the customer message." }, "MessageAccepted": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The id of the saved customer message." }, "conversation_id": { "type": "string", "description": "The conversation." }, "ai_reply": { "$ref": "#/components/schemas/AiReply" }, "reply": { "description": "replied only: the AI reply id. No text here — read it with GET /conversations/{id}/messages (the disclosure is logged).", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "operation": { "description": "The conversation.ai_reply operation: queued or running with 202, finished with 200 (usage.cost — charged to the wallet in its currency). Absent when no AI reply was requested.", "$ref": "#/components/schemas/Operation" } }, "required": [ "message_id", "conversation_id", "ai_reply" ], "description": "The customer message was accepted." }, "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": { "description": "Explanation of the score; null until recorded. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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", "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": { "description": "First name (contact.first_name). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "description": "Last name (contact.last_name). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "description": "Email (contact.email). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "description": "Phone (contact.phone). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "geo_country": { "description": "Country by IP, ISO 3166-1 alpha-2 (contact.geo_country). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "geo_city": { "description": "City by IP (contact.geo_city). Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "tags" ], "description": "The lead contact. Personal-data fields are returned only when named in fields=; 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": { "description": "Lead title. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "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": { "description": "Customer intent. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ai_summary": { "description": "AI summary of the conversation. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_action": { "description": "Next action. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_action_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 UTC." }, { "type": "null" } ] }, "lost_reason": { "description": "Lost reason. Personal data: returned only when named in fields=. On the EN and ID cells in JWE format — a compact JWE string.", "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." }, "_enc": { "description": "EN and ID cells only, when the JWE format is in effect: paths of this object fields whose values are replaced by a compact JWE string (the plaintext is the JSON of the original value).", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "external_id", "external_url", "version", "etag", "status", "archived", "archived_reason", "owner", "source", "assigned_to", "value", "product_id", "course_slug", "contact", "conversation_id", "attribution", "score", "flags", "next_action_at", "qualified_at", "won_at", "lost_at", "last_activity_at", "created_at", "updated_at" ], "description": "A tenant lead. With fields= only the listed fields (and id) are returned." }, "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.", "channels:read": "Requires an owner permission: settings.channels.", "channels:write": "Requires an owner permission: settings.channels.", "cards:read": "Requires an owner permission: settings.products.", "cards:write": "Requires an owner permission: settings.products." }, "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": "The integration daily spend limit was reached (the day is counted in the cell time zone), or the estimated cost of the operation exceeds the per-operation cap (100 in the wallet currency by default). The concurrency limit is a separate code, concurrency_limit (429).", "action": "Wait for the next day or raise the limit; for the per-operation cap, pick a cheaper model for the agent or lower max_tokens. The limit and the spend are in GET /me (wallet.daily_spend, limits.max_operation_cost)." }, { "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": "channel_not_configured", "status": 409, "title": "Integration channel is not configured", "group": "request", "when": "The integration has no api channel, so there is nowhere to create conversations or accept customer messages. Connect the channel in the dashboard (Settings → API → “Connect chat channel”).", "action": "Connect the channel in the dashboard; channel_id is visible in GET /me. Retrying without it is pointless." }, { "code": "encryption_key_required", "status": 409, "title": "Encryption key is required", "group": "request", "when": "The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only.", "action": "Register your public key (PUT /me/encryption-key or the dashboard), or request fields without personal data via fields=." }, { "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": "concurrency_limit", "status": 429, "title": "Too many concurrent operations", "group": "money", "when": "The integration already runs the maximum number of concurrent paid operations (5 by default; see GET /me, limits.paid_concurrency).", "action": "Wait for Retry-After or for running operations to finish and retry with the same Idempotency-Key. Queue the messages on your side." }, { "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." } ] }