> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # List assistants > Paginated list of assistants in your workspace, newest first. **Required scope:** `assistants:read` (keys without scope restrictions have full access). ## OpenAPI ````yaml /api-reference/openapi.json get /assistants 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. 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. REST 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. The same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access. servers: - url: https://app.famulor.io/api/v1 description: Hosted platform. - url: https://{domain}/api/v1 description: White-label tenant domain — same paths, tenant branding. variables: domain: default: app.famulor.io description: Your white-label tenant domain. security: - bearerAuth: [] tags: - name: Account description: Self-inspection of the calling credential. - name: Migrations description: Preview and import data from supported legacy platforms. - name: Assistants description: Create and manage voice assistants. - name: Tools description: >- Reusable tools (HTTP APIs and external MCP servers) assistants can call mid-conversation. - name: Voices description: Browse the text-to-speech voice library. - name: Calls description: Start outbound calls and read call history, transcripts and recordings. - name: History description: Unified conversation history across calls, messaging and assistant emails. - name: Campaigns description: Outbound calling campaigns with a compliant power dialer. - name: Leads description: Manage Audience contacts across campaigns, channels and Call QA metrics. - name: Segments description: >- Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment. - name: Suppression description: Cross-channel marketing opt-outs and active workspace suppression records. - name: Callbacks description: >- Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email. - name: Phone Numbers description: Marketplace numbers and customer-provided numbers. - name: Famulor Loop description: >- Personal business-phone access, directory, presence, devices, and Loop call recents. - name: SIP Trunks description: Bring your own SIP provider and numbers. - name: Carrier Connections description: Connect a supported carrier account and import its existing phone numbers. - name: Knowledge Bases description: RAG knowledge bases and documents for assistants. - name: Settings description: Workspace-level settings such as caller-memory defaults. - name: Billing description: Balance and transaction ledger of the API key's workspace. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan. - name: Milian Missions description: Recurring jobs that Milian runs unattended on schedule. - name: Integrations description: >- Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling. - name: Bookings description: >- Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce. - name: Dashboards description: >- Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires Custom dashboards in the workspace plan. - name: Catalog description: >- Read-only platform catalogs — available models, supported assistant languages, and prompt templates. - name: Simulations description: Assistant simulation tests (plan-gated). - name: Versions description: Assistant configuration version history. - name: Caller IDs description: Outbound caller ID verification. - name: Widgets description: Web widget connectors. - name: Messaging description: >- Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks. - name: QA description: Cohort AI Quality Assurance runs over call transcripts. - name: White Label description: >- Manage white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility. - name: API Keys description: >- Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own. - name: Workspaces description: >- List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace. - name: SMS description: Outbound SMS from workspace phone numbers. - name: Milian description: >- Ask Milian, the AI co-worker in your workspace, and start voice sessions with it. - name: Translation description: >- Live translation sessions that interpret a conversation between two languages. paths: /assistants: get: tags: - Assistants summary: List assistants description: >- Paginated list of assistants in your workspace, newest first. **Required scope:** `assistants:read` (keys without scope restrictions have full access). operationId: listAssistants 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' components: 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. schemas: Assistant: type: object description: >- A voice assistant configuration. Nullable model overrides are independent per engine: pipeline uses `llm_*`, realtime uses `realtime_*`, and half-cascade uses `half_cascade_*` for its text-capable realtime input plus `tts_*` for output. properties: id: type: string format: uuid name: type: string tags: type: array items: type: string maxLength: 40 maxItems: 20 description: >- Free-form workspace tags for filtering assistants. Case-insensitive unique; original spelling is kept. is_active: type: boolean description: Disabled assistants cannot receive or place calls. compliance_status: type: string enum: - clear - scanning - blocked - review_requested - scan_error description: >- Server-managed result of the latest prompt and greeting compliance workflow. compliance_blocked_at: type: - string - 'null' format: date-time description: >- When the assistant was blocked. Null when it is not compliance-blocked. compliance_last_scan_at: type: - string - 'null' format: date-time compliance_last_score: type: - integer - 'null' minimum: 0 maximum: 100 demo_enabled: type: boolean readOnly: true description: >- Whether the assistant's public demo link is on. The link is managed in the dashboard and is not returned by the API. demo_expires_at: type: - string - 'null' format: date-time readOnly: true description: >- When the public demo link stops working; null means it does not expire. created_by: type: - string - 'null' format: uuid system_prompt: type: string response_by_channel: $ref: '#/components/schemas/ResponseByChannel' mode: type: string enum: - pipeline - realtime - half_cascade - translation description: >- Assistant engine: Pipeline, Realtime, Half-cascade, or Translate for a two-person interpreter room. The selected mode must be included in the workspace's current plan. realtime_provider: type: - string - 'null' description: >- Realtime override/voice provider. `realtime_model=null` follows the owner/platform default. realtime_model: type: - string - 'null' description: >- Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement. realtime_voice: type: - string - 'null' description: >- Compatible native conversation voice. Use a neutral ID returned by the native voice library. Available for Realtime; the chosen variant controls compatibility. llm_provider: type: - string - 'null' enum: - openai - azure - google - groq - anthropic - null description: >- Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement. llm_model: type: - string - 'null' description: >- Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement. half_cascade_provider: type: - string - 'null' description: >- Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement. half_cascade_model: type: - string - 'null' description: >- Requires Fallbacks & Guardrails for this workspace. Select a compatible value from the model catalog; null follows workspace then platform defaults. Omitted from responses without this entitlement. llm_temperature: type: number stt_provider: type: string enum: - deepgram - openai - google - azure - soniox - gladia - assemblyai - cartesia - speechmatics - xai - elevenlabs readOnly: true description: >- Platform-managed speech recognition provider. Returned for reference; assistant writes cannot override it. stt_language: type: string description: Primary STT language (ISO-639-1). stt_keyterms: type: array maxItems: 100 items: type: string maxLength: 100 description: >- Speech-recognition glossary for customer, product, and proper names. Plan-gated. stt_keyterm_detection_enabled: type: boolean description: >- Beta: automatically detect additional call-local keyterms. Detected terms are not persisted. tts_provider: type: string enum: - cartesia - elevenlabs - openai - google - azure - fishaudio - deepgram - inworld - rime - xai tts_voice: type: - string - 'null' description: >- Pipeline or Half-Cascade speech voice. For Full Duplex, retained only for a Pipeline fallback; greetings, consent and tool announcements use realtime_voice. Uploaded greeting audio retains its recorded voice. tts_speed: type: number tts_emotion: type: array items: type: string example: - calm description: >- Legacy array field controlling Dynamic emotions (Expressive Mode) for compatible pipeline and half-cascade voices. Send ["calm"] to enable it or an empty array to disable it. On create, omitting the field enables it when supported. Realtime speech models handle expression natively, and text chat never uses voice synthesis. tts_style_prompt: type: - string - 'null' description: >- Optional free-text speaking-style instructions for compatible TTS models. Null uses the model default. elevenlabs_stability: type: - number - 'null' minimum: 0 maximum: 1 description: Voice stability override. Null uses the voice-provider default. elevenlabs_similarity: type: - number - 'null' minimum: 0 maximum: 1 description: Voice similarity override. Null uses the voice-provider default. elevenlabs_style: type: - number - 'null' minimum: 0 maximum: 1 description: >- Voice-style exaggeration override. Null uses the voice-provider default. elevenlabs_speaker_boost: type: - boolean - 'null' description: Speaker-boost override. Null uses the voice-provider default. affective_dialog: type: boolean description: >- Realtime mode with a Google realtime model only: match the caller's tone with warmer, more expressive speech. turn_detection: type: string enum: - multilingual_model - english_model - vad - stt vad_min_silence_ms: type: integer vad_threshold: type: - number - 'null' minimum: 0.1 maximum: 0.9 description: >- Voice-detection threshold. Null uses the effective engine default: 0.50 for pipeline and adaptive voice detection, 0.50 for web server VAD, and 0.70 for phone server VAD. This detects speech; it does not filter audio. allow_interruptions: type: boolean min_interruption_duration_ms: type: integer response_timing: type: string enum: - snappy - balanced - patient description: >- How quickly the assistant answers once the caller pauses: `snappy` answers right away, `balanced` leaves a short pause, `patient` waits longer for callers who pause mid-sentence. Applies to pipeline mode and adaptive realtime turn handling. default: balanced min_interruption_words: type: integer minimum: 0 maximum: 10 description: >- Pipeline mode only: ignore barge-ins shorter than this many words, so back-channel sounds like “mhm” don't interrupt the assistant. 0 turns it off; larger values are capped at 10. default: 0 noise_cancellation: type: string enum: - bvc - bvc_telephony - none preemptive_generation: type: boolean description: >- Begin response generation before turn confirmation. Effective in pipeline mode only. resume_false_interruption: type: boolean description: >- Resume interrupted output when an apparent interruption produces no transcript during the two-second false-interruption window. Effective in pipeline mode and adaptive realtime turn handling, and only while interruptions are enabled. max_tool_steps: type: integer avatar_url: type: - string - 'null' format: uri description: >- Public URL of the custom assistant picture. Null = default mesh orb in the product UI. Set via POST/DELETE /assistants/{id}/avatar, not PATCH. first_message: type: - string - 'null' greeting_mode: type: string enum: - agent_speaks_first - user_speaks_first greeting_allow_interruptions: type: boolean description: >- When true, the caller may barge in during the opening greeting (first message / audio / silence fallback). Default false = play greeting uninterrupted. Separate from allow_interruptions (rest of the call). ai_speaks_after_silence: type: boolean description: >- When greeting_mode is user_speaks_first: after ai_entry_timeout_sec of initial silence, the assistant speaks (static or dynamic). Default false. silence_greeting_mode: type: string enum: - static - dynamic description: >- static = silence_greeting_message; dynamic = LLM improvises from the system prompt. silence_greeting_message: type: string description: >- Fixed opening line when ai_speaks_after_silence and silence_greeting_mode=static. Leave empty ("") to let the assistant speak the platform default in its configured language. ai_entry_timeout_sec: type: integer minimum: 1 maximum: 20 description: Seconds to wait before the silence greeting (1–20). Default 10. pre_call: type: object description: >- iOS/Android Call Screen Handling. When enabled, the agent identifies itself to call-screening services, then waits for a human. Mirrored into `flow_json.pre_call` when a flow exists. properties: enabled: type: boolean default: false agent_name: type: - string - 'null' company_name: type: - string - 'null' reason: type: - string - 'null' flow_json: type: - object - 'null' description: >- Flow-builder graph (Flow JSON v1: `{ version: 1, nodes: [...], edges: [...] }`). `null` = Single prompt agent (system_prompt + greeting). Non-null = Conversational flow. Trivial Start→Agent→End skeletons still behave as prompt-only for global transfer tools until the graph is non-trivial or includes Transfer nodes. recording_enabled: type: boolean description: >- Whether audio recording is enabled for calls handled by this assistant. In PATCH and PUT requests, omitting this field leaves the existing setting unchanged. Saving an explicit boolean (`true` or `false`) updates the setting. Recording calls is independent of Loop recording and voicemail recording; see `/assistants/conversation-quality#consent` for caller consent rules and `/billing/minutes#call-recording` for recording billing. retranscribe_enabled: type: boolean description: >- Enhanced transcription: after the call, the recording is transcribed again with a higher-accuracy engine and shown next to the live transcript. Only takes effect while `recording_enabled` is on. Billed in credits per recorded minute. card_collect_enabled: type: boolean description: >- Allows secure payment card collection (the Collect payment card tool and Flow Collect steps of type `credit_card`). Also needs a connected payment account. Switching it on requires a plan that includes payment card collection; otherwise the request fails with HTTP 403. max_call_duration_sec: type: - integer - 'null' minimum: 60 maximum: 1800 description: >- Maximum call duration in seconds (60–1800). null = unlimited (budget cap still applies). inbound_ringing_timeout_sec: type: integer minimum: 30 maximum: 120 description: >- How long inbound callers hear ringing before the call times out (30–120 s, default 60). If every concurrent line is busy, callers keep ringing within this time until a line frees up. outbound_ringing_timeout_sec: type: integer minimum: 15 maximum: 80 description: >- How long outbound SIP/WhatsApp calls ring before no-answer (15–80 s, default 45). amd_enabled: type: boolean default: false description: >- Answering machine detection on direct outbound calls (dashboard, API, automations, callbacks). New assistants default to `false`: the assistant greets as soon as the call is answered and mailboxes are not detected. Campaign calls use the campaign's `amd_enabled`. voicemail_enabled: type: boolean default: false description: >- What a direct outbound call does at a detected mailbox: `true` = speak `voicemail_message`, then hang up; `false` = hang up without a message. Takes effect while `amd_enabled` is on. Campaign calls use the campaign's voicemail settings. voicemail_message: type: string nullable: true description: >- Message spoken onto a detected mailbox when `voicemail_enabled` is `true`; supports `{{variables}}`. `null` or empty = the greeting / first message is used. idle_timeout_sec: type: integer transcription_timeout_sec: type: - number - 'null' minimum: 1 maximum: 30 description: >- Seconds after speech is detected with no transcript before the assistant asks the caller to repeat. null disables. Distinct from idle_timeout_sec. knowledgebase_id: type: - string - 'null' format: uuid description: Attached knowledge base (RAG). knowledge_gap_mode: type: string enum: - 'off' - questions_only - draft_for_review - tentative_live default: draft_for_review description: >- Beta behavior after a successful knowledge-base search has no relevant result. webhook_url: type: - string - 'null' description: >- Agent-level webhook that receives `call.completed` with transcript, duration, input variables and post-call analysis. webhook_timeout_sec: type: integer minimum: 1 maximum: 30 default: 5 description: Max seconds to wait for the agent-level webhook response. webhook_retries: type: integer minimum: 0 maximum: 5 default: 2 description: >- Extra delivery attempts after the first failure. Total tries = 1 + retries. webhook_delivery_mode: type: string enum: - none - custom - automation description: >- none = do not deliver; custom = POST the assistant webhook URL after the call; automation = deliver through the bound automation. automation_id: type: - string - 'null' format: uuid description: Bound automation when webhook delivery is automation. notification_settings: type: object additionalProperties: type: object properties: email: type: boolean push: type: boolean sms: type: boolean description: Reserved for a future channel. example: call: email: false whatsapp: push: false description: >- Activity notifications for this assistant, keyed by History channel (`call`, `avatar`, `live_chat`, `whatsapp_voice`, `whatsapp`, `telegram`, `slack`, `messenger`, `teams`, `discord`, `gchat`, `x`, `freshdesk`, `gmail`, `outlook`, `zendesk`, `servicenow`, `intercom`, `zoho_mail`, `agent_mail`, `instagram`, `zulip`, `email`; the legacy key `messaging` applies to every messaging channel). Each channel takes `email` and `push` toggles. A missing channel or toggle stays on; set it to `false` to opt out. Unknown keys are dropped. metadata: type: object additionalProperties: true outbound_phone_number_id: type: - string - 'null' format: uuid description: >- Workspace phone number this assistant calls from on outbound calls (an `id` from `GET /phone-numbers`). Several assistants can share one number. A `phone_number_id` passed when starting a call takes precedence. Null clears it. background_audio: type: object additionalProperties: true description: >- BackgroundAudioPlayer config (`ambient`, `ambient_volume`, `thinking`, `thinking_volume`). `{}` = off. Hold music is configured on the warm-transfer tool, not here. adaptive_interruptions: type: boolean realtime_turn_mode: type: string enum: - server_vad - semantic - adaptive default: server_vad description: >- Realtime turn handling: robust voice activity, semantic completion, or adaptive barge-in. Adaptive distinguishes short acknowledgements from intentional interruptions. realtime_eagerness: type: string enum: - auto - low - medium - high default: auto description: >- How quickly the assistant responds when realtime_turn_mode is semantic. long_call_memory: type: string enum: - full - recent description: >- Pipeline mode only: context strategy once a call runs long. `full` keeps the whole conversation in context; `recent` keeps the latest part in focus for faster responses on calls of 10+ minutes. default: full idle_messages: type: array items: type: string description: >- Fixed re-engagement phrases on caller inactivity; `[]` = LLM-generated. idle_max_rounds: type: integer minimum: 1 maximum: 10 description: >- Unanswered idle check-ins before the assistant says goodbye and ends the call (1–10, default 2). fallback_config: type: object additionalProperties: true description: >- Requires Fallbacks & Guardrails. Saved fallback configuration is omitted from responses without this workspace entitlement. fallbacks_enabled: type: boolean description: >- Turns on platform-managed model fallbacks, so a call continues on a backup model if a speech or language model fails. Must be a boolean. Switching it on requires Fallbacks & Guardrails; otherwise the request fails with HTTP 403. pronunciation_map: type: object additionalProperties: type: string description: 'Word → spoken-form replacements, e.g. `{"API": "A P I"}`.' tts_filter_markdown: type: boolean tts_filter_emoji: type: boolean consent_enabled: type: boolean description: >- Ask for consent at call start. What the consent covers is set by consent_covers_recording and consent_covers_memory. consent_text: type: - string - 'null' description: >- Spoken announcement. It must name every purpose that is switched on; leave null to use a purpose- and language-aware default. consent_mode: type: string consent_decline_action: type: string enum: - no_recording - hangup description: >- What happens when the caller declines consent: `no_recording` continues the call without recording, `hangup` says a farewell and ends the call. consent_decline_text: type: - string - 'null' description: >- Custom farewell spoken before the call ends when the caller declines consent and `consent_decline_action` is `hangup`. Null or empty uses the default farewell for the assistant's language. consent_covers_recording: type: boolean description: >- Consent covers call recording. Recording additionally requires recording_enabled, and is skipped entirely when recording_enabled is true while this is false. consent_covers_memory: type: boolean description: >- Consent covers durable customer memory. A granted consent sets contact_memories.consent_status; a declined one leaves it unknown, so the caller is asked again on a later call. guardrails: type: object additionalProperties: true description: Topic filters and forced escalation; `{}` = off. language_voices: type: object additionalProperties: type: string description: >- Per-language voice overrides for Pipeline/Half-cascade, e.g. `{"de": "voiceX"}`. Only explicit map entries override the main voice. A private per-language clone is allowed only when the main voice is also a workspace-owned private clone that uses the same provider runtime. auto_language_switch: type: boolean description: >- Automatic response-language switching. The dashboard derives this as true whenever secondary_languages is non-empty. output_volume: type: number description: 1.0 = neutral. speaking_rate: type: number description: 1.0 = neutral. text_only_enabled: type: boolean description: Enables the text chat channel; no effect on telephony. memory_enabled: type: boolean description: Caller recognition across calls (agent memory). memory_mode: type: string enum: - inherit - 'on' - 'off' description: >- Caller memory for this assistant: `inherit` follows the workspace default (`GET /settings/memory`), `on`/`off` override it. `memory_enabled` is the legacy boolean. memory_scope: type: string enum: - workspace - assistant - both description: >- Where conversation memory is stored: `workspace` = one summary shared across all assistants, `assistant` = one summary private to this assistant, `both` = two complete summaries (one workspace-wide and one assistant-private; default for new assistants). lead_attribute_mode: type: string enum: - all - selected description: >- Workspace contact-field access. `all` is an immutable compatibility state for assistants that already had unrestricted access: it cannot be selected on create or enabled by update (HTTP 400). `selected` exposes only explicit `source: lead` definitions and is the default for new assistants. memory_read_channels: type: array uniqueItems: true items: $ref: '#/components/schemas/ConfigurableMemoryChannel' description: >- Channels allowed to read this assistant's memory. The effective policy is the intersection with the workspace channel allowlist; an empty array disables reads. memory_write_channels: type: array uniqueItems: true items: $ref: '#/components/schemas/ConfigurableMemoryChannel' description: >- Channels allowed to update this assistant's memory. The effective policy is the intersection with the workspace channel allowlist; an empty array disables writes. memory_categories: type: array uniqueItems: true items: type: string enum: - identity - preferences - agreements - open_items description: >- Long-term fact categories the assistant may summarize. An empty array keeps consent/audit/interaction metadata but creates no new content summary. redact_pii: type: boolean description: >- Redact PII in stored transcripts. When true, `pii_redaction.entities` selects which categories are masked. pii_redaction: type: object description: >- Selected PII entity keys and optional custom regexes. Empty `entities` uses email/phone/iban/card defaults. properties: entities: type: array items: type: string custom: type: array items: type: object properties: name: type: string pattern: type: string analysis_config: $ref: '#/components/schemas/AnalysisConfig' qa_scorecard_config: oneOf: - $ref: '#/components/schemas/QaScorecardConfig' - type: 'null' description: >- AI QA scorecard configuration (requires AI QA Scorecards in the workspace plan). `null` or `enabled: false` disables scoring. created_at: type: string format: date-time updated_at: type: string format: date-time timezone: type: string description: >- IANA timezone of the assistant (e.g. `Europe/Berlin`, default). Anchors the `get_current_time` system tool, the `{{time}}`/`{{date}}`/`{{datetime}}`/`{{weekday}}` system variables, and the `check_business_hours` built-in tool. On campaign calls the campaign's timezone overrides it per call. primary_language: type: string description: >- Language the assistant answers in by default (ISO 639-1 or ISO 639-3, see `GET /languages`). Use gsw for German (Switzerland), spoken as Swiss German through dialect instructions; pronunciation depends on the selected voice. de-CH remains standard German. 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. Do not combine de and gsw: automatic detection cannot distinguish these variants. variables: type: array items: $ref: '#/components/schemas/VariableDefinition' description: >- Custom variable definitions, referenced as `{{key}}` and resolved per call (explicit call values > inbound enrichment > current contact values > remembered value > default_value). Each custom definition can be call-only, workspace-shared, or assistant-private. variable_webhook_url: type: - string - 'null' description: >- Optional webhook called on inbound calls to enrich variable values before the conversation starts. builtin_tools: type: array items: $ref: '#/components/schemas/BuiltinTool' description: >- Inline built-in tool configurations (also accepted as `tools` for compatibility). DTMF Input and Collect Keypad Input run as prompt-session tools here; dedicated Flow nodes bind their reusable central-tool equivalents. translation_config: $ref: '#/components/schemas/TranslationConfig' realtime_variant: type: string enum: - standard - full_duplex description: >- Realtime conversation variant. Full Duplex requires workspace Beta features, Realtime plan access and compatible defaults available in the selected workspace region; extra credits may apply. Its reasoning model is managed centrally. Existing assistants use standard. default: standard required: - id - name - is_active - system_prompt - mode - created_at - updated_at ResponseByChannel: type: object additionalProperties: false description: >- Versioned manual response instructions for exact output channels. Omit a channel key to use Automatic. Manual instructions supplement and never replace safety, language, tool, or delivery rules. Requires the workspace's Manual channel responses feature. properties: version: type: integer const: 1 overrides: type: object maxProperties: 24 propertyNames: enum: - sms - phone - web_voice - web_chat - whatsapp_voice - email - telegram - slack - messenger - teams - discord - gchat - x - whatsapp - freshdesk - gmail - outlook - zendesk - servicenow - intercom - zoho_mail - agent_mail - instagram - zulip additionalProperties: anyOf: - type: string const: '' description: Clear this channel override and return it to Automatic. - type: string minLength: 1 maxLength: 1500 pattern: \S description: >- At most 8000 Unicode characters across all values. Empty strings clear an override; whitespace-only strings are rejected. required: - version - overrides 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. AnalysisConfig: type: object description: >- Post-conversation sentiment, success and structured extraction for voice, chat, messaging and email. Results retain native JSON types in History, webhooks, the public API and MCP. properties: sentiment: type: boolean default: true description: >- Rate overall caller sentiment (positive/neutral/negative). Defaults to `true`. success: type: object description: Success evaluation against a free-text criterion. properties: enabled: type: boolean default: false criteria: type: string description: Free-text definition of what counts as a successful call. fields: type: array description: >- Up to 30 fields with unique names. Object and List require fixed child fields. Missing scalar values are null; missing lists are empty; configured choice fallbacks override missing values. items: type: object required: - name - type properties: name: type: string description: >- snake_case key; unique within the array. Becomes a key in `calls.analysis.data`. minLength: 1 maxLength: 100 type: type: string enum: - string - number - boolean - enum - object - list - json description: type: string maxLength: 500 description: >- What the judge should extract. Maximum 500 characters — longer values are truncated on save. choices: type: array items: type: string minLength: 1 maxLength: 200 description: >- Required, non-empty allowed values for enum; optional for string. Values must be unique ignoring case. maxItems: 100 required: type: boolean default: false allow_multiple: type: boolean default: false description: >- Enum only. Return an array of matching allowed values, without duplicates, instead of one string. No matches returns [] unless fallback_value is set. fallback_value: type: string description: >- Enum only. Must exactly match one of choices. Saved when no allowed value matches; multiple selection returns [fallback_value]. Omit to leave empty. fields: type: array minItems: 1 maxItems: 20 description: >- Required for object and list only. Unique fixed keys of the object or every list item. Missing properties remain null. Lists contain up to 100 objects. JSON is free-form (up to 16000 characters and 8 nesting levels) and does not accept fields. items: type: object required: - name - type properties: name: type: string description: >- snake_case key; unique within the array. Becomes a key in `calls.analysis.data`. minLength: 1 maxLength: 100 type: type: string enum: - string - number - boolean - enum description: type: string maxLength: 500 description: >- What the judge should extract. Maximum 500 characters — longer values are truncated on save. choices: type: array items: type: string minLength: 1 maxLength: 200 description: >- Required, non-empty allowed values for enum; optional for string. Values must be unique ignoring case. maxItems: 100 required: type: boolean default: false allow_multiple: type: boolean default: false description: >- Enum only. Return an array of matching allowed values, without duplicates, instead of one string. No matches returns [] unless fallback_value is set. fallback_value: type: string description: >- Enum only. Must exactly match one of choices. Saved when no allowed value matches; multiple selection returns [fallback_value]. Omit to leave empty. additionalProperties: false description: >- A fixed Object property or List item property. Only scalar types are supported. additionalProperties: false maxItems: 30 QaScorecardConfig: type: object description: >- AI QA scorecard configuration. Requires AI QA Scorecards in the workspace plan. When `enabled` is true and criteria are set, every finished call is scored and the result is written to `qa_scorecard` / `qa_score` / `qa_passed` on the call. properties: enabled: type: boolean default: false pass_threshold: type: number minimum: 0 maximum: 100 default: 70 description: Overall score 0–100 must be at least this value to pass. criteria: type: array maxItems: 20 items: type: object required: - id - name properties: id: type: string description: snake_case key; unique within the array. name: type: string description: type: string weight: type: number minimum: 0.1 default: 1 source: type: string enum: - llm - reuse_success - reuse_sentiment default: llm description: >- `llm` = judge from transcript; `reuse_success`/`reuse_sentiment` reuse post-call analysis fields. 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. BuiltinTool: type: object required: - type description: >- One built-in tool configuration. `type` selects the tool; the remaining fields depend on the type. DTMF Input sends keypad tones to an IVR or phone menu; Collect Keypad Input collects keypad or spoken digits from the caller. In an assistant's inline `builtin_tools` they run as prompt-session tools. Reusable copies created through the Tools API can also be assigned to assistants and bound to their dedicated Flow Builder nodes. Calendars use Integrations. All types accept an optional `description` that tells the model when to use the tool. Saved caller-facing announcements, filler phrases and end-call farewells remain editable. With secondary languages configured on the assistant, they guide generated wording in the current supported conversation language without fixed saved audio. Otherwise their existing delivery behavior is preserved. An empty End call farewell adds no speech. properties: type: type: string enum: - end_call - call_transfer - warm_call_transfer - dtmf_input - collect_keypad - calendar_integration - assistant_transfer - send_sms - send_email - check_business_hours - schedule_callback - collect_payment_card - set_variable tones: type: string pattern: ^[0-9*#A-D]{1,32}$ maxLength: 32 description: >- Optional for dtmf_input: keypad tones the agent sends. Omit to let the model choose during the call. This field is never a digit count. post_answer_dtmf: type: string maxLength: 32 pattern: ^[0-9*#A-Da-dWw]*$ description: >- Optional for warm_call_transfer: keypad tones sent to the transfer target after its line answers and before the briefing. Each w adds a fixed half-second pause; the sequence does not detect when an IVR or extension is ready. Empty or omitted disables it. Case-insensitive. examples: - wwww1234#wwww timeout: type: integer minimum: 5 maximum: 120 description: >- Optional for collect_keypad: total collection timeout in seconds, including the entry prompt. Default 30; explicitly saved timeouts remain unchanged. default: 30 stop_key: type: string enum: - '#' - '*' description: >- Keypad submit key. exact mode still requires the fixed length; until_stop accepts it once min_digits is reached. The stop key is not part of the returned digits. max_digits: type: integer minimum: 1 maximum: 32 description: >- exact keypad or spoken digit count to collect in exact mode, or maximum in until_stop mode. Defaults to 16 for explicit exact mode and 32 for an unconfigured until_stop tool. stripe_connection_id: type: string format: uuid description: >- Required for collect_payment_card: the ID of the workspace's own Stripe connection (set up in the dashboard under Tools → App Store → Stripe). allowed_keys: type: array items: type: string description: >- Optional for set_variable — snake_case keys the agent may write. Empty or omitted = any valid non-protected key. description: type: - string - 'null' description: >- When the model should use this tool. Falls back to a sensible default. assistant_id: type: string format: uuid description: >- Required for assistant_transfer — destination assistant in the same workspace. context_mode: type: string enum: - all_messages - no_messages - last_n_messages - user_and_assistant_messages - summary_and_last_n - summary_only description: >- For assistant_transfer: which conversation context is handed to the destination assistant. Default all_messages. context_last_n_messages: type: integer minimum: 1 maximum: 100 description: >- For assistant_transfer when context_mode is last_n_messages or summary_and_last_n. Default 10. message_before_transfer: type: - string - 'null' maxLength: 500 description: >- Optional line the current assistant speaks immediately before an assistant_transfer handoff. email_to_mode: type: string enum: - ask - fixed description: Ask and confirm the address during the call, or use email_fixed_to. email_fixed_to: type: string format: email email_sender_mode: type: string enum: - auto - workspace_smtp - platform - address description: >- Explicit modes never silently fall back. Use GET /email-senders to discover available choices. email_sender_address_id: type: string format: uuid description: Required when email_sender_mode is address. email_from_name: type: string maxLength: 128 email_content_mode: type: string enum: - llm - fixed - template email_subject_template: type: string maxLength: 500 description: >- Required for fixed/template content. Template mode supports call variables such as {{customer_name}}. email_body_template: type: string maxLength: 20000 email_signature_mode: type: string enum: - workspace - custom - none email_custom_signature: type: string maxLength: 5000 digit_mode: type: string enum: - exact - until_stop description: >- Collect Keypad Input length mode. exact requires a fixed count; until_stop accepts the stop key after the minimum or finishes at the maximum. Omitted mode with a saved max_digits preserves exact behavior; a fully unconfigured tool defaults to until_stop. min_digits: type: integer minimum: 1 maximum: 32 default: 1 description: >- Minimum digits before submit-key completion in until_stop mode. Must not exceed max_digits; ignored in exact mode. retry_enabled: type: boolean default: false description: >- Warm transfer only: automatically redial the same destination on no answer, busy, temporary unavailability or detected voicemail before running the configured fallback. Stops on connection, decline, permanent error or caller departure. retry_max_attempts: type: integer minimum: 0 maximum: 100 default: 0 description: >- Warm transfer retry limit including the first attempt. 0 retries while the caller remains connected, subject to call duration and credit limits. Used only when retry_enabled is true. retry_delay_sec: type: integer minimum: 5 maximum: 120 default: 10 description: Seconds between warm-transfer attempts when retry_enabled is true. additionalProperties: true example: type: send_sms description: Text the caller a booking confirmation. sms_to_mode: caller TranslationConfig: type: object properties: version: type: integer enum: - 1 speaker1: type: object properties: language: type: string pattern: ^[a-z]{2,3}$ description: >- Native source/target language code. Prompted conversational dialects such as Swiss German (gsw) are not available in Translate. not: enum: - gsw 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}$ description: >- Native source/target language code. Prompted conversational dialects such as Swiss German (gsw) are not available in Translate. not: enum: - gsw 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 ErrorEnvelope: type: object description: Error envelope returned by every /api/v1 endpoint on failure. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - api_access_required - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - destination_forbidden - internal_error - service_unavailable description: >- Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable). message: type: string description: Human-readable description of the error. responses: 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. 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. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.