{"openapi":"3.0.3","info":{"title":"Public API Service","version":"1.0.0","description":"Public API for communications, speaker profiles, balance history, payment links, cabinet session links, and chat agents."},"servers":[{"url":"/"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Client API key (`sk_live_…`)"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Client API key (`sk_live_…`). Alternative to Bearer."}},"schemas":{"SpeakerSummaryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary_id":{"type":["string","null"],"format":"uuid"},"item_type":{"type":"string"},"subtype":{"type":["string","null"]},"content":{"type":"string"},"meta":{"type":["object","null"]},"speaker_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"}},"additionalProperties":true},"CommunicationSpeaker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"label":{"type":["string","null"]}},"additionalProperties":true},"ContentItem":{"type":"object","required":["idx","kind","text","media"],"properties":{"idx":{"type":"integer","minimum":0,"description":"0-based order; sort by idx if needed"},"kind":{"type":"string","enum":["audio_utterance","chat_message","email_message"]},"at":{"type":["string","null"],"format":"date-time","description":"Absolute ISO wall-clock; null when base time or start_ms unknown"},"text":{"type":"string","description":"Empty string allowed for media-only items"},"label":{"type":["string","null"],"description":"Join key to speakers[].label (e.g. SPEAKER_00)"},"start_ms":{"type":["integer","null"],"description":"Offset from recording start"},"end_ms":{"type":["integer","null"]},"media":{"type":"array","items":{"type":"object","required":["type","ref"],"properties":{"type":{"type":"string","enum":["audio","image","video","file"]},"ref":{"type":"string"},"mime":{"type":"string"},"name":{"type":"string"},"size_bytes":{"type":"integer"},"duration_ms":{"type":"integer"}}}}},"additionalProperties":false},"CommunicationDetails":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid","description":"Communication id"},"kind":{"type":"string","description":"call | chat | email"},"channel_type":{"type":"string","description":"phone | telegram | whatsapp | email | widget"},"communication_status":{"type":"string","description":"active | closed"},"request_record_id":{"type":"string"},"created_at":{"type":"string"},"occured_at":{"type":"string"},"duration_ms":{"type":["integer","null"],"description":"Communication media duration in milliseconds."},"language":{"type":["string","null"],"description":"Communication language (ASR code, e.g. ru)."},"direction":{"type":["string","null"]},"transcription_status":{"type":["string","null"],"description":"ASR pipeline status: pending, processing, success, error (null when ASR does not apply)."},"summary_generation_status":{"type":"string","description":"Analyze/summary pipeline status: pending, processing, success, error, or skipped (aligned with communication_job.analyze; missing job → skipped). Terminal: success, error, skipped."},"qc_generation_status":{"type":"string","description":"Quality-control status: pending, processing, success, error, or skipped"},"memory_generation_status":{"type":"string","description":"Speaker-memory extract status: pending, processing, success, error, or skipped (aligned with communication_job.memory; missing job → skipped). Terminal: success, error, skipped. Runs after summarize when features.memory is on."},"qc_generation_error_message":{"type":["string","null"],"description":"Error details when QC failed; otherwise null"},"qc_generation_updated_at":{"type":["string","null"],"format":"date-time","description":"Last QC status update time"},"qc_evaluation":{"type":["object","null"],"description":"Quality-control result when available","properties":{"evaluation_id":{"type":"string","format":"uuid"},"scenario_code":{"type":"string","description":"Matched scenario code"},"score_pct":{"type":["number","null"],"description":"Share of passed binary criteria, percent"},"comment":{"type":["string","null"]},"status":{"type":"string"},"criteria":{"type":"array","description":"Per-criterion scores and evidence","items":{"type":"object","additionalProperties":true}}}},"content":{"type":["array","null"],"description":"Canonical omnichannel timeline (ContentItem). Required for integrations — do not rely on transcription for text.","items":{"$ref":"#/components/schemas/ContentItem"}},"summary_text":{"type":["string","null"]},"user_summary":{"type":["string","null"],"description":"Пользовательский отчёт"},"category":{"type":["string","null"]},"category_label":{"type":["string","null"]},"speakers":{"type":"array","items":{"$ref":"#/components/schemas/CommunicationSpeaker"}},"summary_items":{"type":"array","items":{"$ref":"#/components/schemas/SpeakerSummaryItem"}}},"additionalProperties":true},"CommunicationBySpeaker":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid","description":"Communication id"},"kind":{"type":"string"},"channel_type":{"type":"string"},"request_record_id":{"type":"string"},"created_at":{"type":"string"},"occured_at":{"type":"string"},"duration_ms":{"type":["integer","null"],"description":"Communication media duration in milliseconds (canonical)."},"language":{"type":["string","null"],"description":"Communication language (ASR code, e.g. ru)."},"direction":{"type":["string","null"]},"category":{"type":["string","null"]},"label_ru":{"type":["string","null"]},"summary_text":{"type":["string","null"]},"user_summary":{"type":["string","null"],"description":"Пользовательский отчёт"},"speakers":{"type":"array","items":{"$ref":"#/components/schemas/CommunicationSpeaker"}}},"additionalProperties":true},"SpeakerProfile":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"speaker_id":{"type":"string","format":"uuid"},"speaker_external_id":{"type":"string"},"speaker_name":{"type":"string"},"speaker_role":{"type":"string"},"speaker_department":{"type":["string","null"]},"speaker_created_at":{"type":"string"},"speaker_updated_at":{"type":"string"},"summary_items":{"type":"array","items":{"$ref":"#/components/schemas/SpeakerSummaryItem"}}},"additionalProperties":true},"Balance":{"type":"object","properties":{"balance_rub":{"type":"string","description":"Current balance in RUB (string decimal)."},"is_active":{"type":"boolean","description":"Whether the client is allowed to use paid APIs. False when paused (e.g. insufficient balance without credit)."},"allow_credit":{"type":"boolean","description":"When true, negative balance does not auto-deactivate the client."}},"required":["balance_rub","is_active","allow_credit"],"additionalProperties":true},"BalanceHistoryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount_rub":{"type":"number"},"kind":{"type":"string","enum":["credit","debit","usage"]},"description":{"type":["string","null"]},"product":{"type":["string","null"]},"source":{"type":["string","null"]},"source_ref":{"type":["string","null"],"format":"uuid"},"lines":{"nullable":true},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"BalanceHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BalanceHistoryItem"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","count","total"]}},"additionalProperties":false},"PaymentLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"payment_url":{"type":["string","null"],"format":"uri"},"amount_rub":{"type":"number"},"status":{"type":"string","description":"pending | paid | expired | cancelled | failed"},"customer_email":{"type":"string","description":"Receipt email when known; may be empty when the link was created without a profile/body email"},"purpose":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"SessionLink":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Open in the user's browser; exchanges code for a cabinet session"},"expires_in":{"type":"integer","description":"Code TTL in seconds"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"ChatListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"header_title":{"type":"string"},"is_default":{"type":"boolean"},"default_space_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"workflow_flow_id":{"type":["string","null"],"format":"uuid"},"public_key":{"type":"string","description":"Public embed key (`wk_…`) for site snippets (`data-widget-key`)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"ChatListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChatListItem"}}},"additionalProperties":false},"ChatMessageRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000},"history":{"type":"array","maxItems":40,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":4000}}}},"space_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"additionalProperties":false},"ChatMessageResponse":{"type":"object","required":["request_id","markdown","context"],"properties":{"request_id":{"type":"string","format":"uuid"},"markdown":{"type":"string"},"context":{"type":"object","description":"Source chips (communications, documents, memory) — no expand endpoint in v1","additionalProperties":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{}},"additionalProperties":true},"AuthApiError":{"type":"object","description":"API key auth error in Speech/STT shape. 401 codes: missing_api_key, invalid_api_key, malformed_bearer. 403 code: client_inactive.","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","example":"invalid_request_error"},"param":{"nullable":true,"example":null},"code":{"type":"string","enum":["missing_api_key","invalid_api_key","malformed_bearer","client_inactive"]}},"required":["message","type","code"]}},"required":["error"]}}},"paths":{"/v1/communications":{"get":{"summary":"Get communication by id or request_record_id","description":"Either `id` or `request_record_id` must be provided. Query `id` is the communication UUID. Summary/QC statuses come from communication jobs; Speech task poll is ASR-only. Available when `is_active=false` (read-only pause).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"query","required":false,"description":"Communication UUID.","schema":{"type":"string","format":"uuid"}},{"name":"request_record_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Communication details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationDetails"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/communications/list":{"get":{"summary":"List communications by speaker","description":"At least one of `speaker_id`, `speaker_name` or `speaker_external_id` must be provided. Available when `is_active=false` (read-only pause).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"speaker_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"speaker_name","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"speaker_external_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"List response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CommunicationBySpeaker"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}}}}},"/v1/speakers/profile":{"get":{"summary":"Get speaker profile by speaker_name or speaker_external_id","description":"Either `speaker_name` or `speaker_external_id` must be provided. Available when `is_active=false` (read-only pause).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"speaker_name","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"speaker_external_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Speaker profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeakerProfile"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/balance":{"get":{"summary":"Get balance by API key (client)","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}}},"description":"Returns current balance and billing flags. Available even when `is_active=false` (so partners can detect pause and whether credit is allowed)."}},"/v1/balance/history":{"get":{"summary":"Paginated balance history","description":"Balance history: top-ups and charges (usage lines excluded). Newest first.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"kind","in":"query","description":"Filter by kind. Omit for credit+debit.","schema":{"type":"string","enum":["credit","debit"]}},{"name":"from","in":"query","description":"Inclusive lower bound (ISO datetime)","schema":{"type":"string"}},{"name":"to","in":"query","description":"Inclusive upper bound (ISO datetime)","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance history page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceHistoryResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}}}}},"/v1/payment-link":{"post":{"summary":"Create payment link (top-up)","description":"Creates a payment link (100…100000 RUB, TTL ~15 min). Optional receipt email: `customer_email` in body, else client profile email; without email a payment link is created without fiscal receipt. Available when client is inactive (for top-up / cabinet billing).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_rub"],"properties":{"amount_rub":{"type":"number","minimum":100,"maximum":100000},"customer_email":{"type":"string","format":"email"},"redirect_url":{"type":"string","format":"uri"},"fail_redirect_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Payment link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"502":{"description":"Payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Payment links not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payment-link/{id}":{"get":{"summary":"Get payment link status","description":"`id` from POST /v1/payment-link. Order must belong to the authenticated client. Available when client is inactive (for top-up / cabinet billing).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment link order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Payment links not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/session-link":{"post":{"summary":"Create cabinet session link","description":"Issues a short-lived HMAC link to open the A5X cabinet (`app.a5x.pro/session-link?code=…`). Authenticated by the client's API key. Requires a client email. No request body. Available when client is inactive (for top-up / cabinet billing).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Session link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionLink"},"example":{"tenant_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","url":"https://app.a5x.pro/session-link?code=…","expires_in":60,"expires_at":"2026-08-04T09:01:00.000Z"}}}},"401":{"description":"Unauthorized (missing / invalid / malformed API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"422":{"description":"Client has no email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Session links not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chats/list":{"get":{"summary":"List active chat configs","description":"Active chats for the account: id, name, public_key (embed), and default knowledge-base spaces. Requires the Chat product. Available when the client is paused (`is_active=false`).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Active chats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"403":{"description":"Chat product disabled for the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chats/{chat_id}/messages":{"post":{"summary":"Send a message to a chat agent","description":"Send a question to the selected chat agent and receive the full reply in one HTTP response. Optional body fields: history, space_ids. Without them, chat settings are used. The integrator stores history. Abort the HTTP request to cancel. Billed as chat messages. Requires an active client.","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessageRequest"}}}},"responses":{"200":{"description":"Agent reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessageResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthApiError"}}}},"403":{"description":"Client inactive or feature disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat not found or inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Widget rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Widget upstream error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Chat API not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}