> ## 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 credential after a failed plan payment so an owner 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 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 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 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: /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_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' meta: pagination: limit: 50 offset: 0 total: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' 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 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 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). 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_model: type: - string - 'null' tts_voice: type: - string - 'null' 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 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 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 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. 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` = 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 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 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 - freshdesk - gmail - outlook - zendesk - servicenow - intercom - zoho_mail - agent_mail - instagram - zulip 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. 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 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 - 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. 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. 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`, `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. ````