{ "openapi": "3.1.0", "info": { "title": "Famulor API", "version": "1.0.0", "description": "REST API for Famulor. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token.\n\nEvery response uses a consistent envelope: `{ \"data\": ... , \"meta\": { ... } }` on success and `{ \"error\": { \"code\", \"message\" } }` on failure. List endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`; `meta.pagination.total` carries the total match count.\n\nREST operations require API Access through the workspace plan or a recurring add-on. Without it, regular operations return `403 api_access_required`. The invoice-payment and billing-portal operations remain available with a valid `billing:write` credential after a failed plan payment so an authorized owner, admin, or billing member can recover billing.\n\nThe same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access." }, "servers": [ { "url": "https://app.famulor.io/api/v1", "description": "Hosted platform." }, { "url": "https://{domain}/api/v1", "description": "White-label tenant domain — same paths, tenant branding.", "variables": { "domain": { "default": "app.famulor.io", "description": "Your white-label tenant domain." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Self-inspection of the calling credential." }, { "name": "Migrations", "description": "Preview and import data from supported legacy platforms." }, { "name": "Assistants", "description": "Create and manage voice assistants." }, { "name": "Tools", "description": "Reusable tools (HTTP APIs and external MCP servers) assistants can call mid-conversation." }, { "name": "Voices", "description": "Browse the text-to-speech voice library." }, { "name": "Calls", "description": "Start outbound calls and read call history, transcripts and recordings." }, { "name": "History", "description": "Unified conversation history across calls, messaging and assistant emails." }, { "name": "Campaigns", "description": "Outbound calling campaigns with a compliant power dialer." }, { "name": "Leads", "description": "Manage Audience contacts across campaigns, channels and Call QA metrics." }, { "name": "Segments", "description": "Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment." }, { "name": "Suppression", "description": "Cross-channel marketing opt-outs and active workspace suppression records." }, { "name": "Callbacks", "description": "Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email." }, { "name": "Phone Numbers", "description": "Marketplace numbers and customer-provided numbers." }, { "name": "Famulor Loop", "description": "Personal business-phone access, directory, presence, devices, and Loop call recents." }, { "name": "SIP Trunks", "description": "Bring your own SIP provider and numbers." }, { "name": "Carrier Connections", "description": "Connect a supported carrier account and import its existing phone numbers." }, { "name": "Knowledge Bases", "description": "RAG knowledge bases and documents for assistants." }, { "name": "Settings", "description": "Workspace-level settings such as caller-memory defaults." }, { "name": "Billing", "description": "Balance and transaction ledger of the API key's workspace." }, { "name": "Automations", "description": "Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan." }, { "name": "Milian Missions", "description": "Recurring jobs that Milian runs unattended on schedule." }, { "name": "Integrations", "description": "Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling." }, { "name": "Bookings", "description": "Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce." }, { "name": "Dashboards", "description": "Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires Custom dashboards in the workspace plan." }, { "name": "Catalog", "description": "Read-only platform catalogs — available models, supported assistant languages, and prompt templates." }, { "name": "Simulations", "description": "Assistant simulation tests (plan-gated)." }, { "name": "Versions", "description": "Assistant configuration version history." }, { "name": "Caller IDs", "description": "Outbound caller ID verification." }, { "name": "Widgets", "description": "Web widget connectors." }, { "name": "Messaging", "description": "Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks." }, { "name": "QA", "description": "Cohort AI Quality Assurance runs over call transcripts." }, { "name": "White Label", "description": "Manage white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility." }, { "name": "API Keys", "description": "Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own." }, { "name": "Workspaces", "description": "List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace." }, { "name": "SMS", "description": "Outbound SMS from workspace phone numbers." }, { "name": "Milian", "description": "Ask Milian, the AI co-worker in your workspace, and start voice sessions with it." }, { "name": "Translation", "description": "Live translation sessions that interpret a conversation between two languages." } ], "paths": { "/milian/ask": { "post": { "tags": [ "Milian" ], "summary": "Ask Milian", "operationId": "askMilian", "description": "Ask Milian for answers, analysis, and recommendations. Requires milian:write and explicit user approval of additional workspace credits before every question. Usage is billed at the same rates as the dashboard. Milian reads only data permitted by the credential's other scopes and OAuth tool-group grants; it cannot change workspace resources. Questions are standalone, are not added to dashboard chat history, and every new call (including a retry or follow-up) can incur additional credits. Do not retry automatically. Read-only workspace roles cannot start paid questions.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "question", "confirmed" ], "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 12000, "description": "The approved question and necessary context. Must contain non-whitespace text." }, "confirmed": { "type": "boolean", "enum": [ true ], "description": "True only after the user explicitly approves additional Milian credits for this question. No default approval." }, "locale": { "type": "string", "enum": [ "en", "de", "fr", "es" ], "description": "Fallback response language." } } }, "example": { "question": "Analyse the outcome of my recent calls.", "confirmed": true, "locale": "en" } } } }, "responses": { "200": { "description": "Answer and actual charged credits. Check status and billing_complete; incomplete work can still consume credits.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "status", "answer", "credits", "billing_complete" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Question reference for support." }, "status": { "type": "string", "enum": [ "completed", "incomplete" ] }, "answer": { "type": "string" }, "credits": { "type": "number", "minimum": 0, "description": "Credits actually charged to this workspace, including partial work." }, "billing_complete": { "type": "boolean", "description": "Whether usage was fully settled. False can mean insufficient remaining credits or a billing failure; do not automatically ask again." } } } } } } } }, "400": { "description": "Invalid question or missing explicit credit approval." }, "401": { "description": "Missing or invalid authentication." }, "402": { "description": "Insufficient available workspace credits; no question is started." }, "403": { "description": "Missing API entitlement, scope, or writable workspace role." }, "503": { "description": "Milian is unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/platform/users/{user_id}/password": { "get": { "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "getPlatformUserPasswordAccess", "summary": "Get customer password permissions", "description": "Requires platform:read. Checks whether an operator may set this customer’s password or send a branded reset email. Customer must own the selected workspace.", "responses": { "200": { "description": "Password permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "can_set_password": { "type": "boolean" }, "can_send_reset": { "type": "boolean" } } } } } } } }, "403": { "description": "Operator access required" }, "404": { "description": "Customer workspace not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "managePlatformUserPassword", "summary": "Set a customer password or send a reset email", "description": "Requires platform:write. Use action reset to send a branded reset email. Action set requires an account used exclusively within your platform and sends a security notification. Administrator accounts and accounts with access outside the operator’s platform cannot have their password set. Passwords are never returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace_id", "action" ], "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "set", "reset" ] }, "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 8, "maxLength": 1024, "description": "Required for action set." } } } } } }, "responses": { "200": { "description": "Password updated or reset email accepted for sending" }, "400": { "description": "Invalid input or password rejected" }, "403": { "description": "Account is not exclusive to the operator’s platform" }, "404": { "description": "Customer workspace not found" }, "502": { "description": "Reset email delivery failed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/flow/layout": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "post": { "operationId": "tidyAssistantFlow", "summary": "Tidy up an assistant flow", "description": "Arrange the saved flow with clear spacing between nodes, branches and merges. Changes node positions only; preserves all instructions, tool bindings, connections, conditions and call settings. No request body. Requires Flow Builder access for advanced flows. Read the assistant afterward to retrieve the updated positions. Required scope: `assistants:write`. Also available as the MCP tool `tidy_assistant_flow`.", "tags": [ "Assistants" ], "responses": { "200": { "description": "Layout saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "persisted", "node_count", "edge_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "persisted": { "type": "boolean", "const": true }, "node_count": { "type": "integer" }, "edge_count": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/assistants/{id}/announcements": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "getAssistantAnnouncements", "summary": "Get saved announcement audio", "description": "Read preparation status and authenticated preview links for the saved greeting, consent and farewell. Reading does not start generation. Changed text, voice or effective speech settings revoke older previews. With secondary languages configured, end-call farewell text guides a live message in the caller's current supported language; these farewells are skipped for saved audio. **Required scope:** `assistants:read`.", "tags": [ "Assistants" ], "responses": { "200": { "description": "Current preparation state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantAnnouncementAudio" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "prepareAssistantAnnouncements", "summary": "Prepare saved announcement audio", "description": "Queue missing supported fixed announcements from the assistant’s saved settings. No request body is needed; this operation cannot render an unsaved draft. Matching clips are reused. Returns immediately with background progress; poll GET on this path. Failed or unsupported preparation keeps existing call-time behavior. Saving an assistant also requests preparation. With secondary languages configured, end-call farewell text guides a live message in the caller's current supported language; these farewells are skipped for saved audio. **Required scope:** `assistants:write`.", "tags": [ "Assistants" ], "responses": { "202": { "description": "Preparation registered or already in progress.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantAnnouncementAudio" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "Preparation is temporarily unavailable. Saved assistant settings remain intact." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/assistants/{id}/announcements/{assetId}/audio": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Audio identity from the current preview link." } ], "get": { "operationId": "getAssistantAnnouncementAudio", "summary": "Play saved announcement audio", "description": "Return the current private WAV audio with the same Bearer authentication as other API requests. Audio is not generated by this endpoint. A replaced or no longer available announcement cannot be played. **Required scope:** `assistants:read`.", "tags": [ "Assistants" ], "responses": { "200": { "description": "Private WAV audio; Cache-Control: private, no-store. This response is binary and does not use a JSON envelope.", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The saved announcement changed. Read its current status before playing again." }, "503": { "description": "Audio is temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reseller/billing": { "get": { "operationId": "getResellerBilling", "summary": "Get reseller financial overview or activity", "description": "Read the payment-account readiness, settlement balances, customer payments, bank payout history, balance transactions or tax registration details for the credential’s own Whitelabel workspace. Requires owner or admin authority, Whitelabel access, API Access and billing:read. Financial data is returned only after payments and payouts are enabled and account verification is complete. Amounts are in settlement or transaction currency minor units, without display-currency conversion. Provider IDs, metadata, customer personal data, bank details, fee breakdowns and session secrets are excluded. This operation never moves funds.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "overview", "payments", "payouts", "transactions", "tax" ], "default": "overview" }, "description": "Choose account overview, payments, payouts, balance transactions or tax registrations." }, { "name": "limit", "in": "query", "description": "Activity page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the preceding page for the same view.", "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "200": { "description": "Read-only overview or financial activity. Before activation the overview has empty balances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "connected", "state", "payments_enabled", "payouts_enabled", "balances" ], "properties": { "connected": { "type": "boolean" }, "state": { "type": "string", "enum": [ "not_connected", "incomplete", "in_review", "action_required", "ready" ] }, "payments_enabled": { "type": "boolean" }, "payouts_enabled": { "type": "boolean" }, "balances": { "type": "array", "items": { "type": "object", "required": [ "currency", "available_minor", "pending_minor" ], "properties": { "currency": { "type": "string", "example": "EUR" }, "available_minor": { "type": "integer" }, "pending_minor": { "type": "integer" } } } } } }, { "type": "object", "required": [ "view", "items", "next_cursor" ], "properties": { "view": { "type": "string", "enum": [ "payments", "payouts", "transactions" ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "amount_minor", "currency", "status", "created_at" ], "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "received_minor": { "type": "integer", "description": "Amount received for a payment." }, "arrival_date": { "type": "string", "format": "date", "description": "Expected bank arrival date for a payout." }, "net_minor": { "type": "integer", "description": "Net change in settlement minor units (transactions view)." }, "category": { "type": "string", "description": "Public transaction category (transactions view)." }, "available_on": { "type": "string", "format": "date", "description": "Date the funds become available (transactions view)." } } } }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque next-page cursor, valid for 24 hours for this account and view. Null ends pagination." } } }, { "type": "object", "required": [ "view", "status", "origin_country", "registrations", "next_cursor" ], "properties": { "view": { "type": "string", "enum": [ "tax" ] }, "status": { "type": "string", "enum": [ "active", "pending" ] }, "origin_country": { "type": "string", "nullable": true, "description": "Business country code; addresses are excluded." }, "registrations": { "type": "array", "items": { "type": "object", "required": [ "country", "region", "status", "active_from", "expires_at", "registration_ref" ], "properties": { "country": { "type": "string" }, "region": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "scheduled", "expired" ] }, "active_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "registration_ref": { "type": "string", "description": "Opaque account-bound reference valid for 24 hours. Refresh this view before updating an expired reference." } } } }, "next_cursor": { "type": "string", "nullable": true } } } ] } } } } } }, "400": { "description": "Invalid query or expired cursor." }, "401": { "description": "Authentication required." }, "403": { "description": "Required scope, role or Whitelabel access missing." }, "409": { "description": "Payment account is not active for financial activity." }, "502": { "description": "Payment account data temporarily unavailable." }, "503": { "description": "Payment service temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reseller/tax/settings": { "get": { "operationId": "getResellerTaxSettings", "summary": "Get reseller tax settings", "description": "Requires an active Whitelabel payment account, API Access and workspace owner/admin authority. Requires billing:read. Business address and tax defaults are returned for the credential’s own workspace.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace tax configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "defaults": { "type": "object", "additionalProperties": false, "properties": { "tax_behavior": { "type": "string", "enum": [ "inclusive", "exclusive", "inferred_by_currency" ], "nullable": true }, "tax_code": { "type": "string", "example": "txcd_10000000", "nullable": true } } }, "head_office": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "object", "required": [ "country" ], "additionalProperties": false, "properties": { "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" } } } }, "nullable": true } } } } } } } }, "400": { "description": "Invalid tax configuration or registration reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Required scope, role or Whitelabel access missing." }, "409": { "description": "Payment account is not active." }, "502": { "description": "Tax configuration temporarily unavailable." }, "503": { "description": "Payment service or workspace access temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "updateResellerTaxSettings", "summary": "Update reseller tax settings", "description": "Requires an active Whitelabel payment account, API Access and workspace owner/admin authority. Requires billing:write. Changes affect customer tax calculations. Act only on explicit instructions from the business owner. Registrations describe where to collect tax and do not register a business with tax authorities. Registrations cannot be deleted; end collection with an expiry time.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace tax configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "defaults": { "type": "object", "additionalProperties": false, "properties": { "tax_behavior": { "type": "string", "enum": [ "inclusive", "exclusive", "inferred_by_currency" ], "nullable": true }, "tax_code": { "type": "string", "example": "txcd_10000000", "nullable": true } } }, "head_office": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "object", "required": [ "country" ], "additionalProperties": false, "properties": { "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" } } } }, "nullable": true } } } } } } } }, "400": { "description": "Invalid tax configuration or registration reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Required scope, role or Whitelabel access missing." }, "409": { "description": "Payment account is not active." }, "502": { "description": "Tax configuration temporarily unavailable." }, "503": { "description": "Payment service or workspace access temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "defaults": { "type": "object", "additionalProperties": false, "properties": { "tax_behavior": { "type": "string", "enum": [ "inclusive", "exclusive", "inferred_by_currency" ] }, "tax_code": { "type": "string", "example": "txcd_10000000" } } }, "head_office": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "object", "required": [ "country" ], "additionalProperties": false, "properties": { "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" } } } } } } } } } } } }, "/reseller/tax/registrations": { "post": { "operationId": "createResellerTaxRegistration", "summary": "Create reseller tax registration", "description": "Requires an active Whitelabel payment account, API Access and workspace owner/admin authority. Requires billing:write. Changes affect customer tax calculations. Act only on explicit instructions from the business owner. Registrations describe where to collect tax and do not register a business with tax authorities. Registrations cannot be deleted; end collection with an expiry time.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace tax configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "country", "region", "status", "active_from", "expires_at", "registration_ref" ], "properties": { "country": { "type": "string" }, "region": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "scheduled", "expired" ] }, "active_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "registration_ref": { "type": "string", "description": "Opaque account-bound reference valid for 24 hours. Refresh this view before updating an expired reference." } } } } } } } }, "400": { "description": "Invalid tax configuration or registration reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Required scope, role or Whitelabel access missing." }, "409": { "description": "Payment account is not active." }, "502": { "description": "Tax configuration temporarily unavailable." }, "503": { "description": "Payment service or workspace access temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "country", "registration_options", "active_from", "request_key" ], "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "registration_options": { "type": "object", "additionalProperties": true, "description": "Options for the selected jurisdiction, without a wrapping country key. For DE use {\"type\":\"standard\"}; for US use {\"type\":\"state_sales_tax\",\"state\":\"CA\"}. Must match the tax registration already held by the business." }, "active_from": { "oneOf": [ { "type": "string", "enum": [ "now" ] }, { "type": "integer", "minimum": 1 } ] }, "expires_at": { "type": "integer", "minimum": 1 }, "request_key": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Unique per creation request. Reuse only for an identical retry to prevent duplicates." } } } } } } }, "patch": { "operationId": "updateResellerTaxRegistration", "summary": "Update reseller tax registration", "description": "Requires an active Whitelabel payment account, API Access and workspace owner/admin authority. Requires billing:write. Changes affect customer tax calculations. Act only on explicit instructions from the business owner. Registrations describe where to collect tax and do not register a business with tax authorities. Registrations cannot be deleted; end collection with an expiry time.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workspace tax configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "country", "region", "status", "active_from", "expires_at", "registration_ref" ], "properties": { "country": { "type": "string" }, "region": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "scheduled", "expired" ] }, "active_from": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "registration_ref": { "type": "string", "description": "Opaque account-bound reference valid for 24 hours. Refresh this view before updating an expired reference." } } } } } } } }, "400": { "description": "Invalid tax configuration or registration reference." }, "401": { "description": "Authentication required." }, "403": { "description": "Required scope, role or Whitelabel access missing." }, "409": { "description": "Payment account is not active." }, "502": { "description": "Tax configuration temporarily unavailable." }, "503": { "description": "Payment service or workspace access temporarily unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "registration_ref" ], "properties": { "registration_ref": { "type": "string", "description": "Opaque account-bound reference valid for 24 hours. Refresh this view before updating an expired reference." }, "active_from": { "oneOf": [ { "type": "string", "enum": [ "now" ] }, { "type": "integer", "minimum": 1 } ] }, "expires_at": { "nullable": true, "oneOf": [ { "type": "string", "enum": [ "now" ] }, { "type": "integer", "minimum": 1 } ], "description": "now ends tax collection; null removes a scheduled expiry." } } } } } } } }, "/reseller/plans": { "get": { "operationId": "listResellerPlans", "summary": "List customer plans and inclusions", "description": "List plans belonging to the credential’s Whitelabel workspace and the available services to include. Requires owner or admin authority, Whitelabel access and settings:read. Wholesale costs and payment-provider identifiers are not returned. Plan prices use EUR minor units.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Customer plans and available inclusion codes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "price_monthly_cents": { "type": "integer" }, "price_yearly_cents": { "type": [ "integer", "null" ] }, "included_credits": { "type": "number" }, "inclusions": { "type": "array", "items": { "type": "object", "required": [ "code", "quantity" ], "properties": { "code": { "type": "string", "description": "Available inclusion code from the plan catalogue." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Additional capacity units above the baseline, or 1 for a feature." } } } }, "knowledge_sources": { "$ref": "#/components/schemas/ResellerKnowledgeSourceAccess" } } } }, "available_inclusions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "unit_size": { "type": "integer" }, "quantity_type": { "type": "string", "enum": [ "feature", "additional_capacity" ] } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/reseller/plans/{id}/inclusions": { "put": { "operationId": "updateResellerPlanInclusions", "summary": "Update included plan services", "description": "Replace the services included in one recurring customer plan price. Requires owner or admin authority, Whitelabel access and settings:write. Only plans without retained subscriptions can change; duplicate a subscribed plan in the dashboard. This configures an offer and never charges a customer or activates a subscription. Empty inclusions remove all configured inclusions.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inclusions" ], "properties": { "inclusions": { "type": "array", "maxItems": 15, "items": { "type": "object", "required": [ "code", "quantity" ], "properties": { "code": { "type": "string", "description": "Available inclusion code from the plan catalogue." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Additional capacity units above the baseline, or 1 for a feature." } } } } } }, "example": { "inclusions": [ { "code": "knowledge_bases", "quantity": 3 }, { "code": "fallbacks", "quantity": 1 } ] } } } }, "responses": { "200": { "description": "The saved inclusions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "inclusions": { "type": "array", "items": { "type": "object", "required": [ "code", "quantity" ], "properties": { "code": { "type": "string", "description": "Available inclusion code from the plan catalogue." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Additional capacity units above the baseline, or 1 for a feature." } } } } } } } } } } }, "400": { "description": "Invalid inclusion, missing underlying feature or insufficient plan price." }, "404": { "description": "Plan not found in this reseller workspace." }, "409": { "description": "Existing subscriptions require a new plan." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/search": { "post": { "tags": [ "Knowledge Bases" ], "operationId": "searchKnowledgeBase", "summary": "Search knowledge or query a table", "description": "Search document excerpts and exact table values with original cells and sources. Send either `query` (natural-language question) or `table_query` (exact lookup or aggregate on one sheet). Table queries evaluate complete sheets, independent of search limits. Cached formulas are unverified; ambiguous or missing numeric values and mixed units are rejected by aggregates. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Natural-language question to search document excerpts (max 2000 characters)." }, "table_query": { "$ref": "#/components/schemas/KnowledgeTableQuery", "description": "Exact table lookup or aggregate (rows, count, sum, min, max) on one sheet; use instead of `query`. Take `document_id`, `sheet` and column keys from earlier search results." } }, "anyOf": [ { "required": [ "query" ] }, { "required": [ "table_query" ] } ], "description": "Send `query` or `table_query`. If both are present, only `table_query` is evaluated." }, "examples": { "query": { "summary": "Natural-language search", "value": { "query": "What is the price for AX-100?" } }, "table_query": { "summary": "Exact table lookup", "value": { "table_query": { "document_id": "44444444-4444-4444-8444-444444444444", "sheet": "Prices", "operation": "rows", "filters": [ { "column": "c1", "operator": "eq", "type": "text", "value": "AX-100" } ], "limit": 5 } } } } } } }, "responses": { "200": { "description": "Search results with content, similarity, document reference and source (file, sheet, row, cells, indexed time and match method), or a table result with matching row count, exact decimal value as a string, unit, rows and display truncation flag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } }, "table_result": { "type": "object" } } } } } } } }, "400": { "description": "Invalid search or table query" }, "403": { "description": "Scope or workspace API access required" }, "404": { "description": "Knowledge base or document not found" }, "422": { "description": "Ambiguous, missing or incompatible table values" }, "500": { "description": "Search unavailable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "security": [ { "bearerAuth": [] } ] } }, "/me": { "get": { "operationId": "getMe", "summary": "Get current credential", "description": "Self-inspection of the calling API key: key metadata, workspace (tenant), active plan, effective limits, feature toggles, and Assistant engine-mode availability (`-1` = unlimited, `0` = disabled). No scope required — any valid key works.", "tags": [ "Account" ], "responses": { "200": { "description": "Metadata of the calling credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" } } }, "example": { "data": { "api_key": { "id": "k1b2c3d4-0000-4000-8000-000000000070", "name": "Production", "prefix": "fam_Ab12Cd34", "scopes": [], "created_at": "2026-06-01T12:00:00Z", "last_used_at": "2026-07-04T09:00:00Z", "expires_at": null }, "tenant": { "id": "t1b2c3d4-0000-4000-8000-000000000002", "name": "Acme Corp" }, "user_id": "u1b2c3d4-0000-4000-8000-000000000003", "plan": { "id": "pl1b2c3d-0000-4000-8000-000000000080", "name": "Pro", "price_monthly_cents": 9900, "included_minutes": 1000, "extra_minute_cost_cents": 12, "currency": "EUR" }, "limits": { "max_assistants": 10, "max_campaigns": 5, "max_cloned_voices": 3, "max_knowledgebases": 5, "max_tools": 20, "max_parallel_calls": 5, "max_automation_runs": 100, "max_crm_syncs": 3, "max_crm_synced_contacts": 25000, "max_own_numbers": 3, "max_members": 5 }, "features": { "web_widget": true, "ai_avatar": false, "secondary_languages": true, "stt_keyterms": true, "automation_platform": true, "calendar_integrations": true, "custom_dashboards": false, "flow_builder": true, "connect_ai_mcp": true, "whitelabel_enabled": false, "live_monitoring": true, "simulations": false, "assistant_engine_modes": { "pipeline": true, "realtime": true, "half_cascade": true, "translation": true } }, "display_currency": "USD", "display_currency_rate": 1.08 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/me/credit-notifications": { "get": { "operationId": "getCreditNotificationPreferences", "summary": "Get low-credit warning preferences", "description": "Reads the personal low-credit warning threshold and delivery channels for the user associated with this credential. This preference follows the user across workspaces. A user-owned API key or OAuth token is required; service-account credentials are rejected. **Required scope:** `settings:read`.", "tags": [ "Account" ], "responses": { "200": { "description": "Current personal low-credit warning preferences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNotificationPreferences" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCreditNotificationPreferences", "summary": "Update low-credit warning preferences", "description": "Updates the personal low-credit warning threshold and delivery channels for the user associated with this credential. At least one delivery channel must remain enabled while warnings are enabled. This preference follows the user across workspaces. A user-owned API key or OAuth token is required; service-account credentials are rejected. **Required scope:** `settings:write`.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNotificationPreferences" }, "example": { "enabled": true, "threshold_credits": 300, "push_enabled": true, "email_enabled": false } } } }, "responses": { "200": { "description": "Updated personal low-credit warning preferences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CreditNotificationPreferences" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/usage/rates": { "get": { "operationId": "getWorkspaceUsageRates", "summary": "Get workspace usage rates", "description": "Current customer credit rates for the credential workspace, including fixed charges, token-based AI usage and variable charges. Requires billing:read or calls:read. A null credit amount means usage-based or variable pricing, never free usage. Monthly add-on subscriptions and phone-number rental are separate. Rates include separate full_duplex and avatar surcharges per active minute, in addition to the normal talk_minute rate. Both apply when used together; prices are fixed at call start.", "tags": [ "Billing" ], "responses": { "200": { "description": "Workspace customer rates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "rates" ], "properties": { "rates": { "type": "array", "items": { "type": "object", "required": [ "code", "mode", "unit", "credits" ], "properties": { "code": { "type": "string", "description": "Stable usage category code." }, "mode": { "type": "string", "enum": [ "fixed", "usage_based", "variable" ] }, "unit": { "type": "string", "enum": [ "minute", "message", "page", "file", "run", "collection", "request", "token" ] }, "credits": { "type": "number", "nullable": true, "minimum": 0 } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/usage/telephony-rates": { "get": { "operationId": "getTelephonyUsageRates", "summary": "Estimate assistant or Loop phone rates", "description": "List available countries or estimate incoming or outgoing assistant or Loop phone rates for the current workspace. Loop requires calls:read or loop:read; assistant estimates require calls:read. Omit country to list supported countries. Assistant estimates cover purchased numbers and verified caller IDs using the included phone service. Your own connected phone service is billed separately. Amounts are EUR equivalents at the current credit top-up rate, not a guaranteed invoice total. Country ranges cover available number types and destination networks. Transfers can involve multiple call legs; Loop conference participation, recording and queue handling can add separate usage. AI assistant talk time is separate. Final charges are calculated after the call ends.", "tags": [ "Billing" ], "parameters": [ { "name": "context", "in": "query", "required": false, "description": "Choose assistant phone service or Loop calling.", "schema": { "type": "string", "enum": [ "loop", "assistant" ], "default": "loop" } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code. Incoming: receiving number country. Outgoing: destination country. Omit for the country list.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ], "default": "outbound" } } ], "responses": { "200": { "description": "Available countries or workspace-specific estimates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "countries" ], "properties": { "countries": { "type": "array", "items": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "name": { "type": "string" } } } } } }, { "type": "object", "required": [ "context", "country", "direction", "currency", "estimated", "updated_at", "amount_basis", "rates", "unavailable_categories", "finalized_after_call" ], "properties": { "context": { "type": "string", "enum": [ "loop", "assistant" ] }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "currency": { "type": "string", "enum": [ "EUR" ] }, "estimated": { "type": "boolean", "enum": [ true ] }, "updated_at": { "type": "string", "format": "date-time" }, "amount_basis": { "type": "string", "enum": [ "topup_credit_value" ] }, "rates": { "type": "array", "items": { "type": "object", "required": [ "category", "unit", "min_credits", "max_credits", "min_amount", "max_amount" ], "properties": { "category": { "type": "string", "enum": [ "phone", "browser", "sip", "conference", "queue", "queue_waiting", "recording", "whatsapp_voice" ] }, "unit": { "type": "string", "enum": [ "minute", "participant_minute", "task" ] }, "min_credits": { "type": "number", "minimum": 0 }, "max_credits": { "type": "number", "minimum": 0 }, "min_amount": { "type": "number", "minimum": 0, "description": "EUR equivalent at the current workspace credit top-up rate, in major units." }, "max_amount": { "type": "number", "minimum": 0, "description": "EUR equivalent at the current workspace credit top-up rate, in major units." } } } }, "unavailable_categories": { "type": "array", "items": { "type": "string", "enum": [ "phone", "browser", "sip", "conference", "queue", "queue_waiting", "recording", "whatsapp_voice" ] }, "description": "Components without an available estimate. Missing prices do not mean free." }, "finalized_after_call": { "type": "boolean", "enum": [ true ] } } } ] } } } } } }, "400": { "description": "Invalid country or call direction." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "Prices are temporarily unavailable. No fallback estimate is invented." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/balance": { "get": { "operationId": "getBalance", "summary": "Get balance", "description": "Minutes and credits balance of the API key's workspace plus a summary of its active plan. **Required scope:** `billing:read` (keys without scope restrictions have full access).", "tags": [ "Billing" ], "responses": { "200": { "description": "Current balance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Balance" } } }, "example": { "data": { "minutes_balance": 742.5, "credits_balance": 0, "plan_credits_balance": 12500, "available_credits": 12500, "currency": "EUR", "display_currency": "USD", "display_currency_rate": 1.08, "topup_extra_minute_cost_cents": 12, "topup_credits_per_euro": 208.33, "voice_credits_per_min": 25, "plan": { "id": "pl1b2c3d-0000-4000-8000-000000000080", "name": "Pro", "price_monthly_cents": 9900, "included_minutes": 1000, "extra_minute_cost_cents": 12, "currency": "EUR" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/referrals": { "get": { "operationId": "getReferrals", "summary": "Get referrals", "description": "Refer and Earn share link, reward amounts, and masked referral history for the API-key workspace. Only available on the main platform. **Required scope:** `billing:read` (keys without scope restrictions have full access).", "tags": [ "Billing" ], "responses": { "200": { "description": "Referral program summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Referrals" } } }, "example": { "data": { "available": true, "enabled": true, "code": "fam_AB12CD34", "url": "https://app.example.com/register?ref=fam_AB12CD34", "credits_each": 1250, "reward_cap": 10, "rewarded_count": 1, "pending_count": 2, "history": [ { "email": "a***@example.com", "status": "pending", "credits": null, "created_at": "2026-08-17T10:00:00.000Z", "rewarded_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/billing/payment-status": { "get": { "operationId": "getPaymentStatus", "summary": "Get workspace payment status", "description": "Check whether the workspace has open invoices with an amount remaining. These invoices require payment before continuing in the app. Returns the oldest outstanding invoice and the number still open. Paid, void, draft, zero-balance and uncollectible invoices do not block the app. A failed automatic prepaid top-up is a separate notice. Amounts use the invoice currency’s minor unit. No payment links or provider resource identifiers are exposed; use the invoice payment link operation to pay. Available with a valid credential even when API Access is paused. Required scope: billing:read.", "tags": [ "Billing" ], "responses": { "200": { "description": "Verified workspace payment status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "workspace_id", "payment_required", "invoice_count", "invoice", "topup_failure", "can_manage_billing" ], "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "payment_required": { "type": "boolean" }, "invoice_count": { "type": "integer", "minimum": 0 }, "invoice": { "type": "object", "nullable": true, "properties": { "number": { "type": "string", "nullable": true }, "amount_due": { "type": "integer", "description": "Amount remaining in the invoice currency’s minor unit." }, "currency": { "type": "string" }, "due_at": { "type": "string", "format": "date-time", "nullable": true } } }, "topup_failure": { "type": "object", "nullable": true, "properties": { "attempted_at": { "type": "string", "format": "date-time" } } }, "can_manage_billing": { "type": "boolean", "description": "Whether this credential can create payment or billing management links." } } } } } } } }, "401": { "description": "Invalid or missing credential." }, "403": { "description": "Missing billing read permission." }, "500": { "description": "Payment status could not be verified. Retry; do not treat this as a settled invoice." } } } }, "/billing/invoice-payment": { "post": { "operationId": "createInvoicePaymentLink", "summary": "Create invoice payment link", "description": "Creates a short-lived, one-time billing link on the current platform domain. The link opens the oldest payable workspace invoice and falls back to billing management when no payable invoice exists. This recovery operation remains available with a valid credential when API Access is paused after a failed plan payment. The credential's current workspace role must be `owner`, `admin`, or `billing`. No payment-provider identifiers are returned. **Required scope:** `billing:write`; `billing:read` is insufficient (keys without scope restrictions have full access).", "tags": [ "Billing" ], "responses": { "200": { "description": "Short-lived first-party billing link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "billing_url" ], "properties": { "billing_url": { "type": "string", "format": "uri", "description": "One-time URL on the platform or white-label domain. Open it in a browser before it expires." } } } } }, "example": { "data": { "billing_url": "https://workspace.example/api/billing/action/short-lived-token" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/billing/portal": { "post": { "operationId": "createBillingPortalLink", "summary": "Create billing management link", "description": "Creates a short-lived, one-time billing link on the current platform domain for invoice history, payment methods, and cancellation. This recovery operation remains available with a valid credential when API Access is paused after a failed plan payment. The credential's current workspace role must be `owner`, `admin`, or `billing`. Plan changes are disabled in the portal; use the app plan page or the subscription-change review and confirmation operations. No payment-provider identifiers are returned. **Required scope:** `billing:write`; `billing:read` is insufficient (keys without scope restrictions have full access).", "tags": [ "Billing" ], "responses": { "200": { "description": "Short-lived first-party billing link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "billing_url" ], "properties": { "billing_url": { "type": "string", "format": "uri", "description": "One-time URL on the platform or white-label domain. Open it in a browser before it expires." } } } } }, "example": { "data": { "billing_url": "https://workspace.example/api/billing/action/short-lived-token" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/transactions": { "get": { "operationId": "listTransactions", "summary": "List transactions", "description": "Workspace balance ledger, newest first. `note` contains a customer-facing description; payment-provider IDs and internal reconciliation references are never returned. Zero-amount entries of the automatic telephony cost reconciliation are omitted because they change no balance. **Required scope:** `billing:read` (keys without scope restrictions have full access).", "tags": [ "Billing" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "transfer", "call_usage", "loop_usage", "recording_usage", "referral", "purchase", "plan_included", "admin_adjust", "email_usage", "crawl_usage", "sla_fee", "retranscribe_usage", "sms_usage", "simulation_usage", "reanalyze_usage", "card_collect_usage", "chat_usage", "messaging_usage", "qa_usage", "automation_usage", "milian_usage" ] }, "description": "Filter by transaction type." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Ledger entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } }, "currency": { "type": "string", "description": "Denomination of any cents-based ledger fields — always EUR (canonical).", "example": "EUR" }, "display_currency": { "type": "string", "description": "Workspace's resolved display currency (reseller customers inherit their reseller's currency).", "example": "USD" }, "display_currency_rate": { "type": "number", "description": "Units of display_currency per 1 EUR; 0 when the platform has not configured a rate yet.", "example": 1.08 } } } } }, "example": { "data": [ { "id": "tx1b2c3d-0000-4000-8000-000000000090", "type": "call_usage", "delta_minutes": 0, "delta_credits": 0, "delta_plan_credits": -85, "note": "Call usage", "recording_source": null, "usage_source": null, "call_id": "c1b2c3d4-0000-4000-8000-000000000010", "created_at": "2026-07-01T10:03:30Z" }, { "id": "tx1b2c3d-0000-4000-8000-000000000091", "type": "plan_included", "delta_minutes": 0, "delta_credits": 0, "delta_plan_credits": 12500, "note": "Plan payment", "recording_source": null, "usage_source": null, "call_id": null, "created_at": "2026-07-01T00:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 2 }, "currency": "EUR", "display_currency": "USD", "display_currency_rate": 1.08 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/migrations/famulor": { "post": { "operationId": "migrateFamulor1", "summary": "Preview or import Famulor 1.0 data", "description": "Use `action: preview` first to list source resources, mappings and warnings. Use `action: import` with exact selected source IDs to create target resources. The Famulor 1.0 source API key is request-only and is never logged, persisted or returned. Built-in tools are created in the central Tools library and assigned to their source assistant; selected account-scoped HTTP tools are assigned to every assistant imported in the run. Selected knowledge bases are linked to referencing assistants, and `dualplex` maps to Half-cascade. Campaigns and automations are always created as inactive drafts. A source HTTP 403 for plan-gated automations skips that resource family without blocking the rest of the migration. Preview requires one relevant read scope (`assistants:read`, `campaigns:read`, `automations:read`, or `calls:read`). Import requires the matching write scope for every selected resource family; unrestricted keys have full access.", "tags": [ "Migrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action", "source_api_key" ], "properties": { "action": { "type": "string", "const": "preview" }, "source_api_key": { "type": "string", "writeOnly": true, "description": "Famulor 1.0 REST API key." } } }, { "type": "object", "required": [ "action", "source_api_key", "selection" ], "properties": { "action": { "type": "string", "const": "import" }, "source_api_key": { "type": "string", "writeOnly": true, "description": "Famulor 1.0 REST API key." }, "selection": { "type": "object", "description": "Exact old IDs returned by preview. Only selected resources are imported.", "properties": { "assistants": { "type": "array", "items": { "type": "integer" }, "maxItems": 200 }, "tools": { "type": "array", "items": { "type": "integer" }, "maxItems": 200 }, "knowledgebases": { "type": "array", "items": { "type": "integer" }, "maxItems": 50 }, "campaigns": { "type": "array", "items": { "type": "integer" }, "maxItems": 100 }, "automations": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }, "sip_trunks": { "type": "array", "items": { "type": "integer" }, "maxItems": 100 } } }, "overrides": { "type": "object", "description": "Optional target voice overrides keyed by old assistant ID.", "properties": { "assistants": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tts_provider": { "type": "string" }, "tts_voice": { "type": "string" } } } } } } } } ] }, "examples": { "preview": { "summary": "Preview all source resources", "value": { "action": "preview", "source_api_key": "" } }, "import": { "summary": "Import selected source resources", "value": { "action": "import", "source_api_key": "", "selection": { "assistants": [ 123 ], "campaigns": [ 456 ], "automations": [ "flow-id" ] } } } } } } }, "responses": { "200": { "description": "Preview or per-item import report.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "The Famulor 1.0 source API rate limit remained exhausted after retries. Also returned when the shared REST request budget is exhausted; honor Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, as determined by the applicable limit.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/migrations/providers": { "post": { "operationId": "migrateProviderAssistants", "summary": "Preview or import provider assistants", "description": "Preview and import inactive assistant shells from Retell AI, Vapi, Synthflow, or ElevenAgents (ElevenLabs Global). The source API key is request-only and is never logged, persisted, or returned. Preview requires `assistants:read`; import requires `assistants:write`. Tools, knowledge content, flows, squads, phone numbers, routing, and credentials are not copied and are returned as manual review items.", "tags": [ "Migrations" ], "x-mint": { "href": "/api-reference/migrate-provider-assistants" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action", "provider", "source_api_key" ], "properties": { "action": { "type": "string", "const": "preview", "description": "Preview the source agents or import the selected agents." }, "provider": { "type": "string", "enum": [ "retell", "vapi", "synthflow", "elevenlabs" ], "description": "Source platform. Use elevenlabs for ElevenAgents in an ElevenLabs Global workspace." }, "source_api_key": { "type": "string", "writeOnly": true, "description": "Private source-provider API key. Never include it in chat or logs." }, "synthflow_region": { "type": "string", "enum": [ "global", "us", "eu" ], "description": "Synthflow workspace region. Omit for Global; ignored by other providers." } } }, { "type": "object", "required": [ "action", "provider", "source_api_key", "selected_assistant_ids" ], "properties": { "action": { "type": "string", "const": "import", "description": "Preview the source agents or import the selected agents." }, "provider": { "type": "string", "enum": [ "retell", "vapi", "synthflow", "elevenlabs" ], "description": "Source platform. Use elevenlabs for ElevenAgents in an ElevenLabs Global workspace." }, "source_api_key": { "type": "string", "writeOnly": true, "description": "Private source-provider API key. Never include it in chat or logs." }, "synthflow_region": { "type": "string", "enum": [ "global", "us", "eu" ], "description": "Synthflow workspace region. Omit for Global; ignored by other providers." }, "selected_assistant_ids": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string" }, "description": "Exact source assistant IDs returned by preview." } } } ] }, "examples": { "preview": { "summary": "Preview Vapi assistants", "value": { "action": "preview", "provider": "vapi", "source_api_key": "" } }, "import": { "summary": "Import selected Retell assistants", "value": { "action": "import", "provider": "retell", "source_api_key": "", "selected_assistant_ids": [ "agent_123" ] } } } } } }, "responses": { "200": { "description": "Normalized preview or per-assistant import report.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "The source-provider rate limit is currently exhausted. Also returned when the shared REST request budget is exhausted; honor Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, as determined by the applicable limit.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants": { "get": { "operationId": "listAssistants", "summary": "List assistants", "description": "Paginated list of assistants in your workspace, newest first. **Required scope:** `assistants:read` (keys without scope restrictions have full access).", "tags": [ "Assistants" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of assistants.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Support Agent", "is_active": true, "created_by": "u1b2c3d4-0000-4000-8000-000000000003", "system_prompt": "You are a friendly support agent for Acme Corp...", "mode": "pipeline", "realtime_provider": null, "realtime_voice": null, "llm_temperature": 0.7, "stt_provider": "deepgram", "stt_language": "en", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_speed": 1, "turn_detection": "multilingual_model", "first_message": "Hi! How can I help you today?", "greeting_mode": "agent_speaks_first", "recording_enabled": true, "max_call_duration_sec": 1200, "inbound_ringing_timeout_sec": 60, "outbound_ringing_timeout_sec": 45, "idle_timeout_sec": 30, "knowledgebase_id": null, "webhook_url": null, "metadata": {}, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAssistant", "summary": "Create an assistant", "description": "Creates an assistant. Provide `name`, or pass a visible catalog `template_id` to resolve its prompt, greeting, language, variables and optional Flow JSON server-side. Explicit request fields override the template seed. Default agent type is **Single prompt** (`flow_json` omitted or `null` — uses `system_prompt` + greeting). For **Conversational flow**, pass a Flow JSON v1 object in `flow_json` (typically a Start→Agent→End seed). Model fields are validated against the platform model catalog, the workspace assistant limit is enforced, and non-trivial flows may require the Flow Builder feature. Pipeline and Half-cascade assistants are checked against the languages their voice can speak: a request whose voice can't speak the primary language, a secondary language or a language with its own voice returns `400 invalid_request`. Without `tts_voice`, a default voice that speaks the primary language is chosen. **Required scope:** `assistants:write` (keys without scope restrictions have full access).", "tags": [ "Assistants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantCreateInput" }, "examples": { "from_template": { "summary": "Resolve a visible use-case template", "value": { "template_id": "a1b2c3d4-0000-4000-8000-000000000010", "name": "Website Concierge" } }, "single_prompt": { "summary": "Single prompt (default)", "value": { "name": "Support Agent", "system_prompt": "You are a friendly support agent for Acme Corp...", "first_message": "Hi! How can I help you today?", "flow_json": null, "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "stt_language": "en" } }, "conversational_flow": { "summary": "Conversational flow (seeded Start→Agent→End)", "value": { "name": "Qualification Flow", "system_prompt": "You are a friendly qualifier for Acme Corp. Keep replies short.", "first_message": "Hi! Thanks for calling Acme — what can I help with?", "flow_json": { "version": 1, "nodes": [ { "id": "n1", "type": "start", "position": { "x": 0, "y": 0 }, "data": { "greeting": "Hi! Thanks for calling Acme — what can I help with?", "greeting_mode": "agent_speaks_first" } }, { "id": "n2", "type": "agent", "position": { "x": 0, "y": 180 }, "data": {} }, { "id": "n3", "type": "end", "position": { "x": 0, "y": 380 }, "data": {} } ], "edges": [ { "id": "e1", "source": "n1", "target": "n2", "label": null }, { "id": "e2", "source": "n2", "target": "n3", "label": null } ] } } } } } } }, "responses": { "201": { "description": "The created assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Assistant" } } }, "example": { "data": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Support Agent", "is_active": true, "created_by": "u1b2c3d4-0000-4000-8000-000000000003", "system_prompt": "You are a friendly support agent for Acme Corp...", "mode": "pipeline", "realtime_provider": null, "realtime_voice": null, "llm_temperature": 0.7, "stt_provider": "deepgram", "stt_language": "en", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_speed": 1, "turn_detection": "multilingual_model", "first_message": "Hi! How can I help you today?", "greeting_mode": "agent_speaks_first", "recording_enabled": true, "max_call_duration_sec": 1200, "inbound_ringing_timeout_sec": 60, "outbound_ringing_timeout_sec": 45, "idle_timeout_sec": 30, "knowledgebase_id": null, "webhook_url": null, "metadata": {}, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "getAssistant", "summary": "Get an assistant", "description": "**Required scope:** `assistants:read` (keys without scope restrictions have full access).", "tags": [ "Assistants" ], "responses": { "200": { "description": "The assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Assistant" } } }, "example": { "data": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Support Agent", "is_active": true, "created_by": "u1b2c3d4-0000-4000-8000-000000000003", "system_prompt": "You are a friendly support agent for Acme Corp...", "mode": "pipeline", "realtime_provider": null, "realtime_voice": null, "llm_temperature": 0.7, "stt_provider": "deepgram", "stt_language": "en", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_speed": 1, "turn_detection": "multilingual_model", "first_message": "Hi! How can I help you today?", "greeting_mode": "agent_speaks_first", "recording_enabled": true, "max_call_duration_sec": 1200, "inbound_ringing_timeout_sec": 60, "outbound_ringing_timeout_sec": 45, "idle_timeout_sec": 30, "knowledgebase_id": null, "webhook_url": null, "metadata": {}, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateAssistant", "summary": "Update an assistant", "description": "Partial update — only the provided fields change. Every update creates a version snapshot. `PUT` is accepted as an alias of `PATCH`. Pipeline and Half-cascade assistants are checked against the languages their voice can speak, with `400 invalid_request` on failure. Every language is re-checked when the voice moves to a different voice provider or the engine switches to Pipeline or Half-cascade; otherwise only languages the request adds are checked, so another voice from the same provider and unrelated edits keep the current languages. **Required scope:** `assistants:write` (keys without scope restrictions have full access).", "tags": [ "Assistants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantInput" }, "example": { "first_message": "Welcome to Acme! How can I help?", "llm_temperature": 0.5 } } } }, "responses": { "200": { "description": "The updated assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Assistant" } } }, "example": { "data": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Support Agent", "is_active": true, "created_by": "u1b2c3d4-0000-4000-8000-000000000003", "system_prompt": "You are a friendly support agent for Acme Corp...", "mode": "pipeline", "realtime_provider": null, "realtime_voice": null, "llm_temperature": 0.7, "stt_provider": "deepgram", "stt_language": "en", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_speed": 1, "turn_detection": "multilingual_model", "first_message": "Hi! How can I help you today?", "greeting_mode": "agent_speaks_first", "recording_enabled": true, "max_call_duration_sec": 1200, "inbound_ringing_timeout_sec": 60, "outbound_ringing_timeout_sec": 45, "idle_timeout_sec": 30, "knowledgebase_id": null, "webhook_url": null, "metadata": {}, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "replaceAssistant", "summary": "Update an assistant (PUT alias)", "description": "Alias of `PATCH /assistants/{id}` — identical behavior (partial update, version snapshot). Kept for clients that only support PUT. Pipeline and Half-cascade assistants are checked against the languages their voice can speak, with `400 invalid_request` on failure. Every language is re-checked when the voice moves to a different voice provider or the engine switches to Pipeline or Half-cascade; otherwise only languages the request adds are checked, so another voice from the same provider and unrelated edits keep the current languages. **Required scope:** `assistants:write`.", "tags": [ "Assistants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantInput" }, "example": { "first_message": "Welcome to Acme! How can I help?", "llm_temperature": 0.5 } } } }, "responses": { "200": { "description": "The updated assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Assistant" } } }, "example": { "data": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Support Agent", "is_active": true, "created_by": "u1b2c3d4-0000-4000-8000-000000000003", "system_prompt": "You are a friendly support agent for Acme Corp...", "mode": "pipeline", "realtime_provider": null, "realtime_voice": null, "llm_temperature": 0.7, "stt_provider": "deepgram", "stt_language": "en", "tts_provider": "elevenlabs", "tts_voice": "21m00Tcm4TlvDq8ikWAM", "tts_speed": 1, "turn_detection": "multilingual_model", "first_message": "Hi! How can I help you today?", "greeting_mode": "agent_speaks_first", "recording_enabled": true, "max_call_duration_sec": 1200, "inbound_ringing_timeout_sec": 60, "outbound_ringing_timeout_sec": 45, "idle_timeout_sec": 30, "knowledgebase_id": null, "webhook_url": null, "metadata": {}, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteAssistant", "summary": "Delete an assistant", "description": "Deletes the assistant permanently. Phone numbers pointing at it are unassigned. Not possible while one of its calls is live: wait until the call has ended, then retry. Open translation rooms that nobody has joined are ended. **Required scope:** `assistants:write` (keys without scope restrictions have full access).", "tags": [ "Assistants" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The assistant is on a live call. Wait until the call ends, then delete it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "This assistant is on a live call. Wait until the call ends, then delete it." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/compliance-review": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "getAssistantComplianceReview", "summary": "Get assistant compliance review", "description": "Returns the customer-visible automated compliance status, score, flags, reason, and manual-review state. Internal model, workflow, token, and prompt-snapshot fields are omitted. **Required scope:** `assistants:read`.", "tags": [ "Assistants" ], "responses": { "200": { "description": "Current assistant compliance state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantComplianceReview" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "requestAssistantComplianceReview", "summary": "Request manual compliance review", "description": "Submits the current blocked assistant snapshot for manual platform review. **Required scope:** `assistants:write`.", "tags": [ "Assistants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Why the current assistant content should be approved." } } }, "example": { "reason": "We are the authorized support team for the named brand and the greeting identifies our company clearly." } } } }, "responses": { "200": { "description": "The review request was submitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The assistant is not blocked, the case is closed, or its content changed." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices": { "get": { "operationId": "listVoices", "summary": "List voices", "description": "Complete paginated voice library for the active workspace. Voice IDs are provider-neutral local selectors; upstream identifiers and supplier names are never returned. Workspace-owned cloned voices use the same selector contract. Use a voice's `id` as `tts_voice` for Pipeline or fallback speech, or `realtime_voice` for native conversation voices. **Required scope:** `voices:read` (keys without scope restrictions have full access). For TTS use `?mode=tts&language=de`. For Full Duplex use `?mode=realtime&realtime_variant=full_duplex&language=de`. Do not send `realtime_variant` with TTS mode.", "tags": [ "Voices" ], "parameters": [ { "name": "language", "in": "query", "schema": { "type": "string" }, "description": "ISO-639-1 language filter, e.g. `de`." }, { "name": "gender", "in": "query", "schema": { "type": "string", "enum": [ "female", "male", "neutral" ] } }, { "name": "accent", "in": "query", "schema": { "type": "string" }, "description": "Accent slug filter, e.g. `bavarian`, `american`, `british`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Free-text search over name/accent/age." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tts", "realtime" ], "default": "tts" }, "description": "Choose Pipeline/fallback voices or native conversation voices. Full Duplex uses its native voice for greetings, consent and tool announcements." }, { "name": "realtime_variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "standard", "full_duplex" ] }, "description": "Only send with mode=realtime. Omit this parameter for TTS voices; a variant with mode=tts returns 400. When realtime mode is selected and this parameter is omitted, standard is used. Full Duplex requires Beta and compatible workspace defaults." } ], "responses": { "200": { "description": "A page of voices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "voice:9a53d9f9-1f61-43a9-b877-80e006f775ad", "name": "Rachel", "language": "en", "languages": [ "en" ], "gender": "female", "category": "premade", "age": "young", "accent": "american", "preview_url": null, "source": "library" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices/{id}/preview": { "get": { "operationId": "getVoicePreview", "summary": "Play a stored voice preview", "description": "Download an existing TTS or Full Duplex catalog voice recording using the preview_url returned by List voices. Requires voices:read and current workspace access to the voice. No speech is generated. Preview references are relative to the API origin and require the same Bearer authentication.", "tags": [ "Voices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque catalog voice selector, such as voice:9a53d9f9-1f61-43a9-b877-80e006f775ad." }, { "name": "realtime_variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full_duplex" ] }, "description": "Only for realtime mode. Omit for TTS. Native previews default to full_duplex." }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tts", "realtime" ], "default": "realtime" }, "description": "Use tts for catalog speech previews; omit realtime_variant in that mode. The default preserves native Full Duplex previews." } ], "responses": { "200": { "description": "Existing stored audio recording.", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid selector or unsupported variant." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The compatible voice or recorded preview is unavailable." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/history": { "get": { "operationId": "listHistory", "summary": "List conversation history", "description": "Calls and assistant email conversations in your workspace, globally sorted by latest activity. Failed outbound call rows include the provider-neutral `failure` object. Every inbound and outbound email turn with the same stable `thread_id` is grouped into one conversation row. Email reply states are normalized to the shared statuses (`pending` → `in_progress`, `replied`/outbound → `completed`). **Required scope:** `calls:read`.\n\nRemoved conversations are excluded. Their detail IDs return not found.", "tags": [ "History" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "call", "avatar", "email", "live_chat", "whatsapp_voice", "whatsapp", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "description": "Filter by channel: matches the `channel` field of each row. `avatar` = web voice with virtual avatar; `live_chat` = widget text chat; messaging channels (chat apps, help desks, mailboxes) query messaging conversations." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound", "web" ] }, "description": "Filter by direction. `web` applies only to calls." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed", "failed", "no_answer", "busy", "skipped" ] } }, { "name": "assistant_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter calls and emails by assistant." }, { "name": "campaign_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by campaign; campaign history contains calls only." }, { "name": "lead_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter the unified history by one Audience contact across calls, messaging and email." }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Filter by Audience contact tags. Comma-separated; conversations whose contact has any of these tags are included." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search phone numbers, email addresses, email subject/body, and call summaries." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only entries active at or after this ISO 8601 date/datetime (latest message time for email threads)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only entries active at or before this ISO 8601 date/datetime (latest message time for email threads)." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A globally sorted page of calls and emails.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/history/emails/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Email message or thread-root ID. Any message ID in the thread resolves to the complete conversation." } ], "get": { "operationId": "getEmailHistoryItem", "summary": "Get an email conversation", "description": "Returns every inbound and outbound turn in the email thread in chronological order, including stable thread and immediate-parent IDs, full plain-text bodies, reply states/errors, and attachment metadata. Inbound audio and image attachments can include a transcript or a short image description, with media links valid for one hour. Image descriptions can include readable text; PDFs, videos and other files retain metadata only. **Required scope:** `calls:read`.\n\nRemoved conversations are excluded. Their detail IDs return not found.", "tags": [ "History" ], "responses": { "200": { "description": "Grouped email conversation detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailHistoryDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/history/messaging/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Messaging conversation ID returned by the history list." } ], "get": { "operationId": "getMessagingHistoryItem", "summary": "Get a messaging conversation", "description": "Returns up to 500 messages in chronological order with full text, attachment metadata, available voice-note transcripts, short image descriptions, and media links valid for one hour. Applies to chat channels and connected mailbox or support channels. Transcripts and image descriptions are available only when an accessible attachment could be analyzed. Image descriptions can include readable text; this attachment feature does not analyze PDFs or videos. Fetch this endpoint again to refresh media links. **Required scope:** `calls:read`.\n\nRemoved conversations are excluded. Their detail IDs return not found.", "tags": [ "History" ], "responses": { "200": { "description": "Messaging conversation detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MessagingHistoryDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls": { "get": { "operationId": "listCalls", "summary": "List calls", "description": "Calls in your workspace, newest first by creation time unless `sort=updated_at` is set. Failed outbound calls include a provider-neutral `failure` object with stable retry/action guidance. **Required scope:** `calls:read` (keys without scope restrictions have full access).\n\nRemoved conversations are excluded. Their detail IDs return not found.", "tags": [ "Calls" ], "parameters": [ { "name": "assistant_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by assistant." }, { "name": "campaign_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by campaign (dialer calls)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed", "failed", "no_answer", "busy" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound", "web" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" }, "description": "Sort newest first by creation time (default) or latest update. Use `updated_at` when polling completed calls so older calls that finish later appear in the recent page." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only calls created at or after this ISO 8601 date/datetime." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only calls created at or before this ISO 8601 date/datetime." }, { "name": "sentiment", "in": "query", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "description": "Filter by post-call sentiment (requires the assistant's `analysis_config` sentiment to be enabled)." }, { "name": "success", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by post-call success verdict (requires the assistant's `analysis_config.success` to be enabled)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Lexical search across the call transcript and summary. Case-insensitive substring match." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of calls.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "c1b2c3d4-0000-4000-8000-000000000010", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "phone_number_id": "p1b2c3d4-0000-4000-8000-000000000020", "direction": "outbound", "from_number": "+4930123456", "to_number": "+4915123456789", "status": "completed", "started_at": "2026-07-01T10:00:00Z", "answered_at": "2026-07-01T10:00:05Z", "ended_at": "2026-07-01T10:03:25Z", "duration_sec": 200, "transcript": { "items": [ { "type": "message", "role": "assistant", "content": [ "Hi! How can I help you today?" ] }, { "type": "message", "role": "user", "content": [ "I'd like to reschedule my appointment." ] } ] }, "summary": "Caller rescheduled their appointment to Friday.", "evaluation": null, "metadata": {}, "created_at": "2026-07-01T10:00:00Z", "updated_at": "2026-07-01T10:03:30Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCall", "summary": "Start an outbound call", "description": "Places an outbound call: the assistant must be active and needs an outbound-capable phone number (assigned to it, or passed via `phone_number_id`). Returns the created call immediately (status `queued`) — poll `GET /calls/{id}` or use the assistant's webhook for the result and provider-neutral `failure` guidance. Destinations that are not allowed return `403 destination_forbidden`. **Required scope:** `calls:write` (keys without scope restrictions have full access).", "tags": [ "Calls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundCallRequest" }, "example": { "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "to_number": "+4915123456789", "lead": { "name": "Jane Doe", "company": "Acme Corp" } } } } }, "responses": { "201": { "description": "The created call (status `queued`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Call" } } }, "example": { "data": { "id": "c1b2c3d4-0000-4000-8000-000000000010", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "phone_number_id": "p1b2c3d4-0000-4000-8000-000000000020", "direction": "outbound", "from_number": "+4930123456", "to_number": "+4915123456789", "status": "queued", "started_at": null, "answered_at": null, "ended_at": null, "duration_sec": null, "transcript": null, "summary": null, "evaluation": null, "metadata": {}, "created_at": "2026-07-01T10:00:00Z", "updated_at": "2026-07-01T10:03:30Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/TelephonyConfigurationError" }, "503": { "$ref": "#/components/responses/TelephonyUnavailable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/calls/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Call ID." } ], "get": { "operationId": "getCall", "summary": "Get a call", "description": "Call details including the transcript, the AI summary, provider-neutral failure guidance, the chronological event log, and a signed `recording_url` (valid 1 hour) if a recording exists. Failed transfer events expose the same safe failure shape without raw SIP or SDK diagnostics. **Required scope:** `calls:read` (keys without scope restrictions have full access).\n\nRemoved conversations are excluded. Their detail IDs return not found.\n\nIncludes measured call insights. Unavailable measurements are null. Transcript recognition confidence is a score, not a correctness guarantee. Recording playback is limited to available consent-permitted audio.", "tags": [ "Calls" ], "responses": { "200": { "description": "The call with events and recording URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CallDetail" } } }, "example": { "data": { "id": "c1b2c3d4-0000-4000-8000-000000000010", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "phone_number_id": "p1b2c3d4-0000-4000-8000-000000000020", "direction": "outbound", "from_number": "+4930123456", "to_number": "+4915123456789", "status": "completed", "started_at": "2026-07-01T10:00:00Z", "answered_at": "2026-07-01T10:00:05Z", "ended_at": "2026-07-01T10:03:25Z", "duration_sec": 200, "transcript": { "items": [ { "type": "message", "role": "assistant", "content": [ "Hi! How can I help you today?" ] }, { "type": "message", "role": "user", "content": [ "Please book Friday afternoon." ] }, { "type": "function_call", "name": "book_appointment", "call_id": "tool-1", "arguments": "{\"day\":\"Friday\",\"period\":\"afternoon\"}", "created_at": 1782900005.25 }, { "type": "function_call_output", "name": "book_appointment", "call_id": "tool-1", "output": "{\"booked\":true}", "is_error": false, "created_at": 1782900006.5 } ] }, "structured_transcript": "ai: Hi! How can I help you today?\nhuman: Please book Friday afternoon.", "summary": "Caller rescheduled their appointment to Friday.", "evaluation": null, "metadata": {}, "created_at": "2026-07-01T10:00:00Z", "updated_at": "2026-07-01T10:03:30Z", "recording_url": "https://storage.example.com/recordings/signed-url", "events": [ { "id": "e1", "call_id": "c1b2c3d4-0000-4000-8000-000000000010", "type": "state_changed", "payload": { "status": "in_progress" }, "created_at": "2026-07-01T10:00:05Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls/{id}/verify-inputs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "verifyCallInputs", "summary": "Verify call inputs", "description": "Read-only comparison of explicitly expected inputs with the resolved call-start snapshot. Returns only requested keys and matched, missing, different, or not_available statuses. A queued call or unavailable snapshot is not evidence of successful input delivery; matching inputs do not establish that the scenario succeeded. POST keeps expected values out of URLs. Required scope: calls:read.", "tags": [ "Calls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_variables" ], "properties": { "expected_variables": { "allOf": [ { "$ref": "#/components/schemas/CallInputVariables" }, { "minProperties": 1 } ] } } }, "example": { "expected_variables": { "auftrag": "Book a consultation" } } } } }, "responses": { "200": { "description": "Input comparison.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid" }, "input_verification": { "$ref": "#/components/schemas/CallInputVerification" } } } } } } } }, "400": { "description": "Malformed or empty expected variables." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls/{id}/live-control": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Active call ID." } ], "post": { "operationId": "liveCallControl", "summary": "Live call control", "description": "Supervisor actions on an active call: `listen_token` (join credentials), `whisper` (coach the agent), `end_agent` (mute AI / take-over), or `hangup` (end the call for everyone via room delete). While an inbound caller is still ringing for a free concurrent line, only listening in and `hangup` are available; joining with a microphone (`barge`), `whisper` and `end_agent` return 409 `caller_waiting_for_line`. Requires Live monitoring in the workspace plan. **Required scope:** `calls:write`.", "tags": [ "Calls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "listen_token", "whisper", "end_agent", "hangup" ] }, "text": { "type": "string", "description": "Required when action is `whisper`." }, "speak": { "type": "boolean", "description": "When whispering, have the agent speak immediately." }, "reason": { "type": "string", "description": "Optional reason for `end_agent` or `hangup`." }, "barge": { "type": "boolean", "description": "For `listen_token`: join with publish (audible) instead of hidden listen-only." } } }, "example": { "action": "whisper", "text": "Offer the retention discount.", "speak": true } } } }, "responses": { "200": { "description": "Action result. `listen_token` returns join credentials; other actions return `{ ok: true }`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "token", "url", "identity" ], "properties": { "token": { "type": "string" }, "url": { "type": "string" }, "identity": { "type": "string" } } }, { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls/{id}/recording": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Call ID." } ], "get": { "operationId": "getCallRecording", "summary": "Get a call recording URL", "description": "Returns a time-limited signed download URL for the call recording. 404 if the call does not exist or has no recording. **Required scope:** `calls:read` (keys without scope restrictions have full access).\n\nRemoved conversations are excluded. Their detail IDs return not found.", "tags": [ "Calls" ], "parameters": [ { "name": "expires_in", "in": "query", "schema": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 3600 }, "description": "URL validity in seconds (60–86400)." } ], "responses": { "200": { "description": "Signed recording URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordingUrl" } } }, "example": { "data": { "call_id": "c1b2c3d4-0000-4000-8000-000000000010", "url": "https://storage.example.com/recordings/signed-url", "expires_in": 3600, "expires_at": "2026-07-04T11:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls/actions": { "post": { "operationId": "runCallActions", "summary": "Run call history actions", "description": "Re-evaluate post-call analysis, start an enhanced re-transcription from one call recording, resend `call.completed` webhooks, or add/remove the contact phone from the suppression (blacklist) list. `retranscribe` requires exactly one call ID and returns the rounded recording minutes and credit quote. Other actions process up to 50 call IDs per request. **Required scope:** `calls:write`. Blacklist actions also need `suppression:write` or `campaigns:write` (unrestricted keys have full access).", "tags": [ "Calls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "call_ids" ], "properties": { "action": { "type": "string", "enum": [ "reanalyze", "retranscribe", "resend_webhook", "blacklist_add", "blacklist_remove" ] }, "call_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 } } }, "example": { "action": "reanalyze", "call_ids": [ "c1b2c3d4-0000-4000-8000-000000000010" ] } } } }, "responses": { "200": { "description": "Per-call results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ok", "failed", "results" ], "properties": { "ok": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid" }, "ok": { "type": "boolean" }, "error": { "type": "string" }, "detail": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/history/actions": { "post": { "operationId": "runHistoryActions", "summary": "Run history actions on any channel", "description": "Cross-channel superset of `POST /calls/actions`. Re-evaluate the post-conversation analysis (summary, sentiment, success verdict and extracted fields), start an enhanced re-transcription from a call recording, resend the end-of-conversation webhook, reopen a completed WhatsApp conversation with AI auto-replies, or add/remove the contact phone from the suppression (blacklist) list.\n\nSet `kind` to select the record type:\n\n- `call` — phone calls, live chat, avatar sessions and WhatsApp voice (`ids` are call IDs)\n- `messaging` — WhatsApp, Telegram, Slack, Messenger, Teams, Discord, Google Chat and X conversations (`ids` are conversation IDs)\n- `email` — email threads (`ids` are the thread's root message ID, which is what `GET /history` returns as the row `id`)\n\n`retranscribe` is only valid for `kind: call`, requires exactly one ID, and returns the rounded recording minutes plus the credit quote. `resend_webhook` always rebuilds the payload from the record as it is stored right now, so a resend after a `reanalyze` delivers the updated analysis. `resume_ai` is only valid for `kind: messaging` and only while a completed WhatsApp conversation's 24-hour customer service window is still open. It starts a fresh internal inactivity timer without extending the Meta window. `blacklist_add` and `blacklist_remove` are phone-based and therefore only valid for `kind: call`.\n\nOther actions process up to 50 IDs per request. **Required scope:** `calls:write`. Blacklist actions also need `suppression:write` or `campaigns:write` (unrestricted keys have full access).\n\n`remove` removes a completed conversation from History, call/history list and detail APIs, and MCP reads without immediately erasing stored data. It preserves billing, usage and statistics. Existing workspace retention rules continue to apply using the original timestamps. Active conversations cannot be removed. An email message ID removes its entire thread. Retries are idempotent. User-owned credentials require workspace owner/admin access; workspace service-account credentials require `calls:write`. Check each per-record result: active or missing records return `ok: false`. Previously issued download links and exported copies are not revoked. A new incoming email or messaging reply restores thread visibility; historical imports and outbound messages do not.", "tags": [ "History" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "kind", "ids" ], "properties": { "action": { "type": "string", "enum": [ "remove", "reanalyze", "retranscribe", "resend_webhook", "resume_ai", "blacklist_add", "blacklist_remove" ] }, "kind": { "type": "string", "enum": [ "call", "messaging", "email" ], "description": "Which History record type the ids address." }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50 } } }, "example": { "action": "reanalyze", "kind": "messaging", "ids": [ "be4c9efe-0000-4000-8000-000000000010" ] } } } }, "responses": { "200": { "description": "Per-record results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "ok", "failed", "results" ], "properties": { "ok": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "call", "messaging", "email" ] }, "ok": { "type": "boolean" }, "error": { "type": "string" }, "detail": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "400": { "description": "Invalid action, kind, or ids." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Missing scope." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns": { "get": { "operationId": "listCampaigns", "summary": "List campaigns", "description": "**Required scope:** `campaigns:read` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "archived" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of campaigns.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "ca1b2c3d-0000-4000-8000-000000000030", "name": "July outreach", "status": "draft", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "concurrency": 3, "retry_max": 2, "retry_delay_minutes": 60, "calling_windows": { "mon": [ [ "09:00", "20:00" ] ], "tue": [ [ "09:00", "20:00" ] ] }, "timezone": "Europe/Berlin", "amd_enabled": true, "voicemail_action": "hangup", "voicemail_message": null, "started_at": null, "completed_at": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCampaign", "summary": "Create a campaign", "description": "Creates a campaign in status `draft`. Dialer settings (concurrency, retries, calling windows, AMD/voicemail behavior) can be set right away. The plan's campaign limit is enforced (archived campaigns do not count). **Required scope:** `campaigns:write` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCreate" }, "example": { "name": "July outreach", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "concurrency": 3, "retry_max": 2, "retry_delay_minutes": 60, "calling_windows": { "mon": [ [ "09:00", "20:00" ] ], "tue": [ [ "09:00", "20:00" ] ], "wed": [ [ "09:00", "20:00" ] ], "thu": [ [ "09:00", "20:00" ] ], "fri": [ [ "09:00", "18:00" ] ] }, "timezone": "Europe/Berlin", "amd_enabled": true, "voicemail_action": "hangup" } } } }, "responses": { "201": { "description": "The created campaign.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } }, "example": { "data": { "id": "ca1b2c3d-0000-4000-8000-000000000030", "name": "July outreach", "status": "draft", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "concurrency": 3, "retry_max": 2, "retry_delay_minutes": 60, "calling_windows": { "mon": [ [ "09:00", "20:00" ] ], "tue": [ [ "09:00", "20:00" ] ] }, "timezone": "Europe/Berlin", "amd_enabled": true, "voicemail_action": "hangup", "voicemail_message": null, "started_at": null, "completed_at": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "get": { "operationId": "getCampaign", "summary": "Get a campaign", "description": "Campaign details including `total_leads`. **Required scope:** `campaigns:read` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "responses": { "200": { "description": "The campaign.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Campaign" }, { "type": "object", "properties": { "total_leads": { "type": "integer", "description": "Total number of leads in this campaign." } } } ] } } }, "example": { "data": { "id": "ca1b2c3d-0000-4000-8000-000000000030", "name": "July outreach", "status": "draft", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "concurrency": 3, "retry_max": 2, "retry_delay_minutes": 60, "calling_windows": { "mon": [ [ "09:00", "20:00" ] ], "tue": [ [ "09:00", "20:00" ] ] }, "timezone": "Europe/Berlin", "amd_enabled": true, "voicemail_action": "hangup", "voicemail_message": null, "started_at": null, "completed_at": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z", "total_leads": 120 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCampaign", "summary": "Update a campaign", "description": "Updates name, assistant and/or dialer settings. `voicemail_action: \"drop_message\"` requires an effective `voicemail_message`. **Required scope:** `campaigns:write` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdate" }, "example": { "concurrency": 5, "voicemail_action": "drop_message", "voicemail_message": "Hi, we tried to reach you — we'll call again later." } } } }, "responses": { "200": { "description": "The updated campaign.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } }, "example": { "data": { "id": "ca1b2c3d-0000-4000-8000-000000000030", "name": "July outreach", "status": "draft", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "concurrency": 3, "retry_max": 2, "retry_delay_minutes": 60, "calling_windows": { "mon": [ [ "09:00", "20:00" ] ], "tue": [ [ "09:00", "20:00" ] ] }, "timezone": "Europe/Berlin", "amd_enabled": true, "voicemail_action": "hangup", "voicemail_message": null, "started_at": null, "completed_at": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteCampaign", "summary": "Delete a campaign", "description": "Deletes the campaign. Its leads are kept (their campaign reference is cleared). **Required scope:** `campaigns:write` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "ca1b2c3d-0000-4000-8000-000000000030", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/start": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "post": { "operationId": "startCampaign", "summary": "Start a campaign", "description": "Sets the campaign to `running` and triggers the first dialer wave immediately; subsequent waves run on a schedule. Calling windows, DNC list and concurrency are enforced by the dialer. **Required scope:** `campaigns:write` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Campaign started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "campaign_id", "status" ], "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "running" }, "tick": { "type": [ "object", "null" ], "description": "Result of the first dialer wave (dialed/skipped counts), or `null` if it could not run." }, "tick_error": { "type": "string", "description": "Present when the first wave failed; the campaign is still running and the next scheduled wave retries." } } } } }, "example": { "data": { "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "status": "running", "tick": { "dialed": 3, "skipped": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/stop": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "post": { "operationId": "stopCampaign", "summary": "Stop a campaign", "description": "Pauses a running campaign (status `paused`). Calls already in progress finish normally; the dialer stops dialing new leads. Returns 409 if the campaign is not running. **Required scope:** `campaigns:write` (keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "responses": { "200": { "description": "Campaign paused.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "campaign_id", "status" ], "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "paused" } } } } }, "example": { "data": { "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "status": "paused" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/deliveries": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "get": { "operationId": "listCampaignDeliveries", "summary": "List campaign deliveries", "description": "Lists primary and follow-up delivery attempts. Provider, room, carrier and lease identifiers are never exposed. **Required scope:** `campaigns:read`.", "tags": [ "Campaigns" ], "parameters": [ { "name": "stage", "in": "query", "schema": { "type": "string", "enum": [ "primary", "follow_up" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of campaign deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDelivery" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/leads": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "get": { "operationId": "listLeads", "summary": "List leads", "description": "Leads of a campaign, newest first. Every lead includes the derived `display_status`. **Required scope:** `leads:read` (keys without scope restrictions have full access).", "tags": [ "Leads" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "queued", "calling", "completed", "failed", "no_answer", "busy", "do_not_call" ] } }, { "name": "display_status", "in": "query", "description": "Filter by derived display status. Mutually exclusive with `status` (if both are sent, `display_status` wins).", "schema": { "type": "string", "enum": [ "created", "processing", "rescheduled", "max_retries", "completed", "dnc" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of leads.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CampaignLead" }, { "type": "object", "required": [ "display_status" ], "properties": { "display_status": { "type": "string", "enum": [ "created", "processing", "rescheduled", "max_retries", "completed", "dnc" ], "description": "Status grouped for boards and filters: `created` (waiting for its first attempt), `processing` (queued or being called), `rescheduled` (waiting for a retry), `max_retries` (attempts used up without success), `completed`, `dnc` (on the do-not-call list)." } } } ] } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "le1b2c3d-0000-4000-8000-000000000040", "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "phone": "+4915123456789", "name": "Jane Doe", "email": null, "tags": [], "custom_fields": { "company": "Acme Corp" }, "status": "pending", "attempts": 0, "next_attempt_at": null, "last_amd_result": null, "last_call_id": null, "created_at": "2026-07-01T08:05:00Z", "updated_at": "2026-07-01T08:05:00Z", "display_status": "created" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "addLeads", "summary": "Add leads", "description": "Adds one lead (body = a single lead object; `data` in the response is the created lead) or many (body = an array of lead objects, max 1000; `data` is the array of created leads and `meta` reports `created`, `dnc_flagged` and `invalid` rows). Phone numbers are normalized to E.164. Optional email addresses are validated and normalized; an existing contact with the same phone or email causes a conflict instead of being silently merged. Numbers on your Do-Not-Call list are created with status `do_not_call` — the dialer never calls them. **Required scope:** `leads:write` (keys without scope restrictions have full access).", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LeadInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/LeadInput" }, "maxItems": 1000 } ] }, "examples": { "single": { "summary": "Single lead", "value": { "phone": "+4915123456789", "email": "jane.doe@example.com", "name": "Jane Doe", "custom_fields": { "company": "Acme Corp" } } }, "bulk": { "summary": "Bulk import", "value": [ { "phone": "+4915123456789", "email": "jane.doe@example.com", "name": "Jane Doe" }, { "phone": "+14155551234", "name": "John Smith", "custom_fields": { "plan": "pro" } } ] } } } } }, "responses": { "201": { "description": "Created lead(s). Single body → `data` is the lead object; array body → `data` is an array plus `meta.created` / `meta.dnc_flagged` / `meta.invalid`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CampaignLead" } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLead" } }, "meta": { "type": "object", "properties": { "created": { "type": "integer" }, "dnc_flagged": { "type": "integer", "description": "Created leads whose number is on the DNC list (status `do_not_call`)." }, "invalid": { "type": "array", "description": "Rejected input rows (invalid phone, email, or structure).", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "error": { "type": "string" } } } } } } } } ] }, "examples": { "single": { "summary": "Single lead", "value": { "data": { "id": "le1b2c3d-0000-4000-8000-000000000040", "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "phone": "+4915123456789", "email": "jane.doe@example.com", "name": "Jane Doe", "custom_fields": { "company": "Acme Corp" }, "status": "pending", "attempts": 0, "next_attempt_at": null, "last_amd_result": null, "last_call_id": null, "created_at": "2026-07-01T08:05:00Z", "updated_at": "2026-07-01T08:05:00Z" } } }, "bulk": { "summary": "Bulk import", "value": { "data": [ { "id": "le1b2c3d-0000-4000-8000-000000000040", "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "phone": "+4915123456789", "email": "jane.doe@example.com", "name": "Jane Doe", "custom_fields": { "company": "Acme Corp" }, "status": "pending", "attempts": 0, "next_attempt_at": null, "last_amd_result": null, "last_call_id": null, "created_at": "2026-07-01T08:05:00Z", "updated_at": "2026-07-01T08:05:00Z" } ], "meta": { "created": 1, "dnc_flagged": 0, "invalid": [ { "index": 1, "phone": "12345", "error": "phone must be a valid E.164 number (e.g. +4915123456789)." } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/leads/{leadId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Lead ID." } ], "get": { "operationId": "getLead", "summary": "Get a campaign lead", "description": "Returns editable contact data and user-managed `custom_fields` plus a separate read-only `system_variables` object. **Required scope:** `leads:read`.", "tags": [ "Leads" ], "responses": { "200": { "description": "Campaign lead detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CampaignLead" }, { "type": "object", "properties": { "system_variables": { "type": "object", "readOnly": true, "additionalProperties": { "type": "string" }, "description": "Read-only values the platform keeps for this lead (for example the last call), available to the assistant as variables." } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLead", "summary": "Update a campaign lead", "description": "Updates name, phone, email, tags, or user-managed custom fields. System variables and channel identities are read-only. **Required scope:** `leads:write`.", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": "string", "description": "International E.164 phone number." }, "email": { "type": [ "string", "null" ], "format": "email" }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 40 } }, "custom_fields": { "type": "object", "description": "Flat user-managed variables. Null deletes a key; system-managed keys are rejected.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Updated campaign lead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CampaignLead" }, { "type": "object", "properties": { "system_variables": { "type": "object", "readOnly": true, "additionalProperties": { "type": "string" }, "description": "Read-only values the platform keeps for this lead (for example the last call), available to the assistant as variables." } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteLead", "summary": "Remove a lead from a campaign", "description": "Removes the lead from campaign execution while retaining the Audience contact, calls, and completed campaign history. This operation never permanently deletes the contact. **Required scope:** `leads:write` (keys without scope restrictions have full access).", "tags": [ "Leads" ], "responses": { "200": { "description": "Campaign removal confirmation. `deleted` is always false.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "campaign_id", "removed_from_campaign", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "removed_from_campaign": { "type": "boolean", "const": true }, "deleted": { "type": "boolean", "const": false } } } } }, "example": { "data": { "id": "le1b2c3d-0000-4000-8000-000000000040", "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "removed_from_campaign": true, "deleted": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/variables/catalog": { "get": { "operationId": "listVariableSources", "summary": "List campaign variable sources", "description": "Lists system variables, workspace lead attributes, and assistant variables available for campaign and WhatsApp template mappings. **Required scope:** `leads:read`.", "tags": [ "Leads" ], "responses": { "200": { "description": "Variable source catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "group", "read_only" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string", "enum": [ "system", "lead_attribute", "assistant_variable" ] }, "read_only": { "type": "boolean" }, "assistant_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers": { "get": { "operationId": "listPhoneNumbers", "summary": "List phone numbers", "description": "Phone numbers of your workspace, newest first. **Required scope:** `phone_numbers:read` (keys without scope restrictions have full access).", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "assistant_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by assigned assistant." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "pending", "released", "suspended" ] } }, { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "ISO-2 country code, e.g. `DE`." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of phone numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "p1b2c3d4-0000-4000-8000-000000000020", "number": "+4930123456", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "sip_trunk_id": null, "direction_inbound": true, "direction_outbound": true, "source": "platform", "country_iso": "DE", "number_type": "local", "monthly_price_cents": 500, "status": "active", "purchased_by": "u1b2c3d4-0000-4000-8000-000000000003", "released_at": null, "created_at": "2026-06-15T12:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "buyPhoneNumber", "summary": "Buy a phone number", "description": "Starts a payment-confirmed marketplace purchase. The response is pending and includes `checkout_url`. Open this URL to review and confirm payment; it may open an authenticated in-app checkout or a hosted payment page. Routing and call access are provisioned only after verified payment. Failed, expired, or unpaid purchases release the held number. Requires a user-scoped API key. Pick a number from `GET /phone-numbers/available` first and pass its short-lived `purchase_token` unchanged. **Required scope:** `phone_numbers:write`.", "tags": [ "Phone Numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberPurchase" }, "example": { "number": "+4930123456", "country": "DE", "type": "local", "purchase_token": "eyJ2IjoxLCJvZmZlciI6IntcIn...", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001" } } } }, "responses": { "201": { "description": "A pending phone number and the checkout URL required to activate it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PhoneNumber" }, { "type": "object", "required": [ "checkout_url" ], "properties": { "checkout_url": { "type": "string", "format": "uri", "description": "Open this URL to complete payment." } } } ] } } }, "example": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000020", "number": "+4930123456", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "sip_trunk_id": null, "direction_inbound": false, "direction_outbound": false, "source": "platform", "country_iso": "DE", "number_type": "local", "monthly_price_cents": 500, "status": "pending", "purchased_by": "u1b2c3d4-0000-4000-8000-000000000003", "released_at": null, "created_at": "2026-06-15T12:00:00Z", "updated_at": "2026-07-01T09:00:00Z", "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_example" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/phone-numbers/verifications": { "get": { "operationId": "listPhoneNumberVerifications", "summary": "List regulatory number verifications", "description": "List regulatory verification cases for the workspace. **Required scope:** `phone_numbers:read`.", "tags": [ "Phone Numbers" ], "responses": { "200": { "description": "Verification cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberVerification" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "submitPhoneNumberVerification", "summary": "Submit regulatory number verification", "description": "Submit a number verification case with the required address, registration details, and supporting documents. Discover supported combinations with GET /phone-numbers/verifications/catalog and load required fields with GET /phone-numbers/verifications/requirements. To correct your own failed, rejected, or draft case instead of opening a new one, send `replace_verification_id`: GET /phone-numbers/verifications/{id}/submission returns its last details, and supporting documents without a new attachment are reused. A submission that fails the automated check is stored as a failed case. Requires a user-scoped API key. **Required scope:** `phone_numbers:write`.", "tags": [ "Phone Numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country", "email", "prefix" ], "properties": { "replace_verification_id": { "type": "string", "format": "uuid", "description": "Correct and resubmit this own failed, rejected, or draft verification instead of opening a new one. Supporting documents whose `file_field` has no new attachment are reused from it." }, "country": { "type": "string", "description": "ISO-2" }, "type": { "type": "string", "enum": [ "local", "mobile", "national" ] }, "end_user_type": { "type": "string", "enum": [ "individual", "business" ] }, "email": { "type": "string", "format": "email" }, "prefix": { "type": "string", "description": "Area code or E.164 prefix, e.g. 030 or +4930. National digits are completed with the country calling code." }, "address": { "type": "object", "required": [ "customer_name", "street", "city", "region", "postal_code" ], "properties": { "customer_name": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" } } }, "end_user_attributes": { "type": "object", "additionalProperties": true }, "supporting_documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "field", "content_base64" ], "properties": { "field": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_base64": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Verification case created / submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumberVerification" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/verifications/catalog": { "get": { "operationId": "listPhoneNumberVerificationCatalog", "summary": "List countries requiring number verification", "description": "Lists countries and number types that require verification, including the supported business or individual registrations for each type. Use only the combinations in this catalog, then load their current requirements before submitting a case. **Required scope:** `phone_numbers:read`.", "tags": [ "Phone Numbers" ], "responses": { "200": { "description": "Verification catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "iso": { "type": "string" }, "name": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } }, "calling_code": { "type": "string", "nullable": true }, "end_user_types": { "type": "object", "description": "Supported registration types, keyed by number type. An absent registration type is not available for verification.", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "business", "individual" ] } }, "example": { "local": [ "business" ], "mobile": [ "business" ] } } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/verifications/{id}": { "get": { "operationId": "getPhoneNumberVerification", "summary": "Get regulatory number verification", "description": "Fetch one verification case with its progress `timeline`: submitted → automated check → regulatory review → verified → buy a number. **Required scope:** `phone_numbers:read`.", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification case", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PhoneNumberVerification" }, { "type": "object", "properties": { "timeline": { "type": "array", "description": "Progress steps in fixed order. Exactly one step is `active` or `failed` until the case is verified; after verification, `buy_number` is active.", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "submitted", "automated_check", "review", "verified", "buy_number" ] }, "state": { "type": "string", "enum": [ "done", "active", "failed", "upcoming" ] }, "at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the step completed or failed; for an active step, since when it has been running." } } } } } } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deletePhoneNumberVerification", "summary": "Delete regulatory number verification", "description": "Delete a draft or failed verification case and its archived documents. Cases already submitted for review are retained. **Required scope:** `phone_numbers:write`.", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification case deleted" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/verifications/{id}/submission": { "get": { "operationId": "getPhoneNumberVerificationSubmission", "summary": "Get the last submitted verification details", "description": "Returns the details last submitted for your own verification case: country, number type, registration type, contact email, prefix, address, registration details, supporting documents, and the names of the stored document files. Use it to correct a failed or rejected case and resubmit it with `replace_verification_id`. Only the person who submitted the case can read it. Requires a user-scoped API key. **Required scope:** `phone_numbers:read`.", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Last submitted details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verification_id": { "type": "string", "format": "uuid" }, "can_resubmit": { "type": "boolean", "description": "Whether the case can be corrected and resubmitted now (draft, failed, or rejected)." }, "country": { "type": "string" }, "number_type": { "type": "string" }, "end_user_type": { "type": "string", "enum": [ "business", "individual" ] }, "email": { "type": "string" }, "friendly_name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "additionalProperties": true }, "end_user_attributes": { "type": "object", "additionalProperties": true }, "supporting_documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "files": { "type": "array", "description": "Stored document files. Omit an attachment for a `field` to reuse its file when resubmitting.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "document_type": { "type": "string", "nullable": true } } } }, "submitted_at": { "type": "string", "format": "date-time" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/available": { "get": { "operationId": "searchAvailablePhoneNumbers", "summary": "Search purchasable numbers", "description": "Searches the marketplace for purchasable numbers, including the workspace's final customer-facing retail price and a short-lived `purchase_token` required to buy that exact offer. The country and number type must be enabled by the platform admin; countries with regulatory requirements additionally need an approved regulatory bundle on file. **Required scope:** `phone_numbers:read` (keys without scope restrictions have full access).", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "ISO-2 country code, e.g. `DE`." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "local", "mobile", "national" ] }, "description": "Number type to search. Omit it to search every type enabled for the country; each result reports its own `type`." }, { "name": "contains", "in": "query", "schema": { "type": "string" }, "description": "Digit pattern the number must contain, e.g. `030`." }, { "name": "area_code", "in": "query", "schema": { "type": "integer" }, "description": "Area code filter, e.g. `415`." } ], "responses": { "200": { "description": "Purchasable numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailablePhoneNumber" } } } }, "example": { "data": [ { "number": "+4930123456", "friendly_name": "+49 30 123456", "type": "local", "country": "DE", "monthly_price_cents": 500, "setup_fee_cents": 0, "currency": "EUR", "display_currency": "USD", "display_currency_rate": 1.08, "display_monthly_price_cents": 540, "display_setup_fee_cents": 0, "purchase_token": "eyJ2IjoxLCJvZmZlciI6IntcIn...", "capabilities": { "voice": true, "sms": false } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Phone number ID." } ], "get": { "operationId": "getPhoneNumber", "summary": "Get a phone number", "description": "**Required scope:** `phone_numbers:read` (keys without scope restrictions have full access).", "tags": [ "Phone Numbers" ], "responses": { "200": { "description": "The phone number.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" } } }, "example": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000020", "number": "+4930123456", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "sip_trunk_id": null, "direction_inbound": true, "direction_outbound": true, "source": "platform", "country_iso": "DE", "number_type": "local", "monthly_price_cents": 500, "status": "active", "purchased_by": "u1b2c3d4-0000-4000-8000-000000000003", "released_at": null, "created_at": "2026-06-15T12:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updatePhoneNumber", "summary": "Update a phone number", "description": "Assigns an assistant / SIP trunk and toggles inbound/outbound directions. Changing the assistant, trunk or inbound direction re-creates the inbound SIP dispatch rule. **Required scope:** `phone_numbers:write` (keys without scope restrictions have full access).", "tags": [ "Phone Numbers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberUpdate" }, "example": { "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "direction_inbound": true, "direction_outbound": true } } } }, "responses": { "200": { "description": "The updated phone number.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" } } }, "example": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000020", "number": "+4930123456", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001", "sip_trunk_id": null, "direction_inbound": true, "direction_outbound": true, "source": "platform", "country_iso": "DE", "number_type": "local", "monthly_price_cents": 500, "status": "active", "purchased_by": "u1b2c3d4-0000-4000-8000-000000000003", "released_at": null, "created_at": "2026-06-15T12:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "releasePhoneNumber", "summary": "Release or delete a phone number", "description": "Release a phone number. Paid marketplace numbers are soft-scheduled: the subscription ends at the end of the billing period, the number stays active until then (`release_scheduled_at`), then the number is given up and status becomes `released`. Complimentary plan numbers and unpaid purchases are released immediately. Customer-provided numbers are deleted together with their call routing. **Required scope:** `phone_numbers:write` (keys without scope restrictions have full access).", "tags": [ "Phone Numbers" ], "responses": { "200": { "description": "Release/delete confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Paid marketplace soft-release returns the updated number row (`status` still `active`, `release_scheduled_at` set). Immediate marketplace release returns `status=released`. Customer-provided numbers return `{ id, deleted: true }`.", "additionalProperties": true } } }, "examples": { "softRelease": { "summary": "Paid marketplace — scheduled until period end", "value": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000020", "status": "active", "release_scheduled_at": "2026-08-01T00:00:00.000Z", "number": "+49301234567" } } }, "hardRelease": { "summary": "Complimentary / immediate release", "value": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000021", "status": "released", "released_at": "2026-07-24T16:00:00.000Z", "release_scheduled_at": null } } }, "byoDeleted": { "summary": "Customer-provided number deleted", "value": { "data": { "id": "p1b2c3d4-0000-4000-8000-000000000022", "deleted": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop": { "get": { "operationId": "getLoop", "summary": "Get Famulor Loop access and settings", "description": "Returns member access and safe workspace settings. Requires `loop:read`. Registration secrets and internal cost data are never returned; credentials without an associated member receive `not_authenticated` access.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop access and settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopOverview" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopSettings", "summary": "Update Famulor Loop settings", "description": "Updates customer-facing Loop settings. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopSettingsInput" } } } }, "responses": { "200": { "description": "Updated Loop settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopSettings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/ring-groups": { "get": { "operationId": "listLoopRingGroups", "summary": "List Loop ring groups", "description": "Lists Loop ring groups and their enabled workspace members. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop ring groups.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopRingGroup" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createLoopRingGroup", "summary": "Create a Loop ring group", "description": "Creates a Loop ring group. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRingGroupInput" } } } }, "responses": { "201": { "description": "Created ring group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRingGroup" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/ring-groups/{id}": { "parameters": [ { "$ref": "#/components/parameters/LoopResourceId" } ], "get": { "operationId": "getLoopRingGroup", "summary": "Get a Loop ring group", "description": "Returns one ring group. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop ring group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRingGroup" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopRingGroup", "summary": "Update a Loop ring group", "description": "Replaces a ring group's routing behavior and members. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRingGroupInput" } } } }, "responses": { "200": { "description": "Updated ring group.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRingGroup" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteLoopRingGroup", "summary": "Delete a Loop ring group", "description": "Deletes a ring group. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/queues": { "get": { "operationId": "listLoopQueues", "summary": "List Loop call queues", "description": "Lists Loop call queues and their enabled workspace members. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop call queues.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopQueue" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createLoopQueue", "summary": "Create a Loop call queue", "description": "Creates a Loop call queue. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopQueueInput" } } } }, "responses": { "201": { "description": "Created call queue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopQueue" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/queues/{id}": { "parameters": [ { "$ref": "#/components/parameters/LoopResourceId" } ], "get": { "operationId": "getLoopQueue", "summary": "Get a Loop call queue", "description": "Returns one call queue. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop call queue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopQueue" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopQueue", "summary": "Update a Loop call queue", "description": "Replaces a queue's behavior and members. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopQueueInput" } } } }, "responses": { "200": { "description": "Updated call queue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopQueue" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteLoopQueue", "summary": "Delete a Loop call queue", "description": "Deletes a call queue. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/routing-rules": { "get": { "operationId": "listLoopRoutingRules", "summary": "List Loop routing rules", "description": "Lists ordered routing rules with shared weekly hours, time-conditioned steps, and pre-answer continuation outcomes. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop routing rules.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopRoutingRule" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createLoopRoutingRule", "summary": "Create a Loop routing rule", "description": "Creates an ordered routing rule with optional weekly hours and time-conditioned steps. Continuation outcomes cover pre-answer failures only; an answered person or assistant is terminal. Cycles are rejected. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRoutingRuleInput" } } } }, "responses": { "201": { "description": "Created routing rule.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRoutingRule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/routing-rules/{id}": { "parameters": [ { "$ref": "#/components/parameters/LoopResourceId" } ], "get": { "operationId": "getLoopRoutingRule", "summary": "Get a Loop routing rule", "description": "Returns one routing rule including shared weekly hours, time conditions, and continuation outcomes. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop routing rule.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRoutingRule" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopRoutingRule", "summary": "Update a Loop routing rule", "description": "Atomically replaces a routing rule, shared weekly hours, time-conditioned steps, and pre-answer continuation outcomes. Cycles are rejected and the previous rule remains unchanged on failure. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRoutingRuleInput" } } } }, "responses": { "200": { "description": "Updated routing rule.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRoutingRule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteLoopRoutingRule", "summary": "Delete a Loop routing rule", "description": "Deletes a routing rule. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/number-routes": { "get": { "operationId": "listLoopNumberRoutes", "summary": "List Loop phone number routes", "description": "Lists eligible purchased phone numbers and their logical destinations. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop phone number routes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopNumberRoute" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/number-routes/{id}": { "parameters": [ { "$ref": "#/components/parameters/LoopResourceId" } ], "get": { "operationId": "getLoopNumberRoute", "summary": "Get a Loop phone number route", "description": "Returns one eligible purchased phone number and its logical destination. Requires `loop:read` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Loop phone number route.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopNumberRoute" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "setLoopNumberRoute", "summary": "Set a Loop phone number route", "description": "Sets the logical destination for an eligible purchased phone number. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopNumberRouteInput" } } } }, "responses": { "200": { "description": "Updated phone number route.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopNumberRoute" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteLoopNumberRoute", "summary": "Delete a Loop phone number route", "description": "Removes the Loop destination from an eligible purchased phone number. Requires `loop:write` and a workspace owner or admin credential.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopNumberRouteDeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/directory": { "get": { "operationId": "listLoopDirectory", "summary": "List the Loop directory", "description": "Lists Loop-enabled workspace members, extensions, and availability. Requires a user-scoped credential with `loop:read` and active Loop access.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Safe workspace directory.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopDirectoryEntry" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/presence": { "get": { "operationId": "getLoopPresence", "summary": "Get personal Loop presence", "description": "Returns the authenticated member's availability and reachable device classes. Requires `loop:read`.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Current personal presence.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopPresence" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "setLoopPresence", "summary": "Set personal Loop presence", "description": "Updates the authenticated member's availability. Active calls continue to determine the effective busy state. Requires `loop:write`.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "offline" ] } } } } } }, "responses": { "200": { "description": "Presence updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "offline" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/devices": { "get": { "operationId": "listLoopDevices", "summary": "List personal Loop devices", "description": "Lists safe metadata for the authenticated member's registered devices. Registration usernames, passwords, credential versions, and internal resource identifiers are excluded. Requires `loop:read`.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Registered device metadata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopDevice" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/devices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Loop device ID." } ], "patch": { "operationId": "renameLoopDevice", "summary": "Rename a personal Loop device", "description": "Updates the customer-facing name of a device owned by the authenticated member. Registration credentials are never returned. Requires `loop:write`.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopDeviceRenameInput" } } } }, "responses": { "200": { "description": "Device renamed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopDeviceRenameResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "revokeLoopDevice", "summary": "Revoke a personal Loop device", "description": "Revokes a device owned by the authenticated member. The operation is tenant-scoped and requires `loop:write`.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Device revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRevokeResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/calls/{id}": { "get": { "operationId": "getLoopCall", "summary": "Get a Loop call", "description": "Read a Loop call with participant names, avatars, and available recordings with playback links valid for one hour. Personal scope requires ownership or participation; workspace scope requires workspace owner/admin access. Requires a user-owned credential with loop:read. Human conversations are not automatically transcribed.", "tags": [ "Famulor Loop" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "personal", "workspace" ], "default": "personal" }, "description": "Personal call history by default. Workspace call history is available to authorized workspace managers." } ], "responses": { "200": { "description": "Loop call and available recordings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoopCallDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Call not found or not accessible." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "patch": { "operationId": "linkLoopCallContact", "summary": "Link a Loop call to a contact", "description": "Link a Loop call you own or participated in to an Audience contact, or pass `lead_id: null` to remove the link. The linked contact is shown in History → Loop calls; without a link the contact is matched by phone number. Requires a user-owned credential with `loop:write`.", "tags": [ "Famulor Loop" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead_id" ], "properties": { "lead_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Audience contact ID from the same workspace, or null to unlink." } } } } } }, "responses": { "200": { "description": "Updated personal Loop call including the resolved contact.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoopCallDetail" } } } } } }, "400": { "description": "lead_id missing or not a UUID / null." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Call or contact not found or not accessible." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/calls": { "get": { "operationId": "listLoopCalls", "summary": "List Loop calls", "description": "List paginated Loop calls with participant names and avatars. Personal scope shows only calls you own or participated in, with direction relative to you. Workspace scope requires workspace owner/admin access. Usage is returned in minutes and credits. Requires a user-owned credential with loop:read.", "tags": [ "Famulor Loop" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of calls to return." }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 }, "description": "Number of calls to skip." }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "personal", "workspace" ], "default": "personal" }, "description": "Personal call history by default. Workspace call history is available to authorized workspace managers." } ], "responses": { "200": { "description": "Paginated Loop calls.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoopCall" } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/loop/recording": { "get": { "operationId": "getLoopRecording", "summary": "Get Loop call recording", "description": "Read the recording state and available controls for an active Loop call. Requires loop:read, a user-owned credential and permission to control this call. Does not start recording.", "tags": [ "Famulor Loop" ], "parameters": [ { "name": "call_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Public Loop call ID." } ], "responses": { "200": { "description": "Confirmed recording controls for the selected call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recording": { "$ref": "#/components/schemas/LoopRecordingControl" } }, "required": [ "recording" ] } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "setLoopRecording", "summary": "Start or stop Loop recording", "description": "Start or stop recording the selected active Loop call. Requires loop:write, a user-owned credential and permission to control this call. Recording uses workspace credits. Reuse the same idempotency key only when retrying the same action; use a new key for the next separate action. Active recordings may be paused and resumed; paused time is excluded from recorded duration. The response confirms the current state.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "call_id", "action", "idempotency_key" ], "properties": { "call_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "start", "stop" ] }, "idempotency_key": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Confirmed recording controls for the selected call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recording": { "$ref": "#/components/schemas/LoopRecordingControl" } }, "required": [ "recording" ] } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A recording action is already in progress or the idempotency key conflicts with another action." }, "503": { "description": "Recording is temporarily unavailable; read the current state before retrying with the same action key." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/loop/availability": { "get": { "operationId": "getLoopAvailability", "summary": "Get personal Loop availability", "description": "Returns the authenticated member's weekly Loop schedule, effective timezone, current schedule result, and selected Recall appointment calendar. Requires a user-owned credential with `loop:read`.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Personal Loop availability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopAvailability" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopAvailability", "summary": "Update personal Loop availability", "description": "Replaces the authenticated member's weekly Loop schedule and optionally the Recall appointment calendar. A null timezone inherits the workspace timezone. Omit recall_appointment_calendar_id to keep the saved calendar. Requires a user-owned credential with `loop:write`.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopAvailabilityInput" } } } }, "responses": { "200": { "description": "Updated personal availability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopAvailability" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/preferences": { "get": { "operationId": "getLoopDialingPreferences", "summary": "Get personal Loop dialing preferences", "description": "Returns the authenticated member's default country for national dial-pad numbers. Requires a user-owned credential with `loop:read`.", "tags": [ "Famulor Loop" ], "responses": { "200": { "description": "Personal dialing preferences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopDialingPreferences" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateLoopDialingPreferences", "summary": "Update personal Loop dialing preferences", "description": "Sets the ISO country used to expand national dial-pad numbers to international E.164 format. Explicit international numbers and internal extensions remain unchanged. Requires a user-owned credential with `loop:write`.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopDialingPreferencesInput" } } } }, "responses": { "200": { "description": "Updated personal dialing preferences.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopDialingPreferences" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/recalls": { "get": { "operationId": "listLoopRecalls", "summary": "List personal Loop Recall items", "description": "Lists only Recall items assigned to the authenticated member. Workspace administrators do not receive other members' Recall items through this personal endpoint. Requires a user-owned credential with `loop:read`.", "tags": [ "Famulor Loop" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "action_required", "completed", "failed", "cancelled" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Personal Recall items and saved assistant choice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "recalls", "default_assistant_id" ], "properties": { "recalls": { "type": "array", "items": { "$ref": "#/components/schemas/LoopRecall" } }, "default_assistant_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/loop/recalls/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/LoopResourceId" } ], "post": { "operationId": "actOnLoopRecall", "summary": "Act on a personal Loop Recall item", "description": "Calls the requester, asks a selected assistant to connect the caller or arrange an appointment, or marks the authenticated member's Recall item as resolved. The item must be assigned to that member. Requires a user-owned credential with `loop:write`.", "tags": [ "Famulor Loop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoopRecallActionInput" } } } }, "responses": { "200": { "description": "Recall action result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LoopRecallActionResult" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/sip-trunks": { "get": { "operationId": "listSipTrunks", "summary": "List SIP trunks", "description": "Lists only customer-owned BYO/BYOC SIP trunks. Managed trunks behind marketplace purchases and verified caller IDs are never returned; use the phone-number endpoints for those numbers. Passwords and internal trunk identifiers are never returned. **Required scope:** `sip_trunks:read` (keys without scope restrictions have full access).", "tags": [ "SIP Trunks" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of SIP trunks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SipTrunk" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "st1b2c3d-0000-4000-8000-000000000050", "name": "My SIP provider", "provider": "custom", "sip_address": "sip.example-provider.com", "auth_username": "acme", "numbers": [ "+4930123456" ], "metadata": {}, "created_at": "2026-06-01T12:00:00Z", "updated_at": "2026-06-01T12:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createSipTrunk", "summary": "Create a SIP trunk", "description": "Registers your own SIP provider for inbound and outbound calling. Supports DID or Extension (`trunk_kind`), calling-number format, transport, and advanced options (secure trunking, headers, codecs). Use this to bring your own numbers instead of buying from the marketplace. See [BYO SIP trunk](/telephony/sip-trunks). **Required scope:** `sip_trunks:write` (keys without scope restrictions have full access).", "tags": [ "SIP Trunks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SipTrunkCreate" }, "example": { "name": "My SIP provider", "sip_address": "sip.example-provider.com", "numbers": [ "+4930123456" ], "auth_username": "acme", "auth_password": "s3cret" } } } }, "responses": { "201": { "description": "The created SIP trunk (sanitized).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SipTrunk" } } }, "example": { "data": { "id": "st1b2c3d-0000-4000-8000-000000000050", "name": "My SIP provider", "provider": "custom", "sip_address": "sip.example-provider.com", "auth_username": "acme", "numbers": [ "+4930123456" ], "metadata": {}, "created_at": "2026-06-01T12:00:00Z", "updated_at": "2026-06-01T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/sip-trunks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "SIP trunk ID." } ], "get": { "operationId": "getSipTrunk", "summary": "Get a SIP trunk", "description": "Returns a customer-owned BYO/BYOC SIP trunk. Managed trunks behind marketplace purchases and verified caller IDs return `404` and are not part of this resource. Passwords and internal trunk identifiers are never returned. **Required scope:** `sip_trunks:read` (keys without scope restrictions have full access).", "tags": [ "SIP Trunks" ], "responses": { "200": { "description": "The SIP trunk (sanitized).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SipTrunk" } } }, "example": { "data": { "id": "st1b2c3d-0000-4000-8000-000000000050", "name": "My SIP provider", "provider": "custom", "sip_address": "sip.example-provider.com", "auth_username": "acme", "numbers": [ "+4930123456" ], "metadata": {}, "created_at": "2026-06-01T12:00:00Z", "updated_at": "2026-06-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteSipTrunk", "summary": "Delete a SIP trunk", "description": "Deletes a customer-owned SIP trunk and its associated voice routing. Managed marketplace and verified caller-ID infrastructure is not accessible through this endpoint. **Required scope:** `sip_trunks:write` (keys without scope restrictions have full access).", "tags": [ "SIP Trunks" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "st1b2c3d-0000-4000-8000-000000000050", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "tags": [ "SIP Trunks" ], "summary": "Update outbound SIP identity", "operationId": "updateSipTrunkIdentity", "description": "Updates only the outbound identity policy for your own SIP trunk. Incoming routing, phone numbers and provider connections are preserved. Requires sip_trunks:write. Existing configurations keep phone_number until explicitly changed.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "outbound_from_user_mode": { "type": "string", "enum": [ "phone_number", "auth_username" ], "default": "phone_number", "description": "Outbound From user for your own SIP trunk. Phone number preserves the existing behavior. SIP username uses the authentication username and keeps the primary DID unchanged. Not available on imported carrier connections." }, "outbound_caller_id_header": { "type": "string", "enum": [ "from_display", "p_asserted_identity", "p_preferred_identity" ], "default": "from_display", "description": "Used with SIP username identity. The primary international DID is sent in the From display name and optionally the selected identity header. Match the carrier caller ID settings." } } } } } }, "responses": { "200": { "description": "The SIP trunk (sanitized).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SipTrunk" } } }, "example": { "data": { "id": "st1b2c3d-0000-4000-8000-000000000050", "name": "My SIP provider", "provider": "custom", "sip_address": "sip.example-provider.com", "auth_username": "acme", "numbers": [ "+4930123456" ], "metadata": {}, "created_at": "2026-06-01T12:00:00Z", "updated_at": "2026-06-01T12:00:00Z" } } } } }, "400": { "description": "Invalid identity settings or imported carrier connection" }, "404": { "description": "SIP trunk not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "security": [ { "bearerAuth": [] } ] } }, "/carrier-connections": { "get": { "operationId": "listCarrierConnections", "summary": "List carrier connections", "description": "Lists BYOC connections and their imported numbers. Secrets are never returned. **Required scope:** `sip_trunks:read`.", "tags": [ "Carrier Connections" ], "responses": { "200": { "description": "Carrier connections.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierConnection" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCarrierConnection", "summary": "Create a carrier connection", "description": "Validates carrier credentials and stores secrets encrypted. Provider routing is configured on the first number import. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierConnectionCreate" }, "example": { "carrier": "vonage", "name": "My Vonage account", "api_key": "1a2345b7", "api_secret": "secret", "sip_region": "eu" } } } }, "responses": { "201": { "description": "Created connection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CarrierConnection" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A connection with this name already exists." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/carrier-connections/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Carrier connection ID." } ], "get": { "operationId": "getCarrierConnection", "summary": "Get a carrier connection", "description": "**Required scope:** `sip_trunks:read`.", "tags": [ "Carrier Connections" ], "responses": { "200": { "description": "Connection details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CarrierConnection" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCarrierConnection", "summary": "Update a carrier connection", "description": "Changes the SIP region and repairs the carrier-side inbound route. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierConnectionUpdate" } } } }, "responses": { "200": { "description": "Updated connection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CarrierConnection" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteCarrierConnection", "summary": "Disconnect a carrier connection", "description": "Safely detaches imported numbers, removes their platform trunks, deletes provider resources, and forgets credentials. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/carrier-connections/{id}/available-numbers": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Carrier connection ID." } ], "get": { "operationId": "listCarrierAvailableNumbers", "summary": "List carrier numbers available to import", "description": "Lists carrier-owned numbers and flags routing conflicts and numbers already imported into this workspace. **Required scope:** `sip_trunks:read`.", "tags": [ "Carrier Connections" ], "responses": { "200": { "description": "Carrier-owned numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "numbers" ], "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierAvailableNumber" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/carrier-connections/{id}/import": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Carrier connection ID." } ], "post": { "operationId": "importCarrierNumbers", "summary": "Import carrier numbers", "description": "Configures carrier routing and creates platform SIP trunks. Returns one result per number; individual failures do not fail the whole batch. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierImportRequest" } } } }, "responses": { "200": { "description": "Updated connection and per-number results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "connection", "results" ], "properties": { "connection": { "$ref": "#/components/schemas/CarrierConnection" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierImportResult" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/carrier-connections/{id}/numbers/{numberId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Carrier connection ID." }, { "name": "numberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Imported phone-number resource ID." } ], "delete": { "operationId": "removeCarrierNumber", "summary": "Remove an imported carrier number", "description": "Detaches one number at the carrier and removes its platform SIP resources. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/carrier-connections/{id}/troubleshoot": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Carrier connection ID." } ], "post": { "operationId": "troubleshootCarrierConnection", "summary": "Troubleshoot a carrier connection", "description": "Checks credentials, provider routing, platform trunks, and dispatch rules; optionally repairs safe drift. **Required scope:** `sip_trunks:write`.", "tags": [ "Carrier Connections" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "repair": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Diagnostic result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CarrierTroubleshootResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases": { "get": { "operationId": "listKnowledgeBases", "summary": "List knowledge bases", "description": "**Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of knowledge bases.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 } } } } } } }, "example": { "data": [ { "id": "kb1b2c3d-0000-4000-8000-000000000060", "name": "Product FAQ", "description": "Frequently asked questions about our product", "document_count": 3, "created_at": "2026-06-20T12:00:00Z", "updated_at": "2026-07-01T12:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createKnowledgeBase", "summary": "Create a knowledge base", "description": "Creates an empty knowledge base. Attach it to an assistant via the assistant's `knowledgebase_id`. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseCreate" }, "example": { "name": "Product FAQ", "description": "Frequently asked questions about our product" } } } }, "responses": { "201": { "description": "The created knowledge base.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBase" } } }, "example": { "data": { "id": "kb1b2c3d-0000-4000-8000-000000000060", "name": "Product FAQ", "description": "Frequently asked questions about our product", "document_count": 0, "created_at": "2026-06-20T12:00:00Z", "updated_at": "2026-07-01T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "get": { "operationId": "getKnowledgeBase", "summary": "Get a knowledge base", "description": "**Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "The knowledge base.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBase" } } }, "example": { "data": { "id": "kb1b2c3d-0000-4000-8000-000000000060", "name": "Product FAQ", "description": "Frequently asked questions about our product", "document_count": 3, "created_at": "2026-06-20T12:00:00Z", "updated_at": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteKnowledgeBase", "summary": "Delete a knowledge base", "description": "Deletes the knowledge base including all its documents and chunks. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "kb1b2c3d-0000-4000-8000-000000000060", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/faqs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listKnowledgeBaseFaqs", "summary": "List FAQ entries and knowledge gaps", "description": "Lists approved FAQ entries or the human-review knowledge-gap inbox. **Required scope:** `knowledge:read`. Beta Features must be enabled for the workspace. Search is case-insensitive literal text matching across questions, answers and proposed answers, applied together with status before pagination. Results are ordered by most recently updated first. meta.pagination.total is the number matching both filters; meta.pending is all open entries (needs_answer and needs_review) in the knowledge base, independent of search, status and page.", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "status", "in": "query", "description": "One or more statuses, comma-separated or supplied as repeated status parameters. Omit for all statuses.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "needs_answer", "needs_review", "approved", "dismissed" ] } }, "style": "form", "explode": false, "example": [ "needs_answer", "needs_review" ] }, { "name": "search", "in": "query", "description": "Literal text to find in questions, answers or proposed answers. Case-insensitive; surrounding whitespace is ignored. Empty text applies no search filter.", "schema": { "type": "string", "maxLength": 200 }, "example": "opening hours" }, { "name": "include_occurrences", "in": "query", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "FAQ entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeFaqEntry" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "description": "Entries matching search and status before pagination." } } }, "pending": { "type": "integer", "description": "All open entries in the knowledge base, independent of search, status and page." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createKnowledgeBaseFaq", "summary": "Create and publish an FAQ entry", "description": "Creates human-approved FAQ knowledge and indexes it immediately. **Required scope:** `knowledge:write`.", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "maxLength": 2000 }, "answer": { "type": "string", "maxLength": 16000 } } } } } }, "responses": { "201": { "description": "Published FAQ entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeFaqEntry" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/faqs/{faqId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "faqId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getKnowledgeBaseFaq", "summary": "Get an FAQ entry", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "FAQ entry and recent occurrences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeFaqEntry" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateKnowledgeBaseFaq", "summary": "Review or update an FAQ entry", "description": "Approval requires an answer and publishes it to retrieval. **Required scope:** `knowledge:write`.", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": [ "string", "null" ] }, "proposed_answer": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "needs_answer", "needs_review", "approved", "dismissed" ] } } } } } }, "responses": { "200": { "description": "Updated FAQ entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeFaqEntry" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteKnowledgeBaseFaq", "summary": "Delete an FAQ entry", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Deletion confirmation." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/documents": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "get": { "operationId": "listKnowledgeBaseDocuments", "summary": "List documents", "description": "Lists the documents of one knowledge base, newest first: uploaded files, raw text, file URLs, single web pages, crawled website pages and cloud drive files. Each document shows its source, indexing status and chunk count. Use a document `id` to read its indexed chunks (`GET /knowledge-bases/{id}/documents/{docId}/chunks`) or to retry it (`POST /knowledge-bases/{id}/documents` with only `document_id`). Unknown, foreign or malformed knowledge base IDs return 404. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of knowledge documents, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of documents in the knowledge base (ignoring limit/offset).", "required": [ "pagination" ], "properties": { "pagination": { "type": "object", "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 2 } } } } } } }, "example": { "data": [ { "id": "55555555-5555-4555-8555-555555555555", "knowledge_base_id": "22222222-2222-4222-8222-222222222222", "name": "Opening hours", "description": null, "source_type": "crawl", "source_url": "https://example.com/opening-hours", "status": "ready", "error_message": null, "chunk_count": 3, "mime_type": "text/plain", "size_bytes": 2048, "created_at": "2026-09-30T08:15:00Z", "updated_at": "2026-09-30T08:15:20Z" }, { "id": "44444444-4444-4444-8444-444444444444", "knowledge_base_id": "22222222-2222-4222-8222-222222222222", "name": "Price list.pdf", "description": "Current prices", "source_type": "file", "source_url": null, "status": "ready", "error_message": null, "chunk_count": 12, "mime_type": "application/pdf", "size_bytes": 184320, "created_at": "2026-09-28T14:02:00Z", "updated_at": "2026-09-28T14:02:41Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 2 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "addKnowledgeDocument", "summary": "Add or retry a document", "description": "Add a document using exactly one of `content` (raw text; `name` required) or `url` (file URL, max 20 MB). Alternatively, provide `document_id` alone to retry an existing document synchronously, without creating or renaming one. For a cloud drive document, retry downloads the current remote version of only that file, even when unchanged, charges normal sync credits, preserves the previous index on failure and never imports or deletes other files. The workspace must retain cloud drive sync access and no sync may already be running. Discovery is bounded to 500 files; a target beyond that listing limit returns 422. Other source types retry their retained file or website; a purged upload without a remote source cannot be retried. Creation returns 201 with the final document, including status `error` when ingestion fails. Retry returns 200 with processing counts; failures return a non-2xx error with a safe customer message. **Required scope:** `knowledge:write` and a workspace role allowed to write (unrestricted keys retain full scope access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentCreate" }, "examples": { "text": { "summary": "Raw text", "value": { "name": "FAQ", "content": "Q: What are your opening hours?\nA: Mon-Fri 9:00-18:00...", "description": "Answers to common questions" } }, "url": { "summary": "File URL", "value": { "url": "https://example.com/files/manual.pdf" } }, "retry": { "summary": "Retry an existing document", "value": { "document_id": "44444444-4444-4444-8444-444444444444" } } } } } }, "responses": { "200": { "description": "The existing document was processed successfully. No new document was created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KnowledgeDocumentProcessResult" } } }, "example": { "data": { "document_id": "44444444-4444-4444-8444-444444444444", "chunk_count": 12, "total_chunks": 12, "truncated": false } } } } }, "201": { "description": "The processed document.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "example": { "data": { "id": "kd1b2c3d-0000-4000-8000-000000000061", "knowledge_base_id": "kb1b2c3d-0000-4000-8000-000000000060", "name": "FAQ", "description": "Answers to common questions", "source_type": "text", "source_url": null, "status": "ready", "error_message": null, "chunk_count": 12, "mime_type": "text/plain", "size_bytes": 20480, "created_at": "2026-07-01T12:00:00Z", "updated_at": "2026-07-01T12:00:30Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "An active plan or enough sync credits is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The source is already syncing or the document changed during processing. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The file format, size or source folder listing prevents retry. Check the source and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Document processing failed. The previous searchable index is preserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Document processing is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/knowledge-bases/{id}/documents/delete": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "post": { "operationId": "deleteKnowledgeBaseDocuments", "summary": "Delete documents in bulk", "description": "Deletes up to 200 documents of one knowledge base in a single request, together with their indexed chunks and stored original files. IDs that do not exist in this knowledge base (or were already deleted) are returned in `not_found_ids` instead of failing the request, so a retry is safe. Pages that came from an Auto Refresh website are imported again on the next refresh unless you add them to that source's exclude paths; files from a cloud drive come back on the next sync unless you remove them from the synced folder. An unknown knowledge base returns 404. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentBulkDeleteInput" }, "examples": { "basic": { "summary": "Delete two documents", "value": { "document_ids": [ "d0c1b2c3-0000-4000-8000-000000000010", "d0c1b2c3-0000-4000-8000-000000000011" ] } } } } } }, "responses": { "200": { "description": "IDs that were deleted and IDs that were not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KnowledgeDocumentBulkDeleteResult" } } }, "example": { "data": { "deleted_ids": [ "d0c1b2c3-0000-4000-8000-000000000010" ], "not_found_ids": [ "d0c1b2c3-0000-4000-8000-000000000011" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/documents/{docId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge document ID, as returned by `GET /knowledge-bases/{id}/documents`." } ], "delete": { "operationId": "deleteKnowledgeBaseDocument", "summary": "Delete a document", "description": "Deletes one knowledge-base document together with its indexed chunks and its stored original file. Assistants stop using its content right away. A page that came from an Auto Refresh website is imported again on the next refresh unless you add it to that source's exclude paths; a file from a cloud drive comes back on the next sync unless you remove it from the synced folder. Unknown, foreign or malformed IDs return 404. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted document." }, "deleted": { "type": "boolean", "description": "Always true." } } } } }, "example": { "data": { "id": "d0c1b2c3-0000-4000-8000-000000000010", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/documents/{docId}/chunks": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge document ID, as returned by `GET /knowledge-bases/{id}/documents`." } ], "get": { "operationId": "listKnowledgeDocumentChunks", "summary": "List document chunks", "description": "Lists the exact searchable chunks produced for one knowledge-base document, in source order. Get document IDs from `GET /knowledge-bases/{id}/documents`. Embeddings and internal indexing metadata are never returned. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Indexed document chunks in source order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocumentChunk" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } }, "example": { "data": [ { "chunk_index": 0, "content": "Opening hours are Monday to Friday, 09:00–18:00.", "token_count": 14 } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/crawl-sources": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "get": { "operationId": "listCrawlSources", "summary": "List crawl sources", "description": "List the website crawl sources of a knowledge base, including each source's editable custom display name. Each source crawls pages under a root URL (same host only, static HTML — no JavaScript rendering) into knowledge documents. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "All crawl sources of the knowledge base.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/CrawlSource" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCrawlSource", "summary": "Create a crawl source", "description": "Register a website as a crawl source for a knowledge base. You can provide an optional custom `name`; when omitted, the source receives a URL-based display name that can be edited later. The crawler fetches pages under `root_url` (same host only, static HTML — no JavaScript rendering, max 2 MB per page), indexes them as documents and charges credits per crawled page. Trigger a crawl with `POST /knowledge-bases/{id}/crawl-sources/{sourceId}/run`, or enable `auto_sync` for periodic re-crawls. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlSourceCreate" }, "examples": { "basic": { "summary": "Docs section, auto-sync daily", "value": { "name": "Help center", "root_url": "https://example.com/docs", "include_paths": [ "/docs" ], "max_pages": 100, "auto_sync": true, "sync_interval_hours": 24 } } } } } }, "responses": { "201": { "description": "The created crawl source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/CrawlSource" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/crawl-sources/discover": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "post": { "operationId": "discoverCrawlSourcePaths", "summary": "Discover website crawl paths", "description": "Inspect a website before creating or updating a crawl source. The preview uses the same-host, SSRF, `robots.txt` and sitemap rules as the crawler, but creates no source or documents, performs no indexing and spends no credits. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlPathDiscoveryRequest" }, "example": { "root_url": "https://example.com/docs", "max_pages": 50 } } } }, "responses": { "200": { "description": "Crawlable page paths and editable include/exclude suggestions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "discovery" ], "properties": { "discovery": { "$ref": "#/components/schemas/CrawlPathDiscovery" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/crawl-sources/{sourceId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Crawl source ID." } ], "get": { "operationId": "getCrawlSource", "summary": "Get a crawl source", "description": "Fetch a single website crawl source, including its custom display name, last run status, `pages_crawled`, `credits_spent` and `last_error`. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "The crawl source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/CrawlSource" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCrawlSource", "summary": "Update a crawl source", "description": "Update a website crawl source (custom display name, root URL, include paths, page limit, or auto-sync settings). **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlSourceUpdate" } } } }, "responses": { "200": { "description": "The updated crawl source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/CrawlSource" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteCrawlSource", "summary": "Delete a crawl source", "description": "Delete a website crawl source. Documents already created by past crawls are kept; only future syncs stop. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/crawl-sources/{sourceId}/pages": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Crawl source ID." } ], "get": { "operationId": "listCrawlSourcePages", "summary": "List indexed crawl-source pages", "description": "List up to 500 ready website pages already indexed for a crawl source. This read-only request does not fetch the website, start a refresh, or spend credits. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Ready pages already indexed for the crawl source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "pages" ], "properties": { "pages": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/CrawlSourcePage" } } } } } }, "example": { "data": { "pages": [ { "id": "kd1b2c3d-0000-4000-8000-000000000071", "name": "Getting started", "source_url": "https://example.com/docs/getting-started", "status": "ready", "chunk_count": 8, "created_at": "2026-08-25T10:00:00Z", "updated_at": "2026-08-25T10:00:30Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/crawl-sources/{sourceId}/run": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Crawl source ID." } ], "post": { "operationId": "runCrawlSource", "summary": "Run a crawl now", "description": "Crawl a website source immediately (synchronous). Fetches pages under the root URL, re-indexes changed pages (unchanged pages are skipped via content hash — no re-embedding, no credits) and charges credits per crawled page. Aborts gracefully when the account runs out of credits (partial results kept, `status` = `error`, `error` = `insufficient credits`). **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Crawl run result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CrawlRunResult" } } }, "example": { "data": { "source_id": "cs1b2c3d-0000-4000-8000-000000000070", "pages_crawled": 42, "pages_skipped": 8, "credits_spent": 42, "status": "idle", "error": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/drive-sources": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "get": { "operationId": "listDriveSources", "summary": "List cloud drive sources", "description": "List the cloud drive sync sources of a knowledge base, including each source's editable custom display name. Each source syncs files from a Google Drive, OneDrive, Box, Dropbox, or SharePoint folder (via an app connection under Automations → Connections) into knowledge documents. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "All cloud drive sources of the knowledge base.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/DriveSource" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createDriveSource", "summary": "Create a cloud drive source", "description": "Register a Google Drive, OneDrive, Box, Dropbox, or SharePoint folder as a sync source for a knowledge base, using an existing app connection (Automations → Connections). You can provide an optional custom `name`; when omitted, the remote folder name or ID becomes the initial display name and can be edited later. The sync lists files under `folder_id` (optionally recursive), indexes them as documents and charges credits per new/changed file. Trigger a sync with `POST /knowledge-bases/{id}/drive-sources/{sourceId}/run`, or enable `auto_sync` for periodic re-syncs. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSourceCreate" }, "examples": { "basic": { "summary": "Google Drive folder, auto-sync daily", "value": { "name": "Support knowledge", "provider": "googledrive", "connection_id": "conn1b2c-0000-4000-8000-000000000090", "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz", "folder_name": "Support docs", "include_subfolders": true, "max_files": 100, "auto_sync": true, "sync_interval_hours": 24 } } } } } }, "responses": { "201": { "description": "The created cloud drive source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/DriveSource" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/drive-sources/{sourceId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Drive source ID." } ], "get": { "operationId": "getDriveSource", "summary": "Get a cloud drive source", "description": "Fetch a single cloud drive sync source, including its custom display name, remote folder metadata, last run status, `files_synced`, `credits_spent` and `last_error`. **Required scope:** `knowledge:read` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "The cloud drive source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/DriveSource" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateDriveSource", "summary": "Update a cloud drive source", "description": "Update a cloud drive sync source (custom display name, app connection, folder, subfolder recursion, file limit, or auto-sync settings). **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSourceUpdate" } } } }, "responses": { "200": { "description": "The updated cloud drive source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/DriveSource" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteDriveSource", "summary": "Delete a cloud drive source", "description": "Delete a cloud drive sync source. Documents already created by past syncs are kept by default; only future syncs stop. Pass `?purge=true` to also remove the documents this source already created. **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "purge", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Also delete the kb_documents already synced from this source." } ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/knowledge-bases/{id}/drive-sources/{sourceId}/run": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Drive source ID." } ], "post": { "operationId": "runDriveSource", "summary": "Run a cloud drive sync now", "description": "Sync a cloud drive source immediately (synchronous). Lists files under the folder (optionally recursive), re-indexes new/changed files (unchanged files are skipped via content hash — no re-embedding, no credits), removes documents whose file no longer exists in the folder, and charges credits per new/changed file. Aborts gracefully when the account runs out of credits (partial results kept, `status` = `error`, `error` = `insufficient credits`). **Required scope:** `knowledge:write` (keys without scope restrictions have full access).", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Drive sync run result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DriveRunResult" } } }, "example": { "data": { "source_id": "ds1b2c3d-0000-4000-8000-000000000080", "files_synced": 12, "files_unchanged": 30, "files_deleted": 1, "files_failed": 0, "files_skipped_unsupported": 2, "credits_spent": 12, "status": "idle", "error": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/perplexity/models": { "post": { "operationId": "listPerplexityModels", "summary": "List Perplexity models", "description": "Return the current Agent API model catalog using either a supplied Perplexity API key or the securely stored key of an existing connector. Secret keys are never returned. Requires an admin-level credential. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "required": [ "api_key" ] }, { "required": [ "tool_id" ] } ], "properties": { "api_key": { "type": "string", "format": "password", "writeOnly": true, "maxLength": 512, "description": "Perplexity API key used for this lookup. Supply this or tool_id, not both." }, "tool_id": { "type": "string", "format": "uuid", "description": "Existing Perplexity connector whose securely stored key should be used. Supply this or api_key, not both." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Models currently available to the Perplexity account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "object", "required": [ "id", "owned_by" ], "properties": { "id": { "type": "string" }, "owned_by": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools": { "get": { "operationId": "listTools", "summary": "List reusable tools", "description": "List the central API, MCP, and built-in Tool Registry. Each item includes its optimistic `revision`, `usage_count`, OAuth connection health, and latest execution result; secret values are masked. **Required scope:** `assistants:read`.", "tags": [ "Tools" ], "responses": { "200": { "description": "All reusable tools of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserTool" } } } }, "example": { "data": [ { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "health": { "connection_status": null, "latest_run": { "status": "success", "created_at": "2026-07-01T09:05:00Z" } }, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createTool", "summary": "Create a tool", "description": "Create one centrally managed API, MCP, or built-in tool. Requires an admin-level credential because configs may contain secrets. Assign it via `PUT /assistants/{id}/tools`. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserToolInput" } ], "required": [ "name", "type", "config" ] }, "example": { "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "Bearer sk_live_..." }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." } } } } }, "responses": { "201": { "description": "The created tool (secret values masked).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UserTool" } } }, "example": { "data": { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/variables": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "getAssistantVariables", "summary": "Get assistant variables", "description": "Returns the custom variable definitions of an assistant plus the inbound variable webhook URL. The webhook secret is never returned. **Required scope:** `assistants:read`.", "tags": [ "Assistants" ], "responses": { "200": { "description": "Variable definitions of the assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantVariables" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateAssistantVariables", "summary": "Update assistant variables", "description": "Replaces the custom variable definitions, contact-field access mode, and/or the inbound variable webhook URL. Send at least one supported field; `variables` always replaces the full list. Legacy `all` contact-field access is read-only and cannot be enabled; attempts return HTTP 400. **Required scope:** `assistants:write`.", "tags": [ "Assistants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "required": [ "variables" ] }, { "required": [ "variable_webhook_url" ] }, { "required": [ "lead_attribute_mode" ] } ], "properties": { "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" }, "description": "Full replacement list of variable definitions." }, "lead_attribute_mode": { "type": "string", "enum": [ "selected" ], "description": "Switches contact-field access to explicit definitions with `source: lead`. Legacy all-fields mode is read-only and cannot be enabled." }, "variable_webhook_url": { "type": [ "string", "null" ], "description": "Endpoint called before an inbound call to fetch variable values. Empty string clears it." } } }, "example": { "variables": [ { "key": "company_name", "label": "Company name", "source": "lead" } ] } } } }, "responses": { "200": { "description": "Updated variable definitions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantVariables" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/tools": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "getAssistantTools", "summary": "List assigned tools", "description": "List assigned central tools. `meta.revision` is required for an atomic replacement. **Required scope:** `assistants:read`.", "tags": [ "Tools" ], "responses": { "200": { "description": "Tools assigned to the assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserTool" } }, "meta": { "$ref": "#/components/schemas/ToolsetRevisionMeta" } } }, "example": { "data": [ { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "setAssistantTools", "summary": "Replace assigned tools", "description": "Atomically replace the assistant's complete tool set. `expected_revision` prevents overwriting concurrent assignment changes. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_ids", "expected_revision" ], "properties": { "tool_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Complete target set of tool IDs to assign." }, "expected_revision": { "type": "integer", "minimum": 1, "description": "Toolset revision returned by GET /assistants/{id}/tools." } } }, "example": { "tool_ids": [ "f1b2c3d4-0000-4000-8000-000000000010" ], "expected_revision": 3 } } } }, "responses": { "200": { "description": "The new set of assigned tools and its new revision.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserTool" } }, "meta": { "$ref": "#/components/schemas/ToolsetRevisionMeta" } } }, "example": { "data": [ { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/automations": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." } ], "get": { "operationId": "listAssistantAutomations", "summary": "List assistant-callable automations", "description": "List automations this assistant can choose to run in voice, web chat, messaging, or email conversations. **Required scope:** `assistants:read`.", "tags": [ "Automations" ], "responses": { "200": { "description": "Assistant-callable automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "tool_name": { "type": "string" }, "tool_active": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAssistantAutomation", "summary": "Create and connect an assistant automation", "description": "Create a draft automation and securely connect it across voice, web chat, messaging, and email conversations. Credentials and assignment are handled automatically. Requires both `assistants:write` and `automations:write`.", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_description" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "tool_description": { "type": "string", "minLength": 10, "maxLength": 1000, "description": "Explain exactly when the assistant should run this automation." } } } } } }, "responses": { "201": { "description": "Draft automation created and connected." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/automations/{automationId}": { "delete": { "operationId": "disconnectAssistantAutomation", "summary": "Disconnect an assistant automation", "description": "Pause and disconnect an assistant-callable automation. Requires both `assistants:write` and `automations:write`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID." }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation ID." } ], "responses": { "200": { "description": "Automation disconnected." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/greeting-audio": { "post": { "summary": "Set audio first message", "description": "Uploads an audio greeting played verbatim at call start instead of TTS. Send JSON `{ \"url\": \"https://…/greeting.mp3\" }` (downloaded server-side) or multipart/form-data with a `file` field. Formats mp3/wav/ogg/m4a, max 5 MB. `first_message` remains the transcript / chat / voicemail fallback.", "operationId": "setAssistantGreetingAudio", "tags": [ "Assistants" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http(s) URL of the audio file to download." } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file (mp3/wav/ogg/m4a, max 5 MB)." } } } } } }, "responses": { "200": { "description": "Audio greeting stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant": { "$ref": "#/components/schemas/Assistant" }, "greeting_audio_url": { "type": [ "string", "null" ], "description": "Short-lived signed playback URL (1 h)." } } } } } }, "400": { "description": "Invalid request (format/size/url).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Assistant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "summary": "Remove audio first message", "description": "Deletes the stored audio greeting and clears `greeting_audio_path`. The assistant falls back to the `first_message` text / TTS. No-op if none is set.", "operationId": "deleteAssistantGreetingAudio", "tags": [ "Assistants" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant id." } ], "responses": { "200": { "description": "Audio greeting removed (assistant returned).", "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant": { "$ref": "#/components/schemas/Assistant" } } } } } }, "404": { "description": "Assistant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/avatar": { "post": { "summary": "Set assistant picture", "description": "Set a gallery picture or upload a custom image. Discover gallery ids with GET /assistants/avatar-gallery, then send gallery_id and optional appearance (light or dark). Alternatively send url, data_base64 with content_type, or multipart file. Choose exactly one source. PNG/JPEG/WebP uploads accept up to 1 MB; images are compressed automatically. Replaces the current picture. Not writable via PATCH.", "operationId": "setAssistantAvatar", "tags": [ "Assistants" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http(s) URL of the image to download." } } }, { "type": "object", "required": [ "data_base64", "content_type" ], "properties": { "data_base64": { "type": "string", "description": "Base64-encoded image bytes." }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] } } }, { "type": "object", "required": [ "gallery_id" ], "properties": { "gallery_id": { "type": "string", "description": "Picture id returned by listAssistantAvatarGallery. Choose this instead of url or data_base64." }, "appearance": { "type": "string", "enum": [ "light", "dark" ], "default": "light", "description": "Background and line colors of the gallery picture." } } } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image file (PNG/JPEG/WebP, max 1 MB incoming)." } } } } } }, "responses": { "200": { "description": "Assistant picture stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant": { "$ref": "#/components/schemas/Assistant" }, "avatar_url": { "type": "string", "format": "uri", "description": "Public URL of the stored picture." } } } } } }, "400": { "description": "Invalid request (format/size/url).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Assistant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "summary": "Remove assistant picture", "description": "Deletes the custom picture and clears `avatar_url`. The UI falls back to the default mesh orb. No-op if none is set.", "operationId": "deleteAssistantAvatar", "tags": [ "Assistants" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant id." } ], "responses": { "200": { "description": "Assistant picture removed (assistant returned).", "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant": { "$ref": "#/components/schemas/Assistant" } } } } } }, "404": { "description": "Assistant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Tool ID." } ], "get": { "operationId": "getTool", "summary": "Get a tool", "description": "Read a single reusable tool. Secret values in `config` are always masked as `•••`.\n\n**Required scope:** `assistants:read` (keys without scope restrictions have full access).", "tags": [ "Tools" ], "responses": { "200": { "description": "The tool.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UserTool" } } }, "example": { "data": { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateTool", "summary": "Update a tool", "description": "Revision-protected partial update. `type` is immutable. Sending `•••` for a secret keeps the stored value. A provided `config` replaces the stored configuration: send back every header from the read response (masked values as `•••`); omitted headers are removed. A stale revision returns `409 revision_conflict`. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserToolInput" }, { "type": "object", "required": [ "expected_revision" ] } ] }, "example": { "description": "Look up an order by its number.", "is_active": false, "expected_revision": 4 } } } }, "responses": { "200": { "description": "The updated tool (secret values masked).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UserTool" } } }, "example": { "data": { "id": "f1b2c3d4-0000-4000-8000-000000000010", "name": "check_order_status", "description": "Look up the status of a customer order by order number.", "type": "api", "config": { "method": "GET", "url": "https://api.example.com/orders/status", "headers": { "Authorization": "•••" }, "parameters": [ { "name": "order_number", "type": "string", "description": "The order number", "required": true, "source": "llm", "location": "query" } ], "static_values": {}, "response_mapping": {}, "timeout_ms": 10000, "async": false, "filler_phrase": "One moment, I am checking that for you." }, "is_active": true, "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-01T09:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "archiveTool", "summary": "Archive an unused tool", "description": "Archive an unused tool. Active assignments return `409 tool_in_use`; disabling remains available at any time. Pass the current revision as `expected_revision` or `If-Match`. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "parameters": [ { "name": "expected_revision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archive confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "f1b2c3d4-0000-4000-8000-000000000010", "archived": true, "revision": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}/usage": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getToolUsage", "summary": "Get tool usage and impact", "description": "Lists assistants currently assigned to the tool. **Required scope:** `assistants:read`.", "tags": [ "Tools" ], "responses": { "200": { "description": "Tool usage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ToolUsage" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}/reauthorize": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "reauthorizeTool", "summary": "Reauthorize an OAuth MCP tool", "description": "Creates a short-lived browser authorization URL for an existing OAuth MCP tool. Completing the flow repairs the same tool id and preserves assignments, allowed tools, settings, and run history. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "responses": { "200": { "description": "Interactive authorization URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "tool_id", "url", "expires_in_seconds" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Open this URL in the user's browser to complete authorization." }, "expires_in_seconds": { "type": "integer", "example": 600 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}/versions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listToolVersions", "summary": "List tool versions", "description": "Lists immutable, secret-masked tool versions newest first. **Required scope:** `assistants:read`.", "tags": [ "Tools" ], "responses": { "200": { "description": "Version history.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserToolVersion" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}/versions/{revision}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "operationId": "restoreToolVersion", "summary": "Restore a tool version", "description": "Restores a historical snapshot as a new revision. **Required scope:** `assistants:write`.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Restored tool.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UserTool" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/suppression-list": { "get": { "operationId": "listSuppressionEntries", "summary": "List suppression entries", "description": "Lists active marketing suppressions across voice, SMS, email, and supported messaging channels. Results expose the public contact identity, scope, origin channel, source, and consent mode captured at opt-out. **Required scope:** `suppression:read` (keys without scope restrictions have full access).", "tags": [ "Suppression" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by phone number, email, identity, or reason (substring match)." }, { "name": "channel", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ConsentChannel" }, "description": "Return records that block this channel, including universal (`all`) suppressions." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of suppression entries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionEntry" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 2 } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "addSuppressionEntry", "summary": "Add a suppression entry", "description": "Records a marketing opt-out for a contact identified by contact ID, phone, or email. The current workspace consent mode determines whether the resulting scope is universal or limited to the originating channel. **Required scope:** `suppression:write`.", "tags": [ "Suppression" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "required": [ "contact_id" ] }, { "required": [ "phone" ] }, { "required": [ "email" ] } ], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "Existing workspace contact/lead ID." }, "phone": { "type": "string", "description": "Phone number in E.164 format. Separators are stripped.", "example": "+4930123456" }, "email": { "type": "string", "format": "email", "description": "Contact email address.", "example": "contact@example.com" }, "channel": { "$ref": "#/components/schemas/ConsentChannel", "description": "Channel where the opt-out occurred. When omitted, phone defaults to `voice` and email defaults to `email`." }, "reason": { "type": "string", "maxLength": 500, "description": "Optional reason (max 500 characters).", "example": "Unsubscribe request" } } } } } }, "responses": { "201": { "description": "The created entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuppressionEntry" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/suppression-list/{id}": { "delete": { "operationId": "removeSuppressionEntry", "summary": "Restore contact consent", "description": "Revokes one active suppression and appends an opt-in audit event; compliance history is not erased. `{id}` accepts the suppression entry ID, an E.164 phone number, or an email address. Prefer the entry ID when a contact has multiple channel-specific records. **Required scope:** `suppression:write`.", "tags": [ "Suppression" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suppression entry ID, URL-encoded E.164 phone number, or URL-encoded email address." } ], "responses": { "200": { "description": "Consent was restored and an audit event was appended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "restored", "id" ], "properties": { "restored": { "type": "boolean", "const": true, "example": true }, "id": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/scheduled-callbacks": { "get": { "operationId": "listScheduledCallbacks", "summary": "List scheduled callbacks", "description": "Callbacks booked by the Schedule callback tool across voice, chat/messaging, and email. Due `pending` rows are dialed automatically by the platform dialer. **Required scope:** `calls:read`.", "tags": [ "Callbacks" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "dialing", "completed", "failed", "cancelled" ] }, "description": "Filter by status." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by phone number or reason (substring match)." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of scheduled callbacks.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledCallback" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 2 } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/scheduled-callbacks/{id}": { "patch": { "operationId": "cancelScheduledCallback", "summary": "Cancel a scheduled callback", "description": "Cancels a `pending` or `dialing` callback so it will not be dialed. Body must be `{ \"status\": \"cancelled\" }`. **Required scope:** `calls:write`.", "tags": [ "Callbacks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "cancelled" ] } } } } } }, "responses": { "200": { "description": "The callback was cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScheduledCallback" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Request body is invalid (only `{ \"status\": \"cancelled\" }` is supported).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/workspace-country": { "get": { "operationId": "getWorkspaceCountry", "summary": "Get workspace country", "description": "Reads the workspace home country. A null value means the country has not yet been detected or selected. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace country setting.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "nullable": true, "pattern": "^[A-Z]{2}$", "description": "ISO-3166-1 alpha-2 workspace country, or null until detected or selected." } } } } }, "example": { "data": { "country_code": "DE" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateWorkspaceCountry", "summary": "Update workspace country", "description": "Sets the workspace home country. Pass null to use automatic location detection on the next dashboard or sign-in request. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "nullable": true, "pattern": "^[A-Z]{2}$", "description": "Supported ISO-3166-1 alpha-2 country code, or null for automatic detection." } } }, "example": { "country_code": "DE" } } } }, "responses": { "200": { "description": "The updated workspace country setting.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "nullable": true, "pattern": "^[A-Z]{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Missing or unsupported country code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/memory": { "get": { "operationId": "getMemorySettings", "summary": "Get memory settings", "description": "Reads the workspace defaults for caller memory. Assistants with `memory_mode: \"inherit\"` (see `PATCH /assistants/{id}`) follow `memory_enabled_default`. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace memory settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemorySettings" } } }, "example": { "data": { "memory_enabled_default": true, "memory_staleness_days": 180, "memory_channels": [ "voice", "sms", "whatsapp", "email" ], "memory_consent_required": true, "memory_retention_days": 365 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateMemorySettings", "summary": "Update memory settings", "description": "Updates the workspace defaults for caller memory. Provide at least one field. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memory_enabled_default": { "type": "boolean", "description": "Workspace default for caller memory." }, "memory_staleness_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Days without a successful memory update until content goes stale; `null` = never." }, "memory_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Configured memory channels. Web Chat and Web Voice require a current verified widget email or phone and visitor consent. Web and SMS memory require a root workspace. An empty array disables all memory channels." }, "memory_consent_required": { "type": "boolean", "description": "When true, unknown consent blocks memory reads and writes." }, "memory_retention_days": { "type": "integer", "minimum": -1, "maximum": 3650, "description": "Rolling retention in days; `-1` keeps memory until it is manually erased." } } }, "example": { "memory_enabled_default": true, "memory_staleness_days": 180, "memory_channels": [ "voice", "sms", "whatsapp", "email" ], "memory_consent_required": true, "memory_retention_days": 365 } } } }, "responses": { "200": { "description": "The updated settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemorySettings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/contacts/memory": { "get": { "operationId": "listCustomerMemories", "summary": "List customer memories", "description": "Lists one consent- and retention-aware memory entry per contact with exact channel identities. Private assistant content is never exposed in the list. **Required scope:** `leads:read` or `calls:read`.", "tags": [ "Leads" ], "parameters": [ { "name": "consent", "in": "query", "schema": { "type": "string", "enum": [ "unknown", "granted", "denied" ] } }, { "name": "search", "in": "query", "description": "Case-insensitive search across contact name, phone, email, and the currently visible shared summary. Applied before pagination together with the consent filter. Private, expired, and stale memory content is not searched.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A paginated list of customer memories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMemory" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/contacts/{id}/memory": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Audience contact ID.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getCustomerMemory", "summary": "Get customer memory", "description": "Returns the contact, shared and assistant-specific memories, exact channel identities, and recent audit events. **Required scope:** `leads:read` or `calls:read`.", "tags": [ "Leads" ], "responses": { "200": { "description": "The customer-memory record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerMemoryDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCustomerMemory", "summary": "Update customer memory", "description": "Revision-protected update of either explicit consent or the shared summary/preferences. Read the current workspace-memory `revision` first; consent and content must be changed in separate requests. **Required scope:** `leads:write` or `calls:write`.", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision" ], "minProperties": 2, "additionalProperties": false, "oneOf": [ { "required": [ "consent_status" ], "not": { "anyOf": [ { "required": [ "summary" ] }, { "required": [ "preferences" ] } ] } }, { "anyOf": [ { "required": [ "summary" ] }, { "required": [ "preferences" ] } ], "not": { "required": [ "consent_status" ] } } ], "properties": { "expected_revision": { "type": "integer", "minimum": 0, "description": "Current workspace-memory revision returned by GET. Use 0 only when no workspace memory exists." }, "consent_status": { "$ref": "#/components/schemas/MemoryConsentStatus" }, "summary": { "type": "string", "maxLength": 1500, "nullable": true }, "preferences": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "The updated customer-memory record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerMemoryDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "eraseCustomerMemory", "summary": "Erase customer memory", "description": "Permanently deletes all stored summaries, preferences, and remembered variables for the contact. A content-free deletion audit remains; the contact and exact channel identities remain. **Required scope:** `leads:write` or `calls:write`.", "tags": [ "Leads" ], "responses": { "200": { "description": "The number of erased memory rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "integer", "minimum": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/sessions": { "get": { "operationId": "listAccountSessions", "summary": "List active account sessions", "description": "Lists active sign-in sessions for the user associated with the API credential. Session IDs are opaque revocation handles; authentication tokens, IP addresses, and native authentication-provider identifiers are never returned. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "Active account sessions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "browser", "os", "device_type", "created_at", "last_seen_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Opaque session revocation handle." }, "label": { "type": "string", "example": "Chrome on macOS" }, "browser": { "type": "string", "example": "Chrome" }, "os": { "type": "string", "example": "macOS" }, "device_type": { "type": "string", "enum": [ "desktop", "mobile", "tablet", "unknown" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "signOutAccountSession", "summary": "Sign out an account session", "description": "Revokes one active sign-in session belonging to the user associated with the API credential. The session handle comes from `GET /settings/sessions`. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Opaque session handle returned by the list endpoint." } } } } } }, "responses": { "200": { "description": "The session was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/passkeys": { "get": { "operationId": "listPasskeys", "summary": "List passkeys", "description": "Lists the passkeys the user associated with the API credential can sign in with, newest first. Passkeys are added in the app under Settings → Preferences, because that requires the user's device. Only available on the main platform and with a user-owned API key or OAuth token. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The user's passkeys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "created_at", "last_used_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Passkey id — use it to delete the passkey." }, "name": { "type": [ "string", "null" ], "description": "Name of the password manager or device that stores the passkey, when known.", "example": "iCloud Keychain" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last sign-in with this passkey; null if it was never used." } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deletePasskey", "summary": "Delete a passkey", "description": "Removes one of the user's passkeys, for example for a lost device. The user can no longer sign in with it; other sign-in methods keep working. Only available on the main platform and with a user-owned API key or OAuth token. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "passkey_id" ], "properties": { "passkey_id": { "type": "string", "format": "uuid", "description": "Passkey id returned by the list endpoint." } } } } } }, "responses": { "200": { "description": "The passkey was removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/consent-compliance": { "get": { "operationId": "getConsentComplianceSettings", "summary": "Get consent compliance mode", "description": "Reads how marketing opt-outs are enforced in the workspace. `universal` blocks every linked channel after any opt-out; `per_channel` blocks only the originating channel. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace consent mode and plan availability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConsentComplianceSettings" } } }, "example": { "data": { "mode": "universal", "per_channel_available": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateConsentComplianceSettings", "summary": "Update consent compliance mode", "description": "Updates marketing opt-out enforcement. Universal mode is always available. Per-channel mode requires the Consent & Compliance plan feature; suppression enforcement itself is never disabled. Existing suppression records retain their original scope and `mode_at_opt_out`. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "$ref": "#/components/schemas/ConsentMode" } } }, "example": { "mode": "per_channel" } } } }, "responses": { "200": { "description": "The updated workspace consent mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConsentComplianceSettings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/marketing": { "get": { "operationId": "getMarketingIntegrations", "summary": "Get marketing integrations", "description": "Reads structured marketing pixel IDs (GA4, Meta, Google Ads, Microsoft UET) for this white-label domain. Conversion API secrets are never returned — only whether a secret is stored. **Required scope:** `settings:read`. Requires white-label access.", "tags": [ "Settings" ], "responses": { "200": { "description": "Marketing integrations for the reseller domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MarketingSettingsResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "updateMarketingIntegrations", "summary": "Update marketing integrations", "description": "Merges marketing pixel IDs and optional conversion-API secrets for this white-label domain. Omit a secret to keep the stored value. **Required scope:** `settings:write`. Requires white-label access.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketingSettingsInput" }, "example": { "integrations": { "ga4": { "measurement_id": "G-XXXXXXXX", "enabled": true }, "meta_pixel": { "pixel_id": "1234567890", "enabled": true } } } } } }, "responses": { "200": { "description": "The updated marketing integrations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MarketingSettingsResponse" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/dark-windows": { "get": { "operationId": "getDarkWindowSettings", "summary": "Get Dark Windows settings", "description": "Reads proactive-outbound quiet hours for every supported channel and the workspace timezone. Inbound customer replies remain available. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "All workspace channel windows and the workspace timezone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DarkWindowSettingsResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateDarkWindowSettings", "summary": "Update Dark Windows settings", "description": "Updates one or more proactive-outbound quiet-hour windows. Omitted channels stay unchanged. Times use 24-hour `HH:MM` format and a start later than the end creates an overnight window. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "$ref": "#/components/schemas/DarkWindowSettingsPatch" } }, "additionalProperties": false }, "example": { "settings": { "gmail": { "enabled": true, "start": "21:00", "end": "08:00" }, "outlook": { "enabled": true, "start": "22:00", "end": "07:00" } } } } } }, "responses": { "200": { "description": "The complete updated workspace channel windows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DarkWindowSettingsResponse" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/retention": { "get": { "operationId": "getRetentionSettings", "summary": "Get data retention settings", "description": "Reads per-channel workspace overrides, the governing plan default and limits, and whether the current plan includes Data Retention. A `null` channel value follows `plan_default_days`. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace retention policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RetentionSettingsResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateRetentionSettings", "summary": "Update data retention settings", "description": "Updates one or more per-channel retention overrides in months. Set a field to `null` to restore the plan default. Values are clamped to the governing platform or reseller limits. Requires the Data Retention plan feature. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionSettingsInput" }, "example": { "calls_months": 24, "email_months": 12, "whatsapp_months": null } } } }, "responses": { "200": { "description": "The updated workspace retention policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RetentionSettingsResponse" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/outbound-limits": { "get": { "operationId": "getOutboundLimits", "summary": "Get outbound call limits", "description": "Returns today's workspace-wide usage, remaining allowance, reset time, and request history for outbound calls through integrated numbers. Inbound, web, and customer-owned SIP trunk calls do not count. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace outbound quota and request status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OutboundLimitStatus" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/outbound-limits/requests": { "post": { "operationId": "requestOutboundLimitIncrease", "summary": "Request an outbound call limit increase", "description": "Submits a workspace-wide increase request for review. Only workspace owners and admins can submit a request, and only one request can be pending at a time. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundLimitRequestInput" }, "example": { "requested_daily_limit": 300, "reason": "We are expanding appointment reminders to three locations.", "business_website": "https://example.com" } } } }, "responses": { "201": { "description": "The pending increase request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OutboundLimitRequest" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/support/requests": { "get": { "operationId": "listSupportRequests", "summary": "List support requests", "description": "Lists the API key user's own support requests in this workspace (newest first, max 30) with live status, priority, the assigned support team member and unread replies. Reseller-customer workspaces are not eligible. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "Support requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicket" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSupportRequest", "summary": "Create a support request", "description": "Submits a support request for the authenticated root workspace, including a white-label reseller workspace. Reseller-customer workspaces are not eligible. Reusing the same client request ID with the same content returns the original reference. Workspaces with Priority Support (included in the plan or booked as add-on) are routed to priority support automatically; `priority_support` in the response confirms it. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportRequestInput" }, "example": { "client_request_id": "4bc693c5-fd56-49e3-85d6-75b4b58763d3", "subject": "Outbound calls end after pickup", "message": "The issue started today and affects every outbound call." } } } }, "responses": { "201": { "description": "The submitted request and its public reference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupportRequest" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "The support service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/support/requests/{reference}": { "get": { "operationId": "getSupportRequest", "summary": "Get a support request", "description": "Returns one of your support requests with its status, assigned support team member and the conversation with the support team. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^SUP-[A-Fa-f0-9]{12}$" }, "example": "SUP-4BC693C5FD56" } ], "responses": { "200": { "description": "The support request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupportTicketDetail" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/support/requests/{reference}/messages": { "post": { "operationId": "replyToSupportRequest", "summary": "Reply to a support request", "description": "Sends a reply to the support team. Replying to a resolved request reopens it. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^SUP-[A-Fa-f0-9]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicketReplyInput" }, "example": { "message": "It still happens after the update.", "client_message_id": "9a3a45f1-7b1a-46b4-8909-e5376128e5f7" } } } }, "responses": { "201": { "description": "The sent reply.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupportTicketMessage" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "The support service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/email-senders": { "get": { "operationId": "listEmailSenders", "summary": "List email sender choices", "description": "Returns the secrets-free sender choices that can be stored on a reusable `send_email` tool: automatic routing, workspace SMTP, platform mail, and verified sender addresses. Also returns workspace display-name and signature defaults. **Required scope:** `settings:read` or `assistants:read`. Requires workspace owner/admin role.", "tags": [ "Settings" ], "responses": { "200": { "description": "Available email sender choices and workspace defaults.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailSenderCatalog" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/custom-domain": { "get": { "operationId": "getCustomDomainStatus", "summary": "Get custom domain status", "description": "Reads the workspace custom domain and checks its live ownership plus DNS/TLS configuration. `ready` becomes true only when ownership is verified and the platform reports a valid configuration that can receive a TLS certificate. **Required scope:** `settings:read` or `assistants:read`. Requires workspace owner/admin role and the Whitelabel entitlement. **Requires the white-label entitlement** (plan add-on `whitelabel`, or a workspace override). Workspaces without it get `403 whitelabel_not_in_plan`, and only workspace owners and admins may call it.", "tags": [ "Settings" ], "responses": { "200": { "description": "Live custom-domain status and any DNS records still required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomDomainStatus" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "addCustomDomain", "summary": "Add custom domain", "description": "Attaches a hostname to the platform and returns the exact ownership and routing records to configure. When the hostname is the apex or its `www` sibling, the companion host is also attached with a 308 redirect to the canonical domain. A workspace can have one custom domain. **Required scope:** `settings:write` or `assistants:write`. Requires workspace owner/admin role and the Whitelabel entitlement. **Requires the white-label entitlement** (plan add-on `whitelabel`, or a workspace override). Workspaces without it get `403 whitelabel_not_in_plan`, and only workspace owners and admins may call it.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "app.famulor.io", "description": "Hostname only; do not include a protocol or path." } } } } } }, "responses": { "201": { "description": "Domain attached; apply `required_records` and then call the verify endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomDomainStatus" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "removeCustomDomain", "summary": "Remove custom domain", "description": "Detaches the workspace custom domain (and any www/apex companion redirect) from the platform, removes it where possible, and disables it for host-based login and branding. **Required scope:** `settings:write` or `assistants:write`. Requires workspace owner/admin role. **Requires the white-label entitlement** (plan add-on `whitelabel`, or a workspace override). Workspaces without it get `403 whitelabel_not_in_plan`, and only workspace owners and admins may call it.", "tags": [ "Settings" ], "responses": { "200": { "description": "Domain removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "removed", "domain" ], "properties": { "removed": { "type": "boolean", "const": true }, "domain": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/custom-domain/verify": { "post": { "operationId": "verifyCustomDomain", "summary": "Check custom domain DNS", "description": "Rechecks the ownership challenge and reads the current project-specific DNS/TLS configuration. DNS propagation may take time; an incomplete setup returns `200` with `ready: false` and updated `required_records`. **Required scope:** `settings:write` or `assistants:write`. Requires workspace owner/admin role. **Requires the white-label entitlement** (plan add-on `whitelabel`, or a workspace override). Workspaces without it get `403 whitelabel_not_in_plan`, and only workspace owners and admins may call it.", "tags": [ "Settings" ], "responses": { "200": { "description": "Latest ownership and DNS/TLS state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomDomainStatus" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/calendly/oauth-url": { "post": { "operationId": "createCalendlyOauthUrl", "summary": "Start Calendly OAuth", "description": "Creates a short-lived Calendly OAuth 2.1 authorization URL with PKCE S256. Open the returned URL in a browser. After consent, Calendly redirects to the platform callback and the account appears in the connections endpoint. Pass `integration_id` to reconnect a legacy PAT-backed integration. The credential must be user-owned and belong to a workspace owner or admin; workspace service-account credentials get `403`. **Required scope:** `integrations:write`.", "tags": [ "Integrations" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration_id": { "type": "string", "format": "uuid", "description": "Optional existing Calendly integration to reconnect." } } } } } }, "responses": { "200": { "description": "Short-lived authorization URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "authorization_url" ], "properties": { "authorization_url": { "type": "string", "format": "uri" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/calendly/connections": { "get": { "operationId": "listCalendlyConnections", "summary": "List connected Calendly accounts", "description": "Lists workspace-bound Calendly OAuth accounts. Access tokens, refresh tokens, user resource URIs, refresh locks, and client secrets are never returned. **Required scope:** `integrations:read`. User-owned credentials need a workspace owner or admin role; workspace service-account credentials only need the scope.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Calendly OAuth accounts available to integrations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendlyConnection" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/calendly/event-types": { "get": { "operationId": "listCalendlyEventTypes", "summary": "List active Calendly event types", "description": "Lists active event types by public ID, name and duration, with supported location options. Full Calendly resource URIs stay internal. **Required scope:** `integrations:read`. User-owned credentials need a workspace owner or admin role; workspace service-account credentials only need the scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Active event types for the selected account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendlyEventType" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/acuity/oauth-url": { "post": { "operationId": "createAcuityOauthUrl", "summary": "Start Acuity OAuth", "description": "Creates a short-lived Acuity Scheduling OAuth authorization URL. Open the returned URL in a browser. After consent, Acuity redirects to the platform callback and the account appears in the connections endpoint. Pass `integration_id` to reconnect an existing Acuity integration. The credential must be user-bound and belong to a current workspace owner/admin (or platform admin); service-account credentials cannot complete the interactive OAuth callback. **Required scope:** `integrations:write`.", "tags": [ "Integrations" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration_id": { "type": "string", "format": "uuid", "description": "Optional existing Acuity integration to reconnect." } } } } } }, "responses": { "200": { "description": "Short-lived authorization URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "authorization_url" ], "properties": { "authorization_url": { "type": "string", "format": "uri" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/acuity/connections": { "get": { "operationId": "listAcuityConnections", "summary": "List connected Acuity accounts", "description": "Lists workspace-bound Acuity Scheduling OAuth accounts. Access tokens, provider account URIs, and client secrets are never returned. **Required scope:** `integrations:read`. User-owned credentials need a workspace owner or admin role; workspace service-account credentials only need the scope.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Acuity OAuth accounts available to integrations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AcuityConnection" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/acuity/appointment-types": { "get": { "operationId": "listAcuityAppointmentTypes", "summary": "List Acuity appointment types", "description": "Lists appointment types available to the selected Acuity account, including service, class, and series types. **Required scope:** `integrations:read`. User-owned credentials need a workspace owner or admin role; workspace service-account credentials only need the scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Appointment types for the selected account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AcuityAppointmentType" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/acuity/calendars": { "get": { "operationId": "listAcuityCalendars", "summary": "List Acuity calendars", "description": "Lists calendars available to the selected Acuity account. Use a calendar ID to restrict an integration to one calendar, or omit it to use any compatible calendar. **Required scope:** `integrations:read`. User-owned credentials need a workspace owner or admin role; workspace service-account credentials only need the scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Calendars for the selected account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AcuityCalendar" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations": { "get": { "operationId": "listIntegrations", "summary": "List calendar integrations", "description": "List all calendar integrations of the account (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Secret values in configs are always masked. Assign integrations to an assistant via `PUT /assistants/{id}/integrations` — the assistant then gets availability and booking tools plus provider-supported appointment lookup, cancellation, and rescheduling.\n\n**Required scope:** `integrations:read` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "responses": { "200": { "description": "All calendar integrations of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createIntegration", "summary": "Create a calendar integration", "description": "Create a calendar integration. The connection is verified **before** saving (Cal.com: API key + event type; Calendly: OAuth `connection_id` + public `event_type_id`; Acuity: OAuth `connection_id` + numeric `appointment_type_id` and optional `calendar_id`; google/outlook: the calendar connection must exist; native: the booking event type must exist) — invalid credentials are rejected with `400` and never stored. Calendly resource URIs, Acuity account identifiers, and all OAuth tokens stay internal. Requires a user-owned credential of a workspace owner or admin (workspace service-account credentials can only read calendar integrations and get `403`) and a plan that includes calendar integrations.\n\n**Required scope:** `integrations:write` (keys without scope restrictions have full access).\n\nmeetergo verifies the chosen meeting type using scheduling access before saving. Discover meeting types through POST /integrations/meetergo/meeting-types.", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationInput" }, "example": { "name": "Sales calendar", "provider": "calcom", "config": { "api_key_encrypted": "cal_live_…", "event_type_id": 1427703, "timezone": "Europe/Berlin" } } } } }, "responses": { "201": { "description": "The created integration (secrets masked).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Integration" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/integrations/{id}": { "get": { "operationId": "getIntegration", "summary": "Get a calendar integration", "description": "Read a single calendar integration. Secret values are masked.\n\n**Required scope:** `integrations:read` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Integration ID" } ], "responses": { "200": { "description": "The integration.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Integration" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateIntegration", "summary": "Update a calendar integration", "description": "Update a calendar integration. `provider` is immutable. Send `•••` for a secret config field to keep the stored value; config changes re-run the connection test and reset `status` to `ok`. Requires a user-owned credential of a workspace owner or admin; workspace service-account credentials get `403`.\n\n**Required scope:** `integrations:write` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Integration ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64 }, "config": { "type": "object" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The updated integration.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Integration" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteIntegration", "summary": "Delete a calendar integration", "description": "Permanently delete a calendar integration. Assistant assignments are removed automatically. Requires a user-owned credential of a workspace owner or admin; workspace service-account credentials get `403`.\n\n**Required scope:** `integrations:write` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Integration ID" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/integrations": { "get": { "operationId": "getAssistantIntegrations", "summary": "List assistant integrations", "description": "List the calendar integrations assigned to an assistant. Each assignment adds `check_availability` and `book_appointment` (Calendly link mode: `send_booking_link`) plus provider-supported appointment lookup, cancellation, and rescheduling tools.\n\n**Required scope:** `integrations:read` or `assistants:read` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID" } ], "responses": { "200": { "description": "Assigned integrations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "setAssistantIntegrations", "summary": "Replace assistant integrations", "description": "REPLACE the integration assignments of an assistant with the given set. Pass an empty array to remove all assignments (possible even after a plan downgrade); assigning requires a plan that includes calendar integrations. Requires a user-owned credential of a workspace owner or admin; workspace service-account credentials get `403`.\n\n**Required scope:** `integrations:write` or `assistants:write` (keys without scope restrictions have full access).", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Assistant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "integration_ids" ], "properties": { "integration_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Complete target set of integration IDs." } } } } } }, "responses": { "200": { "description": "The new assignment set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/booking-event-types": { "get": { "operationId": "listBookingEventTypes", "summary": "List booking event types", "description": "List the event types of the native booking engine. Each active event type has a public, iframe-embeddable booking page at `/book/{workspace}/{slug}` and can be attached to assistants via a `native` calendar integration.\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "responses": { "200": { "description": "All event types of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BookingEventType" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createBookingEventType", "summary": "Create a booking event type", "description": "Create an event type. The slug is **unique within the workspace** and becomes the public booking page URL `/book/{workspace}/{slug}`. Requires an admin-level credential; requires Calendar integrations in the workspace plan.\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingEventTypeInput" }, "example": { "name": "Intro call", "slug": "acme-intro", "duration_min": 30, "timezone": "Europe/Berlin", "availability": { "mon": [ { "start": "09:00", "end": "17:00" } ], "tue": [ { "start": "09:00", "end": "17:00" } ], "wed": [ { "start": "09:00", "end": "17:00" } ], "thu": [ { "start": "09:00", "end": "17:00" } ], "fri": [ { "start": "09:00", "end": "17:00" } ] } } } } }, "responses": { "201": { "description": "The created event type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BookingEventType" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/booking-event-types/{id}": { "get": { "operationId": "getBookingEventType", "summary": "Get a booking event type", "description": "Read a single event type.\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Event type ID" } ], "responses": { "200": { "description": "The event type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BookingEventType" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateBookingEventType", "summary": "Update a booking event type", "description": "Update an event type; only provided fields change.\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Event type ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingEventTypeInput" } } } }, "responses": { "200": { "description": "The updated event type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BookingEventType" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteBookingEventType", "summary": "Delete a booking event type", "description": "Permanently delete an event type. **All its bookings are deleted with it** (ON DELETE CASCADE).\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Event type ID" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/bookings": { "get": { "operationId": "listBookings", "summary": "List bookings", "description": "List bookings of the native booking engine. Bookings are created by the public booking page, by assistants mid-call (`book_appointment`), via the public page API, or by `POST /bookings` — which also supports a staff override outside the event type's open times. Use `view` for the dashboard-style lists, or `status` for an exact status; they cannot be combined.\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "event_type_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by event type." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "confirmed", "cancelled", "completed", "no_show" ] }, "description": "Filter by exact status. Cannot be combined with view." }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "web", "call", "api", "manual" ] }, "description": "Filter by booking source." }, { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "upcoming", "unconfirmed", "recurring", "past", "cancelled" ] }, "description": "Dashboard-style booking view. Cannot be combined with status." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only bookings with start_at >= from." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only bookings with start_at <= to." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Bookings (paginated; `meta.pagination.total` carries the total count).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createBooking", "summary": "Create a booking", "description": "Book a free start time of an event type for an invitee. `start` must come from `GET /booking-event-types/{id}/slots`, unless `allow_outside_availability` is true (staff override: any future time within 2 years that does not overlap a confirmed booking of the same event type); otherwise a slot that is no longer free returns `409`. The invitee receives the confirmation email with a calendar invitation (when an email address is given), and the event type's webhook and automations fire. Stored `source` is `api`.\n\nThere is no idempotency key: retrying the same request for the same slot returns `409` via the database's overlap constraint.\n\nA `503` here can mean either request protection is temporarily unavailable (`internal_error`) or the availability engine itself failed to load (`service_unavailable`, message \"Could not load availability\").\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCreateInput" }, "example": { "event_type_id": "5c9f6e2a-4b1d-4b7a-9c1e-8f2a1b3c4d5e", "start": "2026-08-14T09:00:00Z", "name": "Anna Schmidt", "email": "anna@example.com" } } } }, "responses": { "201": { "description": "The created booking.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BookingCreated" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AvailabilityOrProtectionUnavailable" } } } }, "/bookings/lookup": { "post": { "operationId": "lookupBookings", "summary": "Look up upcoming bookings", "description": "Finds confirmed future bookings of the workspace by invitee identity — the same identity check assistants use before rescheduling or cancelling. Provide at least one of `phone`, `email`, `name`.\n\nA match is only returned when the identity is strong enough: a matching phone number alone is sufficient (`match_basis: \"phone\"`), while `email` and `name` must BOTH match (`match_basis: \"email+name\"`). Phone numbers are compared E.164-tolerantly (leading `00` is treated as `+`, suffix match on the last 8+ digits), email case-insensitively and exactly, names leniently by word tokens.\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "required": [ "phone" ] }, { "required": [ "email" ] }, { "required": [ "name" ] } ], "properties": { "phone": { "type": "string", "description": "Invitee phone number in any common notation." }, "email": { "type": "string", "description": "Invitee email address. Only yields matches together with `name`." }, "name": { "type": "string", "description": "Invitee name. Only yields matches together with `email`." }, "limit": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50, "description": "Maximum number of matches to return." } } }, "example": { "phone": "+4930123456789", "limit": 5 } } } }, "responses": { "200": { "description": "Matching upcoming bookings, earliest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "matches", "total" ], "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/BookingLookupMatch" } }, "total": { "type": "integer", "description": "Number of returned matches." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/bookings/{id}": { "get": { "operationId": "getBooking", "summary": "Get a booking", "description": "Read a single booking.\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Booking ID" } ], "responses": { "200": { "description": "The booking.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/bookings/{id}/cancel": { "post": { "operationId": "cancelBooking", "summary": "Cancel a booking", "description": "Cancel a confirmed booking. Sends a `METHOD:CANCEL` ICS email to the invitee and removes the pushed external calendar event (both best-effort). Idempotent for already-cancelled bookings; bookings that already started return `400`.\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Booking ID" } ], "responses": { "200": { "description": "The cancelled booking.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/bookings/{id}/reschedule": { "post": { "operationId": "rescheduleBooking", "summary": "Reschedule a booking", "description": "Moves a confirmed booking to a new start time. The new slot is validated against the event type's availability (the booking's own slot does not block itself), unless `allow_outside_availability` is true (staff override: any future time within 2 years that does not overlap a confirmed booking of the same event type); a lost race for the slot returns `409`. Sends an updated ICS invitation to the invitee and re-pushes the external calendar event (both best-effort).\n\n**Required scope:** `bookings:write` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Booking ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "New start time in ISO 8601 UTC. The duration stays the one of the event type." }, "allow_outside_availability": { "type": "boolean", "default": false, "description": "Set true to book outside the event type's open times (staff override). Any future time within the next 2 years is accepted; the time must not overlap another confirmed booking of the same event type. Guests on the public booking page only ever see open times." } } }, "example": { "start": "2026-08-14T09:30:00Z" } } } }, "responses": { "200": { "description": "The rescheduled booking.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/models": { "get": { "operationId": "listModels", "summary": "List models", "description": "Requires the active workspace Fallbacks & Guardrails entitlement in addition to assistants:read. Returns compatible model choices filtered by workspace inference region. Whitelabel access alone does not grant catalog access. Without type, results are grouped by category; with type, results are an array.", "tags": [ "Catalog" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "llm", "stt", "tts", "realtime" ] }, "description": "Model category to list." }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pipeline", "realtime", "half_cascade" ] }, "description": "Return only models usable in this engine mode. LLM and Realtime models match through their supported_modes; STT models match pipeline; TTS models match pipeline and half_cascade. Realtime mode lists no STT or TTS models." }, { "name": "realtime_variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "standard", "full_duplex" ], "default": "standard" }, "description": "Filter native speech model choices by Realtime conversation variant. Full Duplex also requires workspace Beta access and available defaults." } ], "responses": { "200": { "description": "Selectable models for an entitled workspace; the public catalog omits platform routing and billing details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } }, { "type": "object", "properties": { "llm": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } }, "stt": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } }, "tts": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } }, "realtime": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } } }, "required": [ "llm", "stt", "tts", "realtime" ] } ] } } }, "example": { "data": [ { "id": "00000000-0000-4000-8000-000000000001", "type": "llm", "provider": "catalog-provider", "model": "catalog-model", "label": "Available model", "supported_modes": [ "pipeline" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/languages": { "get": { "operationId": "listLanguages", "summary": "List languages", "description": "The platform's assistant language catalog (ISO 639-1 or ISO 639-3 codes with English labels), managed by the platform admin. Use the codes for `primary_language` and `secondary_languages` on an assistant. Only enabled languages are returned. **Required scope:** `assistants:read` (keys without scope restrictions have full access).", "tags": [ "Catalog" ], "responses": { "200": { "description": "All supported languages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageOption" } } } }, "example": { "data": [ { "code": "en", "label": "English" }, { "code": "de", "label": "German" }, { "code": "tr", "label": "Turkish" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/prompt-templates": { "get": { "operationId": "listPromptTemplates", "summary": "List prompt templates", "description": "System-prompt and conversational-flow templates visible to this workspace: platform templates (respecting global vs root visibility) plus workspace/reseller templates. Use an item's `id` as `template_id` when creating an assistant for server-side resolution. `blueprint` describes the use-case outcome, supported surfaces, setup requirements and presentation. `compatibility` summarizes the validated flow graph. `avatar_url` is only the catalog portrait; avatar-ready blueprint presentation means the assistant is designed for a separately configured virtual speaking avatar. **Required scope:** `assistants:read`.", "tags": [ "Catalog" ], "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-639-1 language filter (e.g. `de`)." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use-case theme. Built-in themes: receptionist, lead_qualifier, appointment, support, screener, survey, sales, personal_assistant, callback_intake, property_lead, service_intake, feedback_survey, guest_concierge, avatar_concierge, loop_recall. Templates can also carry custom themes, which filter the same way." }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Industry branch: general, healthcare, dental, real_estate, home_services, saas, hospitality, legal, automotive, ecommerce, education." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search name, description, and content." }, { "name": "has_flow", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When `true`, only templates with a Flow JSON graph. When `false`, only Single-prompt templates (`flow_json` null)." } ], "responses": { "200": { "description": "Visible prompt templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromptTemplate" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/leads/assign": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "post": { "operationId": "assignLeadsToCampaign", "summary": "Assign leads to a campaign", "description": "Assign leads to a campaign from a saved segment (`segment_id`) OR explicit `lead_ids`; provide exactly one. Unassigned contacts are moved into this campaign. Contacts already in this campaign or currently queued/calling are skipped. A contact assigned to another campaign returns a conflict before any assignments; remove it from that campaign first. Contacts are never duplicated. The compatibility field `copied` is always 0.\n\n**Required scope:** `leads:write` (`campaigns:write` and legacy `calls:write` are also accepted; unrestricted keys have full access).", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignLeadsInput" }, "examples": { "from_segment": { "summary": "From a segment", "value": { "segment_id": "se1b2c3d-0000-4000-8000-000000000050" } }, "explicit_leads": { "summary": "Explicit lead IDs", "value": { "lead_ids": [ "le1b2c3d-0000-4000-8000-000000000040" ] } } } } } }, "responses": { "200": { "description": "Assignment result counts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssignLeadsResult" } } }, "example": { "data": { "assigned": 12, "copied": 0, "skipped": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/campaigns/{id}/stats": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Campaign ID." } ], "get": { "operationId": "getCampaignStats", "summary": "Get campaign stats", "description": "Progress and performance aggregates for a campaign: total and completed leads, calls made, total call duration, and delivery attempts by outcome. **Required scope:** `campaigns:read` (the legacy `calls:read` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Campaigns" ], "responses": { "200": { "description": "The campaign's stats.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CampaignStats" } } }, "example": { "data": { "campaign_id": "ca1b2c3d-0000-4000-8000-000000000030", "total_leads": 100, "completed_leads": 37, "calls_made": 42, "total_duration_sec": 8460, "delivery_attempts": 45, "delivery_successful": 38, "delivery_failed": 4, "delivery_scheduled": 3, "currency": "EUR", "display_currency": "USD", "display_currency_rate": 1.08 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/leads": { "get": { "operationId": "listAudienceContacts", "summary": "List Audience contacts", "description": "List contacts across all campaigns with channel and tenant-scoped Call QA filters. Channel matches use linked calls, SMS, email, messaging conversations and contact channel profiles. Repeating `channel` matches any selected channel. QA uses the per-call History scorecard, counts every call once and excludes unscored calls. QA filters require the AI QA Scorecards feature. **Required scope:** `leads:read` (legacy `calls:read` is also accepted).", "tags": [ "Leads" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search contact name, phone or email." }, { "name": "display_status", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created", "processing", "rescheduled", "max_retries", "completed", "dnc" ] } } }, { "name": "campaign_id", "in": "query", "schema": { "type": "string" }, "description": "Campaign UUID or `none` for contacts without a campaign." }, { "name": "dnc", "in": "query", "schema": { "type": "boolean" }, "description": "When true, only contacts on the Do-Not-Call list are returned. When false, contacts on that list are excluded." }, { "name": "channel", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "call", "sms", "email", "whatsapp", "telegram", "messenger", "slack", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] } }, "description": "Contacts with activity or a profile on any selected channel. Repeat the query parameter for multiple channels." }, { "name": "source", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Contact source tag. Repeat for multiple values; values are ORed." }, { "name": "tag", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Contact tag. Repeat for multiple values; values are ORed." }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound for the contact creation timestamp." }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive upper bound for the contact creation timestamp." }, { "name": "attempts_min", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum outbound call attempts." }, { "name": "attempts_max", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Maximum outbound call attempts." }, { "name": "amd_result", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "human", "uncertain", "machine-vm", "machine-ivr", "machine-unavailable", "none" ] } }, "description": "Last AMD result. Repeat for multiple values; `none` matches contacts without a result." }, { "name": "qa_window", "in": "query", "schema": { "oneOf": [ { "type": "integer", "enum": [ 7, 30, 90 ] }, { "type": "string", "enum": [ "all" ] } ], "default": 90 } }, { "name": "qa_average_min", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "qa_average_max", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "qa_min_scored_calls", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of Audience contacts with Call QA metrics when entitled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAudienceContact", "summary": "Create an Audience contact", "description": "Create an unassigned Audience contact, or merge user-defined tags and missing identity fields into an existing contact with the same phone or email. **Required scope:** `leads:write` (legacy `calls:write` is also accepted).", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceContactInput" }, "example": { "phone": "+491701234567", "name": "Ada Lovelace", "email": "ada@example.com", "tags": [ "vip", "renewal" ] } } } }, "responses": { "200": { "description": "The request matched and enriched an existing contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "created" ], "properties": { "id": { "type": "string", "format": "uuid" }, "created": { "type": "boolean", "enum": [ false ] } } } } } } } }, "201": { "description": "The contact was created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "created" ], "properties": { "id": { "type": "string", "format": "uuid" }, "created": { "type": "boolean", "enum": [ true ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/leads/{id}/channels": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Audience contact ID." } ], "get": { "operationId": "listAudienceContactChannels", "summary": "List contact channels", "description": "List the manually manageable channel profiles linked to one Audience contact. Microsoft Teams profiles expose the visible connection name without internal account or routing identifiers. **Required scope:** `leads:read` (legacy `calls:read` is also accepted).", "tags": [ "Leads" ], "responses": { "200": { "description": "Contact channel profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceContactChannel" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "replaceAudienceContactChannels", "summary": "Replace contact channels", "description": "Replace the contact's manually managed channel profiles. For Microsoft Teams, provide the visible `connection_name`; it may be omitted only when exactly one Teams identity connection is active. Active Teams connection names are unique within a workspace, and reconnected copies of the same Microsoft identity are normalized to one current connection name. A user identity already linked to another contact returns a conflict and never merges records. **Required scope:** `leads:write` (legacy `calls:write` is also accepted).", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channels" ], "properties": { "channels": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/AudienceContactChannelInput" } } } }, "example": { "channels": [ { "platform": "teams", "external_user_id": "29:customer-routing-id", "display_name": "Ada Lovelace", "connection_name": "Customer Support" } ] } } } }, "responses": { "200": { "description": "Updated contact channel profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceContactChannel" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/leads/{id}/merge": { "post": { "operationId": "mergeAudienceContacts", "summary": "Merge Audience contacts", "description": "Explicitly merge one Audience contact into another. The target contact keeps its id; phone, email, channel identities, calls, and conversations move over. The source contact is removed. This never happens automatically — PATCH/POST on a colliding identity still returns 409. **Required scope:** `leads:write` (legacy `calls:write` is also accepted).", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Contact to keep." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_contact_id" ], "properties": { "from_contact_id": { "type": "string", "format": "uuid", "description": "Contact to merge and remove." } } } } } }, "responses": { "200": { "description": "The contacts were merged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "merged_from_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "merged_from_id": { "type": "string", "format": "uuid" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/segments": { "get": { "operationId": "listSegments", "summary": "List segments", "description": "List all segments (saved, dynamic lead filters) of the workspace. **Required scope:** `segments:read` (the legacy `calls:read` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of the workspace's segments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "meta": { "type": "object", "description": "Response metadata. `pagination.total` is the total number of matching items (ignoring limit/offset).", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 1 } } } } } } }, "example": { "data": [ { "id": "se1b2c3d-0000-4000-8000-000000000050", "name": "Not yet reached", "description": "Leads that were never called", "filters": { "display_status": [ "created" ] }, "created_by": "u1b2c3d4-0000-4000-8000-000000000001", "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } ], "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createSegment", "summary": "Create a segment", "description": "Save a lead filter as a reusable segment. Its matches are resolved live (dynamic, not a snapshot) — see `GET /segments/{id}/leads` and `POST /campaigns/{id}/leads/assign`. **Required scope:** `segments:write` (the legacy `calls:write` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SegmentInput" } ], "required": [ "name" ] }, "example": { "name": "Not yet reached", "description": "Leads that were never called", "filters": { "display_status": [ "created" ] } } } } }, "responses": { "201": { "description": "The created segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } }, "example": { "data": { "id": "se1b2c3d-0000-4000-8000-000000000050", "name": "Not yet reached", "description": "Leads that were never called", "filters": { "display_status": [ "created" ] }, "created_by": "u1b2c3d4-0000-4000-8000-000000000001", "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/segments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment ID." } ], "get": { "operationId": "getSegment", "summary": "Get a segment", "description": "Read a single segment. **Required scope:** `segments:read` (the legacy `calls:read` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "responses": { "200": { "description": "The segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } }, "example": { "data": { "id": "se1b2c3d-0000-4000-8000-000000000050", "name": "Not yet reached", "description": "Leads that were never called", "filters": { "display_status": [ "created" ] }, "created_by": "u1b2c3d4-0000-4000-8000-000000000001", "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-07-01T08:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateSegment", "summary": "Update a segment", "description": "Partial update — only the provided fields change. **Required scope:** `segments:write` (the legacy `calls:write` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentInput" }, "example": { "name": "Not yet reached (this week)" } } } }, "responses": { "200": { "description": "The updated segment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteSegment", "summary": "Delete a segment", "description": "Delete a segment. The leads it currently matches are not affected. **Required scope:** `segments:write` (the legacy `calls:write` scope is also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } }, "example": { "data": { "id": "se1b2c3d-0000-4000-8000-000000000050", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/segments/{id}/leads": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Segment ID." } ], "get": { "operationId": "listSegmentLeads", "summary": "List a segment's leads", "description": "Leads currently matching the segment's saved filters, newest first, paginated. Every lead includes the derived `display_status`. Resolution is capped at 5000 matching leads — `meta.pagination.total` reflects that cap, not an unbounded count.\n\n**Required scope:** `segments:read` (`leads:read` and the legacy `calls:read` scope are also accepted; keys without scope restrictions have full access).", "tags": [ "Segments" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of matching leads.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 1 } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/automations": { "get": { "operationId": "listAutomations", "summary": "List automations", "description": "Returns native workspace automations plus platform entitlement/run allowance. **Required scope:** `automations:read` or the legacy `calls:read`. The workspace plan must include Automations.", "tags": [ "Automations" ], "responses": { "200": { "description": "Automations and platform config.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAutomation", "summary": "Create automation", "description": "Create a native automation graph. The `conversation.started` trigger covers messaging and web chat, including widget previews. Set `trigger.platform` to `web_widget` to select web chat; submitted form fields are in `data.preform.values` and assistant input variables in `data.input_variables`. Optional `tags` (`string[]`). Binding `trigger.assistant_id` on an active `call.completed` automation updates the assistant webhook delivery mode. Graph actions may include `app.execute` (run an action in an app connected under Apps); triggers may use `app.event` (an event from a connected app). Reads always return these ids. **Required scope:** `automations:write` or `calls:write`.", "tags": [ "Automations" ], "responses": { "201": { "description": "Created automation." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/automations/{id}": { "get": { "operationId": "getAutomation", "summary": "Get automation", "description": "Get one automation and recent runs.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation and runs." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateAutomation", "summary": "Update automation", "description": "Update name, status, trigger, graph, or tags (`string[]`). **Required scope:** `automations:write` or `calls:write`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated automation." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteAutomation", "summary": "Delete automation", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "triggerAutomation", "summary": "Trigger automation", "description": "Manually start a run for the automation.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Started run id." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/automations/connections": { "get": { "operationId": "listAutomationConnections", "summary": "List automation connections", "description": "Workspace-scoped reusable credentials for CRM providers, SMTP relays, and official remote MCP endpoints used by automation nodes. Provider catalog entries with `supports_crm_sync=true` can power recurring CRM Sync (inbound, outbound, or bidirectional) when connected with `kind=api` (HubSpot, HighLevel, Salesforce, Pipedrive, Close, Zoho CRM, Attio, Keap, and Twenty). Apps connected through Browse apps appear with `provider=connected_app` and `config.toolkit`. Secrets are never returned; secret fields arrive as `\"•••\"`. **Required scope:** `automations:read` or `calls:read`.", "tags": [ "Automations" ], "responses": { "200": { "description": "Connections and provider catalog." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAutomationConnection", "summary": "Create automation connection", "description": "Store a reusable workspace credential. `kind` is `api` (provider REST API — e.g. Airtable PAT, HubSpot Private App token, SMTP host/user/password, Apps connected account) or `mcp` (remote MCP endpoint). App connections (`provider=connected_app`) are created in the app under **Automations → Connections → Add Connection → Browse apps** (OAuth sign-in with the app); their `config.toolkit` names the connected app (secrets never returned). `credentials` values are AES-256-GCM encrypted at rest. For `provider=smtp`, Test Connection verifies the relay and sends a test email to the calling admin. **Required scope:** `automations:write` or `calls:write`.", "tags": [ "Automations" ], "responses": { "201": { "description": "Created connection (secrets masked)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/automations/connections/{id}": { "get": { "operationId": "getAutomationConnection", "summary": "Get automation connection", "description": "Load one connection with secrets masked. **Required scope:** `automations:read` or `calls:read`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateAutomationConnection", "summary": "Update automation connection", "description": "Patch a connection. Sending `\"•••\"` for a secret keeps the stored value; omit a field to leave it unchanged. **Required scope:** `automations:write` or `calls:write`.", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated connection." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteAutomationConnection", "summary": "Delete automation connection", "tags": [ "Automations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/crm-syncs": { "get": { "operationId": "listCrmSyncs", "summary": "List CRM syncs", "description": "List recurring CRM syncs (inbound, outbound, or bidirectional). Requires workspace Beta Features, the automation platform entitlement, CRM sync plan capacity, and `automations:read` or `calls:read`.", "tags": [ "Automations" ], "responses": { "200": { "description": "CRM sync configurations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "syncs": { "type": "array", "items": { "$ref": "#/components/schemas/CrmSync" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCrmSync", "summary": "Create CRM sync", "description": "Create a recurring CRM sync using an existing API connection. Direction can import CRM records into Audience, push Audience contacts to the CRM, or both on the same schedule. Combined {{field}} expressions are import-only; outbound needs a 1:1 phone or email mapping. The provider is resolved from the tenant-scoped connection and cannot be supplied by the caller. Requires `automations:write` or `calls:write`.", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmSyncInput" } } } }, "responses": { "201": { "description": "Created CRM sync." }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/crm-syncs/discover": { "post": { "operationId": "discoverCrmSyncMetadata", "summary": "Discover CRM objects and fields", "description": "Discover importable objects for a connection. Include `object_type` to receive fields and list/view/filter sources. Set `include_preview` with a field mapping to receive up to five read-only mapped sample records after expression evaluation and phone/email normalization. Credentials are decrypted only inside the service and never returned. Requires `automations:read` or `calls:read`.", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connection_id" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "object_type": { "type": "string" }, "selection": { "type": "object", "additionalProperties": true, "description": "Provider-neutral source selection. `sourceId` limits the source; `default_phone_country` is an optional ISO-2 fallback for national phone numbers." }, "field_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^(name|phone|email|tags|custom\\.[a-z][a-z0-9_]{0,63}|channel\\.[a-z]+\\.(user_id|username))$" }, "description": "Source key or composed source expression to destination. Combined values use non-evaluated `{{field}}` tokens plus optional literal text, for example `{{salutation}} {{firstName}} {{lastName}}`. Destinations include channel identities such as `channel.telegram.username` or `channel.whatsapp.user_id`." }, "include_preview": { "type": "boolean", "default": false }, "preview_limit": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } } } } } }, "responses": { "200": { "description": "Objects, or fields and sources with optional mapped sample records." }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/crm-syncs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "CRM sync ID." } ], "get": { "operationId": "getCrmSync", "summary": "Get CRM sync", "tags": [ "Automations" ], "responses": { "200": { "description": "CRM sync.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmSync" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateCrmSync", "summary": "Update CRM sync", "description": "Patch source selection, field mapping, interval, direction, outbound create, policies, or active/paused status. Mapping and source changes reset the cursor but keep the existing schedule; use POST /crm-syncs/{id}/runs to sync immediately. Requires `automations:write` or `calls:write`.", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmSyncUpdate" } } } }, "responses": { "200": { "description": "Updated CRM sync." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteCrmSync", "summary": "Delete CRM sync", "description": "Delete the sync configuration and memberships. Imported Audience contacts are kept. Requires `automations:write` or `calls:write`.", "tags": [ "Automations" ], "responses": { "200": { "description": "Deletion confirmation." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/crm-syncs/{id}/runs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "CRM sync ID." } ], "get": { "operationId": "listCrmSyncRuns", "summary": "List CRM sync runs", "description": "List durable run history and counters. Requires `automations:read` or `calls:read`.", "tags": [ "Automations" ], "responses": { "200": { "description": "CRM sync runs." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "runCrmSync", "summary": "Run CRM sync", "description": "Queue a durable manual CRM sync run. Requires `automations:write` or `calls:write`.", "tags": [ "Automations" ], "responses": { "202": { "description": "Queued CRM sync run and workflow run id." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines": { "get": { "operationId": "listRoutines", "summary": "List missions", "description": "**Required scope:** `routines:read` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "The workspace's Milian Missions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Routine" } } } }, "example": { "data": [ { "id": "r1b2c3d4-0000-4000-8000-000000000040", "name": "Weekly call summary", "prompt": "Summarize last week's calls and email me the highlights.", "schedule_type": "weekly", "schedule_minute": null, "schedule_time": "09:00", "schedule_weekday": 1, "cron_expression": null, "timezone": "Europe/Berlin", "enabled": true, "next_run_at": "2026-08-24T07:00:00Z", "last_run_at": "2026-08-17T07:00:00Z", "last_run_status": "succeeded", "last_error": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-08-17T07:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createRoutine", "summary": "Create a mission", "description": "Creates a Milian Mission. The workspace's included and purchased mission capacity is enforced. **Required scope:** `routines:write` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutineCreate" }, "example": { "name": "Weekly call summary", "prompt": "Summarize last week's calls and email me the highlights.", "schedule_type": "weekly", "schedule_time": "09:00", "schedule_weekday": 1, "timezone": "Europe/Berlin" } } } }, "responses": { "201": { "description": "The created mission.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Routine" } } }, "example": { "data": { "id": "r1b2c3d4-0000-4000-8000-000000000040", "name": "Weekly call summary", "prompt": "Summarize last week's calls and email me the highlights.", "schedule_type": "weekly", "schedule_minute": null, "schedule_time": "09:00", "schedule_weekday": 1, "cron_expression": null, "timezone": "Europe/Berlin", "enabled": true, "next_run_at": "2026-08-24T07:00:00Z", "last_run_at": "2026-08-17T07:00:00Z", "last_run_status": "succeeded", "last_error": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-08-17T07:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "get": { "operationId": "getRoutine", "summary": "Get a mission", "description": "**Required scope:** `routines:read` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "The mission.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Routine" } } }, "example": { "data": { "id": "r1b2c3d4-0000-4000-8000-000000000040", "name": "Weekly call summary", "prompt": "Summarize last week's calls and email me the highlights.", "schedule_type": "weekly", "schedule_minute": null, "schedule_time": "09:00", "schedule_weekday": 1, "cron_expression": null, "timezone": "Europe/Berlin", "enabled": true, "next_run_at": "2026-08-24T07:00:00Z", "last_run_at": "2026-08-17T07:00:00Z", "last_run_status": "succeeded", "last_error": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-08-17T07:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateRoutine", "summary": "Update a mission", "description": "Updates name, prompt, schedule, timezone, or enabled state. Changing schedule fields or `enabled` recomputes `next_run_at`. **Required scope:** `routines:write` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutineUpdate" }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "The updated mission.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Routine" } } }, "example": { "data": { "id": "r1b2c3d4-0000-4000-8000-000000000040", "name": "Weekly call summary", "prompt": "Summarize last week's calls and email me the highlights.", "schedule_type": "weekly", "schedule_minute": null, "schedule_time": "09:00", "schedule_weekday": 1, "cron_expression": null, "timezone": "Europe/Berlin", "enabled": false, "next_run_at": null, "last_run_at": "2026-08-17T07:00:00Z", "last_run_status": "succeeded", "last_error": null, "created_at": "2026-07-01T08:00:00Z", "updated_at": "2026-08-17T07:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteRoutine", "summary": "Delete a mission", "description": "Permanently deletes a mission; it stops running immediately. Past runs already on record are unaffected. **Required scope:** `routines:write` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/run": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "post": { "operationId": "runRoutine", "summary": "Run a mission now", "description": "Starts a background run of this mission right now, independent of its schedule, billed like a normal copilot chat turn. Returns the created run immediately; the run itself keeps executing in the background — poll `GET /routines/{id}/runs` for its outcome. **Required scope:** `routines:write` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "The started run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RoutineRun" } } }, "example": { "data": { "id": "rr1b2c3d-0000-4000-8000-000000000041", "routine_id": "r1b2c3d4-0000-4000-8000-000000000040", "trigger": "manual", "status": "running", "thread_id": "routine-r1b2c3d4-0000-4000-8000-000000000040-a1b2c3d4", "error": null, "credits": 0, "started_at": "2026-08-17T07:00:00Z", "finished_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient workspace credits to start this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/runs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "get": { "operationId": "listRoutineRuns", "summary": "List mission runs", "description": "Lists this mission's recent runs, most recent first. Run transcripts (visible on the workspace Milian Missions page) are kept for 10 days. **Required scope:** `routines:read` (keys without scope restrictions have full access).", "tags": [ "Milian Missions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum number of runs to return (1-100)." } ], "responses": { "200": { "description": "A page of runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutineRun" } } } }, "example": { "data": [ { "id": "rr1b2c3d-0000-4000-8000-000000000041", "routine_id": "r1b2c3d4-0000-4000-8000-000000000040", "trigger": "manual", "status": "succeeded", "thread_id": "routine-r1b2c3d4-0000-4000-8000-000000000040-a1b2c3d4", "error": null, "credits": 12, "started_at": "2026-08-17T07:00:00Z", "finished_at": "2026-08-17T07:01:12Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/runs/{runId}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Finished Mission run ID." } ], "post": { "operationId": "retryRoutineRun", "summary": "Retry a mission run", "description": "Explicitly starts a new run linked to the finished source run. The source run and its immutable published version stay unchanged; no automatic retry is scheduled. **Required scope:** `routines:write`.", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "The newly created retry run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RoutineRun" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient workspace credits to start this retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/versions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "get": { "operationId": "listRoutineVersions", "summary": "List mission versions", "description": "Lists drafts and immutable published versions, newest first. **Required scope:** `routines:read`.", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "Mission versions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MissionVersion" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createRoutineVersionDraft", "summary": "Save a mission draft", "description": "Creates or replaces the editable draft while the active version keeps running. **Required scope:** `routines:write`.", "tags": [ "Milian Missions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "spec" ], "properties": { "spec": { "$ref": "#/components/schemas/MissionVersionSpec" } } } } } }, "responses": { "201": { "description": "Saved draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MissionVersion" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "post": { "operationId": "publishRoutineVersion", "summary": "Publish a mission version", "description": "Atomically activates a reviewed draft and its trigger. Only workspace owners and admins may publish. **Required scope:** `routines:write`.", "tags": [ "Milian Missions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version_id" ], "properties": { "version_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Published Mission and immutable version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "routine", "version" ], "properties": { "routine": { "$ref": "#/components/schemas/Routine" }, "version": { "$ref": "#/components/schemas/MissionVersion" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/webhook": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "get": { "operationId": "getRoutineWebhook", "summary": "Get mission webhook setup", "description": "Returns the public delivery URL, required header name, and configured state. The credential and internal Automation identity are never returned. **Required scope:** `routines:read`.", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "Secret-safe Mission webhook setup.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MissionWebhookSetup" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "setRoutineWebhookSecret", "summary": "Set or rotate mission webhook secret", "description": "Stores a client-generated 32-byte base64url secret. Only workspace owners and admins may set or rotate it. The secret is accepted only as input and is never returned. **Required scope:** `routines:write`.", "tags": [ "Milian Missions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "secret" ], "properties": { "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Client-generated 32-byte base64url secret without padding." } } } } } }, "responses": { "200": { "description": "Updated secret-safe Mission webhook setup.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MissionWebhookSetup" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/routines/{id}/pause": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mission ID." } ], "post": { "operationId": "pauseRoutine", "summary": "Pause a mission", "description": "Pauses the Mission and its trigger without deleting versions or runs. Only workspace owners and admins may pause. **Required scope:** `routines:write`.", "tags": [ "Milian Missions" ], "responses": { "200": { "description": "Paused Mission.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Routine" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards": { "get": { "operationId": "listDashboards", "summary": "List custom dashboards", "description": "Returns the workspace's custom dashboards in display order. **Required scope:** `dashboards:read` or the legacy `calls:read`. The workspace plan must include Custom dashboards.", "tags": [ "Dashboards" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of dashboards.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dashboard" } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createDashboard", "summary": "Create a custom dashboard", "description": "Creates a dashboard in the API key's workspace. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardInput" } } } }, "responses": { "201": { "description": "Created dashboard.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Dashboard ID." } ], "get": { "operationId": "getDashboard", "summary": "Get a custom dashboard", "description": "**Required scope:** `dashboards:read` or `calls:read`.", "tags": [ "Dashboards" ], "responses": { "200": { "description": "Dashboard.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateDashboard", "summary": "Update a custom dashboard", "description": "Rename or reorder a dashboard. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardInput" } } } }, "responses": { "200": { "description": "Updated dashboard.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteDashboard", "summary": "Delete a custom dashboard", "description": "Deletes the dashboard. Reusable widget records are retained. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "responses": { "200": { "description": "Deletion confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeleteResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards/{id}/analytics": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Dashboard ID." } ], "get": { "operationId": "getDashboardAnalytics", "summary": "Get dashboard analytics", "description": "Tenant-scoped call KPIs and deltas, zero-filled daily activity, breakdowns, assistant ranking, campaign progress, recent calls, and plan-gated module summaries. Date buckets follow the workspace timezone. **Required scope:** `dashboards:read` or `calls:read`.", "tags": [ "Dashboards" ], "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "7d", "14d", "30d", "90d" ], "default": "30d" } }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Inclusive ISO date or timestamp." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "A date is inclusive; a timestamp is an exclusive boundary." }, { "name": "assistant_ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated assistant IDs (max 50)." }, { "name": "campaign_ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated campaign IDs (max 50)." }, { "name": "directions", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated call directions." }, { "name": "statuses", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated call statuses." }, { "name": "sentiments", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated post-call sentiments." }, { "name": "success", "in": "query", "schema": { "type": "boolean" } }, { "name": "compare", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Compare with the immediately preceding equal-length period." } ], "responses": { "200": { "description": "Dashboard analytics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DashboardAnalytics" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards/{id}/natural-language": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Dashboard ID." } ], "post": { "operationId": "previewNaturalLanguageDashboard", "summary": "Preview a natural-language dashboard plan", "description": "Maps a plain-language request to the approved semantic analytics catalog. This preview never writes data and never accepts SQL, table names, or arbitrary fields. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 8, "maxLength": 1200, "example": "Show success rate and average duration for outbound calls in the last 30 days" } } } } } }, "responses": { "200": { "description": "Validated preview plan. No dashboard data has changed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NaturalLanguageDashboardPlan" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "saveNaturalLanguageDashboard", "summary": "Save a natural-language dashboard plan", "description": "Revalidates a previewed semantic plan and saves it as regular reusable dashboard widgets. Client-provided metric, filter, grouping, and visualization values are checked against the same server catalog again before any write. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/NaturalLanguageDashboardPlan" } } } } } }, "responses": { "201": { "description": "Canonical plan and saved widgets.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "plan", "widgets" ], "properties": { "plan": { "$ref": "#/components/schemas/NaturalLanguageDashboardPlan" }, "widgets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "metric", "title", "visualization", "group_by" ], "properties": { "id": { "type": "string", "format": "uuid" }, "metric": { "type": "string", "description": "Approved semantic metric ID." }, "title": { "type": "string" }, "visualization": { "type": "string", "enum": [ "number", "line", "area", "bar", "donut", "pie", "table" ] }, "group_by": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards/{id}/widgets": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Dashboard ID." } ], "get": { "operationId": "listDashboardWidgets", "summary": "List dashboard widgets", "description": "Returns widgets with conditions, visualization settings, display order, and 12-column grid layout. **Required scope:** `dashboards:read` or `calls:read`.", "tags": [ "Dashboards" ], "responses": { "200": { "description": "Dashboard widgets.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardWidget" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createDashboardWidget", "summary": "Create or attach a dashboard widget", "description": "Create and attach a widget, or provide `widget_id` to attach an existing reusable widget. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetInput" } } } }, "responses": { "201": { "description": "Created or attached widget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DashboardWidget" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/dashboards/{id}/widgets/{widgetId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Dashboard ID." }, { "name": "widgetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Widget ID." } ], "patch": { "operationId": "updateDashboardWidget", "summary": "Update a dashboard widget", "description": "Partial update of widget data, visualization, conditions, order, or grid layout. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetInput" } } } }, "responses": { "200": { "description": "Updated widget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DashboardWidget" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "removeDashboardWidget", "summary": "Detach a dashboard widget", "description": "Detaches the widget from this dashboard; the reusable widget record is retained. **Required scope:** `dashboards:write` or `calls:write`.", "tags": [ "Dashboards" ], "responses": { "200": { "description": "Detach confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "dashboard_id", "detached" ], "properties": { "id": { "type": "string", "format": "uuid" }, "dashboard_id": { "type": "string", "format": "uuid" }, "detached": { "type": "boolean", "const": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/tests": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listAssistantTests", "summary": "List simulation tests", "description": "List simulation tests for an assistant. **Required scope:** `assistants:read`. Requires the Simulations feature in the workspace plan.", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tests with optional latest_run.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTest" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createAssistantTest", "summary": "Create simulation test", "description": "Create a simulation test. **Required scope:** `assistants:write`. Requires the Simulations feature in the workspace plan.", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "persona": { "type": "string", "nullable": true }, "script": { "type": "string", "nullable": true }, "success_criteria": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "max_turns": { "type": "integer", "minimum": 1, "maximum": 20 }, "is_active": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created test.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SimulationTest" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/tests/from-call": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "createAssistantTestFromCall", "summary": "Create simulation test from call", "description": "Create a simulation test from an existing call transcript and analysis. **Required scope:** `assistants:write`. Requires the Simulations feature in the workspace plan.", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "call_id" ], "properties": { "call_id": { "type": "string", "format": "uuid", "description": "Call in the same workspace to turn into a regression test." } } } } } }, "responses": { "201": { "description": "Created test.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SimulationTest" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/tests/{testId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updateAssistantTest", "summary": "Update simulation test", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "description": "**Required scope:** `assistants:write`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated test.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SimulationTest" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteAssistantTest", "summary": "Delete simulation test", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "description": "**Required scope:** `assistants:write`.", "responses": { "204": { "description": "Deleted." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/tests/{testId}/run": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "runAssistantTest", "summary": "Run simulation test", "description": "Run a chat simulation synchronously (up to ~60s). Linked knowledge bases are searched through real function calls; successful and failed searches are included in tool_calls. Other tools remain simulated and perform no external actions. Voice mode starts a real call asynchronously. **Required scope:** `assistants:write`; voice mode additionally requires `calls:write`.", "tags": [ "Simulations" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Run result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/versions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listAssistantVersions", "summary": "List assistant versions", "description": "**Required scope:** `assistants:read`.", "tags": [ "Versions" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Version summaries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantVersion" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/versions/{versionId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getAssistantVersion", "summary": "Get assistant version", "description": "Includes full snapshot. **Required scope:** `assistants:read`.", "tags": [ "Versions" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Version detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "renameAssistantVersion", "summary": "Rename assistant version", "description": "Sets a customer-facing name for a saved version. Send an empty string to clear the custom name. **Required scope:** `assistants:write`.", "tags": [ "Versions" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "maxLength": 80, "description": "Custom version name. An empty string clears it." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Renamed version summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssistantVersion" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteAssistantVersion", "summary": "Delete assistant version", "description": "**Required scope:** `assistants:write`.", "tags": [ "Versions" ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Deleted." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/assistants/{id}/versions/{versionId}/restore": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "restoreAssistantVersion", "summary": "Restore assistant version", "description": "Restores snapshot; current config is auto-snapshotted first. A restore goes through the same validation as `PATCH /assistants/{id}`: it is rejected with `400 invalid_request` when the restored voice can't speak the restored languages (Pipeline and Half-cascade). **Required scope:** `assistants:write`.", "tags": [ "Versions" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Restored assistant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices/clone": { "get": { "operationId": "listVoiceClones", "summary": "List cloned voices", "description": "Lists ready cloned voices owned by the current workspace. Returned IDs are opaque platform IDs. **Required scope:** `voices:read` or `assistants:read`.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Workspace-owned cloned voices.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "clones" ], "properties": { "clones": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceClone" } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "submitVoiceCloneJob", "summary": "Submit voice clone job", "description": "Submits a prepared job after every sample upload finishes. Send either the preferred `id` returned by the upload-preparation endpoint or its transition alias `job_id`; if both are sent, they must match. Explicit rights confirmation is required. **Required scope:** `voices:write` or `assistants:write`. A user-bound credential is required. Read the current creation price from the capability response and accept it with expected_credits. Included creations are a one-time workspace allowance; additional successful creations consume credits. A higher price or exhausted free allowance returns 409 price_changed before processing. Failed creations are not charged. Retries of the same job cannot charge again.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "consent", "expected_credits" ], "anyOf": [ { "required": [ "id" ] }, { "required": [ "job_id" ] } ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Opaque job ID returned by POST /voices/clone/uploads (preferred)." }, "job_id": { "type": "string", "format": "uuid", "description": "Documented transition alias for `id`." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "language": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 3 }, "consent": { "type": "boolean", "const": true, "description": "Confirms that you have the right to clone this voice." }, "expected_credits": { "type": "number", "minimum": 0, "maximum": 999999999, "description": "Maximum accepted price, in credits. Use pricing.next_creation_credits from the capability response. Zero accepts only a free creation." } } } } } }, "responses": { "202": { "description": "Job accepted for durable processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/VoiceCloneJob" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" }, "402": { "description": "Not enough available workspace credits." }, "409": { "description": "The job cannot be submitted or the creation price increased. Refresh capability and accept the new price before retrying the same unsubmitted job." } } } }, "/voices/clone/capability": { "get": { "operationId": "getVoiceCloneCapability", "summary": "Check voice cloning capability", "description": "Returns access, current audio sample constraints, and the one-time workspace creation allowance and current credit price. Stored voices have no plan capacity limit. Read pricing.next_creation_credits before submitting a job. **Required scope:** voices:read or assistants:read.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current workspace capability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceCloneCapability" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices/clone/uploads": { "post": { "operationId": "createVoiceCloneUpload", "summary": "Prepare voice clone uploads", "description": "Creates an opaque job and short-lived upload destinations for one or more audio samples (at most 3; call GET /voices/clone/capability first and check `sample_constraints.max_files` for the number currently accepted — it can be lower). For each returned URL, send a PUT request with `multipart/form-data`: include `cacheControl=3600`, put the audio Blob in an unnamed file field, and set `x-upsert: false`. Then submit the job. **Required scope:** `voices:write` or `assistants:write`. A user-bound credential is required.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "required": [ "filename", "content_type", "size_bytes" ], "properties": { "filename": { "type": "string", "maxLength": 120 }, "content_type": { "type": "string", "description": "Supported audio MIME type." }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 10485760 } } } } } } } } }, "responses": { "201": { "description": "Job and short-lived upload destinations created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "uploads", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Opaque job ID used by the submit endpoint." }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceCloneUploadGrant" } }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices/clone/jobs/{jobId}": { "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getVoiceCloneJob", "summary": "Get voice clone job", "description": "Returns the workspace-scoped status of a create or delete job. **Required scope:** `voices:read` or `assistants:read`.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current job status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/VoiceCloneJob" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/voices/clone/{cloneId}": { "parameters": [ { "name": "cloneId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getVoiceClone", "summary": "Get cloned voice", "description": "Returns one ready cloned voice owned by the current workspace. **Required scope:** `voices:read` or `assistants:read`.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cloned voice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "clone" ], "properties": { "clone": { "$ref": "#/components/schemas/VoiceClone" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteVoiceClone", "summary": "Delete cloned voice", "description": "Requests durable deletion of a workspace-owned cloned voice. Remove the voice from assistants before deletion. **Required scope:** `voices:write` or `assistants:write`. A user-bound credential is required.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Voice already deleted or deletion completed without a queued job.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceCloneDeleteResult" } } } } } }, "202": { "description": "Deletion accepted for durable processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceCloneDeleteResult" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/caller-ids": { "get": { "operationId": "listCallerIds", "summary": "List caller IDs", "description": "**Required scope:** `phone_numbers:read` or `calls:read`.", "tags": [ "Caller IDs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Caller IDs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallerId" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createCallerId", "summary": "Start caller ID verification", "description": "**Required scope:** `phone_numbers:write` or `calls:write`.", "tags": [ "Caller IDs" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "string", "example": "+12025550123" }, "friendly_name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Pending caller ID + validation_code.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "description": "Too many caller ID verification starts. Wait and retry. Also returned when the shared REST request budget is exhausted; honor Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, as determined by the applicable limit.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Please wait 15 minutes before starting another caller ID verification." } } } } }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/caller-ids/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updateCallerId", "summary": "Update caller ID", "description": "**Required scope:** `phone_numbers:write` or `calls:write`. Updates the display label (`friendly_name`).", "tags": [ "Caller IDs" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "friendly_name": { "type": [ "string", "null" ], "description": "Display name shown under the number in the UI. Null or empty clears it." }, "label": { "type": [ "string", "null" ], "description": "Alias for `friendly_name`." } } } } } }, "responses": { "200": { "description": "Updated caller ID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteCallerId", "summary": "Delete caller ID", "description": "**Required scope:** `phone_numbers:write` or `calls:write`.", "tags": [ "Caller IDs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/widget-connectors": { "get": { "operationId": "listWidgetConnectors", "summary": "List web widgets", "description": "**Required scope:** `assistants:read`.", "tags": [ "Widgets" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "assistant_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Widgets.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetConnector" } }, "meta": { "type": "object", "properties": { "phone_verification": { "type": "object", "properties": { "available": { "type": "boolean" }, "sms_credits": { "type": "number", "nullable": true }, "email_available": { "type": "boolean", "description": "Whether platform email verification is available for this workspace." } }, "description": "Workspace eligibility and the current price to accept before enabling verification." } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createWidgetConnector", "summary": "Create web widget", "description": "**Required scope:** `assistants:write`. Requires the Web widget feature in the workspace plan. `allowed_origins` is optional (defaults to `[]`); an empty allowlist blocks third-party hosts until origins are added. New widgets default to `theme.logo_source=assistant` and follow the selected assistant's current profile picture, including future changes. An explicit `logo_url` defaults to the custom source; an explicit `logo_source` takes precedence. Existing widgets keep their saved source. Phone verification requires explicit acceptance of the current verification SMS credit price. Previously issued browser permissions expire after at most 7 days and are revoked when this widget configuration changes.", "tags": [ "Widgets" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assistant_id", "name" ], "properties": { "assistant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "allowed_origins": { "type": "array", "description": "Optional site origins that may embed the widget (e.g. https://example.com). Empty or omitted blocks third-party hosts.", "items": { "type": "string" } }, "voice_enabled": { "type": "boolean" }, "chat_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "theme": { "$ref": "#/components/schemas/WidgetTheme" }, "phone_verification_enabled": { "type": "boolean", "default": false, "description": "Require the selected email or SMS verification before chat or voice. Available in root workspaces, including a reseller’s own workspace; unavailable to reseller customer workspaces." }, "phone_verification_accepted_credits": { "type": "number", "nullable": true, "exclusiveMinimum": 0, "description": "Explicitly accept the current per-SMS price from the widget list response. Currently 80 credits per accepted send, including resends; code checks and valid remembered visits are free." }, "verification_method": { "type": "string", "enum": [ "sms", "email" ], "default": "sms", "description": "Verify visitors by SMS or email. Email uses the platform sender without additional credits." } } } } } }, "responses": { "201": { "description": "Created widget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WidgetConnector" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/widget-connectors/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getWidgetConnector", "summary": "Get web widget", "tags": [ "Widgets" ], "security": [ { "BearerAuth": [] } ], "description": "**Required scope:** `assistants:read`.", "responses": { "200": { "description": "Widget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WidgetConnector" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateWidgetConnector", "summary": "Update web widget", "tags": [ "Widgets" ], "security": [ { "BearerAuth": [] } ], "description": "**Required scope:** `assistants:write`. You can change `assistant_id` to point the widget at another assistant in the same workspace. Phone verification requires explicit acceptance of the current verification SMS credit price. Previously issued browser permissions expire after at most 7 days and are revoked when this widget configuration changes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "format": "uuid", "description": "Assistant that answers voice and chat from this widget." }, "name": { "type": "string" }, "allowed_origins": { "type": "array", "description": "Replaces the allowlist. Empty array blocks third-party hosts.", "items": { "type": "string" } }, "voice_enabled": { "type": "boolean" }, "chat_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "theme": { "$ref": "#/components/schemas/WidgetTheme" }, "phone_verification_enabled": { "type": "boolean", "default": false, "description": "Require the selected email or SMS verification before chat or voice. Available in root workspaces, including a reseller’s own workspace; unavailable to reseller customer workspaces." }, "phone_verification_accepted_credits": { "type": "number", "nullable": true, "exclusiveMinimum": 0, "description": "Explicitly accept the current per-SMS price from the widget list response. Currently 80 credits per accepted send, including resends; code checks and valid remembered visits are free." }, "verification_method": { "type": "string", "enum": [ "sms", "email" ], "default": "sms", "description": "Verify visitors by SMS or email. Email uses the platform sender without additional credits." } } } } } }, "responses": { "200": { "description": "Updated widget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WidgetConnector" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteWidgetConnector", "summary": "Delete web widget", "tags": [ "Widgets" ], "security": [ { "BearerAuth": [] } ], "description": "**Required scope:** `assistants:write`.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/widget-connectors/{id}/logo": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "uploadWidgetConnectorLogo", "summary": "Upload widget header logo", "description": "Upload a header logo from a URL or inline base64 — exactly one of `url` / `data_base64` is required. `url` is downloaded server-side (private/loopback/link-local/cloud-metadata hosts are blocked) and capped at 10 MB, same as `data_base64`; only PNG/JPEG are accepted (no SVG — stored-XSS risk over the storage origin). This endpoint only uploads the file; write the returned `url` into `theme.logo_url` via `PATCH /widget-connectors/{id}` to actually use it. **Required scope:** `assistants:write`.", "tags": [ "Widgets" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "data_base64": { "type": "string" }, "content_type": { "type": "string", "description": "Required alongside data_base64." } } } } } }, "responses": { "200": { "description": "Uploaded logo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteWidgetConnectorLogo", "summary": "Remove widget header logo", "description": "**Required scope:** `assistants:write`.", "tags": [ "Widgets" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messaging-connectors": { "get": { "operationId": "listMessagingConnectors", "summary": "List messaging connectors", "description": "List the workspace's messaging channel connections: chat apps, help desks and mailboxes. Each channel must be included in the workspace's plan; `meta.entitlements` shows which channels are available. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sms", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "description": "Only return connectors for this channel." } ], "responses": { "200": { "description": "Connectors plus per-platform entitlements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingConnector" } }, "meta": { "type": "object", "properties": { "entitlements": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createMessagingConnector", "summary": "Create messaging connector", "description": "Connect an existing SMS-capable workspace number or a chat app. SMS requires linked_phone_number_id, uses the number’s configured carrier, and leaves automatic replies off by default. Chat apps require their platform-specific credentials. Help desk, mailbox, Instagram and Zulip channels are connected in the dashboard. Conversation settings control reply delay, inactivity, repeated end events and the optional conversation-ended webhook.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagingConnectorCreate" } } } }, "responses": { "201": { "description": "Created connector (may include one-time webhook_secret for Telegram).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MessagingConnector" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messaging-connectors/{id}/watch-options": { "get": { "operationId": "listMessagingConnectorWatchOptions", "summary": "List mailbox watch options", "description": "List Gmail labels or Outlook/Zoho Mail folders the assistant can watch for this connected mailbox. Use a returned `id` and `name` with PATCH `/messaging-connectors/{id}` (`watch_scope` plus `watch_id` / `watch_name`). Returns `{ supported: false }` for other channels. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Watch options for the mailbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "supported": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messaging-connectors/{id}": { "patch": { "operationId": "updateMessagingConnector", "summary": "Update messaging connector", "description": "Patch name, assistant, credentials, or conversation settings. `whatsapp_coexistence` cannot be changed after the connector is created — reconnect instead (400 if included). On a Coexistence sender, voice flags (`whatsapp_voice_enabled`, `whatsapp_outbound_voice_enabled`) and marketplace-number linking are rejected (400) — Coexistence numbers have no Calling API and are never a marketplace/OTP number. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagingConnectorUpdate" } } } }, "responses": { "200": { "description": "Updated connector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MessagingConnector" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteMessagingConnector", "summary": "Delete messaging connector", "description": "**Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messaging-connectors/{id}/ended-webhook-test": { "post": { "operationId": "testMessagingConnectorEndedWebhook", "summary": "Send a test conversation.ended webhook", "description": "Sends an example `conversation.ended` payload (Voice-style envelope, with sample transcript/analysis) to the connector's configured webhook, or to `url` if given (test call only — the saved URL is not changed). **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Overrides the saved conversation_ended_webhook_url for this test call only." } } } } } }, "responses": { "200": { "description": "Delivery result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "raw": { "type": "string", "description": "First 2000 characters of the target's response body." }, "sent_payload": { "type": "object", "additionalProperties": true }, "error": { "type": "string" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/connectors/{id}/profile": { "get": { "operationId": "getWhatsAppSenderProfile", "summary": "Get WhatsApp sender profile", "description": "Load WhatsApp Business Profile draft + Meta status cache. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sender profile payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateWhatsAppSenderProfile", "summary": "Update WhatsApp sender profile", "description": "Patch local sender settings and business profile fields. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ai_enabled": { "type": "boolean", "description": "Automatically reply to incoming customer messages." }, "ignore_message_reactions": { "type": "boolean", "default": true, "description": "Ignore emoji reactions. When false, new reactions are processed as incoming messages." }, "keep_conversations_unread": { "type": "boolean", "description": "Keep customer messages unread and omit the typing indicator." }, "response_delay_sec": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Debounce after the latest customer message. Zero means no deliberate delay; AI generation and delivery take additional time." }, "inactivity_timeout_min": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Customer inactivity before ending a conversation." }, "allow_retrigger": { "type": "boolean", "description": "Send the configured conversation-ended webhook again after a customer resumes the same chat and becomes inactive." }, "conversation_ended_webhook_url": { "type": "string", "nullable": true, "description": "HTTPS destination for the transcript and extracted variables. Null disables this webhook." } } } } } }, "responses": { "200": { "description": "Updated profile." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "whatsAppSenderProfileAction", "summary": "Run a WhatsApp sender profile action", "description": "Actions: `sync` (push the business profile for Cloud senders; local `logo_url` is uploaded when `profile_picture_handle` is omitted), `refresh` (pull the business profile), `test_read_receipts_webhook`, or `rotate_read_receipts_webhook_secret`. Rotation invalidates the previous secret immediately and returns the new `signing_secret` exactly once. Existing secrets cannot be retrieved. Banner stays local-only. Coexistence senders must edit their public profile in the WhatsApp Business app; `sync` returns HTTP 400, while `refresh` and local draft updates remain available. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "sync", "refresh", "test_read_receipts_webhook", "rotate_read_receipts_webhook_secret" ] }, "profile_picture_handle": { "type": "string", "description": "Optional Meta resumable upload handle. When omitted on sync, the connector logo_url is uploaded automatically." } } } } } }, "responses": { "200": { "description": "Action result. Secret rotation returns `data.signing_secret` exactly once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "action": { "type": "string" }, "signing_secret": { "type": "string", "description": "New read-receipts signing secret. Present only for explicit rotation and returned exactly once." } }, "additionalProperties": true } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/calling": { "get": { "operationId": "getWhatsAppCallingReadiness", "summary": "WhatsApp calling readiness", "description": "Voice-calling readiness for a WhatsApp connector's business phone number (Meta call settings, webhook subscription, quality rating). **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "connector_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Readiness report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "runWhatsAppCallingAction", "summary": "Enable / resubscribe WhatsApp calling", "description": "Actions: `enable_calling` (enable inbound calling in Meta call settings), `resubscribe` (re-subscribe the WABA webhook with this connector's callback URL), `ensure_voice` (best-effort resubscribe + enable, used when Voice is turned on). **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connector_id", "action" ], "properties": { "connector_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "enable_calling", "resubscribe", "ensure_voice" ] } } } } } }, "responses": { "200": { "description": "Action result + updated readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/connectors/{id}/assets": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "uploadWhatsAppConnectorAsset", "summary": "Upload WhatsApp sender logo / banner", "description": "Upload a business profile logo or banner from a URL or inline base64 — exactly one of `url` / `data_base64` is required. `url` is downloaded server-side (private/loopback/link-local/cloud-metadata hosts are blocked) and capped at 8 MB, same as `data_base64`; only PNG/JPEG/WebP are accepted. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "logo", "banner" ] }, "url": { "type": "string", "format": "uri" }, "data_base64": { "type": "string" }, "content_type": { "type": "string", "description": "Required alongside data_base64." } } } } } }, "responses": { "200": { "description": "Uploaded asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" }, "kind": { "type": "string" }, "profile": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteWhatsAppConnectorAsset", "summary": "Remove WhatsApp sender logo / banner", "description": "**Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "logo", "banner" ] } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "kind": { "type": "string" }, "profile": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/embedded-signup": { "get": { "operationId": "getWhatsAppEmbeddedSignupConfig", "summary": "WhatsApp Embedded Signup public config", "description": "Returns whether Meta Embedded Signup is enabled and public app/config IDs. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Config payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "app_id": { "type": "string", "nullable": true }, "config_id": { "type": "string", "nullable": true }, "graph_version": { "type": "string" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "completeWhatsAppEmbeddedSignup", "summary": "Complete WhatsApp Embedded Signup", "description": "Exchange the Meta popup code, subscribe WABA, register the phone (Cloud path) or skip registration and request Business-app sync (Coexistence), then create a connector. **Required scope:** `assistants:write`. Code TTL ~30s. `phone_number_id` may be omitted on Coexistence — the server discovers it from the WABA.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "waba_id", "assistant_id" ], "properties": { "code": { "type": "string" }, "waba_id": { "type": "string" }, "phone_number_id": { "type": "string" }, "assistant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "display_phone_number": { "type": "string" }, "phone_number_row_id": { "type": "string", "format": "uuid" }, "whatsapp_text_enabled": { "type": "boolean" }, "whatsapp_voice_enabled": { "type": "boolean" }, "whatsapp_outbound_voice_enabled": { "type": "boolean" }, "whatsapp_coexistence": { "type": "boolean", "description": "True to complete Embedded Signup with Coexistence (WhatsApp Business app stays on the number). Skips phone registration and requests contact plus history sync." } } } } } }, "responses": { "201": { "description": "Created WhatsApp messaging connector." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messenger/facebook-login": { "get": { "operationId": "getMessengerFacebookLoginConfig", "summary": "Messenger Facebook Login public config", "description": "Returns whether Connect with Facebook for Messenger is enabled and the public Meta app ID. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Config payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "app_id": { "type": "string", "nullable": true }, "graph_version": { "type": "string" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "completeMessengerFacebookLogin", "summary": "Complete Messenger Facebook Login", "description": "Subscribe a Facebook Page to the platform Meta app and create a Messenger connector. **Required scope:** `assistants:write`. Provide `page_access_token` or `access_token` + `page_id`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assistant_id", "page_id" ], "properties": { "assistant_id": { "type": "string", "format": "uuid" }, "page_id": { "type": "string" }, "page_access_token": { "type": "string" }, "access_token": { "type": "string" }, "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created Messenger messaging connector." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/messenger/facebook-login/pages": { "post": { "operationId": "listMessengerFacebookPages", "summary": "List Facebook Pages for a user access token", "description": "Server-side Graph API call: lists the Facebook Pages managed by the given user access token, so you can complete Messenger Connect entirely via the API (config → Facebook Login on your own frontend → this endpoint → complete connector). **Required scope:** `assistants:write`. The token is never logged or returned. Complete the connector with the original `access_token` plus the selected `page_id`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token" ], "properties": { "access_token": { "type": "string", "description": "Facebook USER access token obtained via Facebook Login." } } } } } }, "responses": { "200": { "description": "Pages managed by this user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/slack/oauth": { "get": { "operationId": "getSlackOauthConfig", "summary": "Slack Add to Slack public config", "description": "Returns whether Add to Slack is enabled and the public Slack client ID for the platform Famulor app. **Required scope:** `assistants:read`. Platform-root workspaces only (not whitelabel).", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Config payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "client_id": { "type": "string", "nullable": true } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "startSlackOauth", "summary": "Start Slack OAuth (Add to Slack)", "description": "Returns a Slack authorize URL. Open it in a browser to install the platform Famulor Slack app; the OAuth callback creates/updates a Slack messaging connector with `team_id`. **Required scope:** `assistants:write`. Platform-root workspaces only.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assistant_id" ], "properties": { "assistant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Optional connector display name" } } } } } }, "responses": { "200": { "description": "Authorize URL for the Slack consent screen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/templates": { "get": { "operationId": "listWhatsAppTemplates", "summary": "List WhatsApp message templates", "description": "List HSM templates for the workspace. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "connector_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "query", "required": false, "description": "Set to `library` to list official pre-written utility templates.", "schema": { "type": "string", "enum": [ "library" ] } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en_US" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "after", "in": "query", "required": false, "description": "Opaque pagination cursor returned by a previous template-library response.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Exact official library-template name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "whatsAppTemplatesAction", "summary": "Create / update / submit / sync / send / delete WhatsApp templates", "description": "Body.action: `create` | `update` | `submit` | `sync` | `send` | `set_opt_out_buttons` | `delete`. Sync follows all provider pages and imports templates that do not yet exist locally. Draft updates remain local. On editable provider templates, only component or category changes are sent to Meta; parameter mappings and opt-out configuration remain local. Submit returns the provider-controlled review status. Send supports text headers/body plus static quick-reply, URL, phone and call-permission components; templates requiring runtime media, location, dynamic-URL or copy-code values are rejected locally. **Required scope:** `assistants:write`. Requires WhatsApp text in the workspace plan.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update", "submit", "sync", "send", "set_opt_out_buttons", "delete" ], "default": "create" }, "connector_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "template_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "body_text": { "type": "string", "description": "Template body. Variables must use positive contiguous numbering: {{1}}, {{2}}, {{3}}." }, "library_template_name": { "type": "string", "description": "Official library preset name. When supplied with action=create, the preset is created directly for the sender." }, "library_button_values": { "type": "object", "description": "Button index to HTTPS URL or E.164 phone number. Required for official library templates with URL or phone-number buttons.", "additionalProperties": { "type": "string" } }, "language": { "type": "string" }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ] }, "parameter_bindings": { "type": "object", "description": "Maps component positions (`1`, `2`, `header.1`) to system, lead, assistant, or custom variable keys.", "additionalProperties": { "type": "string" } }, "opt_out_buttons": { "type": "array", "description": "Canonical QUICK_REPLY labels whose tap suppresses the contact. With action=set_opt_out_buttons this is always a local-only update.", "items": { "type": "string" } }, "components": { "type": "array", "description": "Ordered template components. The core composer supports HEADER (TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION), BODY, FOOTER, and BUTTONS (QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE). Media headers require example.header_handle from the provider review upload flow. Updates replace the complete component array. Call-permission templates use a BODY plus a CALL_PERMISSION_REQUEST component.", "items": { "type": "object", "additionalProperties": true } }, "to_number": { "type": "string" }, "context": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Action result." }, "201": { "description": "Created draft template." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/whatsapp/templates/media": { "post": { "operationId": "uploadWhatsAppTemplateReviewSample", "summary": "Upload a WhatsApp template review sample", "description": "Upload the review sample required by an IMAGE, VIDEO, or DOCUMENT template header. Send base64-encoded JPEG/PNG, MP4, or PDF data up to 3 MB. The returned handle belongs in HEADER.example.header_handle. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connector_id", "format", "file_name", "content_type", "data_base64" ], "properties": { "connector_id": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": [ "IMAGE", "VIDEO", "DOCUMENT" ] }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "video/mp4", "application/pdf" ] }, "data_base64": { "type": "string", "format": "byte" } } } } } }, "responses": { "201": { "description": "Review sample uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "handle": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/calls/whatsapp-outbound": { "post": { "operationId": "startWhatsAppOutboundCall", "summary": "Start outbound WhatsApp voice call", "description": "Place a WhatsApp voice call via the platform WhatsApp voice connector. **Required scope:** `calls:write`. Requires WhatsApp voice in the workspace plan.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "connector_id", "to_number" ], "properties": { "connector_id": { "type": "string", "format": "uuid" }, "to_number": { "type": "string", "description": "E.164 WhatsApp user" }, "assistant_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Call row created and dial started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Call" } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/qa/runs": { "get": { "operationId": "listQaRuns", "summary": "List QA runs", "description": "List cohort AI Quality Assurance runs. **Required scope:** `calls:read`.", "tags": [ "QA" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createQaRun", "summary": "Create QA run", "description": "Start a cohort QA analysis for a pack and date range. Consumes credits. **Required scope:** `calls:write`.", "tags": [ "QA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pack", "from_at", "to_at" ], "properties": { "pack": { "type": "string", "enum": [ "full", "language_hallucinations", "resolution_sentiment", "performance_trends" ] }, "name": { "type": "string", "maxLength": 120, "description": "Optional cohort display name" }, "from_at": { "type": "string", "format": "date-time" }, "to_at": { "type": "string", "format": "date-time" }, "assistant_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "filters": { "type": "object", "properties": { "min_duration_sec": { "type": "integer", "minimum": 0 }, "max_duration_sec": { "type": "integer", "minimum": 0 }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "inbound", "outbound", "web" ] } }, "statuses": { "type": "array", "items": { "type": "string" } }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "positive", "neutral", "negative" ] } }, "success": { "type": "boolean" }, "campaign_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "has_recording": { "type": "boolean" } } }, "resolution_criteria": { "type": "string", "maxLength": 4000, "description": "What counts as a successful resolution for this cohort" } } } } } }, "responses": { "201": { "description": "Created" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Plan gate" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/qa/runs/{id}": { "get": { "operationId": "getQaRun", "summary": "Get QA run", "description": "Fetch a QA run and optional results. A result that could not be scored has an `error` code: `empty_transcript`, `invalid_json`, `call_not_found`, `process_failed` or `judge_failed`; a failed run has `run_failed`. **Required scope:** `calls:read`.", "tags": [ "QA" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_results", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users": { "get": { "operationId": "listPlatformUsers", "summary": "List platform users", "description": "List the customers you can manage through the White-Label Platform API — your reseller workspace's customers, or (for platform admins) direct platform customers. `q` searches name and email (case-insensitive substring). Sorted by `created_at` descending. **Required scope:** `platform:read`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring search across name and email." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of platform users.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformUser" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 0 } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "registerPlatformUser", "summary": "Register a platform user", "description": "Creates a new customer account and workspace on your behalf — a real user plus a fresh workspace scoped under your reseller (or, for platform admins, a new platform root workspace). Returns `409` if the email is already registered anywhere on the platform; the message never reveals whether that account happens to be inside or outside your own scope (anti-enumeration). **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserRegisterInput" }, "example": { "name": "Jane Doe", "email": "jane@customer.example", "mode": "invite" } } } }, "responses": { "201": { "description": "The new customer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformUserRegisterResult" } } }, "example": { "data": { "user_id": "u1b2c3d4-0000-4000-8000-000000000010", "workspace_id": "w1b2c3d4-0000-4000-8000-000000000011", "email": "jane@customer.example", "welcome_credit": { "status": "granted", "requested_credits": 800, "granted_credits": 800 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "409": { "description": "An account with this email already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "An account with this email already exists." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users/{user_id}": { "get": { "operationId": "getPlatformUser", "summary": "Get a platform user", "description": "Detail, in-scope workspaces, and balances for a single customer. **Required scope:** `platform:read`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Pick a specific workspace when the customer has several in your scope; defaults to the one they own." } ], "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformUserDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No customer with that ID exists in your scope (a different reseller's customer, or an unknown ID, look identical from the outside).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Customer not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users/{user_id}/token": { "post": { "operationId": "createPlatformUserToken", "summary": "Create a platform user token", "description": "Mints a `fam_...` API key for this customer without needing their password — useful for a dashboard, an onboarding email, or an automated workflow acting on their behalf. The key is returned in full exactly once; store it immediately, it cannot be retrieved again. `scopes` defaults to full access for the target customer (this key belongs to a different principal than your own credential, so it is not limited to your own credential's scopes). The key follows the platform's live-membership rule: if the customer ever leaves this workspace, the key stops working automatically. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserTokenInput" }, "example": { "name": "Customer dashboard token", "expires_in_days": 90 } } } }, "responses": { "201": { "description": "The minted token (shown once).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformUserToken" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No customer with that ID exists in your scope (a different reseller's customer, or an unknown ID, look identical from the outside).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Customer not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users/login": { "post": { "operationId": "loginPlatformUser", "summary": "Log in a platform user", "description": "Authenticates a customer with their email and password and, on success, mints them an access token exactly like `POST /platform/users/{user_id}/token` — use this to build your own login form or custom auth flow on your white-label platform, instead of sending customers to the hosted login page. REST-only: this is the one White-Label Platform API operation with no MCP equivalent, since credentials should never travel through an MCP tool call. Rate-limited per IP + email. Every failure — unknown email, wrong password, or an email outside your scope — returns the exact same generic `401` message, so a caller can never use the response to guess which accounts exist. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserLoginInput" }, "example": { "email": "jane@customer.example", "password": "correct horse battery staple" } } } }, "responses": { "201": { "description": "The minted token (shown once).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformUserToken" } } } } } }, "400": { "description": "Missing email or password.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "email and password are required." } } } } }, "401": { "description": "Invalid credentials, or the email does not belong to a customer in your scope. Always the same message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthorized", "message": "Invalid email or password." } } } } }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "429": { "description": "Too many login attempts for this email from this IP. Wait and retry. Also returned when the shared REST request budget is exhausted; honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Too many login attempts. Try again later." } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying, as determined by the applicable limit.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users/{user_id}/logout": { "post": { "operationId": "logoutPlatformUser", "summary": "Log out a platform user", "description": "Revokes every active API key and OAuth token this customer holds across the workspace(s) in your scope — use it to force a sign-out, for example after an account is compromised or your relationship with this customer ends. Idempotent: calling it again on an already-logged-out customer just returns zero counts. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revocation counts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformUserLogoutResult" } } }, "example": { "data": { "revoked_api_keys": 2, "revoked_oauth_tokens": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No customer with that ID exists in your scope (a different reseller's customer, or an unknown ID, look identical from the outside).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Customer not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/users/{user_id}/balance": { "post": { "operationId": "transferPlatformUserBalance", "summary": "Transfer credits to or from a platform user", "description": "Transfers signed credits between your own workspace wallet and this customer's workspace wallet. A **positive** `credits` value grants credits from your wallet to the customer; a **negative** value reclaims credits back from the customer into yours. Either direction requires the source wallet to cover the amount — a wallet balance never goes below zero, and an insufficient-balance attempt fails with `400 invalid_request` rather than partially applying. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformBalanceTransferInput" }, "example": { "credits": 50, "note": "Onboarding credit" } } } }, "responses": { "200": { "description": "New balances after the transfer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformBalanceTransferResult" } } } } } }, "400": { "description": "credits is zero/invalid, or the source wallet does not have enough balance to cover a reclaim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "credits must be a non-zero number." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No customer with that ID exists in your scope (a different reseller's customer, or an unknown ID, look identical from the outside).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Customer not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/default-limits": { "get": { "operationId": "getPlatformDefaultLimits", "summary": "Get platform registration and prepaid defaults", "description": "Returns the independent self-service registration and prepaid-account controls, the prepaid extra-minute price in EUR, and the limits applied to prepaid accounts. Available only to API keys belonging to a white-label reseller workspace. **Required scope:** `platform:read`.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current registration and prepaid-account defaults.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformDefaultLimitsSettings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks `platform:read` or does not belong to a white-label reseller workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updatePlatformDefaultLimits", "summary": "Update platform registration and prepaid defaults", "description": "Updates one or more registration or prepaid-account settings. Self-service registration controls whether new customers can create an account from your login page. Prepaid access independently controls whether customers without a paid plan can use prepaid credits; when it is disabled, registered customers choose a paid plan before using the platform. **Required scope:** `platform:write`.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDefaultLimitsPatch" }, "example": { "self_service_registration_enabled": true, "prepaid_accounts_enabled": false, "prepaid_extra_minute_price_eur": 0.49, "prepaid_default_limits": { "max_assistants": 2, "web_widget": true } } } } }, "responses": { "200": { "description": "Updated registration and prepaid-account defaults.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformDefaultLimitsSettings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks `platform:write` or does not belong to a white-label reseller workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The prepaid extra-minute price would not leave a positive reseller margin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/welcome-credits": { "get": { "operationId": "getPlatformWelcomeCredits", "summary": "Get platform welcome-credit settings", "description": "Returns the one-time wallet credits offered to each newly created free customer, whether automatic grants are active, the reseller wallet balance, and the number of customers that balance can currently fund. Available only to API keys belonging to a white-label reseller workspace. **Required scope:** `platform:read`.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current welcome-credit settings and wallet capacity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformWelcomeCreditSettings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks `platform:read` or does not belong to a white-label reseller workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updatePlatformWelcomeCredits", "summary": "Update platform welcome-credit settings", "description": "Sets the one-time wallet credits offered to future free customers. Use 0 to disable automatic grants. The setting can exceed the current wallet balance; customer signup still succeeds when the wallet cannot cover a grant, and the credits can be transferred manually later. Available only to API keys belonging to a white-label reseller workspace. **Required scope:** `platform:write`.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformWelcomeCreditSettingsPatch" }, "example": { "welcome_credits": 800 } } } }, "responses": { "200": { "description": "Updated welcome-credit settings and wallet capacity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlatformWelcomeCreditSettings" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks `platform:write` or does not belong to a white-label reseller workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "List the API keys created in the calling workspace, including revoked ones (`revoked_at` set). Never returns the secret — only `prefix` plus metadata; use it to audit which keys exist and when each was last used. **Required scope:** `settings:read`.", "tags": [ "API Keys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of API keys.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 0 } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Mints a new self-service API key for the calling workspace. `scopes` must be a subset of the calling credential's own scopes — a key can never mint another key with broader access than itself (a caller with unrestricted access, i.e. no scopes or `*`, may grant any scope, and an omitted `scopes` defaults to its own scopes). A new key cannot outlive a finite calling credential. Requires the calling credential to be a workspace owner/admin (service-account keys always qualify). The plaintext key is returned exactly once and cannot be retrieved again. **Required scope:** `settings:write`.", "tags": [ "API Keys" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateInput" }, "example": { "name": "CRM integration", "scopes": [ "calls:read", "leads:write" ] } } } }, "responses": { "201": { "description": "The minted key (shown once).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeyCreated" } } } } } }, "400": { "description": "Missing name, or requested scopes exceed the calling credential's own scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Requested scopes exceed the scopes granted to this API key. A key can never mint another key with broader access than itself." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Missing scope, or the calling credential is not a workspace owner/admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "Only workspace owners or admins can manage API keys." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/api-keys/{id}": { "get": { "operationId": "getApiKey", "summary": "Get an API key", "description": "Metadata for a single API key (never the secret). 404 if it belongs to another workspace. **Required scope:** `settings:read`.", "tags": [ "API Keys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The key does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "API key not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Revokes (soft-deletes) an API key. Idempotent — revoking an already-revoked key still returns `200 { revoked: true }`. **Required scope:** `settings:write`.", "tags": [ "API Keys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean" } } } } }, "example": { "data": { "id": "k1b2c3d4-0000-4000-8000-000000000099", "revoked": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Missing scope, or the calling credential is not a workspace owner/admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "Only workspace owners or admins can manage API keys." } } } } }, "404": { "description": "The key does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "API key not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/workspaces/{workspace_id}/api-keys": { "post": { "operationId": "createWorkspaceApiKey", "summary": "Create an API key for a workspace", "description": "Mints a service-account API key bound to the selected workspace. The calling credential must be user-owned, carry `settings:write`, and its user must currently be an owner or admin in the target workspace. The target must be visible within the calling credential's brand; no white-label entitlement is required. Requested scopes can only stay equal to or become narrower than the calling credential's scopes. A child key cannot outlive a finite calling credential. The target may still be awaiting plan activation, but a suspended target is rejected. The plaintext key is returned exactly once with `Cache-Control: no-store`; do not retry automatically because each successful request creates a new key.", "tags": [ "Workspaces", "API Keys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace UUID from `GET /workspaces`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateInput" }, "example": { "name": "Customer backend", "scopes": [ "calls:read", "leads:write" ], "expires_in_days": 90 } } } }, "responses": { "201": { "description": "The target-workspace key, including its one-time plaintext secret.", "headers": { "Cache-Control": { "description": "Always `no-store` for the one-time secret response.", "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceApiKeyCreated" } } } } } }, "400": { "description": "Invalid name, scopes or expiry, or the requested scopes exceed the calling credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The calling credential's own workspace requires an active plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Missing scope, service-account caller, insufficient target role, or suspended target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The target does not exist, is outside the credential's brand, or is not one of the user's workspaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "description": "List the workspaces visible to the calling credential. For a user-owned API key or OAuth token: every workspace the key owner is a member of within this key's own brand (a reseller customer's key never sees a different reseller's workspaces). A service-account key is a single workspace by construction and only lists itself. The key's own workspace is flagged `current: true`. Switching the active workspace is per-credential — use or mint a key/token bound to the target workspace; this endpoint only lists what is visible. **Required scope:** `settings:read`.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The workspaces visible to this credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "example": { "data": [ { "id": "t1b2c3d4-0000-4000-8000-000000000002", "name": "Acme Corp", "role": "owner", "current": true }, { "id": "t1b2c3d4-0000-4000-8000-000000000009", "name": "Acme Corp — EU", "role": "member", "current": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace", "description": "Create an additional workspace owned by the calling credential's user. Requires a user-owned API key or OAuth token — a service-account key IS a single workspace and cannot own more (`403`). Limited by the plan's workspace allowance (unlimited, or unavailable when the plan includes none) plus any Extra workspaces add-on, counted across every workspace this user already owns in this same brand. **Required scope:** `settings:write`.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateInput" }, "example": { "name": "Acme Corp — EU" } } } }, "responses": { "201": { "description": "The newly created workspace.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceCreated" } } }, "example": { "data": { "id": "t1b2c3d4-0000-4000-8000-000000000009", "name": "Acme Corp — EU", "role": "owner" } } } } }, "400": { "description": "Missing or invalid name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "name is required." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Missing scope, the credential is a service-account key (not user-owned), or the workspace-creation allowance is exhausted. In the last case the error carries `meta.used`/`meta.allowed`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "used": { "type": "integer", "example": 3 }, "allowed": { "type": "integer", "example": 3, "description": "-1 means unlimited (this field is only present when the limit was actually reached, so it is never -1 here)." } } } } }, "example": { "error": { "code": "forbidden", "message": "Workspace limit reached. Upgrade your plan or contact support to create more workspaces." }, "meta": { "used": 3, "allowed": 3 } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/domains": { "get": { "operationId": "listEmailDomains", "summary": "List email domains", "description": "List the domains connected to the email channel, including DNS verification status and the exact records to add at your DNS provider. **Required scope:** `assistants:read`. Requires workspace owner/admin.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Connected domains.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailDomain" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createEmailDomain", "summary": "Connect an email domain", "description": "Connects a new domain to the email channel. Returns the domain in `pending` status together with the DNS records (CNAMEs for sending/DKIM, an MX record for receiving) to add before calling `POST /email/domains/{id}/verify`. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomainCreateInput" }, "example": { "domain": "mail.your-domain.com" } } } }, "responses": { "201": { "description": "The connected domain, pending DNS verification.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailDomain" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "This domain is already connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "This domain is already connected" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/domains/{id}": { "get": { "operationId": "getEmailDomain", "summary": "Get an email domain", "description": "**Required scope:** `assistants:read`. Requires workspace owner/admin.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The domain.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailDomain" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The domain does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Domain not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteEmailDomain", "summary": "Disconnect an email domain", "description": "Disconnects a domain; its addresses are removed with it. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The domain does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Domain not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/domains/{id}/verify": { "post": { "operationId": "verifyEmailDomain", "summary": "Verify an email domain", "description": "Re-checks the domain's DNS records and flips it to `verified` once every record resolves correctly (also finishing the inbound-receiving setup). Safe to call repeatedly while DNS propagates. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The domain with updated verification status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailDomain" } } } } } }, "400": { "description": "The domain has no mail-provider connection (should not normally happen).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Domain is not connected to a mail provider" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The domain does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Domain not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/addresses": { "get": { "operationId": "listEmailAddresses", "summary": "List email addresses", "description": "List addresses on the email channel, including the resolved domain and assigned assistant. **Required scope:** `assistants:read`. Requires workspace owner/admin.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Addresses.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createEmailAddress", "summary": "Create an email address", "description": "Creates an address on an already-**verified** domain, optionally assigned to an assistant so it can send and receive on that address. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddressCreateInput" }, "example": { "domain_id": "d1b2c3d4-0000-4000-8000-000000000020", "local_part": "support", "assistant_id": "a1b2c3d4-0000-4000-8000-000000000001" } } } }, "responses": { "201": { "description": "The created address.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailAddress" } } } } } }, "400": { "description": "Invalid local part, or the domain is not verified yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Domain is not verified yet" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The domain (or assistant, if given) does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Domain not found" } } } } }, "409": { "description": "This address already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "support@mail.your-domain.com already exists" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/addresses/{id}": { "patch": { "operationId": "updateEmailAddress", "summary": "Update an email address", "description": "Rename (display name), reassign to a different assistant, or toggle active. There is no single-address GET — read it back via the list. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddressUpdateInput" }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "The updated address.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailAddress" } } } } } }, "400": { "description": "No valid fields in the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "No valid fields" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The address (or assistant, if given) does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Address not found" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "delete": { "operationId": "deleteEmailAddress", "summary": "Delete an email address", "description": "**Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/email/settings": { "get": { "operationId": "getEmailSettings", "summary": "Get email channel defaults", "description": "Workspace-wide default sender name and signature, used when an address doesn't have its own. **Required scope:** `assistants:read`. Requires workspace owner/admin.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The defaults.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailSettings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "put": { "operationId": "updateEmailSettings", "summary": "Replace email channel defaults", "description": "Replaces the workspace's default sender name and signature wholesale — omitted fields reset to an empty string, so send both together if you're changing only one. `\"{agent_name}\"` in the signature is replaced with the assistant's name at send time. **Required scope:** `assistants:write`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsInput" }, "example": { "default_display_name": "Acme Support", "default_signature": "Best,\n{agent_name}\nAcme Support" } } } }, "responses": { "200": { "description": "The updated defaults.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailSettings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/settings/ai-inference": { "get": { "operationId": "getAiInferenceSettings", "summary": "Get AI inference settings", "description": "Reads the workspace AI inference region (`global`, `eu`, or `us`). EU also activates after-save AI-disclosure review for assistants. **Required scope:** `settings:read`.", "tags": [ "Settings" ], "responses": { "200": { "description": "The workspace AI inference settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiInferenceSettings" } } }, "example": { "data": { "ai_inference_region": "global" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "patch": { "operationId": "updateAiInferenceSettings", "summary": "Update AI inference settings", "description": "Updates the workspace AI inference region. Changing the region re-reviews existing assistants; EU requires a clear AI introduction in the effective opening. **Required scope:** `settings:write`.", "tags": [ "Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ai_inference_region" ], "properties": { "ai_inference_region": { "type": "string", "enum": [ "global", "eu", "us" ], "description": "AI Gateway inference region for workspace backend AI." } } }, "example": { "ai_inference_region": "eu" } } } }, "responses": { "200": { "description": "The updated settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AiInferenceSettings" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/sms/send": { "post": { "operationId": "sendSms", "summary": "Send an SMS", "description": "Send an outbound SMS from a workspace phone number that has outbound SMS enabled (platform marketplace or Twilio BYOC). US 10DLC senders must be registered with an approved A2P campaign in Twilio. Platform numbers charge SMS credits including carrier pass-through; BYOC charges only the platform SMS fee (customer pays Twilio carrier cost). **Required scope:** `phone_numbers:write`.", "tags": [ "SMS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_number_id", "to", "body" ], "properties": { "from_number_id": { "type": "string", "format": "uuid", "description": "ID of an SMS-capable phone number with outbound SMS enabled." }, "to": { "type": "string", "description": "Recipient in E.164 format.", "example": "+14155550100" }, "body": { "type": "string", "minLength": 1, "maxLength": 1600, "description": "Message body." } } } } } }, "responses": { "201": { "description": "SMS accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "credits": { "type": "number" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/translation-sessions": { "get": { "operationId": "listTranslationSessions", "summary": "List translation rooms", "description": "List the current user’s hosted rooms. Requires calls:read and a credential belonging to the room host.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationSession" } } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createTranslationSession", "summary": "Create a translation room", "description": "Prepare a room for an assistant using Translate. The Translate Agent mode must be included in the workspace's current plan. The credential user is speaker 1; speaker 2 joins without an account. Creating a room does not place calls. Requires calls:write and a credential belonging to the room host. Workspace roles, credits, assistant and calling limits apply.", "tags": [ "Translation" ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TranslationSession" }, "room_url": { "type": "string", "format": "uri" }, "invite_url": { "type": "string", "format": "uri" }, "dial_in": { "type": "object", "properties": { "number": { "type": [ "string", "null" ] }, "code": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "format": "uuid" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/translation-sessions/{id}": { "get": { "operationId": "getTranslationSession", "summary": "Get a translation room", "description": "Read connection state and original/translated phrase pairs while the room is active. Phrase history expires when the room ends. Requires calls:read and a credential belonging to the room host.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TranslationSession" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationSegment" } } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "after", "schema": { "type": "integer", "minimum": 0 }, "description": "Last received phrase sequence; returns up to 200 newer active-session phrases." } ] } }, "/translation-sessions/{id}/start": { "post": { "operationId": "startTranslationSession", "summary": "Start a translation room", "description": "Start each participant in the browser, through a callback, or speaker 1 by dialing the assigned number and entering the room code. The Translate Agent mode must be included in the workspace's current plan. Phone participants require phone_number. One shared talk rate and translation surcharge apply, plus actual costs for each phone connection. Requires calls:write and a credential belonging to the room host. Workspace roles, credits, assistant and calling limits apply.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TranslationSession" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationStart" } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/translation-sessions/{id}/call": { "post": { "operationId": "callTranslationSpeaker", "summary": "Call a translation participant", "description": "Request a callback for either speaker. Reuse the same Idempotency-Key UUID when retrying an uncertain response; a new key creates a new attempt. A connected phone participant uses the browser as a live-text observer. Requires calls:write and a credential belonging to the room host. Workspace roles, credits, assistant and calling limits apply.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TranslationSession" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "side": { "type": "integer", "enum": [ 1, 2 ] }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "International E.164 telephone number." }, "phone_number_id": { "type": "string", "format": "uuid" } }, "required": [ "side", "phone_number" ], "additionalProperties": false } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/translation-sessions/{id}/invite": { "post": { "operationId": "inviteTranslationGuest", "summary": "Invite the external guest", "description": "Return the room invitation link. Supply email to send the invitation; no account is created. The invitation allows guest participation only. Requires calls:write and a credential belonging to the room host. Workspace roles, credits, assistant and calling limits apply.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "invite_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "additionalProperties": false } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/translation-sessions/{id}/end": { "post": { "operationId": "endTranslationSession", "summary": "End a translation room", "description": "Stop the entire shared session and both telephone connections. The status can remain ending while connections close; repeat safely. Requires calls:write and a credential belonging to the room host. Workspace roles, credits, assistant and calling limits apply.", "tags": [ "Translation" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/TranslationSession" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "The credential is not permitted to control this room." }, "409": { "description": "A conflicting room update or connection is already in progress." }, "402": { "description": "Insufficient workspace credits." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/platform/users/{user_id}/custom-payments": { "get": { "operationId": "listPlatformUserCustomPayments", "summary": "List a customer's custom payments", "description": "Lists custom payments billed to one customer, newest first, plus create-time context (resolved workspace, currency options, saved payment methods, tax-automation availability). **Required scope:** `platform:read`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Pick a specific workspace when the customer has several in your scope; defaults to the one they own." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor from the previous page." }, { "name": "sync", "in": "query", "schema": { "type": "boolean" }, "description": "Refresh non-terminal rows from the billing provider before returning them." } ], "responses": { "200": { "description": "The customer's custom payments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPaymentUserListResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No custom payment (or customer) with that ID exists in your scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "No billable workspace found for this user." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "createPlatformCustomPayment", "summary": "Create a custom payment for a customer", "description": "Charges a customer a one-off amount or starts a custom recurring subscription, outside their regular plan. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomPaymentInput" }, "example": { "kind": "one_time", "channel": "invoice", "description": "Custom integration setup", "amount_minor": 25000, "currency": "EUR" } } } }, "responses": { "201": { "description": "The created custom payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPaymentItemResult" } } } } } }, "400": { "description": "Invalid input, an amount below the currency's minimum, or an unusually large amount without confirm_large_amount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "amount_minor is below the minimum chargeable amount for EUR." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The billing provider declined the charge (e.g. card requires authentication or was declined)." }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No custom payment (or customer) with that ID exists in your scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "No billable workspace found for this user." } } } } }, "409": { "description": "The workspace is suspended, billed by a different scope, or the currency conflicts with an existing customer currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "This workspace is billed by its reseller." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/custom-payments": { "get": { "operationId": "listPlatformCustomPayments", "summary": "List custom payments across your customers", "description": "Lists custom payments across every customer in your scope, newest first. **Required scope:** `platform:read`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "one_time", "subscription" ] } }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "charge_saved_method", "payment_link", "invoice" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search the payment description." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Custom payments across your scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPaymentListResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/platform/custom-payments/{payment_id}": { "get": { "operationId": "getPlatformCustomPayment", "summary": "Get a custom payment", "description": "Fetches a single custom payment by ID. **Required scope:** `platform:read`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The custom payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPaymentItemResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No custom payment (or customer) with that ID exists in your scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Custom payment not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "runPlatformCustomPaymentAction", "summary": "Run an action on a custom payment", "description": "Runs an action on an existing custom payment: refresh, resend_notification, cancel, cancel_at_period_end, mark_uncollectible, or deactivate_link. **Required scope:** `platform:write`. Requires white-label platform access (a reseller workspace with the white-label entitlement, or a platform admin acting from a root workspace) plus a live owner/admin membership in the calling credential's own workspace — see [White Label API](/admin/whitelabel-api).", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomPaymentActionInput" }, "example": { "action": "cancel" } } } }, "responses": { "200": { "description": "The custom payment after the action ran.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomPaymentItemResult" } } } } } }, "400": { "description": "action is missing or not one of the accepted values." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential lacks the required scope, or the calling workspace has no white-label platform access (not a reseller with the whitelabel entitlement, and not a platform admin acting from a root workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "forbidden", "message": "White-label platform access required." } } } } }, "404": { "description": "No custom payment (or customer) with that ID exists in your scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Custom payment not found." } } } } }, "409": { "description": "The custom payment is already in a terminal state, or the action does not apply to its kind/channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "This custom payment is already paid and cannot be modified." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/milian/voice-sessions": { "post": { "tags": [ "Milian" ], "summary": "Start a Milian voice session", "operationId": "createMilianVoiceSession", "description": "Create a short-lived live voice connection after explicit approval of additional workspace credits. Requires milian:write, a writable user credential, workspace Beta Features and an eligible plan. Each session starts a new conversation. Workspace tools retain the credential scopes and role. Connect using the returned URL and subprotocols within 60 seconds. Clients can supply optional visible page text; explicit screen sharing takes priority. Screen analysis also consumes credits. Do not retry automatically. See the Milian API guide for the WebSocket protocol.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "approve_credit_usage" ], "properties": { "approve_credit_usage": { "type": "boolean", "const": true, "description": "Explicit user approval for this paid session." }, "context": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string", "enum": [ "en", "de", "fr", "es" ] } } } } } } } }, "responses": { "200": { "description": "Single-use connection. Treat protocols as temporary credentials; do not log or share them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "session_id", "url", "protocols", "expires_in", "max_seconds" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "protocols": { "type": "array", "items": { "type": "string" } }, "expires_in": { "type": "integer", "const": 60 }, "max_seconds": { "type": "integer", "maximum": 800 } } } } } } } }, "400": { "description": "Invalid request or credit approval missing." }, "402": { "description": "Insufficient workspace credits." }, "403": { "description": "Access, role, scope, beta setting or plan does not permit voice." }, "409": { "description": "Another workspace voice session is active or regional processing is incompatible." }, "503": { "description": "Voice is temporarily unavailable." } } } }, "/booking-email-templates": { "get": { "tags": [ "Bookings" ], "summary": "Get standard booking email templates", "description": "Read standard text for all seven guest and host messages, plus supported template variables. Requires bookings:read. Standard messages follow recipient language; custom text is sent as written. Optional location, question answers and calendar attachment notes are omitted from standard messages when not applicable.", "operationId": "getBookingEmailTemplates", "parameters": [ { "name": "locale", "in": "query", "description": "Language of the standard templates.", "schema": { "type": "string", "enum": [ "en", "de", "fr", "es" ], "default": "en" } } ], "responses": { "200": { "description": "Standard templates and variables", "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "templates": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BookingEmailTemplate" } } } } } } }, "400": { "description": "Unsupported locale" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Missing bookings:read scope" } } } }, "/billing/subscription-change/review": { "post": { "operationId": "reviewSubscriptionPaymentChange", "summary": "Review subscription change", "description": "Reviews an existing subscription change without submitting the change or charging a card. Provide the complete desired plan and add-on selection. Returns estimated tax, the amount due, masked eligible methods and short-lived references. This operation does not create new subscriptions or checkouts. Resolve pending invoices in the app before requesting another review. Requires a user-owned credential with billing:write scope and owner, admin or billing access in the active workspace. API Access must be enabled.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "addon_ids", "interval" ], "properties": { "plan_id": { "type": "string", "format": "uuid", "description": "Target plan. Omit only for an add-on-only subscription." }, "addon_ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "Complete desired add-on selection, including every add-on to keep." }, "addon_quantities": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] } } } } } }, "responses": { "200": { "description": "Review subscription change.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "review_ref", "expires_at", "amount_due", "tax_amount", "currency", "summary", "payment_required", "methods", "billing_url" ], "properties": { "review_ref": { "type": "string", "description": "Opaque reference to the exact selection, workspace, user and maximum amount reviewed. Expires after 15 minutes." }, "expires_at": { "type": "string", "format": "date-time" }, "amount_due": { "type": "integer", "description": "Maximum reviewed amount due now, in the currency minor unit. A refreshed lower amount is allowed." }, "tax_amount": { "type": "integer", "description": "Estimated tax in the currency minor unit." }, "currency": { "type": "string", "description": "Three-letter currency code." }, "summary": { "type": "string" }, "payment_required": { "type": "boolean" }, "methods": { "type": "array", "items": { "type": "object", "properties": { "payment_method_ref": { "type": "string", "description": "Opaque reference bound to this review and authorized user." }, "type": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "last4": { "type": "string", "nullable": true }, "exp_month": { "type": "integer", "nullable": true }, "exp_year": { "type": "integer", "nullable": true }, "is_default": { "type": "boolean" } } } }, "billing_url": { "type": "string", "format": "uri", "description": "Open billing in the app to manage methods or resolve a pending payment." } } } } } } } }, "400": { "description": "Invalid request or missing explicit confirmation." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Review expired, terms changed, method unavailable or billing needs attention." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/billing/subscription-change/confirm": { "post": { "operationId": "confirmSubscriptionPaymentChange", "summary": "Confirm subscription change", "description": "Applies a reviewed existing subscription change only after explicit approval. May charge the chosen saved card and select it for future renewals. References are bound to the workspace, user and exact selection. The amount is verified again; an increase, currency change, stale reference or changed subscription requires a new review. A lower refreshed amount is allowed. No card is required for a change with no payment due. Pending payments do not grant upgrades; open the returned app billing link to complete payment. Requires a user-owned credential with billing:write scope and owner, admin or billing access in the active workspace. API Access must be enabled.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "review_ref", "confirm" ], "properties": { "review_ref": { "type": "string", "maxLength": 16000 }, "payment_method_ref": { "type": "string", "maxLength": 4000, "description": "Reference from the same review, required when payment is due. Omit when no payment is due." }, "confirm": { "type": "boolean", "enum": [ true ], "description": "Explicit approval of the reviewed selection, amount, currency and selected card. The selected card also becomes the subscription renewal method." } } } } } }, "responses": { "200": { "description": "Confirm subscription change.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "updated", "pending_payment" ], "properties": { "updated": { "type": "boolean" }, "pending_payment": { "type": "boolean", "description": "Payment is not yet confirmed; requested upgrades remain unavailable until confirmed payment." }, "warnings": { "type": "array", "items": { "type": "string" } }, "billing_url": { "type": "string", "format": "uri", "description": "Sign in to the workspace to complete a pending payment." } } } } } } } }, "400": { "description": "Invalid request or missing explicit confirmation." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Review expired, terms changed, method unavailable or billing needs attention." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/phone-numbers/verifications/requirements": { "get": { "operationId": "getPhoneNumberVerificationRequirements", "summary": "Get number verification requirements", "description": "Returns the current registration fields, accepted document types, and address requirements for a supported catalog combination. Field names are used as keys when submitting registration details. Required address information is supplied through the address object; internal address references are managed automatically. Unsupported registration types return 400. No verification case is created. **Required scope:** `phone_numbers:read`.", "tags": [ "Phone Numbers" ], "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO-2 country code, for example DE." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "local", "mobile", "national" ], "default": "local" } }, { "name": "end_user_type", "in": "query", "schema": { "type": "string", "enum": [ "business", "individual" ], "default": "business" } } ], "responses": { "200": { "description": "Current verification requirements", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "iso_country": { "type": "string", "example": "DE" }, "number_type": { "type": "string", "enum": [ "local", "mobile", "national" ] }, "end_user_type": { "type": "string", "enum": [ "business", "individual" ] }, "friendly_name": { "type": "string" }, "requires_address": { "type": "boolean" }, "address_description": { "type": "string", "nullable": true }, "end_user": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "detailed_fields": { "type": "array", "items": { "type": "object", "properties": { "machine_name": { "type": "string" }, "friendly_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "constraint": { "type": "string", "nullable": true } } } }, "requirement_name": { "type": "string" } } } }, "supporting_document": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "requirement_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string" }, "accepted_documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "detailed_fields": { "type": "array", "items": { "type": "object", "properties": { "machine_name": { "type": "string" }, "friendly_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "constraint": { "type": "string", "nullable": true } } } } } } } } } } } } } } } } } }, "400": { "description": "Invalid or unsupported verification combination" }, "401": { "description": "Invalid API key" }, "403": { "description": "Missing phone_numbers:read scope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/phone-numbers/{id}/sms-registration": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Phone Numbers" ], "operationId": "getSmsRegistration", "summary": "Get SMS registration", "description": "Read registration for a purchased active US local SMS-capable number in the active workspace. Requires phone_numbers:read.", "responses": { "200": { "description": "The workspace registration as seen from this number, plus registration prices while no application exists or it is still a draft. Provider identifiers and internal billing details are omitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "registration", "volume_options" ], "properties": { "registration": { "oneOf": [ { "$ref": "#/components/schemas/SmsRegistrationForNumber" }, { "type": "null" } ], "description": "null while the workspace has no application." }, "volume_options": { "oneOf": [ { "$ref": "#/components/schemas/SmsRegistrationVolumeOptions" }, { "type": "null" } ], "description": "Prices for both registration volumes while no application exists or it is still a draft; null otherwise. The binding quote is created when the application is saved." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Phone Numbers" ], "operationId": "manageSmsRegistration", "summary": "Prepare, check, correct or attach SMS registration", "description": "Requires phone_numbers:write. Save truthful business and consent details to receive a price quote. Review checks the same details for common carrier rejection reasons before you pay; it is advisory and stores nothing. Attach reuses the paid approved workspace registration for another eligible number with the same business and messaging purpose, without an extra subscription. Use POST /billing/sms-registration with billing:write to confirm the price and open checkout.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action", "details" ], "properties": { "action": { "type": "string", "enum": [ "save" ] }, "details": { "$ref": "#/components/schemas/SmsRegistrationInput" } } }, { "type": "object", "required": [ "action", "confirm" ], "properties": { "action": { "type": "string", "enum": [ "attach" ] }, "confirm": { "type": "boolean", "enum": [ true ] } } }, { "type": "object", "required": [ "action", "details" ], "properties": { "action": { "type": "string", "enum": [ "review" ] }, "details": { "$ref": "#/components/schemas/SmsRegistrationInput" }, "locale": { "type": "string", "enum": [ "en", "de", "fr", "es" ], "description": "Language of the review messages. Defaults to en." } } }, { "type": "object", "required": [ "action", "details" ], "properties": { "action": { "type": "string", "enum": [ "resubmit" ] }, "details": { "$ref": "#/components/schemas/SmsRegistrationInput" } }, "description": "Correct a rejected application. Free where the provider charges nothing (business details before the brand registration, a brand retry without changes, campaign edits), at most three times per review step. A correction that needs a new, charged review returns 402 with code correction_requires_payment." }, { "type": "object", "required": [ "action", "confirm" ], "properties": { "action": { "type": "string", "enum": [ "attach_all" ] }, "confirm": { "type": "boolean", "enum": [ true ] } }, "description": "Link every other eligible US number of the workspace to the approved registration at once. One registration covers the workspace, so no subscription is added." } ] } } } }, "responses": { "200": { "description": "Workspace registration, reviewed quote and status. Provider identifiers and internal billing details are omitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "save and resubmit return `registration`; attach and attach_all return the registration as seen from this number; review returns `review`.", "properties": { "registration": { "oneOf": [ { "$ref": "#/components/schemas/SmsRegistrationForNumber" }, { "type": "null" } ] }, "review": { "type": "object", "description": "Returned for action=review.", "properties": { "ready": { "type": "boolean", "description": "False when a finding would likely cause a rejection." }, "checked_by_ai": { "type": "boolean", "description": "False when only the automatic rule checks ran." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Registration field the finding concerns, or general." }, "severity": { "type": "string", "enum": [ "blocker", "warning" ] }, "message": { "type": "string" } } } } } } } } } } } } }, "400": { "description": "Invalid details or number eligibility." }, "403": { "description": "Insufficient workspace role, scope or plan access." }, "409": { "description": "Expired quote, conflicting application or existing messaging service." }, "503": { "description": "Registration or billing is temporarily unavailable." } } } }, "/billing/sms-registration": { "get": { "tags": [ "Billing" ], "operationId": "getSmsRegistrationBilling", "summary": "Get workspace SMS registration billing", "description": "Requires billing:read. User-owned credentials need a workspace owner, admin or billing role; workspace service-account credentials can read it with the scope alone. Available even after the associated phone rentals end.", "responses": { "200": { "description": "Workspace registration, reviewed quote and status. Provider identifiers and internal billing details are omitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "registration" ], "properties": { "registration": { "oneOf": [ { "$ref": "#/components/schemas/SmsRegistration" }, { "type": "null" } ], "description": "null while the workspace has no application." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Billing" ], "operationId": "manageSmsRegistrationBilling", "summary": "Pay for or cancel SMS registration", "description": "Requires billing:write and a user-owned credential of a workspace owner, admin or billing manager; service-account credentials are rejected because a paying user must approve the charge. Checkout returns the secure payment URL for the explicitly approved quote. Cancellation stops renewal at the end of the paid period; it affects every associated number in this workspace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "action", "phone_number_id", "quote_ref", "confirm" ], "properties": { "action": { "type": "string", "enum": [ "checkout" ] }, "phone_number_id": { "type": "string", "format": "uuid" }, "quote_ref": { "type": "string" }, "confirm": { "type": "boolean", "enum": [ true ] } } }, { "type": "object", "required": [ "action", "registration_id", "confirm" ], "properties": { "action": { "type": "string", "enum": [ "cancel" ] }, "registration_id": { "type": "string", "format": "uuid" }, "confirm": { "type": "boolean", "enum": [ true ] } } } ] } } } }, "responses": { "200": { "description": "Workspace registration, reviewed quote and status. Provider identifiers and internal billing details are omitted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "checkout returns `checkout_url`; cancel returns `registration`.", "properties": { "registration": { "$ref": "#/components/schemas/SmsRegistration" }, "checkout_url": { "type": "string", "format": "uri" } } } } } } } }, "400": { "description": "Invalid details or number eligibility." }, "403": { "description": "Insufficient workspace role, scope or plan access." }, "409": { "description": "Expired quote, conflicting application or existing messaging service." }, "503": { "description": "Registration or billing is temporarily unavailable." } } } }, "/inbox-labels/settings": { "get": { "tags": [ "History" ], "operationId": "getInboxLabelSettings", "summary": "Get message label settings", "description": "Requires calls:read. Returns the workspace preference and plan availability.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Message label settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InboxLabelSettings" } } } } } } } }, "patch": { "tags": [ "History" ], "operationId": "updateInboxLabelSettings", "summary": "Update message label settings", "description": "Requires calls:write and workspace owner/admin permission. Applies to new messages. Existing labels and messages remain visible. Connected mailbox labels are unchanged.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Message label settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InboxLabelSettings" } } } } } }, "403": { "description": "Insufficient role or plan access" } } } }, "/history/inbox-labels/{id}/dismiss": { "post": { "tags": [ "History" ], "operationId": "dismissInboxLabel", "summary": "Dismiss a message label", "description": "Requires calls:write and workspace write permission. Repeating the request is safe. Does not remove the message, alter replies, or change the connected mailbox.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Label dismissed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dismissed": { "type": "boolean", "enum": [ true ] } } } } } } } }, "403": { "description": "Workspace write permission required" }, "404": { "description": "Label not found in this workspace" } } } }, "/reseller/plans/{id}/knowledge-sources": { "patch": { "operationId": "updateResellerPlanKnowledgeSources", "summary": "Update plan knowledge source access", "description": "Enable or disable knowledge sources on your Whitelabel customer plan. Requires settings:write and owner or admin authority. Changes apply to customers using the plan. Ingestion remains billed in usage credits; prices, included credits and subscriptions are unchanged. Omitted fields keep their current values.", "tags": [ "White Label" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "website_crawling": { "type": "boolean", "description": "Allow website crawling; new or changed pages consume credits." }, "cloud_drive": { "type": "boolean", "description": "Allow cloud drive sources. The customer workspace must also enable Beta Features." }, "automatic_refresh": { "type": "boolean", "description": "Allow scheduled refresh for enabled website and cloud drive sources." } } }, "example": { "website_crawling": true, "cloud_drive": true, "automatic_refresh": true } } } }, "responses": { "200": { "description": "Saved knowledge source permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "knowledge_sources": { "$ref": "#/components/schemas/ResellerKnowledgeSourceAccess" } } } } } }, "400": { "description": "Invalid or empty settings." }, "401": { "description": "Authentication required." }, "403": { "description": "Missing scope, workspace authority or Whitelabel access." }, "404": { "description": "Plan not found in your workspace." }, "503": { "description": "Settings could not be saved." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/booking-event-types/{id}/slots": { "get": { "operationId": "listBookingSlots", "summary": "List free slots", "description": "List the free start times of one active event type for a date range (at most 28 days; dates default to the workspace time zone). Past times and times after `bookable_until` are never returned. Pass a returned slot unchanged as `start` to `POST /bookings` or `POST /bookings/{id}/reschedule`; when moving a booking, pass `exclude_booking_id` so its own time does not block nearby slots.\n\nReturns `409` instead of `200` when the event type is turned off, or when the workspace has not set up its public booking address yet.\n\nA `503` here can mean either request protection is temporarily unavailable (`internal_error`) or the availability engine itself failed to load (`service_unavailable`, message \"Could not load availability\").\n\n**Required scope:** `bookings:read` (keys without scope restrictions have full access).", "tags": [ "Bookings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Event type ID" }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start of the date range (YYYY-MM-DD); default today." }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End of the date range (YYYY-MM-DD); default start + 6 days, max 28 days." }, { "name": "timezone", "in": "query", "schema": { "type": "string" }, "description": "IANA time zone for the returned range and slots; default the workspace time zone." }, { "name": "exclude_booking_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Exclude this booking's own time from busy calculations (use when rescheduling it)." } ], "responses": { "200": { "description": "Free slots of the event type.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BookingSlots" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AvailabilityOrProtectionUnavailable" } } } }, "/automations/ai-actions": { "get": { "tags": [ "Automations" ], "responses": { "200": { "description": "Success envelope. Execution returns success, optional error and data. data includes accepted/uncertain status, results by question key, nullable values and credits. Preview returns dry_run=true without model usage." }, "401": { "description": "Authentication required" }, "403": { "description": "Missing scope or automation access" } }, "operationId": "listAutomationAiActions", "summary": "List Milian AI automation actions", "description": "Requires automations:read. Returns the five evaluation actions, configuration defaults, output fields and three editable presets. Also available as list_automation_ai_actions over MCP." }, "post": { "tags": [ "Automations" ], "responses": { "200": { "description": "Success envelope. Execution returns success, optional error and data. data includes accepted/uncertain status, results by question key, nullable values and credits. Preview returns dry_run=true without model usage." }, "401": { "description": "Authentication required" }, "403": { "description": "Missing scope or automation access" } }, "operationId": "runAutomationAiAction", "summary": "Preview or run a Milian AI automation action", "description": "Requires automations:write. dry_run=true is a free configuration preview. Set false explicitly to run analysis and charge workspace credits. Each live invocation is a separate paid request. Uncertain answers have null values. Technical failures return success=false. Also available as run_automation_ai_action over MCP. Save the same action/config in a graph using POST or PATCH /automations/{id}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "config" ], "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "ai.classify", "ai.check_condition", "ai.score", "ai.detect_labels", "ai.analyze" ] }, "config": { "type": "object", "required": [ "input", "questions" ], "additionalProperties": false, "properties": { "input": { "type": "string", "description": "Text or a template resolving against context; maximum 32 KB after resolution." }, "questions": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "required": [ "id", "type", "instructions" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$" }, "type": { "type": "string", "enum": [ "choice", "boolean", "score" ] }, "instructions": { "type": "string", "minLength": 1, "maxLength": 2000 }, "options": { "type": "array", "minItems": 2, "maxItems": 32, "items": { "type": "object", "required": [ "value", "description" ], "properties": { "value": { "type": "string" }, "description": { "type": "string" } } } }, "levels": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "string" } } } } }, "min_probability": { "type": "number", "minimum": 0.51, "maximum": 1, "default": 0.9 }, "min_confidence": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 } } }, "context": { "type": "object", "additionalProperties": true }, "dry_run": { "type": "boolean", "default": true } } } } } } } }, "/tools/test": { "post": { "operationId": "testTool", "summary": "Test HTTP tool", "description": "Send a real HTTP test request using the same request preparation, secret handling and outbound protections as Agent Tools. The request may change the remote system. Requires an admin-level credential and assistants:write.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "config" ], "properties": { "tool_id": { "type": "string", "format": "uuid", "description": "Existing tool to reuse masked secrets." }, "config": { "type": "object", "additionalProperties": true, "description": "HTTP or MCP configuration, as accepted when creating this tool type." }, "values": { "type": "object", "additionalProperties": true, "description": "Sample tool parameter values." }, "call_values": { "type": "object", "additionalProperties": true, "description": "Separate sample call variables." } } } } } }, "responses": { "200": { "description": "Test or discovery result. Inspect the nested ok field; remote failures also return HTTP 200.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "status_text": { "type": "string" }, "duration_ms": { "type": "number" }, "content_type": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "truncated": { "type": "boolean" }, "request": { "type": "object", "additionalProperties": true, "description": "The request that was sent: method, final URL including query parameters, and the JSON body (null for GET and DELETE).", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "body": { "type": [ "string", "null" ] } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/discover": { "post": { "operationId": "discoverTool", "summary": "Discover MCP tool functions", "description": "Discover functions and input schemas offered by an MCP server. Does not execute remote functions. Requires an admin-level credential and assistants:write. OAuth consent must be completed in the browser.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "config" ], "properties": { "tool_id": { "type": "string", "format": "uuid", "description": "Existing tool to reuse masked secrets." }, "config": { "type": "object", "additionalProperties": true, "description": "HTTP or MCP configuration, as accepted when creating this tool type." } } } } } }, "responses": { "200": { "description": "Test or discovery result. Inspect the nested ok field; remote failures also return HTTP 200.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "error": { "type": "string" }, "reason": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/tools/{id}/runs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listToolRuns", "summary": "List reusable tool runs", "description": "Recent executions and statistics over only the returned window. Requires an admin-level credential and assistants:read.", "tags": [ "Tools" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Recent runs and window statistics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/automations/trigger-test-data": { "post": { "tags": [ "Automations" ], "operationId": "getAutomationTriggerTestData", "summary": "Preview or capture conversation trigger data", "description": "Read-only Conversation started testing. Requires automations:read or calls:read and automation access. Samples use the selected channel, assistant variables and widget pre-chat form. Listen without since to arm using server time; poll with the returned since timestamp and source_id. Does not activate or execute automations. Real conversations can still execute active automations and use credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trigger", "mode" ], "properties": { "trigger": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "conversation.started" ] }, "assistant_id": { "type": "string", "format": "uuid" }, "connector_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "sample", "listen" ] }, "source_id": { "type": "string", "format": "uuid", "description": "Test source from the response sources list. Required when multiple connections match." }, "since": { "type": "string", "format": "date-time", "description": "Server timestamp from the arming response. Maximum lookback: 10 minutes." } } } } } }, "responses": { "200": { "description": "Success envelope containing payload (null while waiting or before choosing a source), source (sample/live), since, sources, selected_source and assistant_name." }, "400": { "description": "Invalid trigger, source or timestamp" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing scope or automation access" } } } }, "/integrations/meetergo/meeting-types": { "post": { "operationId": "listMeetergoMeetingTypes", "summary": "List meetergo meeting types", "description": "Discover enabled meeting types with scheduling access. Supply a token for a new connection or the ID of an existing active integration to reuse its saved credential. Requires a plan with Calendar integrations and either a workspace service-account credential or a user-owned owner/admin credential. Required scope: integrations:read.", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "writeOnly": true, "description": "Personal token (rgo-) or platform API key (ak_live:). Omit when reusing a saved integration." }, "integration_id": { "type": "string", "format": "uuid" }, "acting_user_id": { "type": "string", "format": "uuid", "description": "Required only for platform API keys. Omit for personal tokens." } } } } } }, "responses": { "200": { "description": "Successful calendar result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "meeting_types" ], "properties": { "meeting_types": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "duration" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "duration": { "type": "number", "description": "Duration in minutes." } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The provider could not complete the request. After a booking request, check the calendar before retrying." } } } }, "/integrations/meetergo/action": { "post": { "operationId": "executeMeetergoCalendarAction", "summary": "Check availability or book with meetergo", "description": "Uses an active meetergo integration in the current workspace. Availability requires integrations:read; booking requires integrations:write, enabled booking permission and confirmation from the attendee. Availability works with a workspace service-account credential or a user-owned owner/admin credential; booking requires a user-owned owner/admin credential. Check availability first and book an exact returned start. The provider is checked again before writing. A pending_confirmation result is not a confirmed booking. Never automatically retry a booking with an unknown outcome.", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "integration_id", "action", "start", "end" ], "properties": { "integration_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "slots" ] }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." }, "timezone": { "type": "string", "description": "Fallback timezone when the integration has no saved timezone." }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." } } }, { "type": "object", "required": [ "integration_id", "action", "start", "name", "email" ], "properties": { "integration_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "book" ] }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." }, "timezone": { "type": "string", "description": "Fallback timezone when the integration has no saved timezone." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 40 } } } ] } } } }, "responses": { "200": { "description": "Successful calendar result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "slots", "timezone" ], "properties": { "slots": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." }, "end": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." } } } }, "timezone": { "type": "string" } } }, { "type": "object", "required": [ "appointment_id", "booking_state", "start" ], "properties": { "appointment_id": { "type": "string", "nullable": true }, "booking_state": { "type": "string", "enum": [ "confirmed", "pending_confirmation" ] }, "start": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp with timezone offset." }, "message": { "type": "string" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The provider could not complete the request. After a booking request, check the calendar before retrying." } } } }, "/team-members": { "get": { "operationId": "listTeamMembers", "summary": "List team members", "description": "List the current workspace team. Requires owner or admin access and settings:read.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer", "billing" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "joined_at": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid input or target account not ready." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Member not found in the current workspace." }, "409": { "description": "Ownership changed or the requested transfer conflicts with workspace ownership." } } } }, "/team-members/{id}": { "patch": { "operationId": "updateTeamMemberRole", "summary": "Change team member role", "description": "Change a non-owner member role. Requires owner or admin access and settings:write. Use the ownership transfer operation to appoint a new owner.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer", "billing" ] } } } } } } } }, "400": { "description": "Invalid input or target account not ready." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Member not found in the current workspace." }, "409": { "description": "Ownership changed or the requested transfer conflicts with workspace ownership." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "admin", "member", "viewer", "billing" ] } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Membership ID from List team members." } ] } }, "/workspace/transfer-ownership": { "post": { "operationId": "transferWorkspaceOwnership", "summary": "Transfer workspace ownership", "description": "Appoint an existing active, verified member as owner. Requires settings:write and a user-owned credential belonging to the current owner; service-account credentials cannot transfer ownership. The previous owner stays as admin. Plan, credits, numbers, workspace data, payment methods and billing details are preserved. Read the current owner from List team members and provide their user ID as the expected owner to reject stale requests. The previous owner’s user-bound API and OAuth credentials may be revoked by the role change; service-account credentials remain in place. The previous owner’s personal API keys and OAuth access for this workspace are revoked; workspace service credentials stay active.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "owner_member_id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" }, "previous_owner_user_id": { "type": "string", "format": "uuid" }, "previous_owner_role": { "type": "string", "const": "admin" } } } } } } } }, "400": { "description": "Invalid input or target account not ready." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Member not found in the current workspace." }, "409": { "description": "Ownership changed or the requested transfer conflicts with workspace ownership." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "member_id", "expected_owner_user_id" ], "properties": { "member_id": { "type": "string", "format": "uuid", "description": "Target membership ID in the current workspace." }, "expected_owner_user_id": { "type": "string", "format": "uuid", "description": "Current owner user ID from List team members." } } } } } } } }, "/assistants/avatar-gallery": { "get": { "summary": "List assistant picture gallery", "operationId": "listAssistantAvatarGallery", "description": "Lists the mascot pictures available to the active workspace, with light and dark previews. An empty items array means this workspace uses custom uploads. Select a returned id with setAssistantAvatar. Requires assistants:read.", "tags": [ "Assistants" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Available gallery pictures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "category", "light_url", "dark_url" ], "properties": { "id": { "type": "string", "description": "Stable picture id; pass as gallery_id when setting the assistant picture." }, "name": { "type": "string", "description": "English display name." }, "light_url": { "type": "string", "description": "Preview image for the light appearance." }, "dark_url": { "type": "string", "description": "Preview image for the dark appearance." }, "country_code": { "type": "string", "description": "Optional ISO 3166-1 alpha-2 country code." }, "category": { "type": "string", "enum": [ "portraits", "outfits", "countries", "scenes", "specials" ], "description": "Gallery category." }, "pose": { "type": "string", "enum": [ "stand", "wave", "cheer" ], "description": "Optional mascot pose." }, "kind": { "type": "string", "enum": [ "flag", "costume" ], "description": "Optional country variant." } } } } } } } } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Missing assistants:read scope." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } }, "/history/reply": { "post": { "operationId": "replyToHistoryConversation", "summary": "Reply to a conversation", "description": "Send a human reply to an email or messaging conversation and pause AI replies. Required scope: calls:write. Attachments are supported for email, WhatsApp, Telegram, Slack and Discord. Email accepts up to five files; messaging accepts one. Total decoded file size is limited to 3 MB. Text can be empty when attaching a file. Channel permissions and WhatsApp reply windows still apply. delivery_status=unconfirmed means that delivery may have occurred: inspect the channel before retrying to avoid duplicates. SMS requires plain text within one segment: 160 GSM-7 units or 70 UTF-16 units. Oversized replies are rejected, never truncated.", "tags": [ "History" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "email", "messaging" ], "description": "Conversation channel type." }, "id": { "type": "string", "format": "uuid", "description": "Messaging conversation ID or an email message ID in the thread." }, "text": { "type": "string", "maxLength": 8000, "description": "Reply text. Optional when attaching a file." }, "attachments": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "filename", "type", "content" ], "properties": { "filename": { "type": "string", "maxLength": 240, "description": "Filename shown to the recipient." }, "type": { "type": "string", "description": "MIME type, for example application/pdf." }, "content": { "type": "string", "format": "byte", "maxLength": 4194304, "writeOnly": true, "description": "Base64 file bytes without a data URL prefix." } } }, "description": "File attachments encoded as base64; up to 3 MB total. Messaging supports one file." } } } } } }, "responses": { "200": { "description": "Reply accepted or delivery requires confirmation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "readOnly": true, "description": "History identifier for the reply or conversation." }, "ai_paused": { "type": "boolean", "readOnly": true, "description": "Whether AI replies are paused." }, "delivery_status": { "type": "string", "enum": [ "sent", "unconfirmed" ], "readOnly": true, "description": "Check the external channel before retrying an unconfirmed reply." } } } } } }, "400": { "description": "Invalid action, kind, or ids." }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Missing scope." }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `billing:write`, `settings:write`, `platform:read`, `platform:write`; a `*:write` scope implies the matching `*:read`. Automation and dashboard endpoints also accept the legacy `calls:*` scope. Keys without scope restrictions have full access within the workspace's available capabilities." } }, "parameters": { "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size (1–200)." }, "offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, "LoopResourceId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace-scoped Loop resource ID." } }, "responses": { "BadRequest": { "description": "Invalid request body or parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "\"to_number\" is required (E.164 format, e.g. +4930123456)." } } } } }, "Unauthorized": { "description": "Missing, invalid, expired or revoked API key / access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } }, "Forbidden": { "description": "The credential lacks the required scope or role, or the workspace does not have the required capability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "scopeDenied": { "summary": "Required scope is missing", "value": { "error": { "code": "forbidden", "message": "This API key is missing the required scope \"assistants:write\"." } } }, "apiAccessRequired": { "summary": "API Access is not available", "value": { "error": { "code": "api_access_required", "message": "API Access is not available for this workspace. Review Settings → Plan." } } } } } } }, "NotFound": { "description": "Resource not found (or it belongs to another workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Assistant not found" } } } } }, "Conflict": { "description": "The resource is in a conflicting state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "conflict", "message": "Campaign is not running." } } } } }, "TelephonyConfigurationError": { "description": "Outbound calling is not configured for the selected assistant, number, or workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "telephony_configuration_error", "message": "No outbound-capable number is connected to this assistant or workspace." } } } } }, "TelephonyUnavailable": { "description": "Outbound calling is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "telephony_unavailable", "message": "Outbound calling is temporarily unavailable." } } } } }, "RateLimited": { "description": "Too many requests. Retry after the indicated delay.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests. Retry after the indicated delay." } } } } }, "RequestProtectionUnavailable": { "description": "Request protection is temporarily unavailable.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Request protection is temporarily unavailable." } } } } }, "AvailabilityOrProtectionUnavailable": { "description": "Either request protection is temporarily unavailable (code `internal_error`), or, specifically for this endpoint, the availability engine could not be reached (code `service_unavailable`, message \"Could not load availability\"). Retry after a short delay in both cases.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "requestProtectionUnavailable": { "summary": "Request protection unavailable", "value": { "error": { "code": "internal_error", "message": "Request protection is temporarily unavailable." } } }, "availabilityUnavailable": { "summary": "Availability engine failed to load", "value": { "error": { "code": "service_unavailable", "message": "Could not load availability" } } } } } } } }, "schemas": { "AssistantAnnouncementAudio": { "type": "object", "required": [ "revision", "status", "items", "updated_at" ], "properties": { "revision": { "type": "integer", "minimum": 0, "description": "Saved preparation revision; a changed revision invalidates older previews." }, "status": { "type": "string", "enum": [ "idle", "queued", "preparing", "ready", "partial", "unavailable", "failed" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "maxItems": 16, "items": { "type": "object", "required": [ "key", "purpose", "status", "duration_seconds", "preview_url", "reason" ], "properties": { "key": { "type": "string", "description": "Stable announcement identity within this assistant. Multiple farewell actions may have separate entries." }, "purpose": { "type": "string", "enum": [ "greeting", "consent", "farewell" ] }, "status": { "type": "string", "enum": [ "pending", "generating", "ready", "failed", "skipped" ] }, "duration_seconds": { "type": [ "number", "null" ], "description": "Prepared audio length in seconds." }, "preview_url": { "type": [ "string", "null" ], "description": "Relative authenticated audio endpoint on the same domain. Send the same Bearer credential; never publish this link as public audio." }, "reason": { "type": [ "string", "null" ], "description": "Customer-facing explanation when preparation cannot be used." } } } } } }, "KnowledgeTableQuery": { "type": "object", "description": "Exact table lookup or aggregate (rows, count, sum, min, max) on one sheet; use instead of `query`. Take `document_id`, `sheet` and column keys from earlier search results.", "additionalProperties": false, "required": [ "document_id", "sheet" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "sheet": { "type": "string", "maxLength": 200 }, "operation": { "type": "string", "enum": [ "rows", "count", "sum", "min", "max" ], "default": "rows" }, "column": { "type": "string", "description": "Positional key returned by search, e.g. c3." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "filters": { "type": "array", "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "required": [ "column", "operator", "value" ], "properties": { "column": { "type": "string" }, "operator": { "type": "string", "enum": [ "eq", "gt", "gte", "lt", "lte" ] }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean" ], "default": "text" }, "value": { "type": "string", "maxLength": 2000 } } } } } }, "LoopSettingsInput": { "type": "object", "additionalProperties": false, "required": [ "enabled", "default_outbound_number_id", "dialing_country", "recording_enabled", "voicemail_enabled" ], "properties": { "enabled": { "type": "boolean" }, "default_outbound_number_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_route_id": { "type": [ "string", "null" ], "format": "uuid" }, "dialing_country": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$" }, "recording_enabled": { "type": "boolean" }, "voicemail_enabled": { "type": "boolean", "description": "Unused. Famulor Loop does not offer mailbox recording. Always false." } } }, "LoopSettings": { "type": "object", "required": [ "enabled", "default_outbound_number_id", "default_route_id", "dialing_country", "recording_enabled", "voicemail_enabled" ], "properties": { "enabled": { "type": "boolean" }, "default_outbound_number_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_route_id": { "type": [ "string", "null" ], "format": "uuid" }, "dialing_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" }, "recording_enabled": { "type": "boolean" }, "voicemail_enabled": { "type": "boolean", "description": "Unused. Famulor Loop does not offer mailbox recording. Always false." } } }, "LoopRingGroupInput": { "type": "object", "additionalProperties": false, "required": [ "name", "strategy", "ring_timeout_seconds", "presence_required", "active" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "strategy": { "type": "string", "enum": [ "simultaneous", "sequential", "round_robin" ] }, "ring_timeout_seconds": { "type": "integer", "minimum": 5, "maximum": 120 }, "presence_required": { "type": "boolean" }, "active": { "type": "boolean" }, "member_ids": { "type": "array", "maxItems": 100, "deprecated": true, "description": "Legacy member list. Use members for ordered delay settings.", "items": { "type": "string", "format": "uuid" } }, "members": { "type": "array", "maxItems": 100, "description": "Members in ringing order with an optional pre-ring delay.", "items": { "type": "object", "additionalProperties": false, "required": [ "membership_id", "delay_seconds" ], "properties": { "membership_id": { "type": "string", "format": "uuid" }, "delay_seconds": { "type": "integer", "minimum": 0, "maximum": 120 } } } } } }, "LoopRingGroup": { "type": "object", "required": [ "id", "name", "strategy", "ring_timeout_seconds", "presence_required", "active", "members" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "strategy": { "type": "string", "enum": [ "simultaneous", "sequential", "round_robin" ] }, "ring_timeout_seconds": { "type": "integer" }, "presence_required": { "type": "boolean" }, "active": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object", "required": [ "membership_id", "position", "delay_seconds" ], "properties": { "membership_id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "minimum": 0 }, "delay_seconds": { "type": "integer", "minimum": 0 } } } } } }, "LoopQueueInput": { "type": "object", "additionalProperties": false, "required": [ "name", "strategy", "max_wait_seconds", "wrap_up_seconds", "overflow_rule_id", "active" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "strategy": { "type": "string", "enum": [ "longest_idle", "round_robin", "sequential" ] }, "max_wait_seconds": { "type": "integer", "minimum": 10, "maximum": 3600 }, "wrap_up_seconds": { "type": "integer", "minimum": 0, "maximum": 600 }, "overflow_rule_id": { "type": [ "string", "null" ], "format": "uuid" }, "active": { "type": "boolean" }, "member_ids": { "type": "array", "maxItems": 100, "deprecated": true, "description": "Legacy member list. Use members for ordered capacity settings.", "items": { "type": "string", "format": "uuid" } }, "members": { "type": "array", "maxItems": 100, "description": "Members in queue order with concurrent-call capacity.", "items": { "type": "object", "additionalProperties": false, "required": [ "membership_id", "capacity" ], "properties": { "membership_id": { "type": "string", "format": "uuid" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 10 } } } } } }, "LoopQueue": { "type": "object", "required": [ "id", "name", "strategy", "max_wait_seconds", "wrap_up_seconds", "overflow_rule_id", "active", "members" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "strategy": { "type": "string", "enum": [ "longest_idle", "round_robin", "sequential" ] }, "max_wait_seconds": { "type": "integer" }, "wrap_up_seconds": { "type": "integer" }, "overflow_rule_id": { "type": [ "string", "null" ], "format": "uuid" }, "active": { "type": "boolean" }, "members": { "type": "array", "items": { "type": "object", "required": [ "membership_id", "priority", "capacity" ], "properties": { "membership_id": { "type": "string", "format": "uuid" }, "priority": { "type": "integer", "minimum": 0 }, "capacity": { "type": "integer", "minimum": 1 } } } } } }, "LoopRoutingStepInput": { "type": "object", "additionalProperties": false, "required": [ "target_type", "target_id", "external_number", "timeout_seconds", "continue_on" ], "properties": { "target_type": { "type": "string", "enum": [ "member", "extension", "ring_group", "queue", "routing_rule", "assistant", "external" ] }, "target_id": { "type": [ "string", "null" ], "format": "uuid" }, "external_number": { "type": [ "string", "null" ], "pattern": "^\\+[1-9][0-9]{5,14}$" }, "timeout_seconds": { "type": "integer", "minimum": 5, "maximum": 120 }, "continue_on": { "type": "array", "minItems": 1, "description": "Continue only for pre-answer failures. An answered assistant or person is terminal.", "items": { "type": "string", "enum": [ "unavailable", "busy", "timeout", "error" ] } }, "time_condition": { "type": "string", "enum": [ "always", "during_hours", "outside_hours" ], "default": "always", "description": "Selects the step before dialing from the routing rule's shared weekly hours." } } }, "LoopRoutingRuleInput": { "type": "object", "additionalProperties": false, "required": [ "name", "active", "steps" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "active": { "type": "boolean" }, "schedule_enabled": { "type": "boolean", "default": false }, "schedule_timezone": { "type": [ "string", "null" ], "description": "IANA timezone, or null to inherit the workspace timezone." }, "weekly_availability": { "$ref": "#/components/schemas/LoopWeeklyAvailability" }, "steps": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "$ref": "#/components/schemas/LoopRoutingStepInput" } } } }, "LoopRoutingRule": { "type": "object", "required": [ "id", "name", "active", "schedule_enabled", "schedule_timezone", "weekly_availability", "steps" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "schedule_enabled": { "type": "boolean" }, "schedule_timezone": { "type": [ "string", "null" ] }, "weekly_availability": { "$ref": "#/components/schemas/LoopWeeklyAvailability" }, "steps": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/LoopRoutingStepInput" }, { "type": "object", "required": [ "position" ], "properties": { "position": { "type": "integer", "minimum": 0 } } } ] } } } }, "LoopNumberRouteInput": { "type": "object", "additionalProperties": false, "required": [ "target_type", "target_id" ], "properties": { "target_type": { "type": "string", "enum": [ "member", "extension", "ring_group", "queue", "routing_rule", "assistant" ] }, "target_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "LoopNumberRoute": { "type": "object", "required": [ "number_id", "number", "label", "country", "inbound_enabled", "outbound_enabled", "route" ], "properties": { "number_id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "outbound_enabled": { "type": "boolean" }, "route": { "oneOf": [ { "type": "null" }, { "allOf": [ { "$ref": "#/components/schemas/LoopNumberRouteInput" }, { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean" } } } ] } ] } } }, "LoopNumberRouteDeleteResult": { "type": "object", "required": [ "number_id", "deleted" ], "properties": { "number_id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } } }, "LoopOverview": { "type": "object", "required": [ "access", "settings" ], "properties": { "access": { "type": "object", "required": [ "allowed", "reason" ], "properties": { "allowed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "not_authenticated", "plan_required", "workspace_disabled", "member_disabled", "platform_number_required", null ] } } }, "settings": { "type": "object", "required": [ "enabled", "default_outbound_number_id", "default_route_id", "dialing_country", "recording_enabled", "voicemail_enabled" ], "properties": { "enabled": { "type": "boolean" }, "default_outbound_number_id": { "type": [ "string", "null" ], "format": "uuid" }, "default_route_id": { "type": [ "string", "null" ], "format": "uuid" }, "dialing_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" }, "recording_enabled": { "type": "boolean" }, "voicemail_enabled": { "type": "boolean", "description": "Unused. Famulor Loop does not offer mailbox recording. Always false." } } } } }, "LoopDirectoryEntry": { "type": "object", "required": [ "membership_id", "display_name", "extension_id", "extension", "loop_enabled", "presence", "call_state" ], "properties": { "membership_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public profile photo for this Loop member." }, "extension_id": { "type": [ "string", "null" ], "format": "uuid" }, "extension": { "type": [ "string", "null" ] }, "loop_enabled": { "type": "boolean" }, "presence": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "offline" ] }, "call_state": { "type": "string", "enum": [ "idle", "ringing", "busy", "wrap_up" ] }, "self": { "type": "boolean", "description": "True when this directory entry is the authenticated Loop member." } } }, "LoopPresence": { "type": "object", "required": [ "manual_status", "call_state", "reachable_web", "reachable_mobile", "external_sip_provisioned", "expires_at" ], "properties": { "manual_status": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "offline" ] }, "call_state": { "type": "string", "enum": [ "idle", "ringing", "busy", "wrap_up" ] }, "reachable_web": { "type": "boolean" }, "reachable_mobile": { "type": "boolean" }, "external_sip_provisioned": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "LoopDevice": { "type": "object", "required": [ "id", "kind", "label", "platform", "status", "capabilities", "last_seen_at", "last_successful_call_at", "created_at", "activity" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "web", "mobile", "external_sip" ] }, "label": { "type": "string" }, "platform": { "type": [ "string", "null" ], "enum": [ "web", "ios", "android", "sip", null ] }, "status": { "type": "string", "enum": [ "enabled", "revoked" ] }, "capabilities": { "type": "object", "additionalProperties": true }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_successful_call_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "activity": { "type": "string", "enum": [ "recent", "inactive", "unknown" ], "description": "Recent browser activity expires after two minutes without a heartbeat. Native app activity has a longer lifetime for background incoming calls. Unknown means that activity cannot be inferred. This is separate from authorization status; inactive devices can reconnect." } } }, "LoopDeviceRenameInput": { "type": "object", "required": [ "label" ], "additionalProperties": false, "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "LoopDeviceRenameResult": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" } } }, "LoopCallDetail": { "type": "object", "required": [ "id", "direction", "status", "recordings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string" }, "status": { "type": "string" }, "from_address": { "type": [ "string", "null" ] }, "to_address": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "assistant_call_id": { "type": [ "string", "null" ], "format": "uuid" }, "contact": { "oneOf": [ { "$ref": "#/components/schemas/LoopCallContact" }, { "type": "null" } ], "description": "Audience contact linked to this call, or matched by the external party's phone number; null when none." }, "recordings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "loop", "assistant", "voicemail" ] }, "status": { "type": "string" }, "duration_sec": { "type": "integer" }, "url": { "type": [ "string", "null" ], "description": "Private playback link valid for one hour; null while unavailable or processing." } } } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "joined_at": { "type": [ "string", "null" ] }, "left_at": { "type": [ "string", "null" ] } } } }, "from_party": { "oneOf": [ { "$ref": "#/components/schemas/LoopHistoryParty" }, { "type": "null" } ] }, "to_party": { "oneOf": [ { "$ref": "#/components/schemas/LoopHistoryParty" }, { "type": "null" } ] } } }, "LoopCall": { "type": "object", "required": [ "id", "direction", "channel", "transport", "status", "duration_sec", "billable_minutes", "charged_credits", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "channel": { "type": "string", "enum": [ "phone", "web_voice", "whatsapp_voice" ] }, "transport": { "type": "string", "enum": [ "sip", "webrtc", "connector" ] }, "from_address": { "type": [ "string", "null" ] }, "to_address": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed", "busy", "no_answer", "failed", "canceled" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "answered_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_sec": { "type": "integer", "minimum": 0 }, "billable_minutes": { "type": "integer", "minimum": 0 }, "charged_credits": { "type": "number", "minimum": 0 }, "transfer_context": { "type": [ "object", "null" ], "description": "Pre-answer context for an AI transfer offered to this member; null for other calls or when unavailable.", "additionalProperties": false, "required": [ "reason", "summary" ], "properties": { "reason": { "type": "string", "maxLength": 100 }, "summary": { "type": "string", "maxLength": 350 } } }, "contact": { "oneOf": [ { "$ref": "#/components/schemas/LoopCallContact" }, { "type": "null" } ], "description": "Audience contact linked to this call, or matched by the external party's phone number; null when none." }, "created_at": { "type": "string", "format": "date-time" }, "from_party": { "oneOf": [ { "$ref": "#/components/schemas/LoopHistoryParty" }, { "type": "null" } ] }, "to_party": { "oneOf": [ { "$ref": "#/components/schemas/LoopHistoryParty" }, { "type": "null" } ] } } }, "LoopCallContact": { "type": "object", "required": [ "id", "name", "email", "phone" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Audience contact (lead) ID." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Contact phone number in E.164 format." } } }, "LoopRevokeResult": { "type": "object", "required": [ "id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean", "const": true } } }, "LoopWeeklyAvailability": { "type": "object", "additionalProperties": false, "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "properties": { "mon": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "tue": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "wed": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "thu": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "fri": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "sat": { "$ref": "#/components/schemas/LoopAvailabilityDay" }, "sun": { "$ref": "#/components/schemas/LoopAvailabilityDay" } } }, "LoopAvailabilityDay": { "type": "array", "maxItems": 4, "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } } }, "LoopAvailabilityInput": { "type": "object", "additionalProperties": false, "required": [ "schedule_enabled", "weekly_availability", "timezone" ], "properties": { "schedule_enabled": { "type": "boolean" }, "weekly_availability": { "$ref": "#/components/schemas/LoopWeeklyAvailability" }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone, or null to inherit the workspace timezone." }, "fallback": { "$ref": "#/components/schemas/LoopAvailabilityFallbackInput", "description": "Optional. Omit to preserve the saved fallback." }, "recall_appointment_calendar_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional. Bookable workspace calendar used when arranging a Recall appointment. Omit to preserve the saved calendar; null clears it." } } }, "LoopAvailabilityFallbackInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "const": "disabled" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "destination_type", "destination" ], "properties": { "type": { "const": "cold_transfer" }, "destination_type": { "type": "string", "enum": [ "phone", "sip_uri" ] }, "destination": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "assistant_id" ], "properties": { "type": { "const": "assistant" }, "assistant_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "routing_rule_id" ], "properties": { "type": { "const": "routing_rule" }, "routing_rule_id": { "type": "string", "format": "uuid" } } } ] }, "LoopAvailabilityFallback": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "disabled" } } }, { "type": "object", "required": [ "type", "destination_type", "destination" ], "properties": { "type": { "const": "cold_transfer" }, "destination_type": { "type": "string", "enum": [ "phone", "sip_uri" ] }, "destination": { "type": "string" } } }, { "type": "object", "required": [ "type", "assistant" ], "properties": { "type": { "const": "assistant" }, "assistant": { "$ref": "#/components/schemas/LoopRecallAssistant" } } }, { "type": "object", "required": [ "type", "routing_rule" ], "properties": { "type": { "const": "routing_rule" }, "routing_rule": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } ] }, "LoopDialingPreferencesInput": { "type": "object", "additionalProperties": false, "required": [ "dialing_country" ], "properties": { "dialing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO-3166-1 alpha-2 default country." } } }, "LoopDialingPreferences": { "type": "object", "required": [ "dialing_country" ], "properties": { "dialing_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" } } }, "LoopAvailability": { "type": "object", "required": [ "schedule_enabled", "weekly_availability", "timezone", "workspace_timezone", "timezone_source", "available_now", "fallback", "recall_appointment_calendar", "recall_appointment_calendars" ], "properties": { "schedule_enabled": { "type": "boolean" }, "weekly_availability": { "$ref": "#/components/schemas/LoopWeeklyAvailability" }, "timezone": { "type": "string" }, "workspace_timezone": { "type": "string" }, "timezone_source": { "type": "string", "enum": [ "workspace", "personal" ] }, "available_now": { "type": "boolean" }, "fallback": { "$ref": "#/components/schemas/LoopAvailabilityFallback" }, "recall_appointment_calendar": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LoopRecallCalendar" } ] }, "recall_appointment_calendars": { "type": "array", "items": { "$ref": "#/components/schemas/LoopRecallCalendar" } } } }, "LoopRecallCalendar": { "type": "object", "required": [ "id", "name", "status", "provider" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string", "enum": [ "calcom", "calendly", "acuity", "native", "etermin", "highlevel" ] } } }, "LoopRecallAssistant": { "type": "object", "required": [ "id", "name", "avatar_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" } } }, "LoopRecallAttempt": { "type": "object", "required": [ "id", "mode", "state", "assistant_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "member_manual", "assistant_connect", "assistant_appointment" ] }, "state": { "type": "string" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LoopRecall": { "type": "object", "required": [ "id", "to_number", "reason", "status", "origin", "created_at", "updated_at", "assistant", "recall_assistant", "assigned_member", "last_attempt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "to_number": { "type": "string", "description": "Caller number for this Recall item." }, "reason": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "action_required", "completed", "failed", "cancelled" ] }, "origin": { "type": "string", "enum": [ "assistant_scheduled", "missed_transfer", "recall_tool", "member_action" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "assistant": { "oneOf": [ { "$ref": "#/components/schemas/LoopRecallAssistant" }, { "type": "null" } ] }, "recall_assistant": { "oneOf": [ { "$ref": "#/components/schemas/LoopRecallAssistant" }, { "type": "null" } ] }, "assigned_member": { "oneOf": [ { "type": "object", "required": [ "name", "avatar_url" ], "properties": { "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" } } }, { "type": "null" } ] }, "last_attempt": { "oneOf": [ { "$ref": "#/components/schemas/LoopRecallAttempt" }, { "type": "null" } ] } } }, "LoopRecallActionInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action", "idempotency_key" ], "properties": { "action": { "type": "string", "const": "call" }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 200 } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "assistant_id", "mode", "idempotency_key" ], "properties": { "action": { "type": "string", "const": "assistant_call" }, "assistant_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "assistant_connect", "assistant_appointment" ] }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 200 } } }, { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "const": "resolve" } } } ] }, "LoopRecallActionResult": { "oneOf": [ { "type": "object", "required": [ "action", "destination", "attempt" ], "properties": { "action": { "type": "string", "const": "call" }, "destination": { "type": "string" }, "attempt": { "$ref": "#/components/schemas/LoopRecallAttempt" } } }, { "type": "object", "required": [ "action", "call_id", "attempt" ], "properties": { "action": { "type": "string", "const": "assistant_call" }, "call_id": { "type": "string", "format": "uuid" }, "attempt": { "$ref": "#/components/schemas/LoopRecallAttempt" } } }, { "type": "object", "required": [ "action", "recall" ], "properties": { "action": { "type": "string", "const": "resolve" }, "recall": { "$ref": "#/components/schemas/LoopRecall" } } } ] }, "ErrorEnvelope": { "type": "object", "description": "Error envelope returned by every /api/v1 endpoint on failure.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "api_access_required", "not_found", "invalid_request", "rate_limited", "conflict", "telephony_configuration_error", "telephony_unavailable", "destination_forbidden", "internal_error", "service_unavailable" ], "description": "Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable)." }, "message": { "type": "string", "description": "Human-readable description of the error." } } } } }, "DeleteResult": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted resource." }, "deleted": { "type": "boolean", "const": true } } }, "AssistantComplianceReview": { "type": "object", "required": [ "assistant", "case", "advisories" ], "properties": { "assistant": { "type": "object", "required": [ "id", "is_active", "compliance_status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "compliance_status": { "type": "string", "enum": [ "clear", "scanning", "blocked", "review_requested", "scan_error" ] }, "compliance_blocked_at": { "type": [ "string", "null" ], "format": "date-time" }, "compliance_last_scan_at": { "type": [ "string", "null" ], "format": "date-time" }, "compliance_last_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } } }, "case": { "type": [ "object", "null" ], "description": "Customer-visible current case. Internal prompt snapshots and classifier infrastructure are omitted." }, "advisories": { "type": "array", "readOnly": true, "description": "Current saved-content advisory tags. Restricted uses require written approval but do not deactivate the assistant. EU high-risk-use notices remind the operator to check oversight and information duties.", "items": { "type": "object", "required": [ "code", "label" ], "properties": { "code": { "type": "string", "enum": [ "restricted_gambling", "restricted_credit_services", "restricted_high_risk_finance", "restricted_regulated_products", "restricted_weapons_trade", "restricted_crisis_services", "restricted_political_campaigns", "eu_high_risk_use" ] }, "label": { "type": "string", "description": "Readable policy tag" }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "source_field": { "type": "string", "description": "Saved source containing the finding" }, "evidence": { "type": "string", "description": "Short matching source excerpt" }, "explanation": { "type": "string", "description": "Context for reviewing the advisory" } } } } } }, "ResponseByChannel": { "type": "object", "additionalProperties": false, "description": "Versioned manual response instructions for exact output channels. Omit a channel key to use Automatic. Manual instructions supplement and never replace safety, language, tool, or delivery rules. Requires the workspace's Manual channel responses feature.", "properties": { "version": { "type": "integer", "const": 1 }, "overrides": { "type": "object", "maxProperties": 24, "propertyNames": { "enum": [ "sms", "phone", "web_voice", "web_chat", "whatsapp_voice", "email", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "additionalProperties": { "anyOf": [ { "type": "string", "const": "", "description": "Clear this channel override and return it to Automatic." }, { "type": "string", "minLength": 1, "maxLength": 1500, "pattern": "\\S" } ] }, "description": "At most 8000 Unicode characters across all values. Empty strings clear an override; whitespace-only strings are rejected." } }, "required": [ "version", "overrides" ] }, "Assistant": { "type": "object", "description": "A voice assistant configuration. Nullable model overrides are independent per engine: pipeline uses `llm_*`, realtime uses `realtime_*`, and half-cascade uses `half_cascade_*` for its text-capable realtime input plus `tts_*` for output.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 20, "description": "Free-form workspace tags for filtering assistants. Case-insensitive unique; original spelling is kept." }, "is_active": { "type": "boolean", "description": "Disabled assistants cannot receive or place calls." }, "compliance_status": { "type": "string", "enum": [ "clear", "scanning", "blocked", "review_requested", "scan_error" ], "description": "Server-managed result of the latest prompt and greeting compliance workflow." }, "compliance_blocked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the assistant was blocked. Null when it is not compliance-blocked." }, "compliance_last_scan_at": { "type": [ "string", "null" ], "format": "date-time" }, "compliance_last_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "demo_enabled": { "type": "boolean", "readOnly": true, "description": "Whether the assistant's public demo link is on. The link is managed in the dashboard and is not returned by the API." }, "demo_expires_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the public demo link stops working; null means it does not expire." }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "system_prompt": { "type": "string" }, "response_by_channel": { "$ref": "#/components/schemas/ResponseByChannel" }, "mode": { "type": "string", "enum": [ "pipeline", "realtime", "half_cascade", "translation" ], "description": "Assistant engine: Pipeline, Realtime, Half-cascade, or Translate for a two-person interpreter room. The selected mode must be included in the workspace's current plan." }, "realtime_provider": { "type": [ "string", "null" ], "description": "Realtime override/voice provider. `realtime_model=null` follows the owner/platform default." }, "realtime_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "realtime_voice": { "type": [ "string", "null" ], "description": "Compatible native conversation voice. Use a neutral ID returned by the native voice library. Available for Realtime; the chosen variant controls compatibility." }, "llm_provider": { "type": [ "string", "null" ], "enum": [ "openai", "azure", "google", "groq", "anthropic", null ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "llm_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "half_cascade_provider": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "half_cascade_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "llm_temperature": { "type": "number" }, "stt_provider": { "type": "string", "enum": [ "deepgram", "openai", "google", "azure", "soniox", "gladia", "assemblyai", "cartesia", "speechmatics", "xai", "elevenlabs" ], "readOnly": true, "description": "Platform-managed speech recognition provider. Returned for reference; assistant writes cannot override it." }, "stt_language": { "type": "string", "description": "Primary STT language (ISO-639-1)." }, "stt_keyterms": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 100 }, "description": "Speech-recognition glossary for customer, product, and proper names. Plan-gated." }, "stt_keyterm_detection_enabled": { "type": "boolean", "description": "Beta: automatically detect additional call-local keyterms. Detected terms are not persisted." }, "tts_provider": { "type": "string", "enum": [ "cartesia", "elevenlabs", "openai", "google", "azure", "fishaudio", "deepgram", "inworld", "rime", "xai" ] }, "tts_voice": { "type": [ "string", "null" ], "description": "Pipeline or Half-Cascade speech voice. For Full Duplex, retained only for a Pipeline fallback; greetings, consent and tool announcements use realtime_voice. Uploaded greeting audio retains its recorded voice." }, "tts_speed": { "type": "number" }, "tts_emotion": { "type": "array", "items": { "type": "string" }, "example": [ "calm" ], "description": "Legacy array field controlling Dynamic emotions (Expressive Mode) for compatible pipeline and half-cascade voices. Send [\"calm\"] to enable it or an empty array to disable it. On create, omitting the field enables it when supported. Realtime speech models handle expression natively, and text chat never uses voice synthesis." }, "tts_style_prompt": { "type": [ "string", "null" ], "description": "Optional free-text speaking-style instructions for compatible TTS models. Null uses the model default." }, "elevenlabs_stability": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice stability override. Null uses the voice-provider default." }, "elevenlabs_similarity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice similarity override. Null uses the voice-provider default." }, "elevenlabs_style": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice-style exaggeration override. Null uses the voice-provider default." }, "elevenlabs_speaker_boost": { "type": [ "boolean", "null" ], "description": "Speaker-boost override. Null uses the voice-provider default." }, "affective_dialog": { "type": "boolean", "description": "Realtime mode with a Google realtime model only: match the caller's tone with warmer, more expressive speech." }, "turn_detection": { "type": "string", "enum": [ "multilingual_model", "english_model", "vad", "stt" ] }, "vad_min_silence_ms": { "type": "integer" }, "vad_threshold": { "type": [ "number", "null" ], "minimum": 0.1, "maximum": 0.9, "description": "Voice-detection threshold. Null uses the effective engine default: 0.50 for pipeline and adaptive voice detection, 0.50 for web server VAD, and 0.70 for phone server VAD. This detects speech; it does not filter audio." }, "allow_interruptions": { "type": "boolean" }, "min_interruption_duration_ms": { "type": "integer" }, "response_timing": { "type": "string", "enum": [ "snappy", "balanced", "patient" ], "description": "How quickly the assistant answers once the caller pauses: `snappy` answers right away, `balanced` leaves a short pause, `patient` waits longer for callers who pause mid-sentence. Applies to pipeline mode and adaptive realtime turn handling.", "default": "balanced" }, "min_interruption_words": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Pipeline mode only: ignore barge-ins shorter than this many words, so back-channel sounds like “mhm” don't interrupt the assistant. 0 turns it off; larger values are capped at 10.", "default": 0 }, "noise_cancellation": { "type": "string", "enum": [ "bvc", "bvc_telephony", "none" ] }, "preemptive_generation": { "type": "boolean", "description": "Begin response generation before turn confirmation. Effective in pipeline mode only." }, "resume_false_interruption": { "type": "boolean", "description": "Resume interrupted output when an apparent interruption produces no transcript during the two-second false-interruption window. Effective in pipeline mode and adaptive realtime turn handling, and only while interruptions are enabled." }, "max_tool_steps": { "type": "integer" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public URL of the custom assistant picture. Null = default mesh orb in the product UI. Set via POST/DELETE /assistants/{id}/avatar, not PATCH." }, "first_message": { "type": [ "string", "null" ] }, "greeting_mode": { "type": "string", "enum": [ "agent_speaks_first", "user_speaks_first" ] }, "greeting_allow_interruptions": { "type": "boolean", "description": "When true, the caller may barge in during the opening greeting (first message / audio / silence fallback). Default false = play greeting uninterrupted. Separate from allow_interruptions (rest of the call)." }, "ai_speaks_after_silence": { "type": "boolean", "description": "When greeting_mode is user_speaks_first: after ai_entry_timeout_sec of initial silence, the assistant speaks (static or dynamic). Default false." }, "silence_greeting_mode": { "type": "string", "enum": [ "static", "dynamic" ], "description": "static = silence_greeting_message; dynamic = LLM improvises from the system prompt." }, "silence_greeting_message": { "type": "string", "description": "Fixed opening line when ai_speaks_after_silence and silence_greeting_mode=static. Leave empty (\"\") to let the assistant speak the platform default in its configured language." }, "ai_entry_timeout_sec": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Seconds to wait before the silence greeting (1–20). Default 10." }, "pre_call": { "type": "object", "description": "iOS/Android Call Screen Handling. When enabled, the agent identifies itself to call-screening services, then waits for a human. Mirrored into `flow_json.pre_call` when a flow exists.", "properties": { "enabled": { "type": "boolean", "default": false }, "agent_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "flow_json": { "type": [ "object", "null" ], "description": "Flow-builder graph (Flow JSON v1: `{ version: 1, nodes: [...], edges: [...] }`). `null` = Single prompt agent (system_prompt + greeting). Non-null = Conversational flow. Trivial Start→Agent→End skeletons still behave as prompt-only for global transfer tools until the graph is non-trivial or includes Transfer nodes." }, "recording_enabled": { "type": "boolean", "description": "Whether audio recording is enabled for calls handled by this assistant. In PATCH and PUT requests, omitting this field leaves the existing setting unchanged. Saving an explicit boolean (`true` or `false`) updates the setting. Recording calls is independent of Loop recording and voicemail recording; see `/assistants/conversation-quality#consent` for caller consent rules and `/billing/minutes#call-recording` for recording billing." }, "retranscribe_enabled": { "type": "boolean", "description": "Enhanced transcription: after the call, the recording is transcribed again with a higher-accuracy engine and shown next to the live transcript. Only takes effect while `recording_enabled` is on. Billed in credits per recorded minute." }, "card_collect_enabled": { "type": "boolean", "description": "Allows secure payment card collection (the Collect payment card tool and Flow Collect steps of type `credit_card`). Also needs a connected payment account. Switching it on requires a plan that includes payment card collection; otherwise the request fails with HTTP 403." }, "max_call_duration_sec": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 1800, "description": "Maximum call duration in seconds (60–1800). null = unlimited (budget cap still applies)." }, "inbound_ringing_timeout_sec": { "type": "integer", "minimum": 30, "maximum": 120, "description": "How long inbound callers hear ringing before the call times out (30–120 s, default 60). If every concurrent line is busy, callers keep ringing within this time until a line frees up." }, "outbound_ringing_timeout_sec": { "type": "integer", "minimum": 15, "maximum": 80, "description": "How long outbound SIP/WhatsApp calls ring before no-answer (15–80 s, default 45)." }, "amd_enabled": { "type": "boolean", "default": false, "description": "Answering machine detection on direct outbound calls (dashboard, API, automations, callbacks). New assistants default to `false`: the assistant greets as soon as the call is answered and mailboxes are not detected. Campaign calls use the campaign's `amd_enabled`." }, "voicemail_enabled": { "type": "boolean", "default": false, "description": "What a direct outbound call does at a detected mailbox: `true` = speak `voicemail_message`, then hang up; `false` = hang up without a message. Takes effect while `amd_enabled` is on. Campaign calls use the campaign's voicemail settings." }, "voicemail_message": { "type": "string", "nullable": true, "description": "Message spoken onto a detected mailbox when `voicemail_enabled` is `true`; supports `{{variables}}`. `null` or empty = the greeting / first message is used." }, "idle_timeout_sec": { "type": "integer" }, "transcription_timeout_sec": { "type": [ "number", "null" ], "minimum": 1, "maximum": 30, "description": "Seconds after speech is detected with no transcript before the assistant asks the caller to repeat. null disables. Distinct from idle_timeout_sec." }, "knowledgebase_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Attached knowledge base (RAG)." }, "knowledge_gap_mode": { "type": "string", "enum": [ "off", "questions_only", "draft_for_review", "tentative_live" ], "default": "draft_for_review", "description": "Beta behavior after a successful knowledge-base search has no relevant result." }, "webhook_url": { "type": [ "string", "null" ], "description": "Agent-level webhook that receives `call.completed` with transcript, duration, input variables and post-call analysis." }, "webhook_timeout_sec": { "type": "integer", "minimum": 1, "maximum": 30, "default": 5, "description": "Max seconds to wait for the agent-level webhook response." }, "webhook_retries": { "type": "integer", "minimum": 0, "maximum": 5, "default": 2, "description": "Extra delivery attempts after the first failure. Total tries = 1 + retries." }, "webhook_delivery_mode": { "type": "string", "enum": [ "none", "custom", "automation" ], "description": "none = do not deliver; custom = POST the assistant webhook URL after the call; automation = deliver through the bound automation." }, "automation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Bound automation when webhook delivery is automation." }, "notification_settings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "email": { "type": "boolean" }, "push": { "type": "boolean" }, "sms": { "type": "boolean", "description": "Reserved for a future channel." } } }, "example": { "call": { "email": false }, "whatsapp": { "push": false } }, "description": "Activity notifications for this assistant, keyed by History channel (`call`, `avatar`, `live_chat`, `whatsapp_voice`, `whatsapp`, `telegram`, `slack`, `messenger`, `teams`, `discord`, `gchat`, `x`, `freshdesk`, `gmail`, `outlook`, `zendesk`, `servicenow`, `intercom`, `zoho_mail`, `agent_mail`, `instagram`, `zulip`, `email`; the legacy key `messaging` applies to every messaging channel). Each channel takes `email` and `push` toggles. A missing channel or toggle stays on; set it to `false` to opt out. Unknown keys are dropped." }, "metadata": { "type": "object", "additionalProperties": true }, "outbound_phone_number_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Workspace phone number this assistant calls from on outbound calls (an `id` from `GET /phone-numbers`). Several assistants can share one number. A `phone_number_id` passed when starting a call takes precedence. Null clears it." }, "background_audio": { "type": "object", "additionalProperties": true, "description": "BackgroundAudioPlayer config (`ambient`, `ambient_volume`, `thinking`, `thinking_volume`). `{}` = off. Hold music is configured on the warm-transfer tool, not here." }, "adaptive_interruptions": { "type": "boolean" }, "realtime_turn_mode": { "type": "string", "enum": [ "server_vad", "semantic", "adaptive" ], "default": "server_vad", "description": "Realtime turn handling: robust voice activity, semantic completion, or adaptive barge-in. Adaptive distinguishes short acknowledgements from intentional interruptions." }, "realtime_eagerness": { "type": "string", "enum": [ "auto", "low", "medium", "high" ], "default": "auto", "description": "How quickly the assistant responds when realtime_turn_mode is semantic." }, "long_call_memory": { "type": "string", "enum": [ "full", "recent" ], "description": "Pipeline mode only: context strategy once a call runs long. `full` keeps the whole conversation in context; `recent` keeps the latest part in focus for faster responses on calls of 10+ minutes.", "default": "full" }, "idle_messages": { "type": "array", "items": { "type": "string" }, "description": "Fixed re-engagement phrases on caller inactivity; `[]` = LLM-generated." }, "idle_max_rounds": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Unanswered idle check-ins before the assistant says goodbye and ends the call (1–10, default 2)." }, "fallback_config": { "type": "object", "additionalProperties": true, "description": "Requires Fallbacks & Guardrails. Saved fallback configuration is omitted from responses without this workspace entitlement." }, "fallbacks_enabled": { "type": "boolean", "description": "Turns on platform-managed model fallbacks, so a call continues on a backup model if a speech or language model fails. Must be a boolean. Switching it on requires Fallbacks & Guardrails; otherwise the request fails with HTTP 403." }, "pronunciation_map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Word → spoken-form replacements, e.g. `{\"API\": \"A P I\"}`." }, "tts_filter_markdown": { "type": "boolean" }, "tts_filter_emoji": { "type": "boolean" }, "consent_enabled": { "type": "boolean", "description": "Ask for consent at call start. What the consent covers is set by consent_covers_recording and consent_covers_memory." }, "consent_text": { "type": [ "string", "null" ], "description": "Spoken announcement. It must name every purpose that is switched on; leave null to use a purpose- and language-aware default." }, "consent_mode": { "type": "string" }, "consent_decline_action": { "type": "string", "enum": [ "no_recording", "hangup" ], "description": "What happens when the caller declines consent: `no_recording` continues the call without recording, `hangup` says a farewell and ends the call." }, "consent_decline_text": { "type": [ "string", "null" ], "description": "Custom farewell spoken before the call ends when the caller declines consent and `consent_decline_action` is `hangup`. Null or empty uses the default farewell for the assistant's language." }, "consent_covers_recording": { "type": "boolean", "description": "Consent covers call recording. Recording additionally requires recording_enabled, and is skipped entirely when recording_enabled is true while this is false." }, "consent_covers_memory": { "type": "boolean", "description": "Consent covers durable customer memory. A granted consent sets contact_memories.consent_status; a declined one leaves it unknown, so the caller is asked again on a later call." }, "guardrails": { "type": "object", "additionalProperties": true, "description": "Topic filters and forced escalation; `{}` = off." }, "language_voices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-language voice overrides for Pipeline/Half-cascade, e.g. `{\"de\": \"voiceX\"}`. Only explicit map entries override the main voice. A private per-language clone is allowed only when the main voice is also a workspace-owned private clone that uses the same provider runtime." }, "auto_language_switch": { "type": "boolean", "description": "Automatic response-language switching. The dashboard derives this as true whenever secondary_languages is non-empty." }, "output_volume": { "type": "number", "description": "1.0 = neutral." }, "speaking_rate": { "type": "number", "description": "1.0 = neutral." }, "text_only_enabled": { "type": "boolean", "description": "Enables the text chat channel; no effect on telephony." }, "memory_enabled": { "type": "boolean", "description": "Caller recognition across calls (agent memory)." }, "memory_mode": { "type": "string", "enum": [ "inherit", "on", "off" ], "description": "Caller memory for this assistant: `inherit` follows the workspace default (`GET /settings/memory`), `on`/`off` override it. `memory_enabled` is the legacy boolean." }, "memory_scope": { "type": "string", "enum": [ "workspace", "assistant", "both" ], "description": "Where conversation memory is stored: `workspace` = one summary shared across all assistants, `assistant` = one summary private to this assistant, `both` = two complete summaries (one workspace-wide and one assistant-private; default for new assistants)." }, "lead_attribute_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "Workspace contact-field access. `all` is an immutable compatibility state for assistants that already had unrestricted access: it cannot be selected on create or enabled by update (HTTP 400). `selected` exposes only explicit `source: lead` definitions and is the default for new assistants." }, "memory_read_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Channels allowed to read this assistant's memory. The effective policy is the intersection with the workspace channel allowlist; an empty array disables reads." }, "memory_write_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Channels allowed to update this assistant's memory. The effective policy is the intersection with the workspace channel allowlist; an empty array disables writes." }, "memory_categories": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "identity", "preferences", "agreements", "open_items" ] }, "description": "Long-term fact categories the assistant may summarize. An empty array keeps consent/audit/interaction metadata but creates no new content summary." }, "redact_pii": { "type": "boolean", "description": "Redact PII in stored transcripts. When true, `pii_redaction.entities` selects which categories are masked." }, "pii_redaction": { "type": "object", "description": "Selected PII entity keys and optional custom regexes. Empty `entities` uses email/phone/iban/card defaults.", "properties": { "entities": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pattern": { "type": "string" } } } } } }, "analysis_config": { "$ref": "#/components/schemas/AnalysisConfig" }, "qa_scorecard_config": { "oneOf": [ { "$ref": "#/components/schemas/QaScorecardConfig" }, { "type": "null" } ], "description": "AI QA scorecard configuration (requires AI QA Scorecards in the workspace plan). `null` or `enabled: false` disables scoring." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "description": "IANA timezone of the assistant (e.g. `Europe/Berlin`, default). Anchors the `get_current_time` system tool, the `{{time}}`/`{{date}}`/`{{datetime}}`/`{{weekday}}` system variables, and the `check_business_hours` built-in tool. On campaign calls the campaign's timezone overrides it per call." }, "primary_language": { "type": "string", "description": "Language the assistant answers in by default (ISO 639-1 or ISO 639-3, see `GET /languages`)." }, "secondary_languages": { "type": "array", "items": { "type": "string" }, "description": "Languages the assistant may switch to when the caller clearly speaks them (ISO 639-1 or ISO 639-3). Non-empty implies multilingual STT + auto language switch." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" }, "description": "Custom variable definitions, referenced as `{{key}}` and resolved per call (explicit call values > inbound enrichment > current contact values > remembered value > default_value). Each custom definition can be call-only, workspace-shared, or assistant-private." }, "variable_webhook_url": { "type": [ "string", "null" ], "description": "Optional webhook called on inbound calls to enrich variable values before the conversation starts." }, "builtin_tools": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltinTool" }, "description": "Inline built-in tool configurations (also accepted as `tools` for compatibility). DTMF Input and Collect Keypad Input run as prompt-session tools here; dedicated Flow nodes bind their reusable central-tool equivalents." }, "translation_config": { "$ref": "#/components/schemas/TranslationConfig" }, "realtime_variant": { "type": "string", "enum": [ "standard", "full_duplex" ], "description": "Realtime conversation variant. Full Duplex requires workspace Beta features, Realtime plan access and compatible defaults available in the selected workspace region; extra credits may apply. Its reasoning model is managed centrally. Existing assistants use standard.", "default": "standard" } }, "required": [ "id", "name", "is_active", "system_prompt", "mode", "created_at", "updated_at" ] }, "AssistantInput": { "type": "object", "description": "Writable assistant fields. Unknown fields are ignored. Non-null engine model overrides require the Fallbacks & Guardrails add-on and are validated against the assistant owner's effective catalog access and engine compatibility. Null resets to the next default level.", "properties": { "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 20, "description": "Free-form workspace tags for filtering assistants. Case-insensitive unique; original spelling is kept." }, "is_active": { "type": "boolean" }, "system_prompt": { "type": "string" }, "response_by_channel": { "$ref": "#/components/schemas/ResponseByChannel" }, "mode": { "type": "string", "enum": [ "pipeline", "realtime", "half_cascade", "translation" ], "description": "Assistant engine: Pipeline, Realtime, Half-cascade, or Translate for a two-person interpreter room. The selected mode must be included in the workspace's current plan." }, "realtime_provider": { "type": [ "string", "null" ] }, "realtime_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "realtime_voice": { "type": [ "string", "null" ], "description": "Compatible native conversation voice. Use a neutral ID returned by the native voice library. Available for Realtime; the chosen variant controls compatibility." }, "llm_provider": { "type": [ "string", "null" ], "enum": [ "openai", "azure", "google", "groq", "anthropic", null ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "llm_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "half_cascade_provider": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "half_cascade_model": { "type": [ "string", "null" ], "description": "Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement." }, "llm_temperature": { "type": "number" }, "stt_provider": { "type": "string", "enum": [ "deepgram", "openai", "google", "azure", "soniox", "gladia", "assemblyai", "cartesia", "speechmatics", "xai", "elevenlabs" ], "readOnly": true, "description": "Platform-managed speech recognition provider. Returned for reference; assistant writes cannot override it." }, "stt_language": { "type": "string" }, "stt_keyterms": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 100 }, "description": "Speech-recognition glossary for customer, product, and proper names. Plan-gated." }, "stt_keyterm_detection_enabled": { "type": "boolean", "description": "Beta: automatically detect additional call-local keyterms. Detected terms are not persisted." }, "tts_provider": { "type": "string", "enum": [ "cartesia", "elevenlabs", "openai", "google", "azure", "fishaudio", "deepgram", "inworld", "rime", "xai" ] }, "tts_voice": { "type": [ "string", "null" ], "description": "Pipeline or Half-Cascade speech voice. For Full Duplex, retained only for a Pipeline fallback; greetings, consent and tool announcements use realtime_voice. Uploaded greeting audio retains its recorded voice. Must be able to speak the primary and secondary languages." }, "tts_speed": { "type": "number" }, "tts_emotion": { "type": "array", "items": { "type": "string" }, "example": [ "calm" ], "description": "Legacy array field controlling Dynamic emotions (Expressive Mode) for compatible pipeline and half-cascade voices. Omit on create to enable it when supported. Send [] to disable it or [\"calm\"] to enable it. Realtime speech models handle expression natively." }, "tts_style_prompt": { "type": [ "string", "null" ], "description": "Optional free-text speaking-style instructions for compatible TTS models. Send null to clear the override." }, "elevenlabs_stability": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice stability override. Send null to use the voice-provider default." }, "elevenlabs_similarity": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice similarity override. Send null to use the voice-provider default." }, "elevenlabs_style": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Voice-style exaggeration override. Send null to use the voice-provider default." }, "elevenlabs_speaker_boost": { "type": [ "boolean", "null" ], "description": "Speaker-boost override. Send null to use the voice-provider default." }, "affective_dialog": { "type": "boolean", "description": "Realtime mode with a Google realtime model only: match the caller's tone with warmer, more expressive speech." }, "turn_detection": { "type": "string", "enum": [ "multilingual_model", "english_model", "vad", "stt" ] }, "vad_min_silence_ms": { "type": "integer" }, "vad_threshold": { "type": [ "number", "null" ], "minimum": 0.1, "maximum": 0.9, "description": "Voice-detection threshold. Null uses the effective engine default: 0.50 for pipeline and adaptive voice detection, 0.50 for web server VAD, and 0.70 for phone server VAD. This detects speech; it does not filter audio." }, "allow_interruptions": { "type": "boolean" }, "min_interruption_duration_ms": { "type": "integer" }, "response_timing": { "type": "string", "enum": [ "snappy", "balanced", "patient" ], "description": "How quickly the assistant answers once the caller pauses: `snappy` answers right away, `balanced` leaves a short pause, `patient` waits longer for callers who pause mid-sentence. Applies to pipeline mode and adaptive realtime turn handling." }, "min_interruption_words": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Pipeline mode only: ignore barge-ins shorter than this many words, so back-channel sounds like “mhm” don't interrupt the assistant. 0 turns it off; larger values are capped at 10." }, "noise_cancellation": { "type": "string", "enum": [ "bvc", "bvc_telephony", "none" ] }, "preemptive_generation": { "type": "boolean", "description": "Begin response generation before turn confirmation. Effective in pipeline mode only." }, "resume_false_interruption": { "type": "boolean", "description": "Resume interrupted output when an apparent interruption produces no transcript during the two-second false-interruption window. Effective in pipeline mode and adaptive realtime turn handling, and only while interruptions are enabled." }, "max_tool_steps": { "type": "integer" }, "first_message": { "type": [ "string", "null" ] }, "greeting_mode": { "type": "string", "enum": [ "agent_speaks_first", "user_speaks_first" ] }, "greeting_allow_interruptions": { "type": "boolean", "description": "When true, the caller may barge in during the opening greeting (first message / audio / silence fallback). Default false = play greeting uninterrupted. Separate from allow_interruptions (rest of the call)." }, "ai_speaks_after_silence": { "type": "boolean", "description": "When greeting_mode is user_speaks_first: after ai_entry_timeout_sec of initial silence, the assistant speaks (static or dynamic). Default false." }, "silence_greeting_mode": { "type": "string", "enum": [ "static", "dynamic" ] }, "silence_greeting_message": { "type": "string" }, "ai_entry_timeout_sec": { "type": "integer", "minimum": 1, "maximum": 20 }, "pre_call": { "type": "object", "description": "iOS/Android Call Screen Handling. Mirrored into flow_json.pre_call when a flow exists.", "properties": { "enabled": { "type": "boolean" }, "agent_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } } }, "flow_json": { "type": [ "object", "null" ], "description": "Agent type. Omit or `null` = Single prompt (default). Object = Conversational flow (Flow JSON v1). Seed Start→Agent→End for a basic flow; non-trivial graphs may require the Flow builder feature in the workspace plan. In flow mode, `system_prompt` is the Advanced / base prompt (agent-node text is appended)." }, "recording_enabled": { "type": "boolean", "description": "Whether audio recording is enabled for calls handled by this assistant. In PATCH and PUT requests, omitting this field leaves the existing setting unchanged. Saving an explicit boolean (`true` or `false`) updates the setting. Recording calls is independent of Loop recording and voicemail recording; see `/assistants/conversation-quality#consent` for caller consent rules and `/billing/minutes#call-recording` for recording billing." }, "retranscribe_enabled": { "type": "boolean", "description": "Enhanced transcription: after the call, the recording is transcribed again with a higher-accuracy engine and shown next to the live transcript. Only takes effect while `recording_enabled` is on. Billed in credits per recorded minute." }, "card_collect_enabled": { "type": "boolean", "description": "Allows secure payment card collection (the Collect payment card tool and Flow Collect steps of type `credit_card`). Also needs a connected payment account. Switching it on requires a plan that includes payment card collection; otherwise the request fails with HTTP 403." }, "max_call_duration_sec": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 1800, "description": "Maximum call duration in seconds (60–1800). null = unlimited (budget cap still applies)." }, "inbound_ringing_timeout_sec": { "type": "integer", "minimum": 30, "maximum": 120, "description": "How long inbound callers hear ringing before the call times out (30–120 s, default 60). If every concurrent line is busy, callers keep ringing within this time until a line frees up." }, "outbound_ringing_timeout_sec": { "type": "integer", "minimum": 15, "maximum": 80, "description": "How long outbound SIP/WhatsApp calls ring before no-answer (15–80 s, default 45)." }, "amd_enabled": { "type": "boolean", "default": false, "description": "Answering machine detection on direct outbound calls (dashboard, API, automations, callbacks). New assistants default to `false`: the assistant greets as soon as the call is answered and mailboxes are not detected. Campaign calls use the campaign's `amd_enabled`." }, "voicemail_enabled": { "type": "boolean", "default": false, "description": "What a direct outbound call does at a detected mailbox: `true` = speak `voicemail_message`, then hang up; `false` = hang up without a message. Takes effect while `amd_enabled` is on. Campaign calls use the campaign's voicemail settings." }, "voicemail_message": { "type": "string", "nullable": true, "description": "Message spoken onto a detected mailbox when `voicemail_enabled` is `true`; supports `{{variables}}`. `null` or empty = the greeting / first message is used." }, "idle_timeout_sec": { "type": "integer" }, "transcription_timeout_sec": { "type": [ "number", "null" ], "minimum": 1, "maximum": 30, "description": "Seconds after VAD detects speech with no STT transcript before asking the caller to repeat. null disables." }, "knowledgebase_id": { "type": [ "string", "null" ], "format": "uuid" }, "knowledge_gap_mode": { "type": "string", "enum": [ "off", "questions_only", "draft_for_review", "tentative_live" ] }, "webhook_url": { "type": [ "string", "null" ], "description": "Agent-level post-call webhook URL." }, "webhook_timeout_sec": { "type": "integer", "minimum": 1, "maximum": 30 }, "webhook_retries": { "type": "integer", "minimum": 0, "maximum": 5 }, "webhook_delivery_mode": { "type": "string", "enum": [ "none", "custom", "automation" ], "description": "none = do not deliver; custom = POST the assistant webhook URL after the call; automation = deliver through the bound automation." }, "automation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Bound automation when webhook delivery is automation." }, "notification_settings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "email": { "type": "boolean" }, "push": { "type": "boolean" }, "sms": { "type": "boolean", "description": "Reserved for a future channel." } } }, "example": { "call": { "email": false }, "whatsapp": { "push": false } }, "description": "Activity notifications for this assistant, keyed by History channel (`call`, `avatar`, `live_chat`, `whatsapp_voice`, `whatsapp`, `telegram`, `slack`, `messenger`, `teams`, `discord`, `gchat`, `x`, `freshdesk`, `gmail`, `outlook`, `zendesk`, `servicenow`, `intercom`, `zoho_mail`, `agent_mail`, `instagram`, `zulip`, `email`; the legacy key `messaging` applies to every messaging channel). Each channel takes `email` and `push` toggles. A missing channel or toggle stays on; set it to `false` to opt out. Unknown keys are dropped." }, "metadata": { "type": "object", "additionalProperties": true }, "outbound_phone_number_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Workspace phone number this assistant calls from on outbound calls (an `id` from `GET /phone-numbers`). Several assistants can share one number. A `phone_number_id` passed when starting a call takes precedence. A number from another workspace or a released number returns HTTP 404. Null clears it." }, "background_audio": { "type": "object", "additionalProperties": true, "description": "BackgroundAudioPlayer config (`ambient`, `ambient_volume`, `thinking`, `thinking_volume`). `{}` = off. Hold music is configured on the warm-transfer tool, not here." }, "adaptive_interruptions": { "type": "boolean" }, "realtime_turn_mode": { "type": "string", "enum": [ "server_vad", "semantic", "adaptive" ], "description": "Realtime turn handling: robust voice activity, semantic completion, or adaptive barge-in." }, "realtime_eagerness": { "type": "string", "enum": [ "auto", "low", "medium", "high" ], "description": "How quickly the assistant responds when realtime_turn_mode is semantic." }, "long_call_memory": { "type": "string", "enum": [ "full", "recent" ], "description": "Pipeline mode only: context strategy once a call runs long. `full` keeps the whole conversation in context; `recent` keeps the latest part in focus for faster responses on calls of 10+ minutes." }, "idle_messages": { "type": "array", "items": { "type": "string" }, "description": "Fixed re-engagement phrases on caller inactivity; `[]` = LLM-generated." }, "idle_max_rounds": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Unanswered idle check-ins before the assistant says goodbye and ends the call (1–10, default 2)." }, "fallback_config": { "type": "object", "additionalProperties": true, "description": "Requires Fallbacks & Guardrails. Saved fallback configuration is omitted from responses without this workspace entitlement." }, "fallbacks_enabled": { "type": "boolean", "description": "Turns on platform-managed model fallbacks, so a call continues on a backup model if a speech or language model fails. Must be a boolean. Switching it on requires Fallbacks & Guardrails; otherwise the request fails with HTTP 403." }, "pronunciation_map": { "type": "object", "additionalProperties": { "type": "string" } }, "tts_filter_markdown": { "type": "boolean" }, "tts_filter_emoji": { "type": "boolean" }, "consent_enabled": { "type": "boolean" }, "consent_text": { "type": [ "string", "null" ] }, "consent_mode": { "type": "string" }, "consent_decline_action": { "type": "string", "enum": [ "no_recording", "hangup" ], "description": "What happens when the caller declines consent: `no_recording` continues the call without recording, `hangup` says a farewell and ends the call." }, "consent_decline_text": { "type": [ "string", "null" ], "description": "Custom farewell spoken before the call ends when the caller declines consent and `consent_decline_action` is `hangup`. Null or empty uses the default farewell for the assistant's language." }, "consent_covers_recording": { "type": "boolean" }, "consent_covers_memory": { "type": "boolean" }, "guardrails": { "type": "object", "additionalProperties": true }, "language_voices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-language voice overrides for Pipeline/Half-cascade. Languages without an entry keep the main voice. A private per-language clone is allowed only when the main voice is also a workspace-owned private clone that uses the same provider runtime. Keys must be languages the voice can speak." }, "auto_language_switch": { "type": "boolean", "description": "Automatic response-language switching; derived from secondary_languages by the dashboard." }, "output_volume": { "type": "number" }, "speaking_rate": { "type": "number" }, "text_only_enabled": { "type": "boolean" }, "memory_enabled": { "type": "boolean" }, "memory_mode": { "type": "string", "enum": [ "inherit", "on", "off" ], "description": "`inherit` follows the workspace memory default; `on`/`off` override it." }, "memory_scope": { "type": "string", "enum": [ "workspace", "assistant", "both" ], "description": "`workspace` = one summary shared across assistants; `assistant` = one summary private to this assistant; `both` = two complete summaries, one shared and one assistant-private." }, "lead_attribute_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "`all` is an immutable compatibility state for an assistant that already had unrestricted contact-field access. Creating with `all` or changing `selected` to `all` returns HTTP 400. `selected` exposes only explicit `source: lead` definitions." }, "memory_read_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Per-assistant read allowlist intersected with workspace policy. Send [] to disable reads." }, "memory_write_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Per-assistant write allowlist intersected with workspace policy. Send [] to disable writes." }, "memory_categories": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "identity", "preferences", "agreements", "open_items" ] }, "description": "Allowed summary categories. Send [] for metadata-only memory with no new content summary." }, "redact_pii": { "type": "boolean", "description": "When true, apply `pii_redaction` entity filters to stored transcripts." }, "pii_redaction": { "type": "object", "additionalProperties": true, "description": "PII entity categories + optional custom regexes." }, "analysis_config": { "$ref": "#/components/schemas/AnalysisConfig" }, "qa_scorecard_config": { "oneOf": [ { "$ref": "#/components/schemas/QaScorecardConfig" }, { "type": "null" } ], "description": "AI QA scorecard configuration (requires AI QA Scorecards in the workspace plan). `null` or `enabled: false` disables scoring." }, "timezone": { "type": "string", "description": "IANA timezone of the assistant (e.g. `Europe/Berlin`, default). Anchors the `get_current_time` system tool, the `{{time}}`/`{{date}}`/`{{datetime}}`/`{{weekday}}` system variables, and the `check_business_hours` built-in tool. On campaign calls the campaign's timezone overrides it per call." }, "primary_language": { "type": "string", "description": "Language the assistant answers in by default (ISO 639-1 or ISO 639-3, see `GET /languages`). Pipeline and Half-cascade: must be a language the assistant's voice can speak. If you omit `tts_voice` when creating, a default voice that speaks this language is chosen." }, "secondary_languages": { "type": "array", "items": { "type": "string" }, "description": "Languages the assistant may switch to when the caller clearly speaks them (ISO 639-1 or ISO 639-3). Non-empty implies multilingual STT + auto language switch. Each language must be speakable by the assistant's voice (Pipeline and Half-cascade); otherwise the request fails with `invalid_request`." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" }, "description": "Custom variable definitions, referenced as `{{key}}` and resolved per call (explicit call values > inbound enrichment > current contact values > remembered value > default_value). Each custom definition can be call-only, workspace-shared, or assistant-private." }, "variable_webhook_url": { "type": [ "string", "null" ], "description": "Optional webhook called on inbound calls to enrich variable values before the conversation starts." }, "variable_webhook_secret": { "type": [ "string", "null" ], "writeOnly": true, "description": "Secret used to sign variable webhook requests (HMAC-SHA256 of the raw body, sent as `X-Famulor-Signature: sha256=`). Write-only: never returned. Null clears it." }, "builtin_tools": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltinTool" }, "description": "Inline built-in tool configurations (also accepted as `tools` for compatibility). DTMF Input and Collect Keypad Input run as prompt-session tools here; dedicated Flow nodes bind their reusable central-tool equivalents." }, "translation_config": { "$ref": "#/components/schemas/TranslationConfig" }, "realtime_variant": { "type": "string", "enum": [ "standard", "full_duplex" ], "description": "Realtime conversation variant. Full Duplex requires workspace Beta features, Realtime plan access and compatible defaults available in the selected workspace region; extra credits may apply. Its reasoning model is managed centrally. Existing assistants use standard." } } }, "AnalysisConfig": { "type": "object", "description": "Post-conversation sentiment, success and structured extraction for voice, chat, messaging and email. Results retain native JSON types in History, webhooks, the public API and MCP.", "properties": { "sentiment": { "type": "boolean", "default": true, "description": "Rate overall caller sentiment (positive/neutral/negative). Defaults to `true`." }, "success": { "type": "object", "description": "Success evaluation against a free-text criterion.", "properties": { "enabled": { "type": "boolean", "default": false }, "criteria": { "type": "string", "description": "Free-text definition of what counts as a successful call." } } }, "fields": { "type": "array", "description": "Up to 30 fields with unique names. Object and List require fixed child fields. Missing scalar values are null; missing lists are empty; configured choice fallbacks override missing values.", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "snake_case key; unique within the array. Becomes a key in `calls.analysis.data`.", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum", "object", "list", "json" ] }, "description": { "type": "string", "maxLength": 500, "description": "What the judge should extract. Maximum 500 characters — longer values are truncated on save." }, "choices": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required, non-empty allowed values for enum; optional for string. Values must be unique ignoring case.", "maxItems": 100 }, "required": { "type": "boolean", "default": false }, "allow_multiple": { "type": "boolean", "default": false, "description": "Enum only. Return an array of matching allowed values, without duplicates, instead of one string. No matches returns [] unless fallback_value is set." }, "fallback_value": { "type": "string", "description": "Enum only. Must exactly match one of choices. Saved when no allowed value matches; multiple selection returns [fallback_value]. Omit to leave empty." }, "fields": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Required for object and list only. Unique fixed keys of the object or every list item. Missing properties remain null. Lists contain up to 100 objects. JSON is free-form (up to 16000 characters and 8 nesting levels) and does not accept fields.", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "snake_case key; unique within the array. Becomes a key in `calls.analysis.data`.", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum" ] }, "description": { "type": "string", "maxLength": 500, "description": "What the judge should extract. Maximum 500 characters — longer values are truncated on save." }, "choices": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required, non-empty allowed values for enum; optional for string. Values must be unique ignoring case.", "maxItems": 100 }, "required": { "type": "boolean", "default": false }, "allow_multiple": { "type": "boolean", "default": false, "description": "Enum only. Return an array of matching allowed values, without duplicates, instead of one string. No matches returns [] unless fallback_value is set." }, "fallback_value": { "type": "string", "description": "Enum only. Must exactly match one of choices. Saved when no allowed value matches; multiple selection returns [fallback_value]. Omit to leave empty." } }, "additionalProperties": false, "description": "A fixed Object property or List item property. Only scalar types are supported." } } }, "additionalProperties": false }, "maxItems": 30 } } }, "Voice": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider-neutral local selector. Use as tts_voice for Pipeline or fallback speech or realtime_voice for native conversation voices." }, "name": { "type": "string" }, "language": { "type": [ "string", "null" ], "description": "Primary language (ISO 639-1 or ISO 639-3)." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "All known languages of this voice." }, "gender": { "type": [ "string", "null" ], "enum": [ "female", "male", "neutral", null ] }, "category": { "type": [ "string", "null" ], "description": "E.g. `premade`, `professional`, `suggested`." }, "age": { "type": [ "string", "null" ], "description": "E.g. `middle_aged`." }, "accent": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview path, if available. Full Duplex uses an authenticated relative API path; resolve it against the API origin and send your usual Bearer token." }, "source": { "type": "string", "enum": [ "library", "own" ], "description": "`library` = workspace voice library, `own` = a private cloned voice owned by the workspace." }, "voice_type": { "type": "string", "enum": [ "tts", "realtime" ], "description": "Native library results identify realtime voices." }, "realtime_variant": { "type": "string", "enum": [ "standard", "full_duplex" ], "description": "Conversation variant for native voice results." } }, "required": [ "id", "name", "source" ] }, "VoiceCloneCapability": { "type": "object", "required": [ "allowed", "reason", "included_slots", "additional_slots", "total_slots", "sample_constraints", "pricing" ], "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "available", "payment_required", "disabled", "not_included" ] }, "included_slots": { "type": "integer", "description": "Legacy storage-capacity field. Stored voices no longer have a plan limit. Use pricing for the creation allowance and credit price.", "deprecated": true }, "additional_slots": { "type": "integer", "minimum": 0, "deprecated": true, "description": "Legacy storage-capacity field. Stored voices no longer have a plan limit. Use pricing for the creation allowance and credit price." }, "total_slots": { "type": "integer", "description": "Legacy storage-capacity field. Stored voices no longer have a plan limit. Use pricing for the creation allowance and credit price.", "deprecated": true }, "sample_constraints": { "type": "object", "required": [ "max_files", "max_bytes_per_file", "max_duration_seconds" ], "description": "Current upload limits for POST /voices/clone/uploads. These can change over time, so read them from this response instead of assuming fixed values.", "properties": { "max_files": { "type": "integer", "minimum": 1, "description": "Maximum number of audio samples currently accepted for a new clone." }, "max_bytes_per_file": { "type": "integer", "minimum": 1, "description": "Maximum size, in bytes, currently accepted for one audio sample." }, "max_duration_seconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Maximum duration, in seconds, currently accepted for one audio sample. null means no duration limit is enforced right now." } } }, "pricing": { "$ref": "#/components/schemas/VoiceCloneCreationPricing" } } }, "VoiceCloneUploadGrant": { "type": "object", "required": [ "upload_id", "upload_url", "expires_at" ], "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "Opaque upload identifier." }, "upload_url": { "type": "string", "format": "uri", "description": "Short-lived destination for exactly one declared sample." }, "expires_at": { "type": "string", "format": "date-time" } } }, "VoiceCloneJob": { "type": "object", "required": [ "id", "operation", "status", "name", "language", "error_code", "clone_id", "created_at", "updated_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "create", "delete" ] }, "status": { "type": "string", "enum": [ "awaiting_upload", "queued", "processing", "ready", "failed", "deleting", "delete_failed", "deleted", "expired" ] }, "name": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ], "description": "Stable customer-facing failure code, when processing failed." }, "clone_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Opaque cloned-voice ID once creation is ready." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "VoiceClone": { "type": "object", "required": [ "id", "name", "language", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Opaque cloned-voice ID." }, "name": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "status": { "type": "string", "const": "ready" }, "created_at": { "type": "string", "format": "date-time" } } }, "VoiceCloneDeleteResult": { "type": "object", "required": [ "ok", "clone_id", "job" ], "properties": { "ok": { "type": "boolean", "const": true }, "clone_id": { "type": "string", "format": "uuid" }, "job": { "oneOf": [ { "$ref": "#/components/schemas/VoiceCloneJob" }, { "type": "null" } ] } } }, "HistoryItem": { "type": "object", "required": [ "id", "thread_id", "channel", "direction", "assistant_id", "assistant_name", "status", "contact", "from", "to", "subject", "body_preview", "summary", "duration_sec", "campaign_id", "reply_status", "reply_error", "attachments_count", "message_count", "created_at", "last_activity_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable email or messaging conversation ID; null for calls." }, "lead_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Canonical Audience contact relation." }, "channel": { "type": "string", "enum": [ "sms", "call", "avatar", "email", "live_chat", "whatsapp_voice", "whatsapp", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ], "description": "Channel of the conversation. Filter with the `type` query parameter." }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "web" ] }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "assistant_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed", "failed", "no_answer", "busy", "skipped" ] }, "failure": { "$ref": "#/components/schemas/PublicCallFailure", "description": "Provider-neutral failure guidance. Present only when a call-row conversation has a normalized outbound failure." }, "contact": { "type": [ "string", "null" ], "description": "External phone number or email address." }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ], "description": "Email subject; null for calls." }, "body_preview": { "type": [ "string", "null" ], "description": "Compact plain-text email or messaging preview, separate from the generated summary; null for calls." }, "summary": { "type": [ "string", "null" ], "description": "Generated conversation recap; null when unavailable. Never replaced by a subject, message preview, transcript excerpt or success explanation." }, "duration_sec": { "type": [ "integer", "null" ], "description": "Call duration; null for emails." }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "reply_status": { "type": [ "string", "null" ], "enum": [ "pending", "replied", "skipped", "failed", null ], "description": "Raw auto-reply state for inbound emails; null for calls and outbound email rows." }, "reply_error": { "type": [ "string", "null" ] }, "attachments_count": { "type": "integer", "minimum": 0 }, "message_count": { "type": "integer", "minimum": 1, "description": "All inbound and outbound messages grouped into this conversation." }, "created_at": { "type": "string", "format": "date-time" }, "last_activity_at": { "type": "string", "format": "date-time", "description": "Latest message time for email threads; equal to created_at for calls." }, "imported_from_whatsapp_history": { "type": "boolean", "description": "WhatsApp Coexistence only: true when this conversation was backfilled from the customer's WhatsApp Business app chat history rather than a live AI session." }, "inbox_labels": { "type": "array", "items": { "$ref": "#/components/schemas/InboxLabel" }, "description": "Active advisory labels. Empty while processing, when no label is assigned, or after dismissal. Absence of a label is not proof of authenticity." } } }, "EmailAttachment": { "type": "object", "required": [ "filename", "type", "size" ], "properties": { "filename": { "type": "string" }, "type": { "type": "string" }, "size": { "type": [ "integer", "null" ] }, "transcript": { "type": [ "string", "null" ], "description": "Recognized speech from a successfully transcribed inbound audio attachment, when available." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Media link for retained inbound audio or images, valid for one hour. Fetch the email conversation again to refresh it." }, "description": { "type": [ "string", "null" ], "description": "Short description of an analyzed image, including readable text when possible. This is a summary rather than a complete OCR export." } } }, "EmailThreadMessage": { "type": "object", "required": [ "id", "thread_id", "in_reply_to", "message_id", "direction", "from", "to", "subject", "text_body", "attachments", "sendgrid_message_id", "reply_status", "reply_error", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "in_reply_to": { "type": [ "string", "null" ], "format": "uuid", "description": "Immediate parent message in this conversation." }, "message_id": { "type": [ "string", "null" ], "description": "RFC Message-ID used by email clients for threading." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "subject": { "type": "string" }, "text_body": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" } }, "sendgrid_message_id": { "type": [ "string", "null" ] }, "reply_status": { "type": [ "string", "null" ], "enum": [ "pending", "replied", "skipped", "failed", null ] }, "reply_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "inbox_labels": { "type": "array", "items": { "$ref": "#/components/schemas/InboxLabel" }, "description": "Active advisory labels. Empty while processing, when no label is assigned, or after dismissal. Absence of a label is not proof of authenticity." } } }, "EmailHistoryDetail": { "allOf": [ { "$ref": "#/components/schemas/HistoryItem" }, { "type": "object", "required": [ "text_body", "html_body", "attachments", "message_id", "sendgrid_message_id", "in_reply_to", "messages" ], "properties": { "channel": { "type": "string", "const": "email" }, "thread_id": { "type": "string", "format": "uuid" }, "text_body": { "type": "string" }, "html_body": { "type": [ "string", "null" ], "description": "Untrusted email HTML; sanitize before rendering." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" } }, "message_id": { "type": [ "string", "null" ] }, "sendgrid_message_id": { "type": [ "string", "null" ] }, "in_reply_to": { "type": [ "string", "null" ], "format": "uuid" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/EmailThreadMessage" }, "description": "Every inbound and outbound message in the stable thread, ordered chronologically." } } } ] }, "MessagingHistoryAttachment": { "type": "object", "required": [ "type", "filename", "mime_type", "size", "description", "transcript", "url" ], "properties": { "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ] }, "filename": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size": { "type": [ "integer", "null" ], "description": "Attachment size in bytes." }, "description": { "type": [ "string", "null" ], "description": "Short description of an analyzed image, including readable text when possible. This is a summary rather than a complete OCR export." }, "transcript": { "type": [ "string", "null" ], "description": "Recognized speech from an audio attachment, when transcription succeeds." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Time-limited media link, valid for one hour. Null when the attachment is unavailable." } } }, "MessagingHistoryMessage": { "type": "object", "required": [ "id", "direction", "role", "text_body", "created_at", "source", "attachments" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text_body": { "type": "string", "description": "Message text including recognized speech used by the assistant." }, "created_at": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "ai", "human", "business_app", "customer" ], "description": "`business_app`: a teammate replied from the WhatsApp Business app (Coexistence sender)." }, "tool_events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingHistoryAttachment" } }, "inbox_labels": { "type": "array", "items": { "$ref": "#/components/schemas/InboxLabel" }, "description": "Active advisory labels. Empty while processing, when no label is assigned, or after dismissal. Absence of a label is not proof of authenticity." }, "delivery_status": { "type": "string", "readOnly": true, "enum": [ "queued", "sent", "delivered", "failed", "unconfirmed", "received" ], "description": "SMS delivery state. Sent means accepted by the carrier; delivered confirms delivery. Unconfirmed means the outcome is unknown: check before retrying." }, "credits_charged": { "type": "number", "readOnly": true, "description": "Credits currently charged for this SMS. An estimated charge can be reconciled when the carrier reports its final price." } } }, "MessagingHistoryDetail": { "allOf": [ { "$ref": "#/components/schemas/HistoryItem" }, { "type": "object", "required": [ "connector_id", "connector_name", "ai_paused", "connector_ai_enabled", "messages" ], "properties": { "connector_id": { "type": "string", "format": "uuid" }, "connector_name": { "type": [ "string", "null" ] }, "external_thread_id": { "type": "string" }, "external_user_id": { "type": [ "string", "null" ] }, "external_user_name": { "type": [ "string", "null" ] }, "ai_paused": { "type": "boolean" }, "connector_ai_enabled": { "type": "boolean" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "contact_phone": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "messages": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/MessagingHistoryMessage" }, "description": "Messages ordered chronologically, limited to the first 500 messages in the conversation." } } } ] }, "CallTranscriptMessage": { "type": "object", "required": [ "type", "role", "content" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Stable history item identifier." }, "type": { "type": "string", "const": "message" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] } }, "interrupted": { "type": "boolean", "description": "Whether assistant speech for this message was interrupted." }, "attachments": { "type": "array", "description": "Files or images the visitor uploaded with this chat turn (web widget chat, chat preview). Only present on user messages that carried uploads. `url` is a temporary signed link valid for about one hour.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "file" ] }, "filename": { "type": "string" }, "mime_type": { "type": "string", "nullable": true }, "size": { "type": "integer", "nullable": true, "description": "Bytes." }, "description": { "type": "string", "nullable": true, "description": "Short vision caption for images, when available." }, "url": { "type": "string", "nullable": true, "description": "Temporary signed download URL." } } } }, "timeline_seq": { "type": "integer", "minimum": 1, "description": "Monotonic ordering key assigned when the turn started." }, "logical_turn_id": { "type": "string", "description": "Stable turn identifier used to merge interim and final transcript updates." }, "started_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] }, "created_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] } } }, "CallTranscriptFunctionCall": { "type": "object", "required": [ "type", "name", "call_id", "arguments" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Stable history item identifier." }, "type": { "type": "string", "const": "function_call" }, "name": { "type": "string" }, "call_id": { "type": "string" }, "arguments": { "type": "string", "description": "JSON-encoded, public-safe tool arguments." }, "timeline_seq": { "type": "integer", "minimum": 1, "description": "Monotonic ordering key assigned when tool execution started." }, "logical_turn_id": { "type": "string", "description": "Stable lifecycle identifier; equal to call_id for tool events." }, "started_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] }, "created_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] } } }, "CallTranscriptFunctionOutput": { "type": "object", "required": [ "type", "name", "call_id", "output", "is_error" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Stable history item identifier." }, "type": { "type": "string", "const": "function_call_output" }, "name": { "type": "string" }, "call_id": { "type": "string" }, "output": { "type": "string", "description": "JSON-encoded or plain-text, public-safe tool result." }, "is_error": { "type": "boolean" }, "timeline_seq": { "type": "integer", "minimum": 1, "description": "Monotonic ordering key assigned when tool execution ended." }, "logical_turn_id": { "type": "string", "description": "Stable lifecycle identifier; equal to call_id for tool events." }, "started_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] }, "created_at": { "oneOf": [ { "type": "number", "description": "Unix epoch seconds." }, { "type": "string", "format": "date-time" } ] } } }, "CallTranscript": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CallTranscriptMessage" }, { "$ref": "#/components/schemas/CallTranscriptFunctionCall" }, { "$ref": "#/components/schemas/CallTranscriptFunctionOutput" } ] } } } }, { "type": "array", "description": "Legacy role/content transcript format.", "items": { "type": "object", "required": [ "role", "content" ], "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": {} } } } ] }, "PublicTelephonyFailure": { "allOf": [ { "$ref": "#/components/schemas/PublicCallFailure" }, { "type": "object", "required": [ "operation" ], "properties": { "domain": { "type": "string", "enum": [ "telephony" ] }, "operation": { "type": "string", "enum": [ "outbound_call", "cold_transfer", "warm_transfer" ] } } } ], "description": "Deprecated alias for telephony-domain PublicCallFailure. Prefer PublicCallFailure." }, "Call": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "phone_number_id": { "type": [ "string", "null" ], "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "web" ] }, "from_number": { "type": [ "string", "null" ] }, "to_number": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed", "failed", "no_answer", "busy" ] }, "failure": { "$ref": "#/components/schemas/PublicCallFailure", "description": "Provider-neutral failure guidance. Present when a call has a normalized failure reason (telephony, billing, runtime, …)." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "answered_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_sec": { "type": [ "integer", "null" ] }, "transcript": { "$ref": "#/components/schemas/CallTranscript", "description": "Public-safe session history. `items` contains messages and typed function_call/function_call_output entries linked by call_id. Provider metrics, request IDs and model-specific metadata are omitted. `timeline_seq`, `logical_turn_id` and `started_at` provide stable ordering when present. Null while no transcript is available." }, "summary": { "type": [ "string", "null" ], "description": "AI-generated post-call summary." }, "evaluation": { "description": "AI post-call evaluation, or `null`." }, "analysis": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Post-call analysis result produced by the LLM judge after the call ends (only when the assistant has `analysis_config` enabled). Shape: `{ sentiment, success, success_reason, data, model, analyzed_at }`. `data` holds the structured fields defined in the assistant's `analysis_config.fields`. `null` until analysis has run.", "properties": { "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative", null ] }, "success": { "type": [ "boolean", "null" ] }, "success_reason": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": true }, "model": { "type": [ "string", "null" ] }, "analyzed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "neutral", "negative", null ], "description": "Denormalized copy of `analysis.sentiment` for filtering. Use `?sentiment=` on `GET /calls`." }, "success": { "type": [ "boolean", "null" ], "description": "Denormalized copy of `analysis.success` for filtering. Use `?success=` on `GET /calls`." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Includes `campaign_id`/`lead_id` for campaign dialer calls." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_scorecard": { "type": [ "object", "null" ], "additionalProperties": true, "description": "AI-QA scorecard result. Shape: `{ score, passed, pass_threshold, criteria[], scored_at }`. `null` until scored." }, "qa_score": { "type": [ "number", "null" ], "description": "Denormalized overall QA score 0–100." }, "qa_passed": { "type": [ "boolean", "null" ], "description": "Denormalized pass/fail against the configured threshold." }, "amd_result": { "type": [ "string", "null" ], "description": "Answering-machine detection result when available, including human, machine-vm, machine-ivr, machine-unavailable, or uncertain. A detected phone menu is an answered call, not a ringing timeout." } }, "required": [ "id", "direction", "status", "created_at", "updated_at" ] }, "CallEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "call_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "E.g. `state_changed`, `transcript_delta`, `tool_called`, `call_transfer_failed`, or `warm_transfer_failed`." }, "payload": { "type": "object", "additionalProperties": true, "description": "Failure events expose a safe `failure` object. Raw SIP status, connection diagnostics and SDK errors are omitted." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "call_id", "type", "created_at" ] }, "CallBilling": { "type": "object", "description": "Actual workspace credit debits posted for one call. total_credits_charged includes the primary call and linked additional services, net of refunds. Later phone adjustments may update the amounts. The primary-call fields and hold calculations remain separate from additional services.", "properties": { "credits_charged": { "type": [ "number", "null" ], "description": "Primary-call credits, including posted primary phone adjustments. Excludes separately booked transfer, recording and other linked services. Use total_credits_charged for the combined posted amount." }, "total_credits_charged": { "type": [ "number", "null" ], "description": "Primary-call credits plus additional_credits, net of posted refunds. Null when a complete ledger summary is unavailable; not an estimate or a guaranteed final amount before later adjustments." }, "additional_credits": { "type": [ "number", "null" ], "description": "Net credits for linked transfer, recording and other call services. Already included in total_credits_charged. Null if the linked ledger could not be fully read." }, "recording_credits": { "type": [ "number", "null" ], "description": "Recording subset of additional_credits, net of posted refunds. Do not add it again to the total. Zero means no net recording debit was found; null means unavailable." }, "telephony_credits": { "type": [ "number", "null" ], "description": "Final telephony credits at the workspace rate. Null until the live carrier price is billed. Not the hold estimate." }, "credits_reserved": { "type": [ "number", "null" ], "description": "Credits held at call start for the maximum talk time." }, "credits_released": { "type": [ "number", "null" ], "description": "Unused hold returned after the call (reserved minus billed, or the full hold when the call was skipped)." }, "credits_per_min": { "type": [ "number", "null" ], "description": "Workspace credit rate used to size the hold (talk plus telephony)." }, "max_duration_sec": { "type": [ "integer", "null" ], "description": "Maximum talk time the hold was sized for." }, "reservation_status": { "type": [ "string", "null" ], "enum": [ "active", "settled", "released", "failed", null ] }, "hold_reason": { "type": [ "string", "null" ], "description": "Why credits were held and how billed/telephony relate to the hold." } } }, "CallDetail": { "allOf": [ { "$ref": "#/components/schemas/Call" }, { "type": "object", "properties": { "recording_url": { "type": [ "string", "null" ], "description": "Signed recording download URL (valid 1 hour), or `null` if the call has no recording." }, "billing": { "$ref": "#/components/schemas/CallBilling" }, "structured_transcript": { "type": "string", "description": "The `transcript` flattened to one line per turn, formatted as `ai: …` / `human: …` (assistant/user), in chronological order. Convenience string for prompts, emails or webhooks that don't want to parse the raw transcript items." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CallEvent" }, "description": "Call events in chronological order." }, "insights": { "oneOf": [ { "$ref": "#/components/schemas/CallInsights" }, { "type": "null" } ], "description": "Measured call insights, or null if insights cannot currently be loaded. Call details remain available." }, "transcript_display": { "type": "array", "items": { "$ref": "#/components/schemas/CallTranscriptDisplayEntry" }, "description": "Customer-safe display timeline with paired tool calls and merged conversational fragments. Insight transcript_index values refer to this array. Internal message identity and raw telemetry are excluded." } } } ] }, "CallInputVariables": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "not": { "enum": [ "constructor", "prototype", "__proto__" ] } }, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Explicit per-call values. Strings are limited to 2000 characters; numbers and booleans become text. Values are sanitized before use. Does not edit assistant definitions or contact fields; durable retention follows the configured variable memory policy." }, "CallInputVerification": { "type": "object", "required": [ "status", "checks" ], "properties": { "status": { "type": "string", "enum": [ "matched", "mismatch", "not_available" ] }, "checks": { "type": "array", "items": { "type": "object", "required": [ "key", "status" ], "properties": { "key": { "type": "string" }, "status": { "type": "string", "enum": [ "matched", "missing", "different", "not_available" ] } } } } }, "description": "Only the requested input keys and comparison statuses. not_available means the resolved call-start snapshot is not available yet. This does not judge the outcome of the scenario." }, "OutboundCallRequest": { "type": "object", "required": [ "assistant_id", "to_number" ], "properties": { "assistant_id": { "type": "string", "format": "uuid", "description": "Assistant that runs the call. Must be active." }, "to_number": { "type": "string", "description": "Destination in E.164 format, e.g. `+4930123456`." }, "lead": { "type": "object", "additionalProperties": true, "description": "Contact context. Custom fields follow the assistant contact-field access settings and do not fill same-named manual variables; use variables for explicit scenario inputs." }, "phone_number_id": { "type": "string", "format": "uuid", "description": "Optional explicit caller ID (one of your phone numbers). Defaults to the number assigned to the assistant." }, "variables": { "$ref": "#/components/schemas/CallInputVariables" } } }, "RecordingUrl": { "type": "object", "required": [ "call_id", "url", "expires_in", "expires_at" ], "properties": { "call_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "description": "Time-limited signed download URL." }, "expires_in": { "type": "integer", "description": "Validity in seconds." }, "expires_at": { "type": "string", "format": "date-time" } } }, "CallingWindows": { "type": "object", "description": "Allowed calling windows per weekday, local to the campaign `timezone`. Keys: `mon`–`sun`; each value is an array of `[\"HH:MM\", \"HH:MM\"]` start/end pairs (24h). An empty array or missing key blocks the whole day.", "propertyNames": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 2, "maxItems": 2 } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "running", "paused", "completed", "archived" ] }, "channel": { "type": "string", "enum": [ "phone_call", "whatsapp_template", "whatsapp_call", "sms" ], "default": "phone_call" }, "channel_config": { "type": "object", "additionalProperties": true }, "follow_up_config": { "type": "object", "additionalProperties": true, "description": "Optional voice follow-up after retries are exhausted. `channel` is `off` | `whatsapp_template` | `sms` | `email`. Email is follow-up only and uses `subject`, `message`, and `variable_mapping`; it sends from the campaign assistant address." }, "scheduled_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assistant that runs the campaign calls." }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Maximum parallel voice calls for this campaign. Must fit the workspace's effective Concurrent Lines allowance, including add-ons. Calls across campaigns share that workspace allowance." }, "retry_max": { "type": "integer", "description": "Max retry attempts per lead." }, "retry_delay_minutes": { "type": "integer" }, "calling_windows": { "$ref": "#/components/schemas/CallingWindows" }, "timezone": { "type": "string", "description": "IANA timezone the calling windows are evaluated in." }, "amd_enabled": { "type": "boolean", "description": "Answering-machine detection at call start." }, "voicemail_action": { "type": "string", "enum": [ "hangup", "drop_message" ] }, "voicemail_message": { "type": [ "string", "null" ], "description": "TTS text spoken to voicemail when `voicemail_action` is `drop_message`." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "amd_mode": { "type": "string", "enum": [ "conservative", "aggressive" ], "description": "Answering-machine detection sensitivity when AMD is enabled." }, "ivr_navigation": { "type": "boolean", "description": "Allow navigating phone menus. Enabling requires workspace Beta features." } }, "required": [ "id", "name", "status", "created_at", "updated_at" ] }, "CampaignCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assistant that runs the calls. Must belong to your workspace." }, "channel": { "type": "string", "enum": [ "phone_call", "whatsapp_template", "whatsapp_call", "sms" ] }, "channel_config": { "type": "object", "additionalProperties": true }, "follow_up_config": { "type": "object", "additionalProperties": true, "description": "Optional voice follow-up after retries are exhausted. `channel` is `off` | `whatsapp_template` | `sms` | `email`. Email is follow-up only and uses `subject`, `message`, and `variable_mapping`; it sends from the campaign assistant address." }, "scheduled_start_at": { "type": [ "string", "null" ], "format": "date-time" }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Maximum parallel voice calls for this campaign. Must fit the workspace's effective Concurrent Lines allowance, including add-ons. Calls across campaigns share that workspace allowance." }, "retry_max": { "type": "integer", "minimum": 0 }, "retry_delay_minutes": { "type": "integer", "minimum": 1 }, "calling_windows": { "$ref": "#/components/schemas/CallingWindows" }, "timezone": { "type": "string", "description": "IANA timezone, e.g. `Europe/Berlin`." }, "amd_enabled": { "type": "boolean" }, "voicemail_action": { "type": "string", "enum": [ "hangup", "drop_message" ] }, "voicemail_message": { "type": [ "string", "null" ], "description": "Required when `voicemail_action` is `drop_message`." }, "amd_mode": { "type": "string", "enum": [ "conservative", "aggressive" ], "description": "Answering-machine detection sensitivity when AMD is enabled." }, "ivr_navigation": { "type": "boolean", "description": "Allow navigating phone menus. Enabling requires workspace Beta features." } } }, "CampaignUpdate": { "type": "object", "description": "Partial update — only the provided fields are changed. At least one valid field is required.", "properties": { "name": { "type": "string" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Maximum parallel voice calls for this campaign. Must fit the workspace's effective Concurrent Lines allowance, including add-ons. Calls across campaigns share that workspace allowance." }, "retry_max": { "type": "integer", "minimum": 0 }, "retry_delay_minutes": { "type": "integer", "minimum": 1 }, "calling_windows": { "$ref": "#/components/schemas/CallingWindows" }, "timezone": { "type": "string" }, "amd_enabled": { "type": "boolean" }, "voicemail_action": { "type": "string", "enum": [ "hangup", "drop_message" ] }, "voicemail_message": { "type": [ "string", "null" ] }, "amd_mode": { "type": "string", "enum": [ "conservative", "aggressive" ], "description": "Answering-machine detection sensitivity when AMD is enabled." }, "ivr_navigation": { "type": "boolean", "description": "Allow navigating phone menus. Enabling requires workspace Beta features." } } }, "CampaignDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lead_id": { "type": "string", "format": "uuid" }, "stage": { "type": "string", "enum": [ "primary", "follow_up" ] }, "channel": { "type": "string", "enum": [ "phone_call", "whatsapp_template", "whatsapp_call", "sms" ] }, "status": { "type": "string" }, "attempt": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "phone": { "type": [ "string", "null" ], "description": "E.164 normalized." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "source": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "pending", "queued", "calling", "completed", "failed", "no_answer", "busy", "do_not_call" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_amd_result": { "type": [ "string", "null" ], "description": "Last answering-machine-detection result: `human`, `machine-ivr`, `machine-vm`, `machine-unavailable`, `uncertain`." }, "last_call_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "display_status": { "type": "string", "enum": [ "created", "processing", "rescheduled", "max_retries", "completed", "dnc" ], "description": "Status grouped for boards and filters: `created` (waiting for its first attempt), `processing` (queued or being called), `rescheduled` (waiting for a retry), `max_retries` (attempts used up without success), `completed`, `dnc` (on the do-not-call list)." }, "call_qa": { "oneOf": [ { "$ref": "#/components/schemas/AudienceCallQaMetrics" }, { "type": "null" } ], "description": "Per-contact metrics for the requested QA window. Null means no scored calls or the feature is unavailable." } }, "required": [ "id", "status", "created_at", "updated_at" ] }, "CampaignLead": { "type": "object", "description": "A lead inside one campaign. Contact-wide fields such as sources and Call QA metrics are on `GET /leads`.", "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "phone": { "type": [ "string", "null" ], "description": "E.164 normalized." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "custom_fields": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "pending", "queued", "calling", "completed", "failed", "no_answer", "busy", "do_not_call" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_amd_result": { "type": [ "string", "null" ], "description": "Last answering-machine-detection result: `human`, `machine-ivr`, `machine-vm`, `machine-unavailable`, `uncertain`." }, "last_call_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "created_at", "updated_at" ] }, "AudienceCallQaMetrics": { "type": "object", "required": [ "lead_id", "average_score", "scored_calls", "passed_calls", "pass_rate", "latest_score", "latest_scored_at" ], "properties": { "lead_id": { "type": "string", "format": "uuid" }, "average_score": { "type": "number" }, "scored_calls": { "type": "integer" }, "passed_calls": { "type": "integer" }, "pass_rate": { "type": "number", "description": "Percentage from 0 to 100." }, "latest_score": { "type": "number" }, "latest_scored_at": { "type": "string", "format": "date-time" } } }, "LeadInput": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Phone number; normalized to E.164 (e.g. `+4915123456789`)." }, "email": { "type": "string", "format": "email", "description": "Optional contact email. It is validated and normalized before storage; an existing identity is rejected instead of merged." }, "name": { "type": [ "string", "null" ] }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Arbitrary key/value data available to the assistant during the call." } } }, "AudienceContactInput": { "type": "object", "anyOf": [ { "required": [ "phone" ] }, { "required": [ "email" ] } ], "properties": { "phone": { "type": [ "string", "null" ], "description": "Phone number normalized to E.164." }, "email": { "type": [ "string", "null" ], "format": "email" }, "name": { "type": [ "string", "null" ] }, "tags": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 40 } }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "User-managed contact fields. Infrastructure-managed keys are ignored." } } }, "AudienceContactChannelInput": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string", "enum": [ "sms", "telegram", "whatsapp", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "external_user_id": { "type": [ "string", "null" ], "maxLength": 200 }, "username": { "type": [ "string", "null" ], "maxLength": 200 }, "display_name": { "type": [ "string", "null" ], "maxLength": 120 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "connection_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Visible connection name. Active Microsoft Teams connection names are unique within a workspace; use this field when more than one Teams connection is active." } }, "description": "At least one identity field (user ID, username, display name, or attribute) must be non-empty. Email is managed through the contact's email field and is not accepted here." }, "AudienceContactChannel": { "allOf": [ { "$ref": "#/components/schemas/AudienceContactChannelInput" }, { "type": "object", "required": [ "id", "contact_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "description": "E.164 phone number." }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Assistant that answers inbound calls on this number." }, "sip_trunk_id": { "type": [ "string", "null" ], "format": "uuid", "description": "SIP trunk this number belongs to (customer-provided numbers)." }, "direction_inbound": { "type": "boolean" }, "direction_outbound": { "type": "boolean" }, "source": { "type": "string", "enum": [ "platform", "byo" ], "description": "`platform` = bought from the number marketplace, `byo` = customer-provided via your own SIP trunk." }, "country_iso": { "type": [ "string", "null" ], "description": "ISO-2 country code." }, "number_type": { "type": [ "string", "null" ], "enum": [ "local", "mobile", "national", "toll_free", null ] }, "monthly_price_cents": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "active", "pending", "released", "suspended" ] }, "label": { "type": [ "string", "null" ], "description": "Optional UI display label under the E.164 (not sent to carriers)." }, "purchased_by": { "type": [ "string", "null" ], "format": "uuid" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "release_scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When set, a paid marketplace number is soft-scheduled for release at the end of its billing period. Status remains `active` and the number stays usable until then." }, "is_plan_free": { "type": "boolean", "description": "Complimentary local marketplace number included with a platform plan (no separate phone-number subscription). Mobile, national, and other number types remain paid. Released immediately when requested." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "sms_capable": { "type": "boolean", "nullable": true, "description": "Whether the number supports SMS." }, "outbound_sms_enabled": { "type": "boolean", "description": "Workspace opt-in to send outbound SMS from this number." }, "a2p_status": { "type": "string", "nullable": true, "enum": [ "not_applicable", "unregistered", "pending", "registered", "failure" ], "description": "Cached A2P 10DLC status for US 10DLC senders." }, "sms_assistant_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Assistant assigned to handle inbound SMS for this number." }, "recurring_price": { "type": "object", "nullable": true, "description": "Verified monthly rental charge in its original contract currency. Null when historical billing evidence is unavailable; do not infer the renewal charge from converted catalog prices.", "properties": { "amount_minor": { "type": "integer", "description": "Monthly amount in the stated currency’s minor units." }, "currency": { "type": "string", "example": "EUR" }, "decimal_digits": { "type": "integer", "example": 2 } }, "required": [ "amount_minor", "currency", "decimal_digits" ] } }, "required": [ "id", "number", "direction_inbound", "direction_outbound", "source", "status", "created_at", "updated_at" ] }, "AvailablePhoneNumber": { "type": "object", "properties": { "number": { "type": "string", "description": "E.164 phone number." }, "friendly_name": { "type": "string" }, "type": { "type": "string", "enum": [ "local", "mobile", "national" ] }, "country": { "type": "string", "description": "ISO-2 country code." }, "monthly_price_cents": { "type": "integer", "description": "Final customer-facing monthly retail price for this workspace, in EUR cents." }, "setup_fee_cents": { "type": "integer", "description": "Final customer-facing one-time setup fee for this workspace, in EUR cents." }, "currency": { "type": "string", "description": "Denomination of monthly_price_cents/setup_fee_cents — currently EUR." }, "display_currency": { "type": "string", "description": "Workspace's resolved display currency (reseller customers inherit their reseller's currency).", "example": "USD" }, "display_currency_rate": { "type": "number", "description": "Units of display_currency per 1 EUR; 0 when the platform has not configured a rate yet.", "example": 1.08 }, "display_monthly_price_cents": { "type": "integer", "description": "monthly_price_cents converted to display_currency at the platform rate — the amount an actual purchase would be charged. Present only when display_currency differs from currency." }, "display_setup_fee_cents": { "type": "integer", "description": "setup_fee_cents converted to display_currency at the platform rate. Present only when display_currency differs from currency." }, "purchase_token": { "type": "string", "description": "Short-lived signed offer token. Pass it unchanged when purchasing this exact number; search again after expiry or a price change." }, "capabilities": { "type": "object", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" } } } }, "required": [ "number", "type", "country", "monthly_price_cents", "setup_fee_cents", "currency", "display_currency", "display_currency_rate", "purchase_token" ] }, "PhoneNumberPurchase": { "type": "object", "required": [ "number", "country" ], "properties": { "number": { "type": "string", "description": "The exact E.164 number returned by `GET /phone-numbers/available`." }, "country": { "type": "string", "description": "ISO-2 country code, e.g. `DE`." }, "type": { "type": "string", "enum": [ "local", "mobile", "national" ], "default": "local", "description": "Number type of the offer. Pass the `type` returned with the number by `GET /phone-numbers/available`; defaults to `local` when omitted." }, "purchase_token": { "type": "string", "description": "The short-lived token returned with the exact number by `GET /phone-numbers/available`; pass it unchanged. Required for workspaces that buy numbers from a reseller. Otherwise optional, but when sent it must match the number, country and type." }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optionally assign an assistant that does not already have an inbound phone number. Pending number reservations also count. An existing assignment returns HTTP 409; omit this field or set it to null to assign an assistant later." } } }, "PhoneNumberUpdate": { "type": "object", "description": "Partial update. When `assistant_id`, `sip_trunk_id` or `direction_inbound` change, the inbound SIP dispatch rule is re-created (or removed). The display-only `label` can be changed for any phone number owned by the workspace.", "properties": { "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "`null` unassigns the assistant." }, "sip_trunk_id": { "type": [ "string", "null" ], "format": "uuid" }, "direction_inbound": { "type": "boolean" }, "direction_outbound": { "type": "boolean" }, "label": { "type": [ "string", "null" ], "description": "Optional UI display label under the E.164 (not sent to carriers). Null or empty clears it." } } }, "CarrierConnection": { "type": "object", "required": [ "id", "carrier", "name", "status", "credentials_hint", "sip_region", "numbers", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "carrier": { "type": "string", "enum": [ "twilio", "telnyx", "vonage" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "error", "disconnected" ] }, "credentials_hint": { "type": "string", "description": "Non-secret masked account hint." }, "outbound_address": { "type": [ "string", "null" ], "description": "Carrier-owned outbound SIP address." }, "sip_region": { "$ref": "#/components/schemas/SipRegion" }, "last_error": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierConnectionNumber" } } } }, "CarrierConnectionNumber": { "type": "object", "required": [ "phone_number_id", "sip_trunk_id", "number", "status" ], "properties": { "phone_number_id": { "type": "string", "format": "uuid" }, "sip_trunk_id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "pattern": "^\\+[1-9]\\d{4,19}$" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" } } }, "CarrierAvailableNumber": { "type": "object", "required": [ "number", "provider_number_id", "voice_capable", "already_attached", "already_imported" ], "properties": { "number": { "type": "string", "pattern": "^\\+[1-9]\\d{4,19}$" }, "provider_number_id": { "type": "string", "description": "Opaque carrier identifier returned unchanged when importing: Twilio PN SID, Telnyx numeric ID, or Vonage COUNTRY:MSISDN." }, "friendly_name": { "type": [ "string", "null" ] }, "voice_capable": { "type": "boolean" }, "already_attached": { "type": "boolean", "description": "True when importing would overwrite unrelated carrier-side routing." }, "already_imported": { "type": "boolean" } } }, "CarrierConnectionCreate": { "type": "object", "required": [ "carrier", "name" ], "properties": { "carrier": { "type": "string", "enum": [ "twilio", "telnyx", "vonage" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "account_sid": { "type": "string", "description": "Required for Twilio." }, "auth_token": { "type": "string", "writeOnly": true, "description": "Required for Twilio; stored encrypted." }, "api_key": { "type": "string", "description": "Required for Telnyx and Vonage. Telnyx keys start with KEY." }, "api_secret": { "type": "string", "writeOnly": true, "description": "Required for Vonage; stored encrypted." }, "sip_region": { "$ref": "#/components/schemas/SipRegion" } } }, "CarrierConnectionUpdate": { "type": "object", "required": [ "sip_region" ], "properties": { "sip_region": { "$ref": "#/components/schemas/SipRegion" } } }, "CarrierImportRequest": { "type": "object", "required": [ "numbers" ], "properties": { "numbers": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "number", "provider_number_id" ], "properties": { "number": { "type": "string", "pattern": "^\\+[1-9]\\d{4,19}$" }, "provider_number_id": { "type": "string", "description": "Value returned by the available-numbers endpoint." } } } } } }, "CarrierImportResult": { "type": "object", "required": [ "number", "ok" ], "properties": { "number": { "type": "string" }, "ok": { "type": "boolean" }, "phone_number_id": { "type": "string", "format": "uuid" }, "sip_trunk_id": { "type": "string", "format": "uuid" }, "error": { "type": "string" } } }, "CarrierTroubleshootResult": { "type": "object", "required": [ "checks", "repaired", "healthy" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierCheck" } }, "repaired": { "type": "integer", "minimum": 0 }, "healthy": { "type": "boolean" } } }, "CarrierCheck": { "type": "object", "required": [ "id", "label", "status", "detail" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "repaired", "failed" ] }, "detail": { "type": [ "string", "null" ] } } }, "SipRegion": { "type": "string", "enum": [ "global", "eu", "us", "uk", "india", "japan", "aus", "sa" ], "default": "global" }, "SipTrunk": { "type": "object", "description": "Customer-owned BYO/BYOC SIP trunk. Managed platform trunks, passwords, and internal trunk identifiers are never returned.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "twilio", "custom" ] }, "sip_address": { "type": [ "string", "null" ], "description": "Provider termination host (no `sip:` prefix, no port)." }, "auth_username": { "type": [ "string", "null" ] }, "inbound_auth_username": { "type": [ "string", "null" ] }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "Exactly one primary number on this trunk. DID: E.164. Extension: E.164 or national digits without country code; still used for exact inbound matching." }, "trunk_kind": { "type": "string", "enum": [ "did", "extension" ], "description": "`did` = one E.164 phone number. `extension` = one exact primary number whose outbound caller-ID format may be national; it is never wildcard inbound." }, "credential_mode": { "type": "string", "enum": [ "shared", "separate" ] }, "outbound_auth_mode": { "type": "string", "enum": [ "credentials", "none" ] }, "transport": { "type": "string", "enum": [ "auto", "udp", "tcp", "tls" ] }, "calling_number_format": { "type": "string", "enum": [ "e164_plus", "e164_no_plus", "national" ], "description": "How the FROM number is formatted toward the carrier." }, "secure_trunking": { "type": "boolean" }, "media_encryption": { "type": "string", "enum": [ "allow", "require", "disable" ] }, "outbound_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom X-* headers on outbound INVITEs." }, "inbound_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "headers_to_attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "outbound_headers_to_attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "include_headers": { "type": "string", "enum": [ "none", "x", "all" ] }, "media_codecs": { "type": "array", "items": { "type": "string" } }, "only_listed_codecs": { "type": "boolean" }, "media_timeout_sec": { "type": [ "integer", "null" ] }, "ringing_timeout_sec": { "type": [ "integer", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "outbound_from_user_mode": { "type": "string", "enum": [ "phone_number", "auth_username" ], "default": "phone_number", "description": "Outbound From user for your own SIP trunk. Phone number preserves the existing behavior. SIP username uses the authentication username and keeps the primary DID unchanged. Not available on imported carrier connections." }, "outbound_caller_id_header": { "type": "string", "enum": [ "from_display", "p_asserted_identity", "p_preferred_identity" ], "default": "from_display", "description": "Used with SIP username identity. The primary international DID is sent in the From display name and optionally the selected identity header. Match the carrier caller ID settings." } }, "required": [ "id", "name", "provider", "numbers", "created_at", "updated_at" ] }, "SipTrunkCreate": { "type": "object", "required": [ "name", "sip_address", "numbers" ], "properties": { "name": { "type": "string" }, "sip_address": { "type": "string", "description": "Provider termination host, e.g. `sip.provider.com` (no `sip:` prefix, no port)." }, "numbers": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1, "description": "Exactly one inbound match number is required. DID: E.164. Extension: E.164 or national digits without country code." }, "trunk_kind": { "type": "string", "enum": [ "did", "extension" ], "default": "did" }, "provider": { "type": "string", "enum": [ "twilio", "custom" ], "default": "custom" }, "auth_username": { "type": "string" }, "auth_password": { "type": "string", "description": "Stored server-side; never returned by the API." }, "inbound_auth_username": { "type": "string" }, "inbound_auth_password": { "type": "string", "description": "Stored server-side; never returned by the API." }, "credential_mode": { "type": "string", "enum": [ "shared", "separate" ], "default": "shared" }, "outbound_auth_mode": { "type": "string", "enum": [ "credentials", "none" ], "default": "credentials" }, "transport": { "type": "string", "enum": [ "auto", "udp", "tcp", "tls" ], "default": "auto" }, "calling_number_format": { "type": "string", "enum": [ "e164_plus", "e164_no_plus", "national" ], "default": "e164_plus" }, "destination_country": { "type": "string", "description": "ISO-3166 alpha-2 for outbound region pinning, or empty for automatic." }, "secure_trunking": { "type": "boolean", "default": false, "description": "TLS signaling + SRTP media." }, "media_encryption": { "type": "string", "enum": [ "allow", "require", "disable" ] }, "outbound_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom outbound INVITE headers (max 10)." }, "inbound_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "headers_to_attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "outbound_headers_to_attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "include_headers": { "type": "string", "enum": [ "none", "x", "all" ], "default": "none" }, "media_codecs": { "type": "array", "items": { "type": "string", "enum": [ "PCMU", "PCMA", "G722", "AMR-WB" ] } }, "only_listed_codecs": { "type": "boolean", "default": false }, "media_timeout_sec": { "type": "integer", "minimum": 1, "maximum": 3600 }, "ringing_timeout_sec": { "type": "integer", "minimum": 5, "maximum": 600 }, "metadata": { "type": "object", "additionalProperties": true, "description": "May include inbound auth mode (`inbound_auth`, `allowed_addresses`) and region hints." }, "outbound_from_user_mode": { "type": "string", "enum": [ "phone_number", "auth_username" ], "default": "phone_number", "description": "Outbound From user for your own SIP trunk. Phone number preserves the existing behavior. SIP username uses the authentication username and keeps the primary DID unchanged. Not available on imported carrier connections." }, "outbound_caller_id_header": { "type": "string", "enum": [ "from_display", "p_asserted_identity", "p_preferred_identity" ], "default": "from_display", "description": "Used with SIP username identity. The primary international DID is sent in the From display name and optionally the selected identity header. Match the carrier caller ID settings." } } }, "KnowledgeFaqEntry": { "type": "object", "required": [ "id", "knowledge_base_id", "question", "status", "source", "occurrence_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "knowledge_base_id": { "type": "string", "format": "uuid" }, "question": { "type": "string" }, "answer": { "type": [ "string", "null" ] }, "proposed_answer": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "needs_answer", "needs_review", "approved", "dismissed" ] }, "source": { "type": "string", "enum": [ "manual", "conversation" ] }, "occurrence_count": { "type": "integer" }, "first_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "occurrences": { "type": "array", "description": "Recent source metadata. Conversation IDs and transcript-like content are intentionally excluded.", "items": { "type": "object", "properties": { "assistant_name": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "conversation_kind": { "type": "string", "enum": [ "call", "messaging", "email" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "document_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "document_count", "created_at", "updated_at" ] }, "KnowledgeBaseCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } }, "KnowledgeDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Document ID. Use it to list chunks or to retry the document." }, "knowledge_base_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string", "description": "How the document was added: `file` (upload), `text` (raw text), `url` (file URL), `website` (single web page), `crawl` (page from a website crawl source) or `drive` (file from a cloud drive source)." }, "source_url": { "type": [ "string", "null" ], "description": "Original web address for URL, website and crawled documents; otherwise null." }, "status": { "type": "string", "enum": [ "processing", "ready", "error" ], "description": "`processing` while the document is being indexed, `ready` once it is searchable, `error` if indexing failed (see `error_message`)." }, "error_message": { "type": [ "string", "null" ], "description": "Why indexing failed; null unless `status` is `error`." }, "chunk_count": { "type": "integer", "description": "Number of indexed chunks." }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ], "description": "Size of the indexed source in bytes, when known." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledge_base_id", "name", "description", "source_type", "source_url", "status", "error_message", "chunk_count", "mime_type", "size_bytes", "created_at", "updated_at" ], "description": "One document of a knowledge base. Internal storage locations are never returned." }, "KnowledgeDocumentCreate": { "type": "object", "description": "Create a document from exactly one of content or url, or retry an existing document by supplying document_id alone. All operations process synchronously. Creation returns a document (201); retry returns processing counts (200).", "properties": { "name": { "type": "string", "description": "Document name. Required for `content` sources; defaults to the file name for `url` sources." }, "content": { "type": "string", "description": "Raw text content." }, "url": { "type": "string", "description": "Public file URL to ingest." }, "description": { "type": [ "string", "null" ] }, "document_id": { "type": "string", "format": "uuid", "description": "Existing document to retry. Omit content, url, name and description." } }, "oneOf": [ { "required": [ "content", "name" ], "not": { "anyOf": [ { "required": [ "url" ] }, { "required": [ "document_id" ] } ] } }, { "required": [ "url" ], "not": { "anyOf": [ { "required": [ "content" ] }, { "required": [ "document_id" ] } ] } }, { "required": [ "document_id" ], "not": { "anyOf": [ { "required": [ "content" ] }, { "required": [ "url" ] }, { "required": [ "name" ] }, { "required": [ "description" ] } ] } } ] }, "KnowledgeDocumentChunk": { "type": "object", "description": "One indexed, searchable section of a knowledge document. Chunks are returned in source order; embeddings and internal index metadata are not exposed.", "required": [ "chunk_index", "content", "token_count" ], "properties": { "chunk_index": { "type": "integer", "minimum": 0, "description": "Zero-based position within the document." }, "content": { "type": "string", "description": "The exact text available to retrieval." }, "token_count": { "type": [ "integer", "null" ], "description": "Approximate token count captured during indexing." } } }, "CrawlSource": { "type": "object", "description": "A website crawl source of a knowledge base. Crawls pages under `root_url` (same host only, static HTML) into knowledge documents and charges credits per crawled page.", "properties": { "id": { "type": "string", "format": "uuid" }, "knowledge_base_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-defined display name shown for this source.", "example": "Help center" }, "root_url": { "type": "string", "description": "Root URL crawled (same host only)." }, "include_paths": { "type": "array", "items": { "type": "string" }, "description": "Paths crawling is restricted to; empty = whole host. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Paths to skip while crawling. Max 200 per source, 500 per knowledge base. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "max_pages": { "type": "integer", "description": "Maximum pages crawled per run (1-500).", "example": 50 }, "auto_sync": { "type": "boolean", "description": "Re-crawl automatically on a schedule." }, "sync_interval_hours": { "type": "integer", "description": "Hours between auto-sync crawls (>= 1). Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months.", "example": 24 }, "status": { "type": "string", "enum": [ "idle", "crawling", "error" ], "description": "Current crawl status." }, "last_error": { "type": [ "string", "null" ], "description": "Error from the last run, e.g. \"insufficient credits\"." }, "last_crawled_at": { "type": [ "string", "null" ], "format": "date-time" }, "pages_crawled": { "type": "integer", "description": "Pages indexed in the last run: new or changed pages, including free re-indexing." }, "credits_spent": { "type": "number", "description": "Credits charged for this source in total, across all manual and automatic runs." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CrawlPathDiscoveryRequest": { "type": "object", "required": [ "root_url" ], "properties": { "root_url": { "type": "string", "format": "uri", "description": "Website root URL to inspect (http/https)." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50, "description": "Maximum discovered pages returned." } } }, "CrawlPathDiscoveryPage": { "type": "object", "required": [ "url", "path" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Normalized same-host page URL." }, "path": { "type": "string", "description": "Page path and query, suitable for reviewing the crawl scope.", "example": "/docs/getting-started" } } }, "CrawlPathDiscovery": { "type": "object", "required": [ "root_url", "pages", "include_paths", "exclude_paths", "robots_txt_found", "sitemap_found", "truncated" ], "properties": { "root_url": { "type": "string", "format": "uri", "description": "Normalized website root URL." }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/CrawlPathDiscoveryPage" }, "description": "Crawlable same-host pages found from a sitemap or a bounded link preview." }, "include_paths": { "type": "array", "items": { "type": "string" }, "description": "Suggested top-level include prefixes derived from the discovered pages. Suggestions are not saved automatically." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Suggested exclude entries: path prefixes disallowed by robots.txt, plus exact entries (ending in $) for discovered privacy policy, cookie policy and accessibility statement pages. Imprint, terms and withdrawal pages are never suggested. The crawler enforces the current robots policy on every run; suggestions are not saved automatically." }, "robots_txt_found": { "type": "boolean", "description": "Whether robots.txt was available." }, "sitemap_found": { "type": "boolean", "description": "Whether a sitemap yielded same-host page URLs." }, "truncated": { "type": "boolean", "description": "Whether more eligible paths existed than max_pages allowed in the response." } } }, "CrawlSourceCreate": { "type": "object", "required": [ "root_url" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional custom display name shown for this source. If omitted, a URL-based name is assigned and can be edited later.", "example": "Help center" }, "root_url": { "type": "string", "description": "Root URL to crawl (http/https)." }, "include_paths": { "type": "array", "items": { "type": "string" }, "description": "Optional paths to restrict crawling (e.g. [\"/docs\"]). Empty = whole host. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Optional paths to skip (e.g. [\"/admin\"]). Max 200 per source, 500 per knowledge base. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum pages per run. Default 50." }, "auto_sync": { "type": "boolean", "description": "Re-crawl automatically on a schedule. Default false." }, "sync_interval_hours": { "type": "integer", "minimum": 1, "description": "Hours between auto-sync crawls. Default 24. Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months." } } }, "CrawlSourceUpdate": { "type": "object", "description": "Any subset of the create fields. Only provided fields are changed.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Custom display name shown for this source.", "example": "Developer documentation" }, "root_url": { "type": "string" }, "include_paths": { "type": "array", "items": { "type": "string" }, "description": "Paths to restrict crawling; empty = whole host. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Paths to skip while crawling. Max 200 per source, 500 per knowledge base. End an entry with $ to match only that exact page (for example /impressum$); without $ it is a prefix." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 500 }, "auto_sync": { "type": "boolean" }, "sync_interval_hours": { "type": "integer", "minimum": 1, "description": "Hours between auto-sync crawls. Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months." } } }, "CrawlSourcePage": { "type": "object", "description": "A ready website page already indexed for a crawl source. Listing these records is read-only and does not start a refresh or spend credits.", "required": [ "id", "name", "source_url", "status", "chunk_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Knowledge document ID." }, "name": { "type": "string", "description": "Indexed page title." }, "source_url": { "type": "string", "format": "uri", "description": "Canonical URL of the indexed page." }, "status": { "type": "string", "enum": [ "ready" ], "description": "Only fully indexed pages are returned." }, "chunk_count": { "type": "integer", "minimum": 0, "description": "Number of searchable chunks indexed for this page." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CrawlRunResult": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid" }, "pages_crawled": { "type": "integer", "description": "Pages indexed this run: new or changed pages, including free re-indexing." }, "pages_skipped": { "type": "integer", "description": "Pages that needed no indexing: unchanged content, or content already indexed under another URL of this knowledge base. Error pages and pages without readable content are not counted." }, "credits_spent": { "type": "number", "description": "Credits charged this run (per new or changed page; free re-indexing is not charged)." }, "status": { "type": "string", "enum": [ "idle", "error" ], "description": "`idle` = finished, `error` = aborted (e.g. insufficient credits; partial results kept)." }, "error": { "type": [ "string", "null" ], "description": "Abort reason when `status` is `error`." } } }, "DriveSource": { "type": "object", "description": "A cloud drive sync source of a knowledge base. Syncs files from a Google Drive, OneDrive, Box, Dropbox, or SharePoint folder (via an app connection) into knowledge documents and charges credits per new/changed file (2x the website-crawl per-page price).", "properties": { "id": { "type": "string", "format": "uuid" }, "knowledge_base_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-defined display name shown for this source.", "example": "Support knowledge" }, "provider": { "type": "string", "enum": [ "googledrive", "one_drive", "box", "dropbox", "sharepoint_graph" ], "description": "Cloud drive provider." }, "connection_id": { "type": "string", "format": "uuid", "description": "App connection used to access the folder (Automations → Connections)." }, "folder_id": { "type": "string", "description": "Remote folder ID being synced." }, "folder_name": { "type": [ "string", "null" ], "description": "Remote folder name captured from the connected drive for reference. This is provider metadata, not the editable source `name`." }, "drive_id": { "type": [ "string", "null" ], "description": "Document library drive ID. REQUIRED for provider \"sharepoint_graph\"; optional for \"one_drive\" (SharePoint/Business drives accessed via the OneDrive toolkit); unused otherwise." }, "include_subfolders": { "type": "boolean", "description": "Whether subfolders are recursed into." }, "max_files": { "type": "integer", "description": "Maximum files synced per run (1-500).", "example": 50 }, "auto_sync": { "type": "boolean", "description": "Re-sync automatically on a schedule." }, "sync_interval_hours": { "type": "integer", "description": "Hours between auto-sync runs (>= 1). Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months.", "example": 24 }, "status": { "type": "string", "enum": [ "idle", "syncing", "error" ], "description": "Current sync status." }, "last_error": { "type": [ "string", "null" ], "description": "Error from the last run, e.g. \"insufficient credits\"." }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "files_synced": { "type": "integer", "description": "Files synced in the last run (new/changed files)." }, "credits_spent": { "type": "number", "description": "Credits charged in total across all runs of this source." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DriveSourceCreate": { "type": "object", "required": [ "provider", "connection_id", "folder_id" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional custom display name shown for this source. If omitted, `folder_name` or `folder_id` is used initially and can be edited later.", "example": "Support knowledge" }, "provider": { "type": "string", "enum": [ "googledrive", "one_drive", "box", "dropbox", "sharepoint_graph" ], "description": "Cloud drive provider." }, "connection_id": { "type": "string", "format": "uuid", "description": "App connection ID — a connection under Automations → Connections whose toolkit matches `provider`." }, "folder_id": { "type": "string", "description": "Remote folder ID to sync." }, "folder_name": { "type": "string", "description": "Optional remote folder name captured from the connected drive. This is provider metadata, not the editable source `name`." }, "drive_id": { "type": "string", "description": "Document library drive ID. REQUIRED for provider \"sharepoint_graph\"; optional for \"one_drive\" (SharePoint/Business drives accessed via the OneDrive toolkit); unused otherwise." }, "include_subfolders": { "type": "boolean", "description": "Recurse into subfolders. Default true." }, "max_files": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum files per run. Default 50." }, "auto_sync": { "type": "boolean", "description": "Re-sync automatically on a schedule. Default false." }, "sync_interval_hours": { "type": "integer", "minimum": 1, "description": "Hours between auto-sync runs. Default 24. Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months." } } }, "DriveSourceUpdate": { "type": "object", "description": "Any subset of the create fields. Only provided fields are changed.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Custom display name shown for this source.", "example": "Customer success files" }, "provider": { "type": "string", "enum": [ "googledrive", "one_drive", "box", "dropbox", "sharepoint_graph" ] }, "connection_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string" }, "folder_name": { "type": [ "string", "null" ], "description": "Remote folder name captured from the connected drive. This is provider metadata, not the editable source `name`." }, "drive_id": { "type": [ "string", "null" ] }, "include_subfolders": { "type": "boolean" }, "max_files": { "type": "integer", "minimum": 1, "maximum": 500 }, "auto_sync": { "type": "boolean" }, "sync_interval_hours": { "type": "integer", "minimum": 1, "description": "Hours between auto-sync runs. Common values: 24 = daily, 168 = weekly, 720 = monthly, 2160 = every 3 months, 4320 = every 6 months." } } }, "DriveRunResult": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid" }, "files_synced": { "type": "integer", "description": "Files downloaded and (re-)indexed this run." }, "files_unchanged": { "type": "integer", "description": "Files skipped because their content was unchanged (content hash match)." }, "files_deleted": { "type": "integer", "description": "Documents removed because their file no longer exists in the folder." }, "files_failed": { "type": "integer", "description": "Files that failed to download or ingest (run continues; already-charged credits are not refunded)." }, "files_skipped_unsupported": { "type": "integer", "description": "Files skipped because their type is not supported for indexing." }, "credits_spent": { "type": "number", "description": "Credits charged this run (per new/changed file)." }, "status": { "type": "string", "enum": [ "idle", "error" ], "description": "`idle` = finished, `error` = aborted (e.g. insufficient credits; partial results kept)." }, "error": { "type": [ "string", "null" ], "description": "Abort reason when `status` is `error`." } } }, "Balance": { "type": "object", "properties": { "minutes_balance": { "type": "number", "description": "Remaining call minutes." }, "credits_balance": { "type": "number", "description": "Purchased/top-up credits that do not expire at the monthly plan reset." }, "plan_credits_balance": { "type": "number", "description": "Remaining credits from the current plan period." }, "available_credits": { "type": "number", "description": "Total spendable credits (wallet plus current plan credits)." }, "currency": { "type": "string", "description": "Denomination of the *_cents amounts in this response — always EUR (canonical).", "example": "EUR" }, "display_currency": { "type": "string", "description": "Workspace's resolved display currency (reseller customers inherit their reseller's currency).", "example": "USD" }, "display_currency_rate": { "type": "number", "description": "Units of display_currency per 1 EUR; 0 when the platform has not configured a rate yet.", "example": 1.08 }, "topup_extra_minute_cost_cents": { "type": [ "number", "null" ], "description": "Retail extra-minute price (EUR cents) used to price credit top-ups for this workspace (plan, free-tier, or platform default). Null when falling back to a flat credits-per-euro rate.", "example": 29 }, "topup_credits_per_euro": { "type": "number", "description": "Effective credits granted per €1 of top-up, derived from the workspace extra-minute rate and voice_credits_per_min.", "example": 86.21 }, "voice_credits_per_min": { "type": "number", "description": "Credits charged per call minute (platform voice rate).", "example": 25 }, "plan": { "type": [ "object", "null" ], "description": "Summary of the active plan, or `null` if none.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "price_monthly_cents": { "type": [ "number", "null" ] }, "included_minutes": { "type": [ "number", "null" ] }, "extra_minute_cost_cents": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] } } } }, "required": [ "minutes_balance", "credits_balance", "plan_credits_balance", "available_credits", "currency", "display_currency", "display_currency_rate", "topup_extra_minute_cost_cents", "topup_credits_per_euro", "voice_credits_per_min" ] }, "Referrals": { "type": "object", "required": [ "available", "enabled", "code", "url", "credits_each", "reward_cap", "rewarded_count", "pending_count", "history" ], "properties": { "available": { "type": "boolean", "description": "True when the workspace can use Refer and Earn (main platform only)." }, "enabled": { "type": "boolean", "description": "Whether the platform currently pays referral rewards." }, "code": { "type": [ "string", "null" ], "description": "Share code, for example `fam_AB12CD34`." }, "url": { "type": [ "string", "null" ], "description": "Signup URL that attributes the invited workspace to this code." }, "credits_each": { "type": "number", "description": "Wallet credits granted to each side after the invited workspace's first paid conversion." }, "reward_cap": { "type": "integer", "description": "Maximum rewarded referrals for this workspace." }, "rewarded_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "required": [ "email", "status", "credits", "created_at", "rewarded_at" ], "properties": { "email": { "type": "string", "description": "Masked friend email." }, "status": { "type": "string", "enum": [ "pending", "rewarded", "void" ] }, "credits": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "rewarded_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "Me": { "type": "object", "properties": { "api_key": { "type": "object", "description": "Metadata of the calling credential.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ], "description": "Display prefix, e.g. `fam_Ab12Cd34`." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Empty array = full access." }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "plan": { "type": [ "object", "null" ], "description": "Active plan summary (id, name, price_monthly_cents, included_minutes, extra_minute_cost_cents, currency), or `null`." }, "limits": { "type": [ "object", "null" ], "description": "Effective numeric plan limits. `-1` = unlimited, `0` = feature disabled.", "properties": { "max_assistants": { "type": [ "integer", "null" ] }, "max_campaigns": { "type": [ "integer", "null" ] }, "max_cloned_voices": { "type": [ "integer", "null" ] }, "max_knowledgebases": { "type": [ "integer", "null" ] }, "max_tools": { "type": [ "integer", "null" ] }, "max_parallel_calls": { "type": [ "integer", "null" ] }, "max_automation_runs": { "type": [ "integer", "null" ] }, "max_crm_syncs": { "type": [ "integer", "null" ] }, "max_crm_synced_contacts": { "type": [ "integer", "null" ] }, "max_own_numbers": { "type": [ "integer", "null" ] }, "max_members": { "type": [ "integer", "null" ] } } }, "features": { "type": [ "object", "null" ], "description": "Boolean feature toggles of the active plan.", "properties": { "web_widget": { "type": [ "boolean", "null" ] }, "ai_avatar": { "type": [ "boolean", "null" ] }, "secondary_languages": { "type": [ "boolean", "null" ] }, "stt_keyterms": { "type": [ "boolean", "null" ] }, "automation_platform": { "type": [ "boolean", "null" ] }, "calendar_integrations": { "type": [ "boolean", "null" ] }, "custom_dashboards": { "type": [ "boolean", "null" ] }, "flow_builder": { "type": [ "boolean", "null" ] }, "connect_ai_mcp": { "type": [ "boolean", "null" ] }, "whitelabel_enabled": { "type": [ "boolean", "null" ] }, "live_monitoring": { "type": [ "boolean", "null" ] }, "simulations": { "type": [ "boolean", "null" ] }, "assistant_engine_modes": { "type": "object", "description": "Assistant voice engine modes included in the workspace's current plan.", "required": [ "pipeline", "realtime", "half_cascade", "translation" ], "properties": { "pipeline": { "type": "boolean" }, "realtime": { "type": "boolean" }, "half_cascade": { "type": "boolean" }, "translation": { "type": "boolean" } } } } }, "display_currency": { "type": "string", "description": "Workspace's resolved display currency (reseller customers inherit their reseller's currency).", "example": "USD" }, "display_currency_rate": { "type": "number", "description": "Units of display_currency per 1 EUR; 0 when the platform has not configured a rate yet.", "example": 1.08 } } }, "CreditNotificationPreferences": { "type": "object", "required": [ "enabled", "threshold_credits", "push_enabled", "email_enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether personal low-credit warnings are enabled." }, "threshold_credits": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Send the warning when the available balance reaches this number of credits." }, "push_enabled": { "type": "boolean", "description": "Deliver the warning through browser push notifications." }, "email_enabled": { "type": "boolean", "description": "Deliver the warning to the account email address." } } }, "LoopRecordingControl": { "type": "object", "required": [ "available", "active", "status", "canStart", "canStop", "reason" ], "properties": { "available": { "type": "boolean", "description": "Whether this call supports recording controls for the authenticated member." }, "active": { "type": "boolean", "description": "Confirmed recording state; false while paused or stopped." }, "status": { "type": "string", "enum": [ "idle", "starting", "recording", "stopping", "paused", "processing", "unavailable" ] }, "canStart": { "type": "boolean" }, "canStop": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "description": "Customer-facing explanation when recording controls are unavailable." } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "transfer", "call_usage", "purchase", "plan_included", "admin_adjust", "email_usage", "crawl_usage", "sla_fee", "retranscribe_usage", "sms_usage", "simulation_usage", "reanalyze_usage", "card_collect_usage", "chat_usage", "messaging_usage", "qa_usage", "automation_usage", "milian_usage", "loop_usage", "recording_usage", "referral" ] }, "delta_minutes": { "type": "number", "deprecated": true, "description": "Legacy minute balance change. Always 0 under credit billing; only entries from older minute-based billing carry a value. Use `delta_credits` and `delta_plan_credits`." }, "delta_credits": { "type": "number", "description": "Purchased-wallet credits credited (positive) or debited (negative)." }, "delta_plan_credits": { "type": "number", "description": "Plan-period credits credited (positive) or debited (negative)." }, "note": { "type": "string", "description": "Customer-facing description such as Credit top-up, Assistant recording, Loop recording, Voicemail recording, Call transfer, WhatsApp voice call or Loop usage. A generic Call recording or Loop usage label is used when its origin cannot be verified. Internal reconciliation references are omitted." }, "call_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set for `call_usage` entries." }, "created_at": { "type": "string", "format": "date-time" }, "recording_source": { "type": [ "string", "null" ], "enum": [ "assistant", "loop", "voicemail", null ], "description": "Verified origin of a recording charge. Null for other transactions or when the original recording link is unavailable. Both current recording entries and older usage entries may carry this value." }, "usage_source": { "type": [ "string", "null" ], "enum": [ "loop", "assistant_transfer", "assistant_whatsapp", null ], "description": "Verified origin of a `loop_usage` charge: `loop` for a Famulor Loop call, `assistant_transfer` for an AI assistant call that was transferred or bridged to another party, `assistant_whatsapp` for an AI assistant WhatsApp voice call. Null for other transactions, for recordings (see `recording_source`) or when the original link is unavailable." } }, "required": [ "id", "type", "delta_minutes", "delta_credits", "delta_plan_credits", "created_at" ] }, "ToolUsage": { "type": "object", "required": [ "tool_id", "usage_count", "assistants" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "usage_count": { "type": "integer", "minimum": 0 }, "assistants": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } }, "UserToolVersion": { "type": "object", "required": [ "tool_id", "revision", "name", "type", "config", "is_active", "created_at" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "description": "Monotone optimistic concurrency revision." }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "api", "mcp", "builtin" ] }, "config": { "type": "object", "description": "Secret-masked historical configuration." }, "is_active": { "type": "boolean" }, "usage_count": { "type": "integer", "minimum": 0, "description": "Number of assistants currently assigned to this tool." }, "health": { "type": "object", "description": "Secret-free connection and latest-run health. Present on tool-list responses.", "properties": { "connection_status": { "type": [ "string", "null" ], "enum": [ "ok", "reauth_required", null ], "description": "OAuth connection status for MCP tools; null for other authentication modes." }, "latest_run": { "oneOf": [ { "type": "object", "required": [ "status", "created_at" ], "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "created_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } }, "created_at": { "type": "string", "format": "date-time" } } }, "ToolsetRevisionMeta": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } } }, "UserTool": { "type": "object", "description": "A reusable tool of the account. Secret values inside `config` (auth values, header values) are always masked as `•••`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Tool name — doubles as the LLM function name (letters, digits, `_`, `-`)." }, "description": { "type": "string", "description": "Human/LLM-readable description of what the tool does." }, "type": { "type": "string", "enum": [ "mcp", "api", "builtin" ], "description": "`api` = HTTP API tool, `mcp` = external MCP server, `builtin` = built-in capability (call transfer, warm call transfer, end call, DTMF, keypad collection, Cal.com scheduling, assistant transfer)." }, "config": { "type": "object", "description": "Type-specific configuration (URL, method, parameters, auth). Secret values are masked." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UserToolInput": { "type": "object", "description": "Create/update payload for a reusable tool. On update, `type` is immutable and sending `•••` for a secret config value keeps the stored value unchanged.", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$", "description": "Tool name — becomes the LLM function name." }, "description": { "type": "string", "maxLength": 1000, "description": "What the tool does — shown to the LLM as the function description." }, "type": { "type": "string", "enum": [ "api", "mcp", "builtin" ], "description": "`api` = HTTP API tool, `mcp` = external MCP server, `builtin` = built-in capability (call transfer & co.). Immutable after creation." }, "config": { "type": "object", "description": "Type-specific configuration. `api`: `{ method, url, headers, parameters[], static_values, response_mapping, timeout_ms, async, filler_phrase, speak_after }`. `speak_after` (default true): when false, the tool completes silently without an LLM spoken reply. `mcp`: `{ url, auth_type, auth_header_name, auth_value_encrypted, allowed_tools[], tool_options: { [toolName]: { cancellable, on_duplicate, report_progress } }, timeout_ms }`; `on_duplicate` is allow, reject, replace, or confirm, and replace requires cancellation. `builtin`: exactly one built-in tool item `{ type: call_transfer|warm_call_transfer|end_call|…|collect_payment_card|set_variable, description?, stripe_connection_id? for collect_payment_card, allowed_keys? for set_variable, ... }` — same shape as one element of an assistant's `builtin_tools` array; secrets are masked as `•••` in responses. For warm_call_transfer, optional post_answer_dtmf accepts up to 32 characters (0-9*#A-D and w, case-insensitive); each w is a fixed half-second pause after answer and before the briefing. Omit or clear it for a direct destination. See BuiltinTool for field constraints. Saved caller-facing announcements, filler phrases and end-call farewells remain editable. With secondary languages configured on the assistant, they guide generated wording in the current supported conversation language without fixed saved audio. Otherwise their existing delivery behavior is preserved. An empty End call farewell adds no speech." }, "is_active": { "type": "boolean", "description": "Whether the tool is active (default `true`)." }, "expected_revision": { "type": "integer", "minimum": 1, "description": "Required for PATCH to prevent lost concurrent updates." } } }, "ConsentMode": { "type": "string", "enum": [ "universal", "per_channel" ], "description": "`universal` suppresses all linked marketing channels; `per_channel` suppresses only the originating channel." }, "ConsentChannel": { "type": "string", "enum": [ "voice", "sms", "email", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ], "description": "Communication channel where an opt-out originated or on which suppression should be evaluated." }, "ConsentComplianceSettings": { "type": "object", "required": [ "mode", "per_channel_available" ], "properties": { "mode": { "$ref": "#/components/schemas/ConsentMode" }, "per_channel_available": { "type": "boolean", "description": "Whether the current plan permits selecting per-channel mode. Suppression enforcement remains active when false." } } }, "SuppressionEntry": { "type": "object", "required": [ "id", "contact_id", "phone", "email", "identity_type", "identity", "scope", "origin_channel", "purpose", "reason", "source", "mode_at_opt_out", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked workspace contact/lead ID, when resolved." }, "phone": { "type": "string", "nullable": true, "description": "Phone number in E.164 format.", "example": "+4930123456" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "contact@example.com" }, "identity_type": { "type": "string", "nullable": true, "enum": [ "phone", "email", "platform_user" ] }, "identity": { "type": "string", "nullable": true, "description": "Normalized public contact identity used for this suppression." }, "scope": { "type": "string", "enum": [ "all", "voice", "sms", "email", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ], "description": "`all` blocks every linked marketing channel; a channel value blocks only that channel." }, "origin_channel": { "$ref": "#/components/schemas/ConsentChannel" }, "purpose": { "type": "string", "const": "marketing" }, "reason": { "type": "string", "nullable": true, "example": "Unsubscribe request" }, "source": { "type": "string", "description": "How the opt-out was recorded, for example `api`, `manual`, `keyword`, `agent`, `unsubscribe`, or `import`." }, "mode_at_opt_out": { "$ref": "#/components/schemas/ConsentMode" }, "created_at": { "type": "string", "format": "date-time" } } }, "ScheduledCallback": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": "string", "format": "uuid" }, "assistant_name": { "type": "string", "nullable": true }, "to_number": { "type": "string", "description": "Phone number to dial in E.164 format.", "example": "+4930123456" }, "scheduled_for": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "dialing", "completed", "failed", "cancelled" ] }, "attempts": { "type": "integer" }, "channel": { "type": "string", "description": "Origin channel: `voice`, `messaging`, `email`, or `unknown`.", "example": "voice" }, "source_call_id": { "type": "string", "format": "uuid", "nullable": true }, "call_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Outbound call created when the callback was dialed." }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MemorySettings": { "type": "object", "required": [ "memory_enabled_default", "memory_staleness_days", "memory_channels", "memory_consent_required", "memory_retention_days" ], "properties": { "memory_enabled_default": { "type": "boolean", "description": "Workspace default for caller memory. Assistants with `memory_mode: \"inherit\"` follow this value; `\"on\"`/`\"off\"` override it per assistant.", "example": false }, "memory_staleness_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Days without a successful memory update until content is considered stale and no longer injected. `null` = content never goes stale.", "example": 180 }, "memory_channels": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Configured channels that may read and write customer memory. Web requires a current verified widget phone and visitor memory consent." }, "memory_consent_required": { "type": "boolean", "description": "When true, unknown consent blocks memory reads and writes. Explicitly denied consent always blocks memory, regardless of this setting.", "example": true }, "memory_retention_days": { "type": "integer", "minimum": -1, "maximum": 3650, "description": "Rolling retention in days; `-1` keeps memory until manually erased.", "example": 365 }, "memory_available_channels": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/ConfigurableMemoryChannel" }, "description": "Channels available to configure in this workspace. Web and SMS are excluded for reseller customer workspaces." } } }, "MemoryChannel": { "type": "string", "enum": [ "voice", "sms", "whatsapp", "email", "web", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip", "web_chat", "web_voice" ], "description": "Memory channels. Web Chat and Web Voice require a current verified widget email or phone and memory consent. Web and SMS memory require a root workspace. Legacy web configuration expands to both web channels; anonymous sessions remain excluded." }, "OperationalMemoryChannel": { "type": "string", "description": "A memory channel available without an additional widget identity grant. Web is excluded from these defaults.", "enum": [ "voice", "sms", "whatsapp", "email", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "MemoryConsentStatus": { "type": "string", "enum": [ "unknown", "granted", "denied" ] }, "CustomerMemory": { "type": "object", "required": [ "id", "lead_id", "scope", "variables", "source_channels", "interaction_count", "revision", "consent_status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "lead_id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": "string", "format": "uuid", "nullable": true }, "assistant_name": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "workspace", "assistant" ] }, "summary": { "type": "string", "nullable": true }, "preferences": { "type": "object", "additionalProperties": true }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Structured values retained under this memory row's scope. Workspace values are shared; assistant values are private to the named assistant." }, "source_channels": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryChannel" } }, "interaction_count": { "type": "integer", "minimum": 0 }, "revision": { "type": "integer", "minimum": 1, "description": "Optimistic concurrency token required by PATCH." }, "consent_status": { "$ref": "#/components/schemas/MemoryConsentStatus" }, "consent_at": { "type": "string", "format": "date-time", "nullable": true }, "consent_source": { "type": "string", "nullable": true }, "last_read_at": { "type": "string", "format": "date-time", "nullable": true }, "last_written_at": { "type": "string", "format": "date-time", "nullable": true }, "retention_until": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "contact": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "avatar_url": { "type": "string", "format": "uri", "nullable": true }, "sources": { "type": "array", "items": { "type": "string" } } } }, "identities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hint": { "type": "string", "description": "Masked, customer-safe identity hint." }, "channel": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time" } } } } } }, "CustomerMemoryDetail": { "type": "object", "required": [ "contact", "memories", "identities", "events" ], "properties": { "contact": { "type": "object", "additionalProperties": true }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMemory" } }, "identities": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "identity_type": { "type": "string", "enum": [ "phone", "email", "platform_user", "web_user" ] }, "identity_hint": { "type": "string", "nullable": true, "description": "Masked, customer-safe identity hint." }, "channel": { "$ref": "#/components/schemas/MemoryChannel" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "description": "Recent customer-memory audit events without transcript contents.", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": "string", "format": "uuid", "nullable": true }, "assistant_name": { "type": "string", "nullable": true }, "channel": { "$ref": "#/components/schemas/MemoryChannel" }, "action": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "source_record_type": { "type": "string", "nullable": true }, "source_record_id": { "type": "string", "nullable": true }, "details": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "DarkWindowChannelConfig": { "type": "object", "required": [ "enabled", "start", "end" ], "properties": { "enabled": { "type": "boolean", "description": "Whether proactive outbound activity is paused during this channel window." }, "start": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "21:00" }, "end": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" } }, "additionalProperties": false }, "DarkWindowSettingsPatch": { "type": "object", "minProperties": 1, "description": "Sparse per-channel quiet-hour update. Omitted channels remain unchanged.", "properties": { "voice": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "sms": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "email": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "whatsapp": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "telegram": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "slack": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "messenger": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "teams": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "discord": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "gchat": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "x": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "freshdesk": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "gmail": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "outlook": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "zendesk": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "servicenow": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "intercom": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "zoho_mail": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "agent_mail": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "instagram": { "$ref": "#/components/schemas/DarkWindowChannelConfig" }, "zulip": { "$ref": "#/components/schemas/DarkWindowChannelConfig" } }, "additionalProperties": false }, "DarkWindowSettings": { "allOf": [ { "$ref": "#/components/schemas/DarkWindowSettingsPatch" }, { "type": "object", "required": [ "voice", "sms", "email", "whatsapp", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] } ] }, "DarkWindowSettingsResponse": { "type": "object", "required": [ "settings", "timezone" ], "properties": { "settings": { "$ref": "#/components/schemas/DarkWindowSettings" }, "timezone": { "type": "string", "description": "IANA workspace timezone used to interpret every channel window.", "example": "Europe/Berlin" } } }, "RetentionSettingsInput": { "type": "object", "minProperties": 1, "description": "Per-channel retention overrides in months. `null` clears an override and restores the plan default.", "properties": { "calls_months": { "type": "integer", "nullable": true }, "leads_months": { "type": "integer", "nullable": true }, "email_months": { "type": "integer", "nullable": true }, "sms_months": { "type": "integer", "nullable": true }, "telegram_months": { "type": "integer", "nullable": true }, "slack_months": { "type": "integer", "nullable": true }, "messenger_months": { "type": "integer", "nullable": true }, "teams_months": { "type": "integer", "nullable": true }, "discord_months": { "type": "integer", "nullable": true }, "gchat_months": { "type": "integer", "nullable": true }, "x_months": { "type": "integer", "nullable": true }, "whatsapp_months": { "type": "integer", "nullable": true } }, "additionalProperties": false }, "RetentionSettingsResponse": { "allOf": [ { "type": "object", "required": [ "settings", "sources", "caps", "entitled", "plan_default_days", "upgrade_url" ], "properties": { "settings": { "$ref": "#/components/schemas/RetentionSettingsInput" }, "sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "workspace", "unset" ] } }, "caps": { "type": "object", "additionalProperties": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "integer", "minimum": 1, "maximum": 24 }, "max": { "type": "integer", "minimum": 1, "maximum": 24 } } } }, "entitled": { "type": "boolean", "description": "Whether the governing workspace plan includes Data Retention." }, "plan_default_days": { "type": "integer", "nullable": true, "description": "Effective plan default in days (`0` = immediate, otherwise typically a multiple of 30 up to 720). `null` means no cleanup fallback is configured." }, "plan_default_months": { "type": "integer", "nullable": true, "description": "Month value when `plan_default_days` is divisible by 30 (1–24); otherwise `null`." }, "upgrade_url": { "type": "string", "example": "/settings?panel=plan" } } } ] }, "MarketingSettingsInput": { "type": "object", "properties": { "integrations": { "type": "object", "description": "Partial marketing_integrations object. Public IDs only.", "additionalProperties": true }, "secrets": { "type": "object", "properties": { "meta_capi_token": { "type": "string" }, "ga4_api_secret": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "MarketingSettingsResponse": { "type": "object", "required": [ "integrations", "secrets" ], "properties": { "integrations": { "type": "object", "additionalProperties": true }, "secrets": { "type": "object", "required": [ "meta_capi_token_set", "ga4_api_secret_set" ], "properties": { "meta_capi_token_set": { "type": "boolean" }, "ga4_api_secret_set": { "type": "boolean" } } } } }, "OutboundLimitRequestInput": { "type": "object", "required": [ "requested_daily_limit", "reason" ], "properties": { "requested_daily_limit": { "type": "integer", "oneOf": [ { "minimum": 1 }, { "enum": [ -1 ] } ], "description": "Requested number of integrated outbound calls per workspace day, or -1 to request unlimited calls.", "example": 300 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "business_website": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true } }, "additionalProperties": false }, "SupportRequestInput": { "type": "object", "required": [ "client_request_id", "subject", "message" ], "properties": { "client_request_id": { "type": "string", "format": "uuid", "description": "Stable UUID generated by the client. Reuse it only when retrying the same request." }, "subject": { "type": "string", "minLength": 1, "maxLength": 160 }, "message": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "additionalProperties": false }, "SupportRequest": { "type": "object", "required": [ "reference", "status", "created_at" ], "properties": { "reference": { "type": "string", "pattern": "^SUP-[A-F0-9]{12}$", "example": "SUP-4BC693C5FD56" }, "status": { "type": "string", "enum": [ "submitted" ] }, "created_at": { "type": "string", "format": "date-time" }, "priority_support": { "type": "boolean", "description": "True when the workspace has Priority Support (included in its plan or booked as add-on) and the request was routed to priority support." } } }, "OutboundLimitRequest": { "type": "object", "required": [ "id", "requested_daily_limit", "reason", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "requested_daily_limit": { "type": "integer" }, "reason": { "type": "string" }, "business_website": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "approved_daily_limit": { "type": "integer", "nullable": true, "description": "The approved daily allowance. `-1` means unlimited." }, "review_note": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OutboundLimitStatus": { "type": "object", "required": [ "limit", "used_today", "remaining", "percent_used", "timezone", "usage_date", "resets_at", "latest_request", "requests" ], "properties": { "limit": { "type": "integer", "nullable": true, "description": "Current daily allowance. `null` means unlimited." }, "used_today": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0, "nullable": true, "description": "Calls remaining today. `null` means unlimited." }, "percent_used": { "type": "number", "minimum": 0, "maximum": 100 }, "timezone": { "type": "string", "description": "Workspace timezone used for the daily reset." }, "usage_date": { "type": "string", "format": "date" }, "resets_at": { "type": "string", "format": "date-time" }, "latest_request": { "$ref": "#/components/schemas/OutboundLimitRequest", "nullable": true }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundLimitRequest" } } } }, "CustomDomainDnsInstruction": { "type": "object", "required": [ "type", "name", "value", "purpose" ], "properties": { "type": { "type": "string", "enum": [ "TXT", "A", "CNAME" ] }, "name": { "type": "string", "description": "DNS record host/name. `@` means the zone apex." }, "value": { "type": "string", "description": "Exact DNS value to configure." }, "purpose": { "type": "string", "enum": [ "ownership", "routing" ] } } }, "CustomDomainStatus": { "type": "object", "required": [ "domain", "companion_domain", "attached", "ownership_verified", "dns_configured", "ready", "configured_by", "accepted_challenges", "verification", "required_records", "verification_error", "companion_error", "last_checked_at" ], "properties": { "domain": { "type": [ "string", "null" ], "example": "app.famulor.io" }, "companion_domain": { "type": [ "string", "null" ], "description": "www/apex companion hostname that 308-redirects to `domain`, when applicable.", "example": "www.example.com" }, "attached": { "type": "boolean", "description": "Whether the domain is attached to the platform." }, "ownership_verified": { "type": "boolean", "description": "Whether the ownership challenge has passed." }, "dns_configured": { "type": "boolean", "description": "Whether DNS points to the platform and TLS can be issued automatically." }, "ready": { "type": "boolean", "description": "True only when both ownership_verified and dns_configured are true." }, "configured_by": { "type": [ "string", "null" ], "enum": [ "A", "CNAME", "http", "dns-01", null ] }, "accepted_challenges": { "type": "array", "items": { "type": "string", "enum": [ "dns-01", "http-01" ] } }, "verification": { "type": "array", "items": { "type": "object", "required": [ "type", "domain", "value", "reason" ], "properties": { "type": { "type": "string" }, "domain": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } } }, "required_records": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDomainDnsInstruction" } }, "verification_error": { "type": [ "string", "null" ], "description": "Most recent non-fatal ownership verification error while DNS is still propagating." }, "companion_error": { "type": [ "string", "null" ], "description": "Non-fatal error while attaching the www/apex companion redirect domain." }, "last_checked_at": { "type": "string", "format": "date-time" } } }, "CalendlyConnection": { "type": "object", "required": [ "id", "provider", "account_email", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "const": "calendly" }, "account_email": { "type": "string", "description": "Calendly account email or display name." }, "status": { "type": "string", "enum": [ "ok", "reauth_required" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CalendlyLocation": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "description": "Calendly location kind required by the Scheduling API." }, "label": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "requires_input": { "type": "boolean", "description": "Whether the assistant must collect a location value from the invitee." } } }, "CalendlyEventType": { "type": "object", "required": [ "id", "name", "duration", "active", "locations" ], "properties": { "id": { "type": "string", "description": "Public event-type identifier used in integration config. The full Calendly resource URI is not exposed." }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "integer", "null" ], "description": "Appointment duration in minutes." }, "active": { "type": "boolean" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/CalendlyLocation" } } } }, "AcuityConnection": { "type": "object", "required": [ "id", "provider", "account_email", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "const": "acuity" }, "account_email": { "type": "string", "description": "Acuity account email or display name." }, "status": { "type": "string", "enum": [ "ok", "reauth_required" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AcuityAppointmentType": { "type": "object", "required": [ "id", "name", "duration", "active", "type", "calendarIDs" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "Numeric appointment-type identifier used in integration config." }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "integer", "null" ], "minimum": 1, "description": "Appointment duration in minutes." }, "type": { "type": "string", "enum": [ "service", "class", "series" ] }, "active": { "type": "boolean" }, "calendarIDs": { "type": "array", "description": "Calendars that can host this appointment type.", "items": { "type": "integer", "minimum": 1 } } } }, "AcuityCalendar": { "type": "object", "required": [ "id", "name", "timezone", "active" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone reported by Acuity, when available." }, "active": { "type": "boolean" } } }, "Integration": { "type": "object", "description": "A calendar integration. `config` is provider-specific; secret values are always masked as `•••`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Display name (unique per workspace)." }, "provider": { "type": "string", "enum": [ "calcom", "calendly", "acuity", "google_calendar", "outlook_calendar", "native", "etermin", "meetergo", "highlevel" ], "description": "Immutable after creation." }, "config": { "type": "object", "description": "Provider-specific configuration. calcom: `{ api_key_encrypted, event_type_id, timezone?, allowed_ops?: { book, cancel, reschedule } }`; with cancel/reschedule allowed, assistants find the caller's upcoming booking by phone number or by email plus full name and can cancel or move it. calendly: `{ connection_id, event_type_id, event_type_name?, event_type_duration_min?, location?: { kind, label?, location?, requires_input? }, booking_mode ('api'|'link'), link_channel ('sms'|'email'), allowed_ops?: { book, cancel, reschedule } }`; use the Calendly discovery endpoints first, and note that `reschedule` is always false. Full Calendly resource URIs are never exposed. acuity writes accept `{ connection_id, appointment_type_id, calendar_id?, allowed_ops?: { book, cancel, reschedule } }`; responses additionally contain provider-canonical `appointment_type_name`, `appointment_type_duration_min`, `appointment_type_kind`, `calendar_name`, and `timezone`. Use the Acuity discovery endpoints first, omit `calendar_id` to use any compatible calendar, and note that `reschedule` is forced false for `series`. Client-supplied Acuity metadata is never authoritative. Acuity account identifiers and all OAuth tokens are never exposed. etermin: `{ public_key_encrypted, secret_key_encrypted, service_id, calendar_id, service_name?, calendar_name?, duration_min?, timezone?, webhook_token (auto), webhook_secret? }` — inbound Web Push at `POST /api/webhooks/etermin/{webhook_token}`. google_calendar / outlook_calendar: `{ connection_id, calendar_id?, default_duration_min?, summary_template? }`. native: `{ event_type_id }` (booking event type UUID). Secret values are masked as `•••` in responses; send `•••` on update to keep a stored legacy secret. For meetergo use a personal access token or platform API key in token_encrypted, a meeting_type_id, optional timezone, and allowed_ops.book. Platform API keys also require acting_user_id; personal tokens must omit it. Meeting title and duration are verified with the provider. Native meetergo supports availability and booking; use the meetergo MCP app for other operations." }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ok", "error", "link_mode" ], "description": "`link_mode` = Calendly fallback: the plan cannot use the Scheduling API, the assistant sends a single-use scheduling link instead of hard-booking." }, "last_error": { "type": [ "string", "null" ] }, "connection_status": { "type": [ "string", "null" ], "enum": [ "ok", "reauth_required", null ], "description": "Health of the OAuth connection behind this integration (Calendly, Acuity, Google Calendar, Outlook Calendar, HighLevel). `reauth_required` means the provider rejected the saved sign-in — reconnect it under Booking → Integrations. `null` for providers without an OAuth connection (Cal.com, eTermin, native)." }, "needs_reauth": { "type": "boolean", "description": "True when `connection_status` is `reauth_required`. Assistants cannot book through this integration until it is reconnected; workspace owners and admins are emailed once and then every 7 days while it stays broken." }, "connection_error": { "type": [ "string", "null" ], "description": "The underlying refresh error for a flagged HighLevel connection (capped to 300 characters). `null` for every other provider — Calendly/Acuity/Google Calendar/Outlook Calendar report only `connection_status`/`needs_reauth`, with no per-connection error text available." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IntegrationInput": { "type": "object", "required": [ "name", "provider", "config" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "provider": { "type": "string", "enum": [ "calcom", "calendly", "acuity", "google_calendar", "outlook_calendar", "native", "etermin", "meetergo", "highlevel" ] }, "config": { "type": "object", "description": "Provider-specific configuration (see the Integration schema). For Acuity send an OAuth `connection_id`, numeric `appointment_type_id`, optional `calendar_id`, and optional `allowed_ops`; appointment metadata and timezone are loaded canonically from Acuity. For meetergo use a personal access token or platform API key in token_encrypted, a meeting_type_id, optional timezone, and allowed_ops.book. Platform API keys also require acting_user_id; personal tokens must omit it. Meeting title and duration are verified with the provider. Native meetergo supports availability and booking; use the meetergo MCP app for other operations." }, "is_active": { "type": "boolean", "default": true } } }, "BookingEventType": { "type": "object", "description": "An event type of the native booking engine. Each active event type has a public, embeddable booking page at `/book/{workspace}/{slug}`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{3,64}$", "description": "Unique within the workspace; public page URL is /book/{workspace}/{slug}." }, "workspace": { "type": "string", "description": "Tenant booking_handle used in the public URL /book/{workspace}/{slug}." }, "description": { "type": "string" }, "duration_min": { "type": "integer", "minimum": 5, "maximum": 480 }, "timezone": { "type": "string", "description": "IANA timezone the weekly availability is defined in." }, "availability": { "type": "object", "description": "Weekly windows: `{ \"mon\": [{\"start\":\"09:00\",\"end\":\"17:00\"}], … \"sun\": [] }` (\"HH:MM\" 24h, non-overlapping per day)." }, "buffer_before_min": { "type": "integer" }, "buffer_after_min": { "type": "integer" }, "min_notice_min": { "type": "integer" }, "max_days_ahead": { "type": "integer" }, "slot_increment_min": { "type": [ "integer", "null" ], "description": "Slot step in minutes; null = duration_min." }, "calendar_connection_id": { "type": [ "string", "null" ], "description": "Optional Google/Outlook connection for free/busy subtraction + event push." }, "reminder_hours": { "type": [ "integer", "null" ], "description": "Reminder email N hours before the meeting; null = no reminder." }, "is_active": { "type": "boolean" }, "booking_fields": { "type": "array", "maxItems": 30, "description": "Custom booking questions, in display order. Name is always required; email_required and phone_required control the system contact fields.", "items": { "$ref": "#/components/schemas/BookingField" } }, "phone_required": { "type": "boolean", "description": "Whether the system \"Phone\" field is required to book. When false, phone is still asked but optional." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "email_required": { "type": "boolean", "default": true, "description": "Whether an invitee email is required. Google Meet and Microsoft Teams always require a valid email." }, "sender_email_address_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Active verified email address belonging to this workspace. Null uses automatic workspace or inherited reseller SMTP, then the platform identity for eligible workspaces." }, "confirmation_email_subject": { "type": "string", "nullable": true, "maxLength": 200, "description": "Custom initial confirmation subject; empty uses the standard subject. Supports the same booking variables as the message." }, "confirmation_email_body": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Custom plain-text confirmation. Supported variables are returned by GET /booking-email-templates. Blank/null restores the localized standard message." }, "email_templates": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Complete replacement of the six additional guest/host email templates. Omit to preserve saved values; null or {} restores all six defaults. Confirmation uses the existing confirmation subject/body fields. GET /booking-email-templates returns standard templates and supported variables.", "properties": { "cancellation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "reschedule": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "reminder": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_confirmation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_cancellation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_reschedule": { "$ref": "#/components/schemas/BookingEmailTemplate" } } }, "email_locale": { "type": "string", "nullable": true, "enum": [ "en", "de", "fr", "es", null ], "description": "Language of the standard booking email texts (guest and host) for this event type. null (default) uses each recipient's language. Custom subject/body text is sent as written." }, "guest_emails_enabled": { "type": "boolean", "default": true, "description": "Send emails to the invitee. false = no confirmation, cancellation, reschedule or reminder emails to guests and no invitations from the connected calendar (the guest is not added as an attendee); host notifications still send." }, "hour_cycle": { "type": "string", "enum": [ "12h", "24h" ], "default": "24h", "description": "Time format for the weekly availability editor and host emails. Availability values remain HH:mm. Guest emails follow the guest's saved booking-page preference, falling back to this format for older bookings." } } }, "BookingField": { "type": "object", "description": "A custom booking question asked on the public booking page. Answers are keyed by `id` on a booking's `answers` object and can be prefilled on the public booking page via the matching URL parameter.", "required": [ "id", "type", "label", "required" ], "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,39}$", "description": "Identifier, unique within the event type. Doubles as the answers key and the URL prefill parameter, e.g. ?company=Acme. Reserved and not allowed: name, email, phone, notes, start, timezone, website, answers, call_id." }, "type": { "type": "string", "enum": [ "email", "phone", "address", "short_text", "number", "long_text", "select", "multiselect", "multiple_emails", "checkbox_group", "radio_group", "checkbox", "url" ], "description": "Input type shown on the booking page." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Question label shown to the visitor." }, "placeholder": { "type": "string", "maxLength": 120 }, "required": { "type": "boolean", "description": "Whether the visitor must answer this question before booking." }, "options": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "description": "Choices, in display order. Required for select, multiselect, checkbox_group and radio_group; unused for other types." }, "disable_if_prefilled": { "type": "boolean", "description": "When true, the field becomes read-only on the public page if its value was prefilled via URL parameter." } } }, "BookingEventTypeInput": { "type": "object", "required": [ "name", "slug", "duration_min", "timezone", "availability" ], "properties": { "name": { "type": "string", "maxLength": 128 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{3,64}$" }, "duration_min": { "type": "integer", "minimum": 5, "maximum": 480 }, "timezone": { "type": "string", "example": "Europe/Berlin" }, "availability": { "type": "object", "example": { "mon": [ { "start": "09:00", "end": "17:00" } ], "fri": [ { "start": "09:00", "end": "12:00" } ] } }, "description": { "type": "string", "maxLength": 2000 }, "buffer_before_min": { "type": "integer", "default": 0 }, "buffer_after_min": { "type": "integer", "default": 0 }, "min_notice_min": { "type": "integer", "default": 60 }, "max_days_ahead": { "type": "integer", "default": 30 }, "slot_increment_min": { "type": [ "integer", "null" ] }, "reminder_hours": { "type": [ "integer", "null" ] }, "is_active": { "type": "boolean", "default": true }, "booking_fields": { "type": "array", "maxItems": 30, "description": "Custom booking questions, in display order. Name is always required; email_required and phone_required control the system contact fields.", "items": { "$ref": "#/components/schemas/BookingField" } }, "phone_required": { "type": "boolean", "default": false, "description": "Require the visitor's phone number (E.164) to book. When false (default), phone is still asked but optional." }, "email_required": { "type": "boolean", "default": true, "description": "Whether an invitee email is required. Google Meet and Microsoft Teams always require a valid email." }, "sender_email_address_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Active verified email address belonging to this workspace. Null uses automatic workspace or inherited reseller SMTP, then the platform identity for eligible workspaces." }, "confirmation_email_subject": { "type": "string", "nullable": true, "maxLength": 200, "description": "Custom initial confirmation subject; empty uses the standard subject. Supports the same booking variables as the message." }, "confirmation_email_body": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Custom plain-text confirmation. Supported variables are returned by GET /booking-email-templates. Blank/null restores the localized standard message." }, "email_templates": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Complete replacement of the six additional guest/host email templates. Omit to preserve saved values; null or {} restores all six defaults. Confirmation uses the existing confirmation subject/body fields. GET /booking-email-templates returns standard templates and supported variables.", "properties": { "cancellation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "reschedule": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "reminder": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_confirmation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_cancellation": { "$ref": "#/components/schemas/BookingEmailTemplate" }, "host_reschedule": { "$ref": "#/components/schemas/BookingEmailTemplate" } } }, "email_locale": { "type": "string", "nullable": true, "enum": [ "en", "de", "fr", "es", null ], "description": "Language of the standard booking email texts (guest and host) for this event type. null (default) uses each recipient's language. Custom subject/body text is sent as written." }, "guest_emails_enabled": { "type": "boolean", "default": true, "description": "Send emails to the invitee. false = no confirmation, cancellation, reschedule or reminder emails to guests and no invitations from the connected calendar (the guest is not added as an attendee); host notifications still send." }, "hour_cycle": { "type": "string", "enum": [ "12h", "24h" ], "default": "24h", "description": "Time format for the weekly availability editor and host emails. Availability values remain HH:mm. Guest emails follow the guest's saved booking-page preference, falling back to this format for older bookings." } } }, "Booking": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type_id": { "type": "string", "format": "uuid" }, "event_type_name": { "type": [ "string", "null" ] }, "event_type_slug": { "type": [ "string", "null" ] }, "invitee_name": { "type": "string" }, "invitee_email": { "type": "string" }, "invitee_phone": { "type": [ "string", "null" ] }, "invitee_timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "confirmed", "cancelled", "completed", "no_show" ] }, "source": { "type": "string", "enum": [ "web", "call", "api", "manual" ], "description": "web = public booking page, call = booked by an assistant mid-call, api = created through the API, MCP or an AI agent on a messaging channel, manual = booked by a team member in the app (including Milian)." }, "call_id": { "type": [ "string", "null" ], "description": "The call during which the assistant booked this appointment (source=call)." }, "notes": { "type": "string" }, "answers": { "type": "object", "description": "Answers to the event type's custom booking questions, keyed by BookingField.id.", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "BookingLookupMatch": { "type": "object", "description": "A confirmed upcoming booking matched by invitee identity.", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type_id": { "type": "string", "format": "uuid" }, "event_type_name": { "type": [ "string", "null" ] }, "event_type_slug": { "type": [ "string", "null" ] }, "invitee_name": { "type": "string" }, "invitee_email": { "type": "string" }, "invitee_phone": { "type": [ "string", "null" ] }, "invitee_timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "confirmed", "cancelled", "completed", "no_show" ] }, "source": { "type": "string", "enum": [ "web", "call", "api", "manual" ], "description": "web = public booking page, call = booked by an assistant mid-call, api = created through the API, MCP or an AI agent on a messaging channel, manual = booked by a team member in the app (including Milian)." }, "match_basis": { "type": "string", "enum": [ "phone", "email+name" ], "description": "Which identity evidence produced this match. `phone` is the strongest; `email+name` requires both to match." } } }, "CatalogModel": { "type": "object", "properties": { "id": { "type": "string", "description": "Catalog row ID." }, "type": { "type": "string", "enum": [ "llm", "stt", "tts", "realtime" ], "description": "Model category." }, "provider": { "type": "string", "description": "Provider selector belonging to this available model choice." }, "model": { "type": "string", "description": "Exact catalog identifier. Fallbacks & Guardrails assistants use compatible LLM/realtime values in the matching engine pair." }, "label": { "type": "string", "description": "Human-readable display name." }, "supported_modes": { "type": "array", "description": "Engine modes in which this LLM or Realtime model may be selected. User overrides cannot bypass this list. Always empty for STT and TTS models: they follow their role instead (STT in pipeline, TTS in pipeline and half_cascade).", "items": { "type": "string", "enum": [ "pipeline", "realtime", "half_cascade" ] } }, "realtime_variant": { "type": "string", "enum": [ "standard", "full_duplex" ], "description": "Conversation variant for native speech model choices." } } }, "AssistantCreateInput": { "allOf": [ { "$ref": "#/components/schemas/AssistantInput" }, { "type": "object", "description": "Assistant creation input. Supply either a non-empty name or a visible template_id. Template values are the base; every explicitly supplied assistant field overrides that value.", "properties": { "template_id": { "type": "string", "format": "uuid", "description": "ID returned by GET /prompt-templates. Resolves the template server-side and is not stored on the assistant." } } } ] }, "LanguageOption": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO-639-1 language code, e.g. `de`." }, "label": { "type": "string", "description": "English display name, e.g. `German`." } }, "example": { "code": "de", "label": "German" } }, "AssistantTemplateRequirement": { "type": "object", "required": [ "kind", "label", "required" ], "properties": { "kind": { "type": "string", "enum": [ "plan", "knowledgebase", "calendar", "tool", "transfer_destination", "recognition_glossary" ] }, "capability": { "type": "string", "description": "Optional capability identifier used to evaluate setup readiness." }, "label": { "type": "string" }, "required": { "type": "boolean" } } }, "AssistantTemplateSetupStep": { "type": "object", "required": [ "id", "label", "required" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "href": { "type": "string", "description": "Optional relative product path for completing this step." } } }, "AssistantTemplateBlueprint": { "type": "object", "required": [ "schema_version", "use_case", "outcome", "complexity", "surfaces", "requirements", "setup_steps" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "use_case": { "type": "string" }, "outcome": { "type": "string" }, "complexity": { "type": "string", "enum": [ "starter", "guided", "advanced" ] }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "phone_inbound", "phone_outbound", "web_voice", "web_avatar" ] } }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantTemplateRequirement" } }, "setup_steps": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantTemplateSetupStep" } }, "presentation": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "visualizer", "avatar" ] }, "avatar_layout": { "type": "string", "enum": [ "avatar", "avatar_chat" ] } } }, "suggested_keyterms": { "type": "array", "maxItems": 100, "items": { "type": "string" }, "description": "Optional proper names or domain terms to review for the speech-recognition glossary when the selected engine supports it." } } }, "AssistantTemplateCompatibility": { "type": "object", "required": [ "valid", "node_count", "branch_count", "collected_fields", "surfaces", "avatar_ready", "setup_required" ], "properties": { "valid": { "type": "boolean" }, "node_count": { "type": "integer", "minimum": 0 }, "branch_count": { "type": "integer", "minimum": 0 }, "collected_fields": { "type": "array", "items": { "type": "string" } }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "phone_inbound", "phone_outbound", "web_voice", "web_avatar" ] } }, "avatar_ready": { "type": "boolean" }, "setup_required": { "type": "integer", "minimum": 0 } } }, "PromptTemplate": { "type": "object", "required": [ "id", "name", "content", "languages", "themes", "branches", "blueprint", "compatibility", "source" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "content": { "type": "string", "description": "System prompt body to copy into an assistant." }, "first_message": { "type": [ "string", "null" ], "description": "Optional greeting to copy into first_message." }, "flow_json": { "type": [ "object", "null" ], "description": "Optional Flow JSON v1 graph. When set, apply as Conversational flow (`assistants.flow_json`); when null, template is Single prompt only.", "additionalProperties": true }, "blueprint": { "anyOf": [ { "$ref": "#/components/schemas/AssistantTemplateBlueprint" }, { "type": "null" } ], "description": "Versioned use-case delivery contract. Null for legacy templates without setup metadata." }, "compatibility": { "$ref": "#/components/schemas/AssistantTemplateCompatibility" }, "category": { "type": [ "string", "null" ] }, "languages": { "type": "array", "items": { "type": "string" }, "description": "ISO-639-1 codes the prompt is written for (any valid 2-letter code, e.g. de, ja)." }, "themes": { "type": "array", "items": { "type": "string" }, "description": "Use-case slugs (snake_case). Built-in themes include receptionist, lead_qualifier and loop_recall; custom values are allowed." }, "branches": { "type": "array", "items": { "type": "string" }, "description": "Industry slugs (snake_case). Presets include general, healthcare, …; custom values are allowed." }, "source": { "type": "string", "enum": [ "platform", "workspace" ] }, "sort_order": { "type": "integer" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public URL of the template catalog portrait (template-avatars bucket). Null when unset — UIs fall back to the default mesh orb. Copied onto a new assistant when creating from this template." }, "updated_at": { "type": "string", "format": "date-time" } } }, "VariableDefinition": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "description": "snake_case identifier, referenced as `{{key}}` in prompts, first message, flow nodes and tool config. Unique per assistant; system variable keys (`time`, `date`, `datetime`, `weekday`, `caller_number`, ...) are reserved." }, "label": { "type": "string", "description": "Human-readable display name." }, "description": { "type": [ "string", "null" ] }, "default_value": { "type": [ "string", "null" ], "description": "Fallback used when no value is supplied at call time." }, "example": { "type": [ "string", "null" ], "description": "Example value (UI/docs only)." }, "source": { "type": "string", "enum": [ "manual", "lead", "webhook", "system" ], "description": "Value source policy. `lead` grants this assistant access to the same-key registered workspace Custom Attribute and is validated against the current catalog. `system` is reserved for supported built-in defaults. `manual` is the default; `webhook` marks inbound enrichment." }, "memory": { "type": "string", "enum": [ "none", "workspace", "assistant" ], "default": "none", "description": "Durable caller-memory policy for this custom variable: `none` keeps it in the current call only, `workspace` shares it with assistants in this workspace, and `assistant` keeps it private to this assistant. Platform system fields are handled automatically by Caller memory and do not need this setting." } } }, "AssistantVariables": { "type": "object", "required": [ "variables", "lead_attribute_mode", "variable_webhook_url" ], "properties": { "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableDefinition" } }, "lead_attribute_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "`all` is returned only for assistants that retain the immutable legacy compatibility state. It cannot be selected on create or enabled by update (HTTP 400). `selected` exposes only explicit variable definitions with `source: lead`." }, "variable_webhook_url": { "type": [ "string", "null" ], "description": "Endpoint called before an inbound call to fetch variable values. The webhook secret is never returned." } } }, "EmailSenderOption": { "type": "object", "required": [ "value", "mode", "label", "description", "available" ], "properties": { "value": { "type": "string", "description": "Value to store in the sender selector. Verified addresses use address:{uuid}." }, "mode": { "type": "string", "enum": [ "auto", "workspace_smtp", "platform", "address" ] }, "address_id": { "type": [ "string", "null" ], "format": "uuid" }, "label": { "type": "string" }, "description": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "display_name": { "type": [ "string", "null" ] }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "assistant_name": { "type": [ "string", "null" ] }, "available": { "type": "boolean" } } }, "EmailSenderCatalog": { "type": "object", "required": [ "options", "workspace_default_display_name", "workspace_default_signature" ], "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSenderOption" } }, "workspace_default_display_name": { "type": "string" }, "workspace_default_signature": { "type": "string" } } }, "BuiltinTool": { "type": "object", "required": [ "type" ], "description": "One built-in tool configuration. `type` selects the tool; the remaining fields depend on the type. DTMF Input sends keypad tones to an IVR or phone menu; Collect Keypad Input collects keypad or spoken digits from the caller. In an assistant's inline `builtin_tools` they run as prompt-session tools. Reusable copies created through the Tools API can also be assigned to assistants and bound to their dedicated Flow Builder nodes. Calendars use Integrations. All types accept an optional `description` that tells the model when to use the tool. Saved caller-facing announcements, filler phrases and end-call farewells remain editable. With secondary languages configured on the assistant, they guide generated wording in the current supported conversation language without fixed saved audio. Otherwise their existing delivery behavior is preserved. An empty End call farewell adds no speech.", "properties": { "type": { "type": "string", "enum": [ "end_call", "call_transfer", "warm_call_transfer", "dtmf_input", "collect_keypad", "calendar_integration", "assistant_transfer", "send_sms", "send_email", "check_business_hours", "schedule_callback", "collect_payment_card", "set_variable" ] }, "tones": { "type": "string", "pattern": "^[0-9*#A-D]{1,32}$", "maxLength": 32, "description": "Optional for dtmf_input: keypad tones the agent sends. Omit to let the model choose during the call. This field is never a digit count." }, "post_answer_dtmf": { "type": "string", "maxLength": 32, "pattern": "^[0-9*#A-Da-dWw]*$", "description": "Optional for warm_call_transfer: keypad tones sent to the transfer target after its line answers and before the briefing. Each w adds a fixed half-second pause; the sequence does not detect when an IVR or extension is ready. Empty or omitted disables it. Case-insensitive.", "examples": [ "wwww1234#wwww" ] }, "timeout": { "type": "integer", "minimum": 5, "maximum": 120, "description": "Optional for collect_keypad: total collection timeout in seconds, including the entry prompt. Default 30; explicitly saved timeouts remain unchanged.", "default": 30 }, "stop_key": { "type": "string", "enum": [ "#", "*" ], "description": "Keypad submit key. exact mode still requires the fixed length; until_stop accepts it once min_digits is reached. The stop key is not part of the returned digits." }, "max_digits": { "type": "integer", "minimum": 1, "maximum": 32, "description": "exact keypad or spoken digit count to collect in exact mode, or maximum in until_stop mode. Defaults to 16 for explicit exact mode and 32 for an unconfigured until_stop tool." }, "stripe_connection_id": { "type": "string", "format": "uuid", "description": "Required for collect_payment_card: the ID of the workspace's own Stripe connection (set up in the dashboard under Tools → App Store → Stripe)." }, "allowed_keys": { "type": "array", "items": { "type": "string" }, "description": "Optional for set_variable — snake_case keys the agent may write. Empty or omitted = any valid non-protected key." }, "description": { "type": [ "string", "null" ], "description": "When the model should use this tool. Falls back to a sensible default." }, "assistant_id": { "type": "string", "format": "uuid", "description": "Required for assistant_transfer — destination assistant in the same workspace." }, "context_mode": { "type": "string", "enum": [ "all_messages", "no_messages", "last_n_messages", "user_and_assistant_messages", "summary_and_last_n", "summary_only" ], "description": "For assistant_transfer: which conversation context is handed to the destination assistant. Default all_messages." }, "context_last_n_messages": { "type": "integer", "minimum": 1, "maximum": 100, "description": "For assistant_transfer when context_mode is last_n_messages or summary_and_last_n. Default 10." }, "message_before_transfer": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional line the current assistant speaks immediately before an assistant_transfer handoff." }, "email_to_mode": { "type": "string", "enum": [ "ask", "fixed" ], "description": "Ask and confirm the address during the call, or use email_fixed_to." }, "email_fixed_to": { "type": "string", "format": "email" }, "email_sender_mode": { "type": "string", "enum": [ "auto", "workspace_smtp", "platform", "address" ], "description": "Explicit modes never silently fall back. Use GET /email-senders to discover available choices." }, "email_sender_address_id": { "type": "string", "format": "uuid", "description": "Required when email_sender_mode is address." }, "email_from_name": { "type": "string", "maxLength": 128 }, "email_content_mode": { "type": "string", "enum": [ "llm", "fixed", "template" ] }, "email_subject_template": { "type": "string", "maxLength": 500, "description": "Required for fixed/template content. Template mode supports call variables such as {{customer_name}}." }, "email_body_template": { "type": "string", "maxLength": 20000 }, "email_signature_mode": { "type": "string", "enum": [ "workspace", "custom", "none" ] }, "email_custom_signature": { "type": "string", "maxLength": 5000 }, "digit_mode": { "type": "string", "enum": [ "exact", "until_stop" ], "description": "Collect Keypad Input length mode. exact requires a fixed count; until_stop accepts the stop key after the minimum or finishes at the maximum. Omitted mode with a saved max_digits preserves exact behavior; a fully unconfigured tool defaults to until_stop." }, "min_digits": { "type": "integer", "minimum": 1, "maximum": 32, "default": 1, "description": "Minimum digits before submit-key completion in until_stop mode. Must not exceed max_digits; ignored in exact mode." }, "retry_enabled": { "type": "boolean", "default": false, "description": "Warm transfer only: automatically redial the same destination on no answer, busy, temporary unavailability or detected voicemail before running the configured fallback. Stops on connection, decline, permanent error or caller departure." }, "retry_max_attempts": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "Warm transfer retry limit including the first attempt. 0 retries while the caller remains connected, subject to call duration and credit limits. Used only when retry_enabled is true." }, "retry_delay_sec": { "type": "integer", "minimum": 5, "maximum": 120, "default": 10, "description": "Seconds between warm-transfer attempts when retry_enabled is true." } }, "additionalProperties": true, "example": { "type": "send_sms", "description": "Text the caller a booking confirmation.", "sms_to_mode": "caller" } }, "SegmentFilters": { "type": "object", "description": "Filter definition. Empty/omitted = \"All Leads\" (no filter). Every field is optional and ANDed together.", "properties": { "search": { "type": "string", "description": "Free-text search, matched against lead phone number and name (substring, case-insensitive)." }, "display_status": { "type": "array", "items": { "type": "string", "enum": [ "created", "processing", "rescheduled", "max_retries", "completed", "dnc" ] }, "description": "Only leads whose derived display status is one of these." }, "campaign_id": { "type": [ "string", "null" ], "description": "Campaign UUID to filter by, the literal string \"none\" for leads without a campaign, or null/omitted for no filter." }, "dnc": { "type": "boolean", "description": "true = only leads on the Do-Not-Call list; false = exclude those leads; omitted = do not filter by DNC status." }, "channels": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "call", "sms", "email", "whatsapp", "telegram", "messenger", "slack", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "description": "Contacts with activity or a profile on any selected channel. Values are ORed within this field and ANDed with the other filters." }, "sources": { "type": "array", "uniqueItems": true, "maxItems": 32, "items": { "type": "string", "maxLength": 80 }, "description": "Contacts originating from any selected source tag. Values are ORed." }, "tags": { "type": "array", "uniqueItems": true, "maxItems": 32, "items": { "type": "string", "maxLength": 80 }, "description": "Contacts containing any selected tag. Values are ORed." }, "created_at": { "type": "object", "description": "Inclusive contact-created timestamp range.", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "attempts": { "type": "object", "description": "Inclusive outbound call-attempt range.", "properties": { "min": { "type": "integer", "minimum": 0, "maximum": 100000 }, "max": { "type": "integer", "minimum": 0, "maximum": 100000 } } }, "amd_results": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "human", "uncertain", "machine-vm", "machine-ivr", "machine-unavailable", "none" ] }, "description": "Last answering-machine-detection result. `none` matches contacts without a result." }, "qa": { "type": "object", "required": [ "window" ], "description": "Dynamic Call QA average filter. Contacts without scored calls are excluded; without an explicit sample minimum at least one scored call is required.", "properties": { "window": { "oneOf": [ { "type": "integer", "enum": [ 7, 30, 90 ] }, { "type": "string", "enum": [ "all" ] } ] }, "average_score_min": { "type": "number", "minimum": 0, "maximum": 100 }, "average_score_max": { "type": "number", "minimum": 0, "maximum": 100 }, "min_scored_calls": { "type": "integer", "minimum": 1 } } } } }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "filters": { "$ref": "#/components/schemas/SegmentFilters" }, "created_by": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "filters", "created_at", "updated_at" ] }, "SegmentInput": { "type": "object", "description": "Create: `name` is required. Update (PATCH): all fields optional, only provided fields change.", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "filters": { "$ref": "#/components/schemas/SegmentFilters" } } }, "CampaignStats": { "type": "object", "description": "Progress and performance aggregates for one campaign.", "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "total_leads": { "type": "integer", "description": "Total leads currently in the campaign." }, "completed_leads": { "type": "integer", "description": "Leads the campaign has finished working on." }, "calls_made": { "type": "integer", "description": "Number of calls placed for this campaign." }, "total_duration_sec": { "type": "integer", "description": "Total duration of those calls in seconds." }, "delivery_attempts": { "type": "integer", "description": "Delivery attempts across all channels and stages (primary and follow-up), as listed by `GET /campaigns/{id}/deliveries`." }, "delivery_successful": { "type": "integer", "description": "Attempts that were delivered or completed." }, "delivery_failed": { "type": "integer", "description": "Attempts that failed or whose outcome could not be confirmed." }, "delivery_scheduled": { "type": "integer", "description": "Attempts still waiting to run: pending, scheduled, or waiting for messaging permission." }, "currency": { "type": "string", "deprecated": true, "description": "Always `EUR`. Kept for compatibility: this response contains no money amounts.", "example": "EUR" }, "display_currency": { "type": "string", "description": "Workspace's resolved display currency (reseller customers inherit their reseller's currency). This response contains no money amounts; the value is informational.", "example": "USD" }, "display_currency_rate": { "type": "number", "description": "Units of display_currency per 1 EUR; 0 when the platform has not configured a rate yet.", "example": 1.08 } }, "required": [ "campaign_id", "total_leads", "completed_leads", "calls_made", "total_duration_sec", "delivery_attempts", "delivery_successful", "delivery_failed", "delivery_scheduled", "currency", "display_currency", "display_currency_rate" ] }, "AssignLeadsInput": { "type": "object", "description": "Provide exactly one of `lead_ids` or `segment_id`.", "properties": { "lead_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Explicit lead IDs to assign — use this OR segment_id, not both." }, "segment_id": { "type": "string", "format": "uuid", "description": "Segment whose current matches are assigned — use this OR lead_ids, not both." } } }, "AssignLeadsResult": { "type": "object", "properties": { "assigned": { "type": "integer", "description": "Leads without a campaign that were moved directly into this campaign." }, "copied": { "type": "integer", "description": "Compatibility field, always 0. Contacts are never duplicated between campaigns." }, "skipped": { "type": "integer", "description": "Leads already in this campaign, currently being called, or not found." } }, "required": [ "assigned", "copied", "skipped" ] }, "AutomationPlatform": { "type": "object", "additionalProperties": false, "required": [ "provider", "entitled", "configured" ], "properties": { "provider": { "type": "string", "enum": [ "native" ], "description": "Native automation platform." }, "entitled": { "type": "boolean", "description": "Whether the workspace plan includes Automations." }, "configured": { "type": "boolean", "description": "True when entitled — native builder is always ready." }, "max_runs_per_month": { "type": [ "integer", "null" ], "minimum": -1, "description": "Free monthly automation runs (max_automation_runs); null or -1 means unlimited free. After free quota, runs debit automation_run_credits." }, "runs_used_this_month": { "type": [ "integer", "null" ], "description": "Runs counted this calendar month when entitled; otherwise null." } } }, "Dashboard": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "sort_order", "show_default_sections", "hidden_default_sections", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sort_order": { "type": "integer", "minimum": 0 }, "show_default_sections": { "type": "boolean", "description": "When false, the built-in KPI, operations, modules, and recent-call sections are hidden so the dashboard starts as a blank canvas." }, "hidden_default_sections": { "type": "array", "uniqueItems": true, "description": "Built-in dashboard cards hidden individually while the default overview remains enabled.", "items": { "type": "string", "enum": [ "filter_bar", "kpi_conversations", "kpi_completion_rate", "kpi_average_duration", "kpi_success_rate", "kpi_conversation_spend", "call_activity", "outcome_mix", "assistant_performance", "post_call_intelligence", "campaign_funnel", "module_assistants", "module_campaigns", "module_audience", "module_booking", "module_knowledge", "module_simulations", "module_live_monitoring", "module_tools", "module_phone_numbers", "recent_calls" ] } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DashboardInput": { "type": "object", "additionalProperties": false, "description": "Create requires name. PATCH accepts name, sort_order, show_default_sections, and/or hidden_default_sections.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "show_default_sections": { "type": "boolean", "description": "Set false for a blank canvas or true to restore the built-in overview." }, "hidden_default_sections": { "type": "array", "uniqueItems": true, "maxItems": 21, "description": "Complete list of built-in cards to hide individually; send an empty array to restore all.", "items": { "type": "string", "enum": [ "filter_bar", "kpi_conversations", "kpi_completion_rate", "kpi_average_duration", "kpi_success_rate", "kpi_conversation_spend", "call_activity", "outcome_mix", "assistant_performance", "post_call_intelligence", "campaign_funnel", "module_assistants", "module_campaigns", "module_audience", "module_booking", "module_knowledge", "module_simulations", "module_live_monitoring", "module_tools", "module_phone_numbers", "recent_calls" ] } } } }, "NaturalLanguageDashboardPlan": { "type": "object", "additionalProperties": false, "description": "Versioned, tenant-safe dashboard plan built exclusively from the semantic analytics catalog.", "required": [ "version", "mode", "prompt", "interpretation", "range", "compare_previous_period", "filters", "widgets", "warnings" ], "properties": { "version": { "type": "string", "const": "1" }, "mode": { "type": "string", "const": "deterministic", "description": "The safe built-in parser is available without a separately configured language model." }, "prompt": { "type": "string", "minLength": 8, "maxLength": 1200 }, "interpretation": { "type": "string", "readOnly": true }, "range": { "type": "string", "enum": [ "7d", "14d", "30d", "90d" ] }, "compare_previous_period": { "type": "boolean" }, "filters": { "type": "array", "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "dimension", "operator", "value", "label" ], "properties": { "dimension": { "type": "string", "enum": [ "status", "direction", "sentiment", "success" ] }, "operator": { "type": "string", "const": "equals" }, "value": { "type": "string" }, "label": { "type": "string", "readOnly": true } } } }, "widgets": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "additionalProperties": false, "required": [ "metric", "title", "description", "visualization", "group_by" ], "properties": { "metric": { "type": "string", "enum": [ "conversation_count", "conversation_activity", "success_rate", "average_duration", "total_duration", "assistant_performance", "campaign_performance", "outcome_mix", "status_breakdown", "direction_breakdown", "sentiment_breakdown", "recent_conversations" ] }, "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "readOnly": true }, "visualization": { "type": "string", "enum": [ "number", "line", "area", "bar", "donut", "pie", "table" ] }, "group_by": { "type": [ "string", "null" ], "enum": [ "date", "assistant", "campaign", "outcome", "status", "direction", "sentiment", null ] } } } }, "warnings": { "type": "array", "maxItems": 3, "items": { "type": "string" }, "readOnly": true } } }, "DashboardWidgetCondition": { "type": "object", "additionalProperties": false, "required": [ "column_ref", "operator" ], "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true }, "column_ref": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "default": "equals" }, "value": { "type": [ "string", "null" ] }, "value_json": {}, "sort_order": { "type": "integer", "readOnly": true } } }, "DashboardWidget": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "widget_type", "data_table", "aggregation", "compare_previous_period", "rate_range", "table_columns", "visualization", "show_legend", "show_values", "conditions", "dashboard_sort_order", "grid_w", "grid_h", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "widget_type": { "type": "string", "enum": [ "statistic", "chart", "table" ] }, "data_table": { "type": "string", "enum": [ "calls", "campaigns", "assistants", "phone_numbers", "conversions", "leads", "knowledge_bases", "bookings", "tools", "simulations" ] }, "aggregation": { "type": "string", "enum": [ "count", "sum", "avg", "max", "min" ] }, "column_name": { "type": [ "string", "null" ] }, "compare_previous_period": { "type": "boolean" }, "rate_range": { "type": "string", "enum": [ "7d", "14d", "30d", "90d" ] }, "table_columns": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "assistant_id": { "type": [ "string", "null" ] }, "visualization": { "type": "string", "enum": [ "auto", "number", "line", "area", "bar", "stacked_bar", "donut", "pie", "funnel", "heatmap", "table", "leaderboard" ] }, "group_by": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "show_legend": { "type": "boolean" }, "show_values": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardWidgetCondition" }, "maxItems": 20 }, "dashboard_sort_order": { "type": "integer", "minimum": 0 }, "grid_w": { "type": "integer", "minimum": 3, "maximum": 12 }, "grid_h": { "type": "integer", "minimum": 1, "maximum": 4 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DashboardWidgetInput": { "type": "object", "additionalProperties": false, "description": "POST: provide widget_id to attach an existing reusable widget, or name to create one. PATCH: only provided fields change.", "properties": { "widget_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "widget_type": { "type": "string", "enum": [ "statistic", "chart", "table" ] }, "data_table": { "type": "string", "enum": [ "calls", "campaigns", "assistants", "phone_numbers", "conversions", "leads", "knowledge_bases", "bookings", "tools", "simulations" ] }, "aggregation": { "type": "string", "enum": [ "count", "sum", "avg", "max", "min" ] }, "column_name": { "type": [ "string", "null" ] }, "compare_previous_period": { "type": "boolean" }, "rate_range": { "type": "string", "enum": [ "7d", "14d", "30d", "90d" ] }, "table_columns": { "type": "array", "items": { "type": "string" }, "maxItems": 30 }, "assistant_id": { "type": [ "string", "null" ] }, "visualization": { "type": "string", "enum": [ "auto", "number", "line", "area", "bar", "stacked_bar", "donut", "pie", "funnel", "heatmap", "table", "leaderboard" ] }, "group_by": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "show_legend": { "type": "boolean" }, "show_values": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardWidgetCondition" }, "maxItems": 20 }, "sort_order": { "type": "integer", "minimum": 0 }, "grid_w": { "type": "integer", "minimum": 3, "maximum": 12 }, "grid_h": { "type": "integer", "minimum": 1, "maximum": 4 } } }, "DashboardAnalyticsKpi": { "type": "object", "additionalProperties": false, "required": [ "value", "previous_value", "delta", "delta_percent" ], "properties": { "value": { "type": "number" }, "previous_value": { "type": [ "number", "null" ] }, "delta": { "type": [ "number", "null" ] }, "delta_percent": { "type": [ "number", "null" ], "description": "Null when comparison is off or the previous value is zero." } } }, "DashboardAnalyticsTimePoint": { "type": "object", "additionalProperties": false, "required": [ "bucket", "date", "total_calls", "completed_calls", "successful_calls", "duration_sec" ], "properties": { "bucket": { "type": "integer", "minimum": 0 }, "date": { "type": "string", "format": "date" }, "total_calls": { "type": "integer" }, "completed_calls": { "type": "integer" }, "successful_calls": { "type": "integer" }, "duration_sec": { "type": "number" } } }, "DashboardAnalyticsBreakdownItem": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "count", "percentage" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100 } } }, "DashboardLatencyMetric": { "type": "object", "additionalProperties": false, "required": [ "p50", "p95", "sample_count" ], "properties": { "p50": { "type": [ "number", "null" ] }, "p95": { "type": [ "number", "null" ] }, "sample_count": { "type": "integer" } } }, "DashboardAnalytics": { "type": "object", "additionalProperties": false, "required": [ "filters", "context", "overview", "time_series", "breakdowns", "top_assistants", "campaign_progress", "recent_calls", "optional", "quality", "generated_at" ], "properties": { "filters": { "type": "object", "additionalProperties": false, "required": [ "range", "current", "previous", "assistant_ids", "campaign_ids", "directions", "statuses", "sentiments", "success", "compare" ], "properties": { "range": { "type": "string", "enum": [ "7d", "14d", "30d", "90d" ] }, "current": { "$ref": "#/components/schemas/DashboardAnalyticsPeriod" }, "previous": { "$ref": "#/components/schemas/DashboardAnalyticsPeriod" }, "assistant_ids": { "type": "array", "items": { "type": "string" } }, "campaign_ids": { "type": "array", "items": { "type": "string" } }, "directions": { "type": "array", "items": { "type": "string" } }, "statuses": { "type": "array", "items": { "type": "string" } }, "sentiments": { "type": "array", "items": { "type": "string" } }, "success": { "type": [ "boolean", "null" ] }, "compare": { "type": "boolean" } } }, "context": { "type": "object", "additionalProperties": false, "required": [ "features", "assistants", "campaigns" ], "properties": { "features": { "type": "object", "additionalProperties": false, "required": [ "custom_dashboards", "assistants", "campaigns", "bookings", "knowledge", "simulations", "live_monitoring", "tools", "phone_numbers" ], "properties": { "custom_dashboards": { "type": "boolean" }, "assistants": { "type": "boolean" }, "campaigns": { "type": "boolean" }, "bookings": { "type": "boolean" }, "knowledge": { "type": "boolean" }, "simulations": { "type": "boolean" }, "live_monitoring": { "type": "boolean" }, "tools": { "type": "boolean" }, "phone_numbers": { "type": "boolean" } } }, "assistants": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "is_active" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_active": { "type": "boolean" } } } }, "campaigns": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "assistant_id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "assistant_id": { "type": [ "string", "null" ] } } } } } }, "overview": { "type": "object", "additionalProperties": false, "required": [ "total_calls", "completed_calls", "analyzed_calls", "total_duration_sec", "avg_duration_sec", "completion_rate", "success_rate" ], "properties": { "total_calls": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "completed_calls": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "analyzed_calls": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "total_duration_sec": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "avg_duration_sec": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "completion_rate": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" }, "success_rate": { "$ref": "#/components/schemas/DashboardAnalyticsKpi" } } }, "time_series": { "type": "object", "required": [ "current", "previous" ], "properties": { "current": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsTimePoint" } }, "previous": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsTimePoint" } }, { "type": "null" } ] } } }, "breakdowns": { "type": "object", "additionalProperties": false, "required": [ "status", "direction", "sentiment", "success", "outcome" ], "properties": { "status": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } }, "direction": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } }, "sentiment": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } }, "success": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } }, "outcome": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } } } }, "top_assistants": { "type": "array", "items": { "type": "object", "required": [ "assistant_id", "assistant_name", "total_calls", "completed_calls", "total_duration_sec", "success_rate" ], "properties": { "assistant_id": { "type": [ "string", "null" ] }, "assistant_name": { "type": "string" }, "total_calls": { "type": "integer" }, "completed_calls": { "type": "integer" }, "total_duration_sec": { "type": "number" }, "success_rate": { "type": "number" } } } }, "campaign_progress": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "status", "total_leads", "completed_leads", "remaining_leads", "calls_made", "progress_percent", "total_duration_sec", "period_calls", "period_success_rate" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "status": { "type": "string" }, "total_leads": { "type": "integer" }, "completed_leads": { "type": "integer" }, "remaining_leads": { "type": "integer" }, "calls_made": { "type": "integer" }, "progress_percent": { "type": "number" }, "total_duration_sec": { "type": "number" }, "period_calls": { "type": "integer" }, "period_success_rate": { "type": "number" } } } }, "recent_calls": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/DashboardRecentCall" } }, "optional": { "$ref": "#/components/schemas/DashboardOptionalAnalytics" }, "quality": { "type": "object", "additionalProperties": false, "required": [ "calls_truncated", "context_truncated", "warnings" ], "properties": { "calls_truncated": { "type": "boolean" }, "context_truncated": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "generated_at": { "type": "string", "format": "date-time" } } }, "DashboardAnalyticsPeriod": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "days" ], "properties": { "from": { "type": "string", "format": "date-time", "description": "Inclusive." }, "to": { "type": "string", "format": "date-time", "description": "Exclusive." }, "days": { "type": "integer", "minimum": 1 } } }, "DashboardRecentCall": { "type": "object", "additionalProperties": false, "required": [ "id", "assistant_id", "assistant_name", "campaign_id", "campaign_name", "direction", "from_number", "to_number", "status", "duration_sec", "sentiment", "success", "outcome", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": [ "string", "null" ] }, "assistant_name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "campaign_name": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "from_number": { "type": [ "string", "null" ] }, "to_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "duration_sec": { "type": "number" }, "sentiment": { "type": [ "string", "null" ] }, "success": { "type": [ "boolean", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "DashboardOptionalAnalytics": { "type": "object", "additionalProperties": false, "required": [ "bookings", "knowledge", "simulations", "live_monitoring" ], "properties": { "bookings": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "total", "by_status", "by_source" ], "properties": { "total": { "type": "integer" }, "by_status": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } }, "by_source": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardAnalyticsBreakdownItem" } } } } ] }, "knowledge": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "knowledge_bases", "documents", "ready_documents", "processing_documents", "error_documents", "total_chunks" ], "properties": { "knowledge_bases": { "type": "integer" }, "documents": { "type": "integer" }, "ready_documents": { "type": "integer" }, "processing_documents": { "type": "integer" }, "error_documents": { "type": "integer" }, "total_chunks": { "type": "integer" } } } ] }, "simulations": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "total_runs", "running", "passed", "failed", "error", "average_score" ], "properties": { "total_runs": { "type": "integer" }, "running": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "error": { "type": "integer" }, "average_score": { "type": [ "number", "null" ] } } } ] }, "live_monitoring": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "active_calls", "latency" ], "properties": { "active_calls": { "type": "integer" }, "latency": { "type": "object", "required": [ "e2e_latency_ms", "llm_ttft_ms", "tts_ttfb_ms", "stt_ms" ], "properties": { "e2e_latency_ms": { "$ref": "#/components/schemas/DashboardLatencyMetric" }, "llm_ttft_ms": { "$ref": "#/components/schemas/DashboardLatencyMetric" }, "tts_ttfb_ms": { "$ref": "#/components/schemas/DashboardLatencyMetric" }, "stt_ms": { "$ref": "#/components/schemas/DashboardLatencyMetric" } } } } } ] } } }, "SimulationTest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "persona": { "type": "string", "nullable": true }, "script": { "type": "string", "nullable": true }, "success_criteria": { "type": "array", "items": { "type": "object" } }, "max_turns": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "latest_run": { "nullable": true, "type": "object" } } }, "AssistantVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version_number": { "type": "integer" }, "label": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by_user_id": { "type": "string", "nullable": true } } }, "CallerId": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string", "example": "+12025550123" }, "friendly_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ] }, "verified_at": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "WidgetTheme": { "type": "object", "description": "Widget appearance. launcher_label_i18n is derived from launcher_label and is read-only — never persist client-supplied maps.", "properties": { "chat_reply_delay": { "type": "object", "description": "Minimum display wait per chat reply. Disabled shows replies as soon as they arrive; typing dots still show while waiting. Dynamic automatically selects 1-10 seconds for each reply. Voice is unchanged.", "properties": { "mode": { "type": "string", "enum": [ "disabled", "fixed", "dynamic" ], "default": "disabled" }, "seconds": { "type": "number", "minimum": 0, "maximum": 10, "default": 3, "description": "Fixed wait in seconds." } } }, "screen_sharing_enabled": { "type": "boolean", "default": false, "description": "Allow visitors to share a screen, window or tab for AI visual help during widget chat and voice sessions. Sharing always requires the visitor's browser permission, can be stopped at any time and does not capture system audio. Requires both Web widget and Widget screen sharing in the workspace plan; actual shared time incurs the displayed credit surcharge in addition to voice and avatar charges. Image uploads are controlled separately." }, "chat_attachments_enabled": { "type": "boolean", "default": true, "description": "Let visitors attach images and documents in chat (PNG, JPG, WEBP, GIF, PDF, DOCX, TXT, MD, CSV, JSON; up to 10 MB each, 5 per message). Images are shown to the assistant; documents are read as text. Attachments appear in the call history transcript." }, "launcher_icon": { "type": "string", "enum": [ "milian", "chat_bubbles", "question", "smiley", "team", "hand_wave", "avatar", "logo" ], "description": "Floating launcher icon. Default milian (mesh orb). avatar uses the selected assistant’s current profile picture; logo uses the widget header logo. Missing images fall back to the orb. With launcher_label none the icon shows without text." }, "launcher_label": { "type": "string", "enum": [ "none", "help", "ask_anything", "assistance", "support", "live_chat", "need_help" ], "default": "none", "description": "Preset launcher label. Translated for the visitor language. Default none (no text)." }, "launcher_label_i18n": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true, "description": "Derived visitor translations; never persist client-supplied maps." }, "primary_color": { "type": "string", "description": "Accent / launcher color (hex)." }, "title": { "type": "string" }, "greeting_text": { "type": "string" }, "position": { "type": "string", "enum": [ "bottom-right", "bottom-left" ], "description": "Floating launcher corner. Ignored when display_mode is inline." }, "display_mode": { "type": "string", "enum": [ "floating", "inline" ] }, "logo_url": { "type": "string", "format": "uri" }, "launcher_text": { "type": "string", "description": "Optional custom launcher text used when launcher_label is none (avatar-only glass CTA)." }, "presence_mode": { "type": "string", "enum": [ "visualizer", "avatar" ] }, "logo_source": { "type": "string", "enum": [ "assistant", "custom" ], "default": "assistant", "description": "Header logo source. New widgets default to assistant unless logo_url is supplied without a source, which selects custom. assistant follows the selected assistant’s current profile picture. custom uses logo_url and preserves an uploaded logo independently. Existing widgets without this field keep their custom logo." } } }, "WidgetConnector": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "public_key": { "type": "string" }, "assistant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "voice_enabled": { "type": "boolean" }, "chat_enabled": { "type": "boolean" }, "is_active": { "type": "boolean" }, "theme": { "$ref": "#/components/schemas/WidgetTheme" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "phone_verification_enabled": { "type": "boolean", "default": false, "description": "Require the selected email or SMS verification before chat or voice. Available in root workspaces, including a reseller’s own workspace; unavailable to reseller customer workspaces." }, "phone_verification_accepted_credits": { "type": "number", "nullable": true, "exclusiveMinimum": 0, "description": "Explicitly accept the current per-SMS price from the widget list response. Currently 80 credits per accepted send, including resends; code checks and valid remembered visits are free." }, "verification_method": { "type": "string", "enum": [ "sms", "email" ], "default": "sms", "description": "Verify visitors by SMS or email. Email uses the platform sender without additional credits." } } }, "MessagingConnector": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "assistant_id": { "type": "string", "format": "uuid" }, "assistant_name": { "type": "string", "nullable": true }, "platform": { "type": "string", "enum": [ "sms", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip" ] }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "connected", "error" ] }, "last_error": { "type": "string", "nullable": true }, "webhook_url": { "type": "string", "format": "uri" }, "response_delay_sec": { "type": "integer", "minimum": 0, "maximum": 30, "default": 5, "description": "Seconds to wait after the last customer message before one reply (0 = instant)." }, "inactivity_timeout_min": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 30 }, "allow_retrigger": { "type": "boolean", "default": false, "description": "Allow conversation.ended webhook again after resume + next idle." }, "conversation_ended_webhook_url": { "type": "string", "format": "uri", "nullable": true }, "reply_mode": { "type": "string", "enum": [ "send", "draft" ], "description": "App channels only (e.g. Gmail, Outlook, helpdesks). `draft` saves replies as drafts instead of sending them; only Gmail and Outlook support drafts." }, "extra_actions_enabled": { "type": "boolean", "description": "App channels only. Lets the assistant run one app-specific action (e.g. label an email, tag or prioritize a ticket) alongside its reply." }, "watch_scope": { "type": "string", "enum": [ "inbox", "all", "label", "folder" ], "description": "Mailbox slice watched by Gmail, Outlook, or Zoho Mail connectors." }, "watch_name": { "type": "string", "nullable": true }, "watch_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "whatsapp_coexistence": { "type": "boolean", "description": "True when this WhatsApp sender was onboarded with Coexistence (Business app stays on the number)." }, "linked_phone_number_id": { "type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "Workspace phone number used by this SMS channel or linked account." }, "ai_enabled": { "type": "boolean", "readOnly": true, "description": "Whether automatic replies are enabled." } } }, "MessagingConnectorCreate": { "type": "object", "required": [ "platform", "name", "assistant_id" ], "properties": { "platform": { "type": "string", "enum": [ "sms", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp" ], "description": "SMS connects an existing SMS-capable workspace number. Chat apps connect with credentials; app channels use dashboard authorization." }, "name": { "type": "string", "maxLength": 120 }, "assistant_id": { "type": "string", "format": "uuid" }, "bot_token": { "type": "string" }, "bot_username": { "type": "string" }, "signing_secret": { "type": "string" }, "team_name": { "type": "string" }, "page_access_token": { "type": "string" }, "app_secret": { "type": "string" }, "verify_token": { "type": "string" }, "page_name": { "type": "string" }, "phone_number_id": { "type": "string", "description": "WhatsApp Cloud API phone number ID" }, "access_token": { "type": "string", "description": "WhatsApp permanent System User token" }, "waba_id": { "type": "string", "description": "WhatsApp Business Account ID" }, "display_phone_number": { "type": "string" }, "whatsapp_text_enabled": { "type": "boolean" }, "whatsapp_voice_enabled": { "type": "boolean" }, "whatsapp_outbound_voice_enabled": { "type": "boolean" }, "response_delay_sec": { "type": "integer", "minimum": 0, "maximum": 30 }, "inactivity_timeout_min": { "type": "integer", "minimum": 1, "maximum": 1440 }, "allow_retrigger": { "type": "boolean" }, "conversation_ended_webhook_url": { "type": "string", "format": "uri", "nullable": true }, "linked_phone_number_id": { "type": "string", "format": "uuid", "description": "Required for SMS. UUID of the active SMS-capable phone number in this workspace. The channel keeps this number; credentials stay on the number." }, "ai_enabled": { "type": "boolean", "description": "Enable automatic replies. Defaults to false for SMS and true for other channels." } } }, "MessagingConnectorUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "assistant_id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "response_delay_sec": { "type": "integer", "minimum": 0, "maximum": 30 }, "inactivity_timeout_min": { "type": "integer", "minimum": 1, "maximum": 1440 }, "allow_retrigger": { "type": "boolean" }, "conversation_ended_webhook_url": { "type": "string", "format": "uri", "nullable": true }, "reply_mode": { "type": "string", "enum": [ "send", "draft" ], "description": "App channels only. `send` (default) or `draft` (Gmail and Outlook only; 400 elsewhere)." }, "extra_actions_enabled": { "type": "boolean", "description": "App channels only. Allow one app-specific action (e.g. label, tag, prioritize) alongside each reply." }, "watch_scope": { "type": "string", "enum": [ "inbox", "all", "label", "folder" ], "description": "Gmail, Outlook, and Zoho Mail only. Which mailbox slice the assistant watches." }, "watch_name": { "type": "string", "nullable": true, "description": "Display name of the selected Gmail label or mail folder." }, "watch_id": { "type": "string", "nullable": true, "description": "Provider id from GET /messaging-connectors/{id}/watch-options." }, "ai_enabled": { "type": "boolean", "description": "Enable or pause automatic replies on this channel." } } }, "CrmSyncInput": { "type": "object", "required": [ "connection_id", "name", "object_type", "field_mapping" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "object_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "selection": { "type": "object", "additionalProperties": true, "description": "Provider-neutral source selection. Discovered list/view/filter IDs use `sourceId`. Set `default_phone_country` to a supported ISO-2 code (for example `DE`) to normalize national phone numbers; international `+`/`00` values take priority. Required provider fields are derived from the mapping." }, "field_mapping": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "pattern": "^(name|phone|email|tags|custom\\.[a-z][a-z0-9_]{0,63}|channel\\.[a-z]+\\.(user_id|username))$" }, "description": "External source to Audience target. A bare key keeps legacy 1:1 behavior. To combine fields or fixed text, use non-evaluated `{{field}}` tokens in one source expression, for example `{{salutation}} {{firstName}} {{lastName}}` or `+49{{phone}}`. Destinations include channel identities such as `channel.telegram.username` or `channel.whatsapp.user_id`. At least one target must be `phone` or `email`, and each target appears once.", "example": { "{{salutation}} {{firstName}} {{lastName}}": "name", "{{phones.primaryPhoneCallingCode}}{{phones.primaryPhoneNumber}}": "phone", "email": "email" } }, "interval_minutes": { "type": "integer", "minimum": 60, "maximum": 10080, "default": 60 }, "null_policy": { "type": "string", "enum": [ "ignore", "clear" ], "default": "ignore" }, "removal_policy": { "type": "string", "enum": [ "deactivate_membership", "keep" ], "default": "deactivate_membership" }, "conflict_policy": { "type": "string", "enum": [ "review", "skip" ], "default": "review" }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "bidirectional" ], "default": "inbound", "description": "inbound imports CRM records into Audience. outbound pushes Audience contacts to the CRM. bidirectional runs inbound first, then outbound, on the same schedule." }, "outbound_create": { "type": "boolean", "default": false, "description": "When direction includes outbound, create CRM records for unlinked Audience contacts. Defaults to true for outbound-only syncs." } } }, "CrmSyncUpdate": { "type": "object", "description": "Partial CRM sync update. All fields are optional; the connection is immutable.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "object_type": { "type": "string", "minLength": 1, "maxLength": 128 }, "selection": { "type": "object", "additionalProperties": true, "description": "Replacement provider-neutral selection. `default_phone_country` accepts a supported ISO-2 country code." }, "field_mapping": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "pattern": "^(name|phone|email|tags|custom\\.[a-z][a-z0-9_]{0,63}|channel\\.[a-z]+\\.(user_id|username))$" }, "description": "Replacement mapping. Bare source keys stay 1:1; composed values use non-evaluated `{{field}}` tokens and optional literal text. Destinations include channel identities such as `channel.telegram.username` or `channel.whatsapp.user_id`. At least one target must be `phone` or `email`, and each target appears once." }, "interval_minutes": { "type": "integer", "minimum": 60, "maximum": 10080 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "null_policy": { "type": "string", "enum": [ "ignore", "clear" ] }, "removal_policy": { "type": "string", "enum": [ "deactivate_membership", "keep" ] }, "conflict_policy": { "type": "string", "enum": [ "review", "skip" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "bidirectional" ] }, "outbound_create": { "type": "boolean" } } }, "CrmSync": { "allOf": [ { "$ref": "#/components/schemas/CrmSyncInput" }, { "type": "object", "required": [ "id", "provider", "status", "next_run_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "hubspot", "highlevel", "salesforce", "pipedrive", "close", "zoho", "attio", "keap", "twenty" ] }, "status": { "type": "string", "enum": [ "active", "paused", "error" ] }, "last_error": { "type": "string", "nullable": true }, "last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true }, "next_run_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "MissionWebhookSetup": { "type": "object", "additionalProperties": false, "required": [ "webhook_url", "header_name", "configured" ], "properties": { "webhook_url": { "type": "string", "example": "/api/routines/11111111-1111-4111-8111-111111111111/webhook" }, "header_name": { "type": "string", "const": "X-Automation-Secret" }, "configured": { "type": "boolean", "description": "Whether a delivery secret is currently configured." } } }, "MissionReference": { "type": "object", "additionalProperties": false, "required": [ "kind", "id", "label" ], "properties": { "kind": { "type": "string", "enum": [ "assistant", "automation", "mission", "call", "contact", "campaign", "knowledge_base", "segment", "booking", "phone_number", "connected_app", "tool" ] }, "id": { "type": "string", "description": "Workspace-scoped resource ID." }, "label": { "type": "string", "description": "Server-normalized display label." } } }, "MissionTrigger": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "call.completed", "call.inbound", "call.variables", "conversation.started", "conversation.ended", "message.received", "booking.created", "booking.cancelled", "booking.rescheduled", "email.received", "lead.created", "manual", "schedule", "webhook.inbound", "airtable.webhook", "hubspot.webhook", "salesforce.webhook", "close.webhook", "highlevel.webhook", "pipedrive.webhook", "zoho.webhook", "attio.webhook", "keap.webhook", "twenty.webhook", "app.event" ] }, "assistant_id": { "type": [ "string", "null" ] }, "connector_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "event_type_id": { "type": [ "string", "null" ] }, "cron": { "type": [ "string", "null" ], "description": "Five-field cron for schedule triggers." }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone for schedule triggers." }, "toolkit": { "type": [ "string", "null" ], "description": "Connected-app family for an app event." }, "trigger_slug": { "type": [ "string", "null" ], "description": "Connected-app event type." }, "connection_id": { "type": [ "string", "null" ], "description": "ID of an existing saved connection." }, "trigger_config": { "type": [ "object", "null" ], "additionalProperties": true } } }, "MissionFilterGroup": { "type": [ "object", "null" ], "required": [ "operator", "conditions" ], "properties": { "operator": { "type": "string", "enum": [ "and", "or" ] }, "conditions": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "Safe path beginning with event, timestamp, or data." }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "exists", "in" ] }, "value": { "description": "Comparison value; omitted for exists." } } } } } }, "MissionVersionSpec": { "type": "object", "additionalProperties": false, "required": [ "objective", "trigger", "filters", "references", "capabilityGrants", "connectionGrants", "limits" ], "properties": { "objective": { "type": "string", "minLength": 1, "maxLength": 8000 }, "trigger": { "$ref": "#/components/schemas/MissionTrigger" }, "filters": { "$ref": "#/components/schemas/MissionFilterGroup" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/MissionReference" } }, "capabilityGrants": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "read", "write", "communicate", "call" ] } }, "connectionGrants": { "type": "array", "uniqueItems": true, "items": { "type": "string", "description": "ID of an existing saved connection." } }, "limits": { "type": "object", "additionalProperties": false, "required": [ "maxCreditsPerRun", "maxToolCalls", "maxRuntimeSeconds" ], "properties": { "maxCreditsPerRun": { "type": "number", "minimum": 1, "maximum": 10000 }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "maxRuntimeSeconds": { "type": "integer", "minimum": 30, "maximum": 1800 } } } } }, "MissionVersion": { "type": "object", "additionalProperties": false, "required": [ "id", "routine_id", "version", "status", "spec", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "routine_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "spec": { "$ref": "#/components/schemas/MissionVersionSpec" }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Routine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prompt": { "type": "string", "description": "The instruction the mission runs unattended each time it fires." }, "schedule_type": { "type": "string", "enum": [ "manual", "hourly", "daily", "weekdays", "weekly", "custom" ], "description": "manual = only runs via POST /routines/{id}/run. hourly/daily/weekdays/weekly/custom fire on the given schedule." }, "schedule_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 59, "description": "hourly only — minute of the hour to fire on (0-59), default 0." }, "schedule_time": { "type": [ "string", "null" ], "description": "daily/weekdays/weekly only — 24h wall-clock time \"HH:MM\", default \"09:00\"." }, "schedule_weekday": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6, "description": "weekly only — day of week, 0=Sunday … 6=Saturday." }, "cron_expression": { "type": [ "string", "null" ], "description": "custom only — standard 5-field cron (minute hour day-of-month month day-of-week). Occurrences must be at least 10 minutes apart." }, "timezone": { "type": "string", "description": "IANA timezone the schedule fields above are evaluated in, e.g. `Europe/Berlin`. Default `UTC`." }, "enabled": { "type": "boolean" }, "required_toolkits": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Connected-app toolkit slugs this mission's prompt depends on, e.g. [\"slack\",\"gmail\"]. The mission refuses to be created, updated, or run while one of these is not connected." }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_status": { "type": [ "string", "null" ], "enum": [ "running", "succeeded", "failed", null ] }, "last_error": { "type": [ "string", "null" ] }, "mission_status": { "type": "string", "enum": [ "legacy", "draft", "active", "paused", "needs_attention", "beta_disabled" ] }, "active_version_id": { "type": [ "string", "null" ], "format": "uuid" }, "active_version": { "type": [ "integer", "null" ], "minimum": 1 }, "trigger_type": { "type": "string", "description": "Trigger type of the active version, or manual/schedule for a classic Mission." }, "needs_attention": { "type": "boolean" }, "max_credits_per_run": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prompt", "schedule_type", "timezone", "enabled", "required_toolkits", "mission_status", "active_version_id", "active_version", "trigger_type", "needs_attention", "max_credits_per_run", "created_at", "updated_at" ] }, "RoutineCreate": { "type": "object", "required": [ "name", "prompt", "schedule_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prompt": { "type": "string", "description": "The instruction the mission runs unattended each time it fires." }, "schedule_type": { "type": "string", "enum": [ "manual", "hourly", "daily", "weekdays", "weekly", "custom" ], "description": "manual = only runs via POST /routines/{id}/run. hourly/daily/weekdays/weekly/custom fire on the given schedule." }, "schedule_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 59, "description": "hourly only — minute of the hour to fire on (0-59), default 0." }, "schedule_time": { "type": [ "string", "null" ], "description": "daily/weekdays/weekly only — 24h wall-clock time \"HH:MM\", default \"09:00\"." }, "schedule_weekday": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6, "description": "weekly only — day of week, 0=Sunday … 6=Saturday." }, "cron_expression": { "type": [ "string", "null" ], "description": "custom only — standard 5-field cron (minute hour day-of-month month day-of-week). Occurrences must be at least 10 minutes apart." }, "timezone": { "type": "string", "description": "IANA timezone the schedule fields above are evaluated in, e.g. `Europe/Berlin`. Default `UTC`." }, "enabled": { "type": "boolean" }, "required_toolkits": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Connected-app toolkit slugs this mission's prompt depends on, e.g. [\"slack\",\"gmail\"]. The mission refuses to be created while one of these is not connected." } } }, "RoutineUpdate": { "type": "object", "description": "Only the fields that change need to be sent.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prompt": { "type": "string", "description": "The instruction the mission runs unattended each time it fires." }, "schedule_type": { "type": "string", "enum": [ "manual", "hourly", "daily", "weekdays", "weekly", "custom" ], "description": "manual = only runs via POST /routines/{id}/run. hourly/daily/weekdays/weekly/custom fire on the given schedule." }, "schedule_minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 59, "description": "hourly only — minute of the hour to fire on (0-59), default 0." }, "schedule_time": { "type": [ "string", "null" ], "description": "daily/weekdays/weekly only — 24h wall-clock time \"HH:MM\", default \"09:00\"." }, "schedule_weekday": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 6, "description": "weekly only — day of week, 0=Sunday … 6=Saturday." }, "cron_expression": { "type": [ "string", "null" ], "description": "custom only — standard 5-field cron (minute hour day-of-month month day-of-week). Occurrences must be at least 10 minutes apart." }, "timezone": { "type": "string", "description": "IANA timezone the schedule fields above are evaluated in, e.g. `Europe/Berlin`. Default `UTC`." }, "enabled": { "type": "boolean" }, "required_toolkits": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Replace the connected-app toolkit slugs this mission's prompt depends on. Omit to leave unchanged. The mission refuses to save or run while one of these is not connected." } } }, "RoutineRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "routine_id": { "type": "string", "format": "uuid" }, "trigger": { "type": "string", "enum": [ "schedule", "manual", "event" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "thread_id": { "type": "string", "description": "Chat thread id for this run's transcript, shown on the workspace Milian Missions page." }, "error": { "type": [ "string", "null" ] }, "credits": { "type": "number", "description": "Credits charged for this run so far." }, "version_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Published Mission version used by this run." }, "event_type": { "type": [ "string", "null" ], "description": "Event trigger type, or null for manual and classic scheduled runs." }, "retry_of_run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Original run when this was an explicit manual retry." }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "tool_calls": { "type": "integer", "description": "Total tool calls made during this run." }, "tool_failures": { "type": "integer", "description": "Of tool_calls, how many failed. Can be greater than 0 even when status is succeeded — the run finished but not every tool call it made worked." } }, "required": [ "id", "routine_id", "trigger", "status", "thread_id", "credits", "version_id", "event_type", "retry_of_run_id", "started_at", "tool_calls", "tool_failures" ] }, "QaScorecardConfig": { "type": "object", "description": "AI QA scorecard configuration. Requires AI QA Scorecards in the workspace plan. When `enabled` is true and criteria are set, every finished call is scored and the result is written to `qa_scorecard` / `qa_score` / `qa_passed` on the call.", "properties": { "enabled": { "type": "boolean", "default": false }, "pass_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 70, "description": "Overall score 0–100 must be at least this value to pass." }, "criteria": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "snake_case key; unique within the array." }, "name": { "type": "string" }, "description": { "type": "string" }, "weight": { "type": "number", "minimum": 0.1, "default": 1 }, "source": { "type": "string", "enum": [ "llm", "reuse_success", "reuse_sentiment" ], "default": "llm", "description": "`llm` = judge from transcript; `reuse_success`/`reuse_sentiment` reuse post-call analysis fields." } } } } } }, "PublicCallFailure": { "type": "object", "additionalProperties": false, "required": [ "domain", "code", "message", "retryable", "action" ], "description": "Provider-neutral failure guidance for calls. Telephony failures also set operation.", "properties": { "domain": { "type": "string", "enum": [ "telephony", "billing", "admission", "runtime", "config", "dispatch", "workspace" ] }, "operation": { "type": "string", "enum": [ "outbound_call", "cold_transfer", "warm_transfer" ], "description": "Present when domain is telephony." }, "code": { "type": "string", "enum": [ "busy", "declined", "no_answer", "temporarily_unavailable", "cancelled_before_answer", "invalid_destination", "destination_not_found", "authentication_failed", "destination_forbidden", "caller_blocked", "call_redirected", "invalid_call_request", "phone_account_payment_required", "destination_gone", "media_not_supported", "connection_timeout", "request_too_large", "calling_feature_unsupported", "call_timer_rejected", "caller_identity_rejected", "phone_connection_failed", "routing_limit_reached", "call_permission_required", "call_session_not_found", "destination_ambiguous", "call_request_pending", "call_security_rejected", "phone_network_timeout", "call_requirements_not_met", "call_unwanted", "call_blocked_by_network", "routing_loop", "routing_conflict", "method_not_allowed", "trunk_unavailable", "no_outbound_trunk", "transfer_unavailable", "unknown", "insufficient_credits", "reservation_failed", "outbound_quota_reservation_failed", "integrated_outbound_limit_reached", "quiet_hours", "budget_service_unavailable", "workspace_concurrency_limit", "campaign_concurrency_limit", "platform_unavailable", "region_unavailable", "capability_unavailable", "capacity_exhausted", "admission_unavailable", "voice_unavailable", "speech_unavailable", "assistant_unavailable", "call_runtime_failed", "workspace_suspended", "dispatch_failed", "missing_destination", "ivr_detected", "voicemail_detected", "mailbox_unavailable" ] }, "message": { "type": "string", "description": "Stable, provider-neutral English explanation." }, "retryable": { "type": "boolean", "description": "Informational retry guidance. It does not change campaign retry policy." }, "action": { "type": "string", "enum": [ "retry_later", "do_not_retry", "check_destination", "check_trunk_credentials", "check_trunk_configuration", "connect_outbound_number", "continue_call", "contact_support", "top_up", "check_assistant", "check_campaign_schedule" ] } } }, "WelcomeCreditGrant": { "type": "object", "description": "Public outcome of the one-time welcome-credit grant for a customer workspace.", "required": [ "status", "requested_credits", "granted_credits" ], "properties": { "status": { "type": "string", "enum": [ "pending", "granted", "insufficient_funds", "disabled", "legacy", "failed" ] }, "requested_credits": { "type": "number", "minimum": 0 }, "granted_credits": { "type": "number", "minimum": 0 } } }, "PlatformPrepaidDefaultLimits": { "type": "object", "description": "Default numeric limits and feature availability for prepaid accounts. Numeric values use -1 for unlimited and 0 for unavailable; boolean values enable or disable the corresponding capability.", "additionalProperties": { "oneOf": [ { "type": "integer", "minimum": -1 }, { "type": "boolean" } ] }, "example": { "max_assistants": 2, "max_campaigns": 0, "web_widget": true } }, "PlatformDefaultLimitsSettings": { "type": "object", "additionalProperties": false, "required": [ "self_service_registration_enabled", "prepaid_accounts_enabled", "prepaid_extra_minute_price_eur", "prepaid_default_limits" ], "properties": { "self_service_registration_enabled": { "type": "boolean", "description": "Whether new customers can create an account from the white-label login page. Existing customers can still sign in when disabled." }, "prepaid_accounts_enabled": { "type": "boolean", "description": "Whether customers without a paid plan can use prepaid credits." }, "prepaid_extra_minute_price_eur": { "type": "number", "minimum": 0, "description": "Customer price per additional minute in EUR major units.", "example": 0.49 }, "prepaid_default_limits": { "$ref": "#/components/schemas/PlatformPrepaidDefaultLimits" } } }, "PlatformDefaultLimitsPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "self_service_registration_enabled": { "type": "boolean" }, "prepaid_accounts_enabled": { "type": "boolean" }, "prepaid_extra_minute_price_eur": { "type": "number", "minimum": 0, "description": "Customer price per additional minute in EUR major units. When prepaid access is enabled, this price must leave a positive reseller margin." }, "prepaid_default_limits": { "$ref": "#/components/schemas/PlatformPrepaidDefaultLimits" } } }, "PlatformWelcomeCreditSettings": { "type": "object", "required": [ "welcome_credits", "free_accounts_enabled", "automatic_grants_active", "wallet_credits_balance", "estimated_fundable_customers" ], "properties": { "welcome_credits": { "type": "number", "minimum": 0, "description": "One-time wallet credits offered to each future free customer.", "example": 800 }, "free_accounts_enabled": { "type": "boolean" }, "automatic_grants_active": { "type": "boolean", "description": "True when free accounts are enabled and welcome_credits is greater than 0." }, "wallet_credits_balance": { "type": "number", "minimum": 0 }, "estimated_fundable_customers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current wallet divided by welcome_credits, rounded down; null when welcome_credits is 0." } } }, "PlatformWelcomeCreditSettingsPatch": { "type": "object", "additionalProperties": false, "required": [ "welcome_credits" ], "properties": { "welcome_credits": { "type": "number", "minimum": 0, "example": 800 } } }, "PlatformUser": { "type": "object", "description": "A customer in your White-Label Platform API scope — your reseller workspace's customer, or (for platform admins) a direct platform customer.", "properties": { "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "workspace_id": { "type": "string", "format": "uuid", "description": "The customer's workspace." }, "workspace_name": { "type": "string" }, "credits_balance": { "type": "number", "description": "Manually-topped-up credits." }, "plan_credits_balance": { "type": "number", "description": "Credits included with the active plan." }, "minutes_balance": { "type": "number" }, "plan_name": { "type": "string", "example": "free" }, "suspended": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "welcome_credit": { "oneOf": [ { "$ref": "#/components/schemas/WelcomeCreditGrant" }, { "type": "null" } ] } } }, "PlatformUserWorkspace": { "type": "object", "description": "One of the customer's workspaces that falls inside your operator scope.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "is_owner": { "type": "boolean" }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "PlatformUserDetail": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string", "format": "uuid", "description": "The selected workspace (see `?workspace_id=`)." }, "workspace_name": { "type": "string" }, "suspended": { "type": "boolean" }, "credits_balance": { "type": "number" }, "plan_credits_balance": { "type": "number" }, "minutes_balance": { "type": "number" }, "plan_name": { "type": "string" }, "subscription_status": { "type": [ "string", "null" ] }, "workspaces": { "type": "array", "description": "Every workspace this customer has that falls inside your operator scope.", "items": { "$ref": "#/components/schemas/PlatformUserWorkspace" } }, "welcome_credit": { "oneOf": [ { "$ref": "#/components/schemas/WelcomeCreditGrant" }, { "type": "null" } ] } } }, "PlatformUserRegisterInput": { "type": "object", "required": [ "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mode": { "type": "string", "enum": [ "invite", "password" ], "default": "invite", "description": "`invite` (default) creates the account without a password — pair it with `POST /platform/users/{user_id}/token` or `.../login` for your own custom auth flow. `password` sets an initial password you choose." }, "password": { "type": "string", "minLength": 8, "description": "Required when `mode` is `password` (min. 8 characters). Ignored otherwise." }, "timezone": { "type": "string", "example": "Europe/Berlin" }, "language": { "type": "string", "enum": [ "en", "de", "fr", "es" ] } } }, "PlatformUserRegisterResult": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "welcome_credit": { "oneOf": [ { "$ref": "#/components/schemas/WelcomeCreditGrant" }, { "type": "null" } ] } } }, "PlatformUserTokenInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "default": "Platform access token" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Subset of the canonical API scopes to grant this token. Omitted or empty = full access for this customer — this is a completely different principal than your own operator credential, so it is NOT limited to your own credential's scopes." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Omitted = the token never expires." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Pick a specific workspace when the customer has several in your scope; defaults to the one they own." } } }, "PlatformUserToken": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "fam_live_a1b2c3d4e5f6...", "description": "Plaintext API key — shown exactly once. It is hashed at rest and cannot be retrieved again; if it's lost, mint a new one." }, "prefix": { "type": "string", "description": "Stable, non-secret prefix for display/audit." }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "workspace_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "PlatformUserLoginInput": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } }, "PlatformUserLogoutResult": { "type": "object", "properties": { "revoked_api_keys": { "type": "integer" }, "revoked_oauth_tokens": { "type": "integer" } } }, "PlatformBalanceTransferInput": { "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "number", "description": "Signed, non-zero. Positive grants credits from your workspace wallet into the customer's; negative reclaims credits back from the customer into yours. The source wallet must cover the amount — wallet balances never go below zero.", "example": 50 }, "note": { "type": "string", "description": "Optional audit note." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Pick a specific workspace when the customer has several in your scope; defaults to the one they own." } } }, "PlatformBalanceTransferResult": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "credits_balance": { "type": "number", "description": "The customer workspace's new balance." }, "plan_credits_balance": { "type": "number" }, "source_credits_balance": { "type": "number", "description": "Your own workspace wallet's new balance after this transfer." }, "direction": { "type": "string", "enum": [ "transfer", "reclaim" ] } } }, "ApiKey": { "type": "object", "description": "An API key belonging to the calling workspace. Never includes the secret.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "principal_type": { "type": "string", "enum": [ "user", "service_account" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiKeyCreateInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "scopes": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Must be a subset of the calling credential's own scopes — a key can never mint another key with broader access than itself. Omitted defaults to the calling credential's own scopes (or, if the credential itself has unrestricted access, every scope)." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Requested lifetime. Omitted inherits a finite calling credential's expiry, or means no expiry when the caller itself does not expire." } } }, "ApiKeyCreated": { "type": "object", "description": "A newly-minted API key, including the plaintext secret.", "required": [ "id", "name", "prefix", "scopes", "principal_type", "expires_at", "created_at", "key" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "principal_type": { "type": "string", "enum": [ "user", "service_account" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "key": { "type": "string", "example": "fam_live_a1b2c3d4e5f6...", "description": "Plaintext API key — shown exactly once. It is hashed at rest and cannot be retrieved again; if it's lost, revoke this key and mint a new one." } } }, "WorkspaceApiKeyCreated": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyCreated" }, { "type": "object", "required": [ "workspace_id" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "The workspace this new service-account key is permanently bound to." } } } ] }, "Workspace": { "type": "object", "description": "A workspace visible to the calling credential.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "logo_url": { "type": "string", "nullable": true, "description": "Workspace logo for light appearance, when available." }, "logo_dark_url": { "type": "string", "nullable": true, "description": "Workspace logo for dark appearance, when available." }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer", "billing" ], "description": "The key owner's role in this workspace. A service-account key always reports its own workspace with role `admin`." }, "current": { "type": "boolean", "description": "True for the workspace this credential is bound to." } } }, "WorkspaceCreateInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Plain-text display name. Must not contain < > { } [ ] ` \\ or line breaks; such names are rejected with 400." } } }, "WorkspaceCreated": { "type": "object", "description": "A newly created workspace. The creating user is always its owner.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner" ] } } }, "EmailDnsRecord": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "MX" ] }, "host": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ], "description": "MX priority; null for CNAME records." }, "purpose": { "type": "string", "enum": [ "sending", "dkim", "receiving" ] }, "valid": { "type": "boolean", "description": "Whether this record currently resolves correctly." } } }, "EmailDomain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "example": "mail.your-domain.com" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ] }, "dns_records": { "type": "array", "items": { "$ref": "#/components/schemas/EmailDnsRecord" }, "description": "The CNAME (sending + DKIM) and MX (receiving) records to add at your DNS provider." }, "inbound_configured": { "type": "boolean", "description": "Whether inbound receiving is wired up." }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmailDomainCreateInput": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "mail.your-domain.com" } } }, "EmailAddress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain_id": { "type": "string", "format": "uuid" }, "local_part": { "type": "string", "example": "support" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email", "description": "Full address (`local_part@domain`)." }, "domain": { "type": "string" }, "assistant_name": { "type": [ "string", "null" ] } } }, "EmailAddressCreateInput": { "type": "object", "required": [ "domain_id", "local_part" ], "properties": { "domain_id": { "type": "string", "format": "uuid", "description": "Must belong to an already-verified domain." }, "local_part": { "type": "string", "example": "support" }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ], "maxLength": 128 } } }, "EmailAddressUpdateInput": { "type": "object", "properties": { "assistant_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ], "maxLength": 128 }, "is_active": { "type": "boolean" } } }, "EmailSettings": { "type": "object", "properties": { "default_display_name": { "type": "string" }, "default_signature": { "type": "string", "description": "\"{agent_name}\" is replaced with the assistant's name at send time." } } }, "EmailSettingsInput": { "type": "object", "properties": { "default_display_name": { "type": "string" }, "default_signature": { "type": "string" } } }, "AiInferenceSettings": { "type": "object", "required": [ "ai_inference_region" ], "properties": { "ai_inference_region": { "type": "string", "enum": [ "global", "eu", "us" ], "description": "AI inference region for the workspace (`global`, `eu`, or `us`). EU activates after-save assistant AI-disclosure review." } } }, "KnowledgeDocumentProcessResult": { "type": "object", "required": [ "document_id", "chunk_count", "total_chunks", "truncated" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "chunk_count": { "type": "integer", "minimum": 0, "description": "Number of indexed chunks after this run." }, "total_chunks": { "type": "integer", "minimum": 0, "description": "Number of chunks extracted from the source." }, "truncated": { "type": "boolean", "description": "Whether text processing stopped at its per-run limit. Table rows are never partially indexed." } } }, "ConfigurableMemoryChannel": { "type": "string", "enum": [ "voice", "sms", "whatsapp", "email", "web", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "freshdesk", "gmail", "outlook", "zendesk", "servicenow", "intercom", "zoho_mail", "agent_mail", "instagram", "zulip", "web_chat", "web_voice" ], "description": "Memory channels. Web Chat and Web Voice require a current verified widget email or phone and memory consent. Web and SMS memory require a root workspace. Legacy web configuration expands to both web channels; anonymous sessions remain excluded." }, "TranslationConfig": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "speaker1": { "type": "object", "properties": { "language": { "type": "string", "pattern": "^[a-z]{2,3}$" }, "voice": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque catalog voice or workspace clone identifier from the voice library." } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "language", "voice" ], "additionalProperties": false }, "speaker2": { "type": "object", "properties": { "language": { "type": "string", "pattern": "^[a-z]{2,3}$" }, "voice": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque catalog voice or workspace clone identifier from the voice library." } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "language", "voice" ], "additionalProperties": false } }, "required": [ "version", "speaker1", "speaker2" ], "additionalProperties": false }, "TranslationSpeaker": { "type": "object", "properties": { "side": { "type": "integer", "enum": [ 1, 2 ] }, "display_name": { "type": "string" }, "language": { "type": "string" }, "transport": { "type": "string", "enum": [ "web", "phone", "inbound" ] }, "status": { "type": "string", "enum": [ "waiting", "connecting", "ringing", "connected", "disconnected", "failed" ] } }, "required": [ "side", "display_name", "language", "transport", "status" ], "additionalProperties": false }, "TranslationSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "waiting", "connecting", "active", "ending", "completed", "failed" ] }, "assistant_name": { "type": "string" }, "host_name": { "type": "string" }, "speakers": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationSpeaker" } }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "talk_duration_sec": { "type": "number", "minimum": 0 }, "max_duration_sec": { "type": "integer", "minimum": 0 }, "invite_url": { "type": "string", "format": "uri" }, "dial_in": { "type": "object", "properties": { "number": { "type": [ "string", "null" ] }, "code": { "type": "string" } }, "additionalProperties": false }, "phone_number_id": { "type": [ "string", "null" ], "format": "uuid" }, "can_call": { "type": "boolean", "readOnly": true, "description": "Host detail only. True when the assistant has a connected outgoing phone number. Uses the configured outbound number, or an outbound number assigned to the assistant when no outbound selection is configured. Destination, credit and calling-limit checks still apply when calling. Omitted from list and guest responses." } }, "required": [ "id", "status", "speakers" ], "additionalProperties": false }, "TranslationSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer" }, "side": { "type": "integer", "enum": [ 1, 2 ] }, "original_text": { "type": "string" }, "translated_text": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "TranslationStart": { "type": "object", "properties": { "speaker1": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "web", "phone", "inbound" ] }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "International E.164 telephone number." } }, "required": [ "transport" ], "additionalProperties": false }, "speaker2": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "web", "phone" ] }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "International E.164 telephone number." } }, "required": [ "transport" ], "additionalProperties": false }, "phone_number_id": { "type": "string", "format": "uuid" } }, "required": [ "speaker1", "speaker2" ], "additionalProperties": false }, "CustomPayment": { "type": "object", "description": "An admin-created one-time charge, invoice or subscription for one customer, outside their regular plan.", "properties": { "id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "platform", "reseller" ] }, "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": [ "string", "null" ] }, "user_id": { "type": "string", "format": "uuid" }, "user_email": { "type": [ "string", "null" ] }, "user_name": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "one_time", "subscription" ] }, "channel": { "type": "string", "enum": [ "charge_saved_method", "payment_link", "invoice" ], "description": "How the customer pays." }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_amount": { "type": "integer", "description": "Unit price in the currency's smallest unit (e.g. cents)." }, "currency": { "type": "string", "description": "3-letter ISO currency code." }, "decimal_digits": { "type": "integer", "description": "Minor-unit decimal digits for display (0 for zero-decimal currencies)." }, "interval": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year", null ] }, "interval_count": { "type": [ "integer", "null" ] }, "trial_days": { "type": [ "integer", "null" ] }, "days_until_due": { "type": [ "integer", "null" ] }, "tax_behavior": { "type": "string", "enum": [ "exclusive", "inclusive", "unspecified" ] }, "tax_code": { "type": [ "string", "null" ] }, "automatic_tax": { "type": "boolean" }, "tax_status": { "type": [ "string", "null" ], "description": "complete, requires_location_inputs, failed, or not_enabled." }, "status": { "type": "string", "enum": [ "pending", "requires_action", "open", "paid", "active", "trialing", "past_due", "failed", "canceled", "void", "uncollectible", "expired", "unpaid", "incomplete" ] }, "amount_subtotal": { "type": [ "integer", "null" ] }, "amount_tax": { "type": [ "integer", "null" ] }, "amount_total": { "type": [ "integer", "null" ] }, "hosted_url": { "type": [ "string", "null" ], "format": "uri", "description": "Payment link URL or hosted invoice page." }, "invoice_pdf_url": { "type": [ "string", "null" ], "format": "uri" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "cancel_at_period_end": { "type": "boolean" }, "notify_customer": { "type": "boolean" }, "notification_status": { "type": [ "string", "null" ] }, "notification_error": { "type": [ "string", "null" ] }, "created_by_kind": { "type": "string", "enum": [ "platform_admin", "tenant_admin", "api" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "available_actions": { "type": "array", "items": { "type": "string", "enum": [ "refresh", "resend_notification", "cancel", "cancel_at_period_end", "mark_uncollectible", "deactivate_link", "open_hosted", "copy_link", "download_pdf" ] } } }, "required": [ "id", "scope", "workspace_id", "user_id", "kind", "channel", "description", "quantity", "unit_amount", "currency", "status", "created_at", "updated_at" ] }, "CreateCustomPaymentInput": { "type": "object", "required": [ "kind", "channel", "description", "amount_minor", "currency" ], "properties": { "kind": { "type": "string", "enum": [ "one_time", "subscription" ] }, "channel": { "type": "string", "enum": [ "charge_saved_method", "payment_link", "invoice" ] }, "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999, "default": 1 }, "amount_minor": { "type": "integer", "minimum": 1, "description": "Unit price in the currency's smallest unit. Total charged = amount_minor * quantity." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "3-letter ISO currency code, e.g. EUR." }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Required when kind is subscription." }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 365, "default": 1 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Subscription only. Not available on the invoice channel." }, "days_until_due": { "type": "integer", "minimum": 1, "maximum": 365, "default": 14, "description": "Invoice channel only." }, "tax_behavior": { "type": "string", "enum": [ "exclusive", "inclusive", "unspecified" ], "default": "exclusive" }, "tax_code": { "type": "string", "maxLength": 40 }, "automatic_tax": { "type": "boolean", "description": "Default: on when available for the billing account." }, "notify_customer": { "type": "boolean", "description": "Default: on for invoice/payment_link, off for charge_saved_method." }, "internal_note": { "type": "string", "maxLength": 1000, "description": "Private note, never shown to the customer." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Disambiguate when the customer has multiple workspaces in your scope." }, "payment_method_id": { "type": "string", "description": "charge_saved_method only: a specific saved payment method id." }, "idempotency_key": { "type": "string", "maxLength": 200, "description": "Resubmitting the same key returns the existing payment instead of charging twice." }, "confirm_large_amount": { "type": "boolean", "description": "Required (true) when amount_minor * quantity is unusually large." } } }, "CustomPaymentActionInput": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "refresh", "resend_notification", "cancel", "cancel_at_period_end", "mark_uncollectible", "deactivate_link" ] }, "immediately": { "type": "boolean", "description": "cancel action on a subscription only: true cancels now, false/omitted schedules cancellation at period end." } } }, "CustomPaymentSummary": { "type": "object", "properties": { "count": { "type": "integer" }, "paid_total_by_currency": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Sum of paid amount_total per currency, in minor units." } } }, "SavedPaymentMethod": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "card", "sepa_debit" ] }, "brand": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "exp_month": { "type": [ "integer", "null" ] }, "exp_year": { "type": [ "integer", "null" ] }, "is_default": { "type": "boolean" } } }, "CustomPaymentsContext": { "type": "object", "description": "Create-time context for one customer: resolved workspace, currency options, and billing readiness.", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "workspace_name": { "type": [ "string", "null" ] }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "decimal_digits": { "type": "integer" }, "locked": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "decimal_digits": { "type": "integer" } } } } } }, "billing_available": { "type": "boolean" }, "billing_unavailable_reason": { "type": "string" }, "tax_automation_enabled": { "type": "boolean" }, "saved_payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/SavedPaymentMethod" } }, "customer_email": { "type": [ "string", "null" ] } } }, "CustomPaymentListResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomPayment" } }, "next_cursor": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/CustomPaymentSummary" } } }, "CustomPaymentUserListResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomPayment" } }, "next_cursor": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/CustomPaymentSummary" }, "context": { "$ref": "#/components/schemas/CustomPaymentsContext" } } }, "CustomPaymentItemResult": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/CustomPayment" } } }, "BookingEmailTemplate": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "subject": { "type": "string", "nullable": true, "maxLength": 200, "description": "Single-line subject with booking template variables. Blank/null restores the standard subject." }, "body": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Plain-text message with booking template variables. Blank/null restores the standard message." } } }, "SmsRegistrationInput": { "type": "object", "properties": { "legal_name": { "description": "Exact legal business name as registered with the IRS or tax authority, including suffixes such as LLC or Inc.", "type": "string", "minLength": 2, "maxLength": 128 }, "business_type": { "type": "string", "enum": [ "Co-operative", "Corporation", "Limited Liability Corporation", "Non-profit Corporation", "Partnership" ] }, "industry": { "type": "string", "enum": [ "AGRICULTURE", "AUTOMOTIVE", "BANKING", "CONSTRUCTION", "CONSUMER", "EDUCATION", "ELECTRONICS", "ENGINEERING", "ENERGY", "FAST_MOVING_CONSUMER_GOODS", "FINANCIAL", "FINTECH", "FOOD_AND_BEVERAGE", "GOVERNMENT", "HEALTHCARE", "HOSPITALITY", "INSURANCE", "JEWELRY", "LEGAL", "MANUFACTURING", "MEDIA", "NOT_FOR_PROFIT", "OIL_AND_GAS", "ONLINE", "PROFESSIONAL_SERVICES", "RAW_MATERIALS", "REAL_ESTATE", "RELIGION", "RETAIL", "TECHNOLOGY", "TELECOMMUNICATIONS", "TRANSPORTATION", "TRAVEL" ] }, "registration_type": { "type": "string", "enum": [ "EIN", "CBN", "CN", "ACN", "CIN", "VAT", "VATRN", "RN", "Other" ] }, "registration_number": { "type": "string", "minLength": 2, "maxLength": 64 }, "website": { "type": "string", "maxLength": 2048, "format": "uri" }, "regions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "AFRICA", "ASIA", "EUROPE", "LATIN_AMERICA", "USA_AND_CANADA" ] } }, "company_type": { "type": "string", "enum": [ "private", "public", "non-profit", "government" ] }, "stock_exchange": { "description": "Exchange code for public companies, for example NASDAQ or NYSE.", "default": "", "type": "string", "minLength": 0, "maxLength": 20 }, "stock_ticker": { "default": "", "type": "string", "minLength": 0, "maxLength": 20 }, "brand_contact_email": { "default": "", "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "volume": { "type": "string", "enum": [ "low", "standard" ] }, "use_case": { "type": "string", "enum": [ "LOW_VOLUME", "2FA", "ACCOUNT_NOTIFICATION", "CUSTOMER_CARE", "DELIVERY_NOTIFICATION", "FRAUD_ALERT", "HIGHER_EDUCATION", "MARKETING", "MIXED", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT", "SECURITY_ALERT" ] }, "representative_first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "representative_last_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "representative_email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "representative_phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "representative_title": { "type": "string", "minLength": 2, "maxLength": 100 }, "representative_position": { "type": "string", "enum": [ "Director", "GM", "VP", "CEO", "CFO", "General Counsel", "Other" ] }, "street": { "type": "string", "minLength": 2, "maxLength": 100 }, "city": { "type": "string", "minLength": 2, "maxLength": 100 }, "region": { "description": "State or province. For US and Canadian businesses use the two-letter code, for example AZ; full state or province names are converted.", "type": "string", "minLength": 1, "maxLength": 100 }, "postal_code": { "type": "string", "minLength": 2, "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "campaign_description": { "type": "string", "minLength": 40, "maxLength": 4096 }, "message_flow": { "type": "string", "minLength": 40, "maxLength": 2048 }, "message_samples": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 20, "maxLength": 1024 } }, "privacy_policy_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "terms_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "has_links": { "type": "boolean" }, "has_phone_numbers": { "type": "boolean" }, "age_gated": { "type": "boolean" }, "direct_lending": { "type": "boolean" }, "consent_confirmed": { "type": "boolean", "enum": [ true ] } }, "required": [ "legal_name", "business_type", "industry", "registration_type", "registration_number", "website", "regions", "company_type", "stock_exchange", "stock_ticker", "brand_contact_email", "volume", "use_case", "representative_first_name", "representative_last_name", "representative_email", "representative_phone", "representative_title", "representative_position", "street", "city", "region", "postal_code", "country", "campaign_description", "message_flow", "message_samples", "privacy_policy_url", "terms_url", "has_links", "has_phone_numbers", "age_gated", "direct_lending", "consent_confirmed" ], "additionalProperties": false }, "SmsRegistration": { "type": "object", "description": "The workspace SMS registration. One registration covers every linked number of the workspace. Provider identifiers and internal billing details are omitted.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "review_stage": { "type": "string", "nullable": true, "enum": [ "business", "brand", "campaign", "numbers" ], "description": "How far the external review got: business verification, brand registration, campaign review or number activation. For a rejected application it names the stage that needs a correction; null before review starts." }, "review_notice": { "type": "string", "nullable": true, "readOnly": true, "description": "Customer-facing correction guidance for the current rejected application or required action. Reflects the recorded external review notice where available; otherwise gives guidance for the review stage. Null when no correction is required. Separate from advisory pre-submit findings." }, "corrections_left": { "type": "integer", "nullable": true, "description": "Free corrections left for the review step a rejected application stopped at; null outside a rejection." }, "details": { "$ref": "#/components/schemas/SmsRegistrationInput" }, "phone_number_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "paid_until": { "type": "string", "nullable": true, "format": "date-time" }, "cancel_at_period_end": { "type": "boolean" }, "quote": { "type": "object", "nullable": true, "properties": { "quote_ref": { "type": "string" }, "setup_amount": { "type": "integer", "description": "One-time net price in currency minor units." }, "monthly_amount": { "type": "integer", "description": "Monthly net price in currency minor units." }, "currency": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } }, "SmsRegistrationForNumber": { "allOf": [ { "$ref": "#/components/schemas/SmsRegistration" }, { "type": "object", "properties": { "number_status": { "type": "string", "description": "Current SMS registration status of this selected number." }, "unlinked_numbers": { "type": "integer", "description": "Eligible US numbers of the workspace that aren't linked to the registration yet." } } } ] }, "SmsRegistrationVolumeOptions": { "type": "object", "properties": { "currency": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "volume": { "type": "string", "enum": [ "low", "standard" ], "description": "low: up to 6,000 message segments per day to US numbers (2,000 per day to T-Mobile). standard: the daily limit follows the trust score, 6,000 to 400,000 message segments (2,000 to 200,000 per day to T-Mobile), with additional business vetting." }, "setup_amount": { "type": "integer", "description": "One-time net price in currency minor units." }, "monthly_amount": { "type": "integer", "description": "Monthly net price in currency minor units." } } } } }, "description": "One-time and monthly prices for both registration volumes in the workspace currency." }, "InboxLabel": { "type": "object", "description": "Advisory label. It never changes message visibility, replies, or the connected mailbox.", "required": [ "id", "label", "message_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "enum": [ "possible_scam", "advertising" ] }, "message_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "InboxLabelSettings": { "type": "object", "required": [ "enabled", "available" ], "properties": { "enabled": { "type": "boolean", "description": "Workspace preference for new inbound messages." }, "available": { "type": "boolean", "description": "Whether the workspace plan includes message labels." } } }, "ResellerKnowledgeSourceAccess": { "type": "object", "additionalProperties": false, "required": [ "website_crawling", "cloud_drive", "automatic_refresh" ], "properties": { "website_crawling": { "type": "boolean", "description": "Allow website crawling; new or changed pages consume credits." }, "cloud_drive": { "type": "boolean", "description": "Allow cloud drive sources. The customer workspace must also enable Beta Features." }, "automatic_refresh": { "type": "boolean", "description": "Allow scheduled refresh for enabled website and cloud drive sources." } } }, "BookingSlotRequirements": { "type": "object", "description": "What create_booking / POST /bookings needs for this event type.", "properties": { "email_required": { "type": "boolean" }, "phone_required": { "type": "boolean" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/BookingField" } }, "location_type": { "type": [ "string", "null" ] } } }, "BookingCreateInput": { "type": "object", "required": [ "event_type_id", "start", "name" ], "properties": { "event_type_id": { "type": "string", "format": "uuid", "description": "Event type ID." }, "start": { "type": "string", "format": "date-time", "description": "Start time in ISO 8601 UTC — must be a value returned by List free slots, unless allow_outside_availability is set." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Invitee name." }, "email": { "type": "string", "description": "Invitee email — required when the event type requires it (e.g. a Google Meet/Teams location)." }, "phone": { "type": "string", "description": "International format, e.g. +4915123456789. Required when the event type requires it." }, "notes": { "type": "string", "maxLength": 2000, "description": "Notes attached to the booking." }, "answers": { "type": "object", "additionalProperties": true, "description": "Answers to the event type's custom booking questions, keyed by BookingField.id." }, "timezone": { "type": "string", "description": "IANA time zone used for the invitee's confirmation email and calendar invite; does not affect how `start` is parsed. Default the workspace time zone." }, "hour_cycle": { "type": "string", "enum": [ "12h", "24h" ], "description": "Time format used in the invitee's confirmation email; default 24h." }, "allow_outside_availability": { "type": "boolean", "default": false, "description": "Set true to book outside the event type's open times (staff override). Any future time within the next 2 years is accepted; the time must not overlap another confirmed booking of the same event type. Guests on the public booking page only ever see open times." } } }, "BookingCreated": { "allOf": [ { "$ref": "#/components/schemas/Booking" }, { "type": "object", "properties": { "email_scheduled": { "type": "boolean", "description": "Whether a confirmation email was scheduled (an email address was given)." }, "meeting_url": { "type": [ "string", "null" ], "description": "Video meeting URL when the event type uses Google Meet/Teams." } } } ] }, "BookingSlots": { "type": "object", "properties": { "event_type_id": { "type": "string", "format": "uuid" }, "event_type_name": { "type": "string" }, "duration_min": { "type": "integer" }, "slot_increment_min": { "type": [ "integer", "null" ] }, "timezone": { "type": "string" }, "start": { "type": "string", "format": "date", "description": "Start of the resolved date range." }, "end": { "type": "string", "format": "date", "description": "End of the resolved date range." }, "bookable_until": { "type": "string", "format": "date-time", "description": "The event type's booking horizon (now + max_days_ahead)." }, "slots": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Free start times, ISO 8601 UTC, ascending." }, "requirements": { "$ref": "#/components/schemas/BookingSlotRequirements" } } }, "VoiceCloneCreationPricing": { "type": "object", "required": [ "creation_credits", "next_creation_credits", "included_creations", "free_creations_used", "free_creations_reserved", "free_creations_remaining", "allowance_period" ], "properties": { "creation_credits": { "type": "number", "minimum": 0, "description": "Current effective price of an additional successful creation, in credits." }, "next_creation_credits": { "type": "number", "minimum": 0, "description": "Price to show and explicitly accept for the next creation; zero while a free creation is available." }, "included_creations": { "type": "integer", "minimum": 0 }, "free_creations_used": { "type": "integer", "minimum": 0 }, "free_creations_reserved": { "type": "integer", "minimum": 0 }, "free_creations_remaining": { "type": "integer", "minimum": 0 }, "allowance_period": { "type": "string", "const": "workspace_lifetime", "description": "Successful free creations count for the lifetime of this workspace. Renewals, deleting voices and plan changes never reset usage." } } }, "LoopHistoryParty": { "type": "object", "required": [ "name", "address", "avatar_url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Workspace member or contact display name when available." }, "address": { "type": [ "string", "null" ], "description": "Public phone number or extension." }, "avatar_url": { "type": [ "string", "null" ], "description": "Avatar image URL when available." } } }, "CallInsightReply": { "type": "object", "additionalProperties": false, "required": [ "transcript_index", "at", "audio_offset_sec", "before_recording", "number", "response_ms", "recognition_ms", "turn_detection_ms", "response_generation_ms", "speech_generation_ms", "playback_ms" ], "properties": { "transcript_index": { "type": [ "integer", "null" ], "minimum": 0, "description": "Index in transcript_display when a unique displayed turn match is available; otherwise null." }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "audio_offset_sec": { "type": [ "number", "null" ], "minimum": 0, "description": "Position in the permitted recording in seconds, or null when unavailable." }, "before_recording": { "type": "boolean", "description": "True when the spoken turn precedes the available recording. Such speech cannot be played." }, "number": { "type": "integer", "minimum": 1 }, "response_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Measured response time in milliseconds. Missing measurements are null, never zero-filled." }, "recognition_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Time from the caller finishing speech until the transcript arrives. Missing measurements are null, never zero-filled." }, "turn_detection_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Additional wait from transcript arrival until the caller turn is committed; recognition time is excluded. Missing measurements are null, never zero-filled." }, "response_generation_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Time until response generation begins returning text. Missing measurements are null, never zero-filled." }, "speech_generation_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Time until speech generation begins returning audio. Missing measurements are null, never zero-filled." }, "playback_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Delay before the generated speech starts playing. Missing measurements are null, never zero-filled." } } }, "CallInsightEvent": { "type": "object", "additionalProperties": false, "required": [ "transcript_index", "at", "audio_offset_sec", "before_recording", "id", "kind", "duration_ms", "confidence" ], "properties": { "transcript_index": { "type": [ "integer", "null" ], "minimum": 0, "description": "Index in transcript_display when a unique displayed turn match is available; otherwise null." }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "audio_offset_sec": { "type": [ "number", "null" ], "minimum": 0, "description": "Position in the permitted recording in seconds, or null when unavailable." }, "before_recording": { "type": "boolean", "description": "True when the spoken turn precedes the available recording. Such speech cannot be played." }, "id": { "type": "string", "description": "Identifier within this insights response." }, "kind": { "type": "string", "enum": [ "interruption", "backchannel", "resumed", "review_transcript", "late_transcript", "overlap", "playback" ] }, "duration_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Measured duration where applicable. Missing measurements are null, never zero-filled." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Recorded recognition score when available. This is not a probability that the sentence is correct." } } }, "CallInsights": { "type": "object", "additionalProperties": false, "required": [ "version", "coverage", "recording_origin", "summary", "timing", "replies", "events" ], "properties": { "version": { "type": "integer", "const": 1 }, "coverage": { "type": "string", "enum": [ "complete", "partial" ], "description": "Coverage of the available observation data. Individual missing measurements remain null." }, "recording_origin": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the available recording. Playback remains subject to recording and consent settings." }, "summary": { "type": "object", "additionalProperties": false, "required": [ "reply_count", "measured_reply_count", "response_median_ms", "response_p95_ms", "interruptions", "backchannels", "resumed", "overlap_ms", "overlap_coverage", "connection_quality" ], "properties": { "reply_count": { "type": "integer", "minimum": 0 }, "measured_reply_count": { "type": "integer", "minimum": 0 }, "response_median_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Median measured response time. Missing measurements are null, never zero-filled." }, "response_p95_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "95th percentile measured response time. Missing measurements are null, never zero-filled." }, "interruptions": { "type": [ "integer", "null" ], "minimum": 0 }, "backchannels": { "type": [ "integer", "null" ], "minimum": 0, "description": "Caller overlaps classified as non-interrupting speech, when observed." }, "resumed": { "type": [ "integer", "null" ], "minimum": 0 }, "overlap_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Observed duration of simultaneous caller and assistant speech. Missing measurements are null, never zero-filled." }, "overlap_coverage": { "type": "string", "enum": [ "complete", "partial", "unavailable" ] }, "connection_quality": { "type": "string", "enum": [ "good", "degraded", "poor", "unknown" ] } } }, "timing": { "type": "object", "additionalProperties": false, "required": [ "recognition_ms", "turn_detection_ms", "response_generation_ms", "speech_generation_ms", "playback_ms" ], "properties": { "recognition_ms": { "type": "object", "additionalProperties": false, "required": [ "average_ms", "samples" ], "properties": { "average_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Mean of available measurements. Missing measurements are null, never zero-filled." }, "samples": { "type": "integer", "minimum": 0 } } }, "turn_detection_ms": { "type": "object", "additionalProperties": false, "required": [ "average_ms", "samples" ], "properties": { "average_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Mean of available measurements. Missing measurements are null, never zero-filled." }, "samples": { "type": "integer", "minimum": 0 } } }, "response_generation_ms": { "type": "object", "additionalProperties": false, "required": [ "average_ms", "samples" ], "properties": { "average_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Mean of available measurements. Missing measurements are null, never zero-filled." }, "samples": { "type": "integer", "minimum": 0 } } }, "speech_generation_ms": { "type": "object", "additionalProperties": false, "required": [ "average_ms", "samples" ], "properties": { "average_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Mean of available measurements. Missing measurements are null, never zero-filled." }, "samples": { "type": "integer", "minimum": 0 } } }, "playback_ms": { "type": "object", "additionalProperties": false, "required": [ "average_ms", "samples" ], "properties": { "average_ms": { "type": [ "number", "null" ], "minimum": 0, "description": "Mean of available measurements. Missing measurements are null, never zero-filled." }, "samples": { "type": "integer", "minimum": 0 } } } } }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CallInsightReply" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CallInsightEvent" } } }, "description": "Customer-facing measured conversation insights. Missing data remains unavailable. Recording positions only refer to audio that was recorded under the conversation recording and consent settings." }, "CallTranscriptDisplayEntry": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "message" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string" }, "interrupted": { "type": "boolean" }, "ended_at": { "type": "string", "format": "date-time" }, "attachments": { "type": "array", "items": { "type": "object" } }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "kind", "role", "text" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "tool_pair" }, "call": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "tool_call" }, "name": { "type": "string" }, "call_id": { "type": "string" }, "args": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "kind", "name", "call_id", "args" ] }, "output": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "tool_output" }, "name": { "type": "string" }, "call_id": { "type": "string" }, "output": { "type": "string" }, "is_error": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "kind", "name", "call_id", "output", "is_error" ] } }, "required": [ "kind", "call" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "tool_output" }, "name": { "type": "string" }, "call_id": { "type": "string" }, "output": { "type": "string" }, "is_error": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "kind", "name", "call_id", "output", "is_error" ] } ] }, "SupportTicketPerson": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Anna" }, "avatar_url": { "type": [ "string", "null" ], "description": "Always null in the public API." } } }, "SupportTicket": { "type": "object", "required": [ "reference", "subject", "created_at", "status", "priority", "assignee", "last_activity_at", "unread_count" ], "properties": { "reference": { "type": "string", "pattern": "^SUP-[A-F0-9]{12}$", "example": "SUP-4BC693C5FD56" }, "subject": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": [ "string", "null" ], "enum": [ "open", "on_hold", "resolved", null ], "description": "Live status; null when it could not be loaded." }, "priority": { "type": [ "string", "null" ], "enum": [ "urgent", "high", "medium", "low", null ] }, "assignee": { "oneOf": [ { "$ref": "#/components/schemas/SupportTicketPerson" }, { "type": "null" } ], "description": "Support team member handling the request." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "unread_count": { "type": "integer", "minimum": 0, "description": "Replies from the support team you have not read in the app yet." } } }, "SupportTicketMessage": { "type": "object", "required": [ "id", "author", "content", "created_at" ], "properties": { "id": { "type": "string" }, "author": { "type": "string", "enum": [ "you", "support" ] }, "author_name": { "type": [ "string", "null" ] }, "author_avatar_url": { "type": [ "string", "null" ], "description": "Always null in the public API." }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SupportTicketDetail": { "allOf": [ { "$ref": "#/components/schemas/SupportTicket" }, { "type": "object", "required": [ "message", "messages" ], "properties": { "message": { "type": "string", "description": "Your original request." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicketMessage" } } } } ] }, "SupportTicketReplyInput": { "type": "object", "required": [ "message", "client_message_id" ], "additionalProperties": false, "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "client_message_id": { "type": "string", "format": "uuid", "description": "Unique UUID for this reply." } } }, "PhoneNumberVerification": { "type": "object", "description": "A regulatory verification case for one country, number type and optional area code.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "pending_review", "in_review", "provisionally_approved", "approved", "rejected", "failed" ], "description": "`draft`: not submitted yet. `pending_review` / `in_review`: the regulatory review is running. `provisionally_approved`: numbers can already be bought while the final review finishes. `approved`: verified — numbers of this country and type can be bought. `rejected`: read `rejection_reason`, correct the details and resubmit. `failed`: the submission stopped (e.g. at the automated document check); read `rejection_reason`, correct and resubmit." }, "country_iso": { "type": "string", "example": "DE" }, "number_type": { "type": "string", "enum": [ "local", "mobile", "national", "toll_free" ] }, "end_user_type": { "type": "string", "enum": [ "business", "individual" ] }, "prefix": { "type": [ "string", "null" ], "description": "Area code the case covers, in international format (e.g. `+497274`)." }, "friendly_name": { "type": [ "string", "null" ] }, "email": { "type": "string", "description": "Contact email for review updates." }, "user_id": { "type": "string", "format": "uuid", "description": "Workspace member who submitted the case." }, "rejection_reason": { "type": [ "string", "null" ], "description": "Why the case was rejected or failed." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "KnowledgeDocumentBulkDeleteInput": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" }, "description": "IDs of the documents to delete (1–200), as returned by `GET /knowledge-bases/{id}/documents`. Duplicates are ignored." } } }, "KnowledgeDocumentBulkDeleteResult": { "type": "object", "required": [ "deleted_ids", "not_found_ids" ], "properties": { "deleted_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Documents that were deleted." }, "not_found_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs that do not exist in this knowledge base or were already deleted." } } } } } }