{ "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 minutes ledger of the key owner." }, { "name": "Automations", "description": "Native workspace automations — list, create, update, trigger. Plan gate: automation_platform." }, { "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 the custom_dashboards plan feature." }, { "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." } ], "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}/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. **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. **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." } } } } } } }, "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. 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. Scope: knowledge:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 2000 }, "table_query": { "$ref": "#/components/schemas/KnowledgeTableQuery" } }, "anyOf": [ { "required": [ "query" ] }, { "required": [ "table_query" ] } ] }, "example": { "query": "What is the price for AX-100?" } } } }, "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 key owner plus a summary of the 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/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 latest payable plan 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 and remain available only through the validated plan page. 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. **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": -3.4, "note": "Call usage", "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": 1000, "note": "Plan payment", "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, or Synthflow. 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" }, "provider": { "type": "string", "enum": [ "retell", "vapi", "synthflow" ] }, "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." } } }, { "type": "object", "required": [ "action", "provider", "source_api_key", "selected_assistant_ids" ], "properties": { "action": { "type": "string", "const": "import" }, "provider": { "type": "string", "enum": [ "retell", "vapi", "synthflow" ] }, "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" ] }, "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. **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`. **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. **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. **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" }, "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).", "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" ], "default": "standard" }, "description": "Native conversation variant when mode is realtime. 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 Full Duplex voice preview", "description": "Download an existing native voice recording. Use the voice ID returned by the compatible Realtime voice catalog. Requires voices:read and current workspace access to Full Duplex. This endpoint does not synthesize new speech. Preview paths returned by the catalog are relative to the API origin and require the same 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" ], "default": "full_duplex" } } ], "responses": { "200": { "description": "Existing native voice recording.", "content": { "audio/wav": { "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`.", "tags": [ "History" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "call", "avatar", "email", "live_chat", "whatsapp_voice", "whatsapp", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x" ] }, "description": "Filter by conversation type. `avatar` = web voice with virtual avatar; `live_chat` = widget text chat; messaging platforms 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`.", "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`.", "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. 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).", "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": "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).", "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). Requires plan feature `live_monitoring`. **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).", "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).", "tags": [ "History" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "kind", "ids" ], "properties": { "action": { "type": "string", "enum": [ "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 limit `max_campaigns` 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` (see src/lib/leads/status.ts). **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": { "$ref": "#/components/schemas/Lead" } }, "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", "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": { "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/Lead" } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "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/Lead" }, { "type": "object", "properties": { "system_variables": { "type": "object", "readOnly": true, "additionalProperties": { "type": "string" } } } } ] } } } } } }, "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": { "$ref": "#/components/schemas/Lead" } } } } } }, "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`; 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 Stripe 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" } } } }, "/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": { "type": "object", "additionalProperties": true } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RequestProtectionUnavailable" } } }, "post": { "operationId": "submitPhoneNumberVerification", "summary": "Submit regulatory number verification", "description": "Submit a regulatory bundle case (address + end-user attributes, optional base64 attachments). Requirements and document types are country-specific — discover eligible countries via `GET /phone-numbers/verifications/catalog` and load fields from the session regulations endpoint. 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": { "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" }, "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": "Returns all countries/number types where a regulatory bundle is required, including countries not currently enabled for marketplace purchase. Use before submitting a verification case. Document and end-user field requirements are loaded per country from the live regulation catalog (session `GET /api/telephony/verification/regulations`). **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 } } } } } } } } }, "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. **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" }, "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/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" ], "default": "local" } }, { "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: Stripe cancels at period end, the number stays active until then (`release_scheduled_at`), then the provider number is returned and status becomes `released`. Complimentary plan numbers and unpaid purchases are released immediately. Customer-provided numbers are deleted together with their dispatch rule. **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 personal Loop call", "description": "Read a Loop call you own or participated in, including available recordings and playback links valid for one hour. 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" } } ], "responses": { "200": { "description": "Personal Loop call and 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" } } }, "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 personal Loop calls", "description": "Lists the authenticated member's Loop recents. This history is separate from omnichannel assistant history. Usage is returned in minutes and credits. Requires `loop:read`.", "tags": [ "Famulor Loop" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Paginated personal 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" } } } }, "/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." } ], "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/{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." } ], "get": { "operationId": "listKnowledgeDocumentChunks", "summary": "List document chunks", "description": "Lists the exact searchable chunks produced for one knowledge-base document, in source order. 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": "Uploads a custom picture shown in the product UI instead of the default orb. Send JSON `{ \"url\": \"https://…/avatar.png\" }` (downloaded server-side), `{ \"data_base64\": \"…\", \"content_type\": \"image/png\" }`, or multipart/form-data with a `file` field. Formats PNG/JPEG/WebP, max 1 MB incoming (server compresses to ≤512×512 / ~400 KB). 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" ] } } } ] } }, "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 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/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": { "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. **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" } } } }, "/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 SendGrid 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. **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`.", "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`.", "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`.", "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`.", "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`.", "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 an admin-level credential; plan gate: `calendar_integrations`.\n\n**Required scope:** `integrations:write` (keys without scope restrictions have full access).", "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`.\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.\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 the `calendar_integrations` plan feature and an admin-level credential.\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; plan gate: `calendar_integrations`.\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`), or via the public page API — this management API is read + reschedule + cancel only. 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" ] }, "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" } } } }, "/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); 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." } } }, "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 compatible with this engine mode." }, { "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: receptionist, lead_qualifier, appointment, support, screener, survey, sales, personal_assistant, callback_intake, property_lead, service_intake, feedback_survey, guest_concierge, avatar_concierge." }, { "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 leads, completed leads, calls made, total call duration, total call cost). **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, "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 `automation_platform`.", "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. Optional `tags` (`string[]`). Binding `trigger.assistant_id` on an active `call.completed` automation updates the assistant webhook delivery mode. Graph actions may include Beta `composio.execute` (Execute app tool via a workspace Apps connection); triggers may use Beta `composio.event` (App event). **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). 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). Apps connections (`provider=composio`) are normally created via the connect-link OAuth flow (`POST /api/oauth/composio/start`); stored fields include `connected_account_id` and `toolkit` (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`. Plan-gate: `plans.simulations`.", "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`. Plan-gate: `plans.simulations`.", "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`. Plan-gate: `plans.simulations`.", "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 simulation synchronously (up to ~60s). **Required scope:** `assistants: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. **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" } } } } } }, "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.", "tags": [ "Voices" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "consent" ], "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." } } } } } }, "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" } } } }, "/voices/clone/capability": { "get": { "operationId": "getVoiceCloneCapability", "summary": "Check voice cloning capability", "description": "Returns whether voice cloning is currently available to the workspace and its customer-facing slot capacity. **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`. Plan-gate: `plans.web_widget`. `allowed_origins` is optional (defaults to `[]`); an empty allowlist blocks third-party hosts until origins are added. If `theme.logo_url` is omitted and the selected assistant has a portrait, that portrait becomes the widget's initial header logo; it can be replaced or removed later. 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 Telegram / Slack / Messenger bots. Plan flags: `telegram_channel`, `slack_channel`, `messenger_channel`. **Required scope:** `assistants:read`.", "tags": [ "Messaging" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp" ] } } ], "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 a bot. Platform-specific credential fields required. Conversation settings optional (`response_delay_sec` 0–30 default 5, `inactivity_timeout_min` default 30, `allow_retrigger`, `conversation_ended_webhook_url`). **Required scope:** `assistants:write`.", "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 } } } }, "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; 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. **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`. Plan flag `whatsapp_channel` required.", "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`. Plan flag `whatsapp_voice` required.", "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. **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`). Gated by the plan's `max_workspaces` limit (`-1` = unlimited, `0` = feature off) plus the `extra_workspaces` capacity add-on, evaluated 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" } } } } }, "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." } } } } } }, "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", "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" ], "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" } } }, "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" ] } } } } } }, "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" } } }, "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" ], "description": "Stable, machine-readable error code." }, "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" ], "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." } } }, "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": 23, "propertyNames": { "enum": [ "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 }, "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." }, "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" }, "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." }, "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)." }, "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)." }, "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." }, "metadata": { "type": "object", "additionalProperties": true }, "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." }, "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." }, "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" }, "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 (plan-gated `ai_qa_scorecards`). `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 a US or Global workspace region, workspace Beta features and available compatible defaults; it is unavailable in EU; 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" }, "revision": { "type": "integer", "minimum": 1, "description": "Monotone optimistic concurrency revision." }, "usage_count": { "type": "integer", "minimum": 0, "description": "Number of assistants currently assigned to this tool." }, "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." }, "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." }, "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" }, "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` plan toggle. 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." }, "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)." }, "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)." }, "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." }, "metadata": { "type": "object", "additionalProperties": true }, "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." }, "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." }, "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" }, "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." }, "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 (plan-gated `ai_qa_scorecards`). `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`)." }, "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 a US or Global workspace region, workspace Beta features and available compatible defaults; it is unavailable in EU; extra credits may apply. Its reasoning model is managed centrally. Existing assistants use standard." } } }, "AnalysisConfig": { "type": "object", "description": "Post-call analysis configuration. When set (non-empty), the LLM judge evaluates each finished transcript and writes the result to `calls.analysis` (plus the denormalized `calls.sentiment`/`calls.success` filter columns). All fields are optional.", "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": "Structured data to extract from each call.", "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`." }, "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" }, "description": "Allowed values (only for `type: enum`)." }, "required": { "type": "boolean", "default": false } } } } } }, "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" ], "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "available", "payment_required", "disabled", "not_included" ] }, "included_slots": { "type": "integer", "description": "Included cloned-voice capacity. -1 means unlimited." }, "additional_slots": { "type": "integer", "minimum": 0 }, "total_slots": { "type": "integer", "description": "Total cloned-voice capacity. -1 means unlimited." }, "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." } } } } }, "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": [ "call", "avatar", "email", "live_chat", "whatsapp_voice", "whatsapp", "telegram", "slack", "messenger", "teams", "discord", "gchat", "x" ] }, "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 preview; null for calls." }, "summary": { "type": [ "string", "null" ], "description": "Call summary or email subject/body preview." }, "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." } } }, "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" } } }, "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" } } } }, "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." } } } ] }, "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": "Derived display status (grouped from `status` + `next_attempt_at`)." }, "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" ] }, "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": [ "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 Stripe period end. 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 Stripe phone 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." } }, "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" }, "purchase_token": { "type": "string", "description": "The short-lived token returned with the exact number by `GET /phone-numbers/available`. Required when the purchase is billed through a reseller's connected Stripe account; optional for legacy platform-root purchases." }, "assistant_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optionally assign an assistant right away." } } }, "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" }, "knowledge_base_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string", "description": "`text` or `url`." }, "source_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`ready` once chunking + embeddings finished, `error` if ingestion failed." }, "error_message": { "type": [ "string", "null" ] }, "chunk_count": { "type": "integer" }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledge_base_id", "name", "source_type", "status", "chunk_count", "created_at", "updated_at" ] }, "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": "Path prefixes crawling is restricted to; empty = whole host." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes to skip while crawling. Max 200 per source, 500 per knowledge base." }, "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).", "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 crawled in the last run (new/changed pages)." }, "credits_spent": { "type": "number", "description": "Credits charged in the last run." }, "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": "Path prefixes announced as disallowed by robots.txt. 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 path prefixes to restrict crawling (e.g. [\"/docs\"]). Empty = whole host." }, "exclude_paths": { "type": "array", "items": { "type": "string" }, "description": "Optional path prefixes to skip (e.g. [\"/admin\"]). Max 200 per source, 500 per knowledge base." }, "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." } } }, "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" } }, "exclude_paths": { "type": "array", "items": { "type": "string" } }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 500 }, "auto_sync": { "type": "boolean" }, "sync_interval_hours": { "type": "integer", "minimum": 1 } } }, "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 fetched and (re-)indexed this run." }, "pages_skipped": { "type": "integer", "description": "Pages skipped because their content was unchanged (content hash match)." }, "credits_spent": { "type": "number", "description": "Credits charged this run (per crawled page)." }, "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).", "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." } } }, "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 } } }, "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", "description": "Minutes credited (positive) or debited (negative)." }, "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 or Voicemail recording. A generic Call recording 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." } }, "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." }, "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" } } }, "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" ], "description": "Immutable after creation." }, "config": { "type": "object", "description": "Provider-specific configuration. calcom: `{ api_key_encrypted, event_type_id, timezone? }`. 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." }, "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" ] }, "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." }, "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\" asked on the public booking page, in display order. The system fields Name and Email are always collected and always required, and are not listed here.", "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" } } }, "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\" asked on the public booking page, in display order. The system fields Name and Email are always collected and always required; use phone_required for the system Phone field.", "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." } } }, "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" ], "description": "web = public booking page, call = booked by an assistant mid-call, api = created programmatically." }, "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" ] }, "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 model may be selected. User overrides cannot bypass this list.", "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). Presets include receptionist, lead_qualifier, …; 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.", "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 — ID from GET /api/stripe-connections (workspace Stripe Secret Key connection from 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." } }, "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" }, "calls_made": { "type": "integer", "description": "Number of calls placed for this campaign (metadata.campaign_id)." }, "total_duration_sec": { "type": "integer" }, "currency": { "type": "string", "description": "Canonical currency of the aggregates — always EUR.", "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 } }, "required": [ "campaign_id", "total_leads", "completed_leads", "calls_made", "total_duration_sec", "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 plans.automation_platform is enabled for this workspace." }, "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." } } }, "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" ], "description": "Floating launcher icon. Default milian (mesh 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" ] } } }, "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": [ "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp" ] }, "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 }, "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)." } } }, "MessagingConnectorCreate": { "type": "object", "required": [ "platform", "name", "assistant_id" ], "properties": { "platform": { "type": "string", "enum": [ "telegram", "slack", "messenger", "teams", "discord", "gchat", "x", "whatsapp" ] }, "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 } } }, "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 }, "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." } } }, "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", "composio.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. Plan-gated via `ai_qa_scorecards`. 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", "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 } } }, "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" } } } } } }