> ## Documentation Index > Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an assistant > Creates an assistant. 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). Prompt templates are listed via `GET /prompt-templates` and applied by copying into `system_prompt` / `first_message`. Model fields are validated against the platform model catalog; the plan limit `max_assistants` is enforced. Non-trivial flows may require the workspace `flow_builder` plan toggle. **Required scope:** `assistants:write` (keys without scope restrictions have full access). ## OpenAPI ````yaml /api-reference/openapi.json post /assistants openapi: 3.1.0 info: title: OurAiCalling API version: 1.0.0 description: >- REST API for OurAiCalling. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token. Every 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. Everything documented here is also exposed as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials and permission model. 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: 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: 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 the customers of your white-label workspace on their behalf — list, register, mint access tokens, log in, log out, and transfer credits. Available to reseller workspaces with white-label access, and to platform admins (scoped to direct platform customers). Requires `platform:read` / `platform:write`. - name: API Keys description: >- Self-service API keys for the calling workspace. A key can only mint further keys with a scope subset of its own. - name: SMS description: Outbound SMS from workspace phone numbers. paths: /assistants: post: tags: - Assistants summary: Create an assistant description: >- Creates an assistant. 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). Prompt templates are listed via `GET /prompt-templates` and applied by copying into `system_prompt` / `first_message`. Model fields are validated against the platform model catalog; the plan limit `max_assistants` is enforced. Non-trivial flows may require the workspace `flow_builder` plan toggle. **Required scope:** `assistants:write` (keys without scope restrictions have full access). operationId: createAssistant requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssistantInput' examples: 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_model: null realtime_voice: null llm_provider: null llm_model: null llm_temperature: 0.7 stt_provider: deepgram stt_model: nova-3 stt_language: en tts_provider: elevenlabs tts_model: eleven_turbo_v2_5 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' components: schemas: 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 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 mode: type: string enum: - pipeline - realtime - half_cascade realtime_provider: type: - string - 'null' realtime_model: type: - string - 'null' realtime_voice: type: - string - 'null' llm_provider: type: - string - 'null' enum: - openai - azure - google - groq - anthropic - null llm_model: type: - string - 'null' half_cascade_provider: type: - string - 'null' half_cascade_model: type: - string - 'null' llm_temperature: type: number stt_provider: type: string enum: - deepgram - openai - google - azure stt_model: type: string stt_language: type: string tts_provider: type: string enum: - cartesia - elevenlabs - openai - google - azure tts_model: type: - string - 'null' tts_voice: type: - string - 'null' tts_speed: type: number tts_emotion: type: array items: type: string description: >- Cartesia dynamic-emotions toggle. Send [] to disable it or any non-empty array to enable every supported Cartesia emotion. 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 allow_interruptions: type: boolean min_interruption_duration_ms: type: integer noise_cancellation: type: string enum: - bvc - bvc_telephony - none preemptive_generation: type: boolean 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 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 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 idle_max_rounds: type: integer fallback_config: type: object additionalProperties: true 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. 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` = shared across assistants; `assistant` = private to this assistant; `both` = shared identity + per-assistant history. memory_read_channels: type: array uniqueItems: true items: $ref: '#/components/schemas/OperationalMemoryChannel' description: >- Per-assistant read allowlist intersected with workspace policy. Send [] to disable reads. memory_write_channels: type: array uniqueItems: true items: $ref: '#/components/schemas/OperationalMemoryChannel' 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, 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). 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 webhook enrichment > system variables > default_value). 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: >- Built-in tool configurations (also accepted as `tools` for compatibility). 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 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 mode: type: string enum: - pipeline - realtime - half_cascade description: >- Engine mode. `pipeline` = STT → LLM → TTS, `realtime` = speech-to-speech, `half_cascade` = realtime input + separate TTS output. realtime_provider: type: - string - 'null' description: >- Realtime override/voice provider. `realtime_model=null` follows the owner/platform default. realtime_model: type: - string - 'null' description: >- Fallbacks & Guardrails realtime model override from the compatible catalog. realtime_voice: type: - string - 'null' description: >- Realtime voice (e.g. `marin`). Only for mode `realtime`/`half_cascade`. llm_provider: type: - string - 'null' enum: - openai - azure - google - groq - anthropic - null llm_model: type: - string - 'null' description: >- Fallbacks & Guardrails pipeline model override. Null follows the owner/platform default. half_cascade_provider: type: - string - 'null' description: Fallbacks & Guardrails half-cascade input-model provider override. half_cascade_model: type: - string - 'null' description: >- Fallbacks & Guardrails text-capable realtime model override for half-cascade. llm_temperature: type: number stt_provider: type: string enum: - deepgram - openai - google - azure stt_model: type: string stt_language: type: string description: Primary STT language (ISO-639-1). tts_provider: type: string enum: - cartesia - elevenlabs - openai - google - azure tts_model: type: - string - 'null' tts_voice: type: - string - 'null' tts_speed: type: number tts_emotion: type: array items: type: string description: >- Cartesia dynamic-emotions toggle. An empty array disables emotion tags; any non-empty array is normalized to the complete supported Cartesia emotion list. Text chat never uses TTS or provider-specific speech tags. 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 allow_interruptions: type: boolean min_interruption_duration_ms: type: integer noise_cancellation: type: string enum: - bvc - bvc_telephony - none preemptive_generation: type: boolean 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. Default: Hi, how can I help you? 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 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 the assistant asks the caller to repeat (LiveKit Agents 1.6.8+). 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. 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 fallback_config: type: object additionalProperties: true description: Provider fallback chains per slot (llm/stt/tts); `{}` = none. 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. 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` = shared across all assistants, `assistant` = private to this assistant, `both` = shared identity plus per-assistant history (default for new assistants). memory_read_channels: type: array uniqueItems: true items: $ref: '#/components/schemas/OperationalMemoryChannel' 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/OperationalMemoryChannel' 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, 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). 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 webhook enrichment > system variables > default_value). 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: >- Built-in tool configurations (also accepted as `tools` for compatibility). required: - id - name - is_active - system_prompt - mode - created_at - updated_at OperationalMemoryChannel: type: string description: >- A currently operational memory channel. Web is deliberately excluded until signed-in browser users have a server-verified identity boundary. enum: - voice - sms - whatsapp - email - telegram - slack - messenger - teams - discord - gchat - x 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 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. 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: Where values typically come from (informational). Default `manual`. BuiltinTool: type: object required: - type description: >- One built-in tool configuration. `type` selects the tool; the remaining fields depend on the type. Reusable standalone built-ins support end_call, call_transfer, warm_call_transfer, send_sms, send_email, check_business_hours, schedule_callback, collect_payment_card, and set_variable. Keypad collection is configured in Flow Builder; 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 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. 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 additionalProperties: true example: type: send_sms description: Text the caller a booking confirmation. sms_to_mode: caller 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 - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - internal_error description: Stable, machine-readable error code. message: type: string description: Human-readable description of the error. 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 API key lacks the required scope, or the plan does not allow this action. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: forbidden message: This API key is missing the required scope "assistants:write". 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_...`). Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `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. ````