Neuratel AI Documentation

APIKeyCreate

Request to create an API key.

name

string · minLength: 1 · maxLength: 100 · required

key_type

string · enum

Type of API key.

Enum values:

master

organization

Default: organization

scopes

string[]

Enum values:

admin:all

admin:organizations

dashboard:view

agents:view

agents:create

agents:edit

agents:delete

agents:duplicate

Use preset: read_only, standard, full_access

rate_limit_per_minute

integer · min: 1 · max: 10000

Default: 60

IP whitelist

object

APIKeyListMetadata

Metadata for API key list responses.

total

integer · required

count

integer · required

include_revoked

boolean · required

APIKeyListResponse

Paginated list of API keys.

object[] · required

object · required

Metadata for API key list responses.

APIKeyResponse

API key response (without secret).

id

string · required

name

string · required

required

key_type

string · enum · required

Type of API key.

Enum values:

master

organization

prefix

string · required

Key prefix for identification (first 8 chars)

scopes

string[] · required

Enum values:

admin:all

admin:organizations

dashboard:view

agents:view

agents:create

agents:edit

agents:delete

agents:duplicate

created_at

string · date-time · required

required

is_active

boolean · required

rate_limit_per_minute

integer · required

required

created_by

string · required

object

APIKeyRotateResponse

Response from key rotation.

old_key_id

string · required

object · required

API key response with secret (only on creation).

grace_period_ends

string · date-time · required

Old key remains valid until this time

APIKeyWithSecret

API key response with secret (only on creation).

id

string · required

name

string · required

required

key_type

string · enum · required

Type of API key.

Enum values:

master

organization

prefix

string · required

Key prefix for identification (first 8 chars)

scopes

string[] · required

Enum values:

admin:all

admin:organizations

dashboard:view

agents:view

agents:create

agents:edit

agents:delete

agents:duplicate

created_at

string · date-time · required

required

is_active

boolean · required

rate_limit_per_minute

integer · required

required

created_by

string · required

key

string · required

Full API key (only shown once)

object

AccountListResponse

object[] · required

AccountResponse

Mirrors ElevenLabs GetWhatsAppAccountResponse schema.

id

string · uuid · required

organization_id

string · uuid · required

phone_number_id

string · required

display_phone_number

string · required

business_account_id

string · required

business_account_name

string · required

phone_number_name

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

enable_messaging

boolean

Default: true

enable_audio_message_response

boolean

Default: true

enable_calling

boolean

Default: false

is_active

boolean

Default: true

webhook_verified

boolean

Default: false

inbound_webhook_secret_set

boolean

Default: false

ActiveCallInfo

Active call info for the supervisor dashboard.

id

string · required

channel

string · required

status

string · required

object[]

ActiveCallParticipant

identity

string · required

ActiveCallsResponse

success

boolean · required

object[] · required

total_active

integer · required

timestamp

string · required

AddToDncConfig

Configuration for the in-call ``add_to_dnc`` agent tool. When enabled, the LLM gets an ``add_to_dnc`` callable it can invoke when the user explicitly asks to never be called again. The tool POSTs to Platform's ``/v1/webhooks/agent/dnc-add`` and the backend looks up the consumer's E.164 from the voice_session row, so the LLM never handles the raw phone number directly. Whether or not this in-call tool is enabled, every finished call's transcript is also scanned post-hoc by ``infer_dnc_from_session_report`` (gpt-5.4-nano classifier) — the in-call tool is a UX win (faster block) but defense-in-depth lives in the post-call inference job.

enabled

boolean

Enable in-call DNC opt-out tool

Default: false

AdminAdjustCreditsRequest

Request to adjust organization credits (admin only).

organization_id

string · uuid · required

amount

number · required

action

string · enum · required

Enum values:

add

remove

AdminAdjustCreditsResponse

Response for admin credit adjustment.

status

string · required

organization_id

string · uuid · required

action

string · required

amount_cents

integer · required

currency

string · required

transaction_id

string · required

new_balance_cents

integer · required

new_balance_dollars

number · required

AdminBillingOverridesRequest

Set per-org billing overrides — DLT compliance flag and/or custom rate-card overrides JSONB. `custom_rate_overrides` is a flat dict of override keys to USD rates. Override keys follow `<rate_type>.<channel>.<region_tier>` (omit NULL parts), e.g. `voice_per_min.webrtc.GLOBAL` or `wa_text.launch`. Checked BEFORE the rate_cards table at billing time. Pass only the fields you want to change. Omitted fields are untouched.

AdminBillingOverridesResponse

organization_id

string · uuid · required

india_dlt_registered

boolean · required

object · required

max_concurrent_calls_effective

integer · required

scale_cap_override

boolean · required

AdminDNCAddRequest

phone

string · minLength: 5 · maxLength: 20 · required

source

string

Default: platform_seed

AdminPilotActionResponse

organization_id

string · uuid · required

required

message

string · required

AdminPilotConvertRequest

Convert a Pilot org to Launch or Scale + apply $2K credit.

target_sku

string · enum · required

Enum values:

launch

scale

india_compliance

boolean

Default: false

china_onboarding

boolean

Default: false

AdminPilotConvertResponse

organization_id

string · uuid · required

new_sku

string · required

new_setup_fee_invoice_id

string · uuid · required

pilot_credit_applied_usd

number · required

AgentAssignRequest

Request model for assigning an agent to a phone number

agent_id

string · uuid · required

AgentCallRequest

Request to start a browser (WebRTC) call with an agent.

Optional session name override

Display name for the caller

Dynamic {{variables}} to inject for this call

AgentCallResponse

Response containing connection details for a browser (WebRTC) call.

success

boolean · required

Whether the session was successfully created

session_id

string · required

Unique identifier for this call session

participant_token

string · required

JWT access token for the participant

token

string · required

JWT access token (alias of participant_token for backward compat)

server_url

string · required

WebSocket URL of the realtime media server

participant_identity

string · required

Your participant identity in this session

expires_in

integer

Token expiry in seconds from now

Default: 3600

AgentCreate

Request schema for creating a new agent. Only `name` is required - all other fields have production-ready defaults. Users can override any field with their own values. The service layer applies defaults via deep_merge_config().

name

string · minLength: 1 · maxLength: 255 · required

Agent display name (required)

agent_type

string · enum

Agent type: advanced (form-based) or workflow (graph-based)

Enum values:

advanced

workflow

Default: advanced

Template ID to apply preset instructions and config. See GET /v1/templates for available templates.

tags

string[] · maxItems: 20

Tags for organization

Agent description

LLM configuration. Default: OpenAI GPT-4.1

TTS configuration. Default: ElevenLabs Flash v2.5

STT configuration. Default: ElevenLabs Scribe v2

Vocal backchanneling config

Enable ultra-low latency word-by-word streaming

Tool and capability settings

Call transfer settings

Analytics and monitoring settings

AgentKnowledgeBaseAssignment

Assign knowledge bases to an agent.

knowledge_base_ids

string[]

KB IDs to assign

AgentKnowledgeBaseListResponse

List of knowledge bases assigned to an agent.

agent_id

string · uuid · required

object[] · required

AgentListResponse

API response for agent list. Standardized pagination format: - results: List of items - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

List of agents

object · required

Pagination metadata

AgentMetricsSummary

Per-call analytics surface read by the call-detail modal. Removed (no backend writer ever populated them): engagement_score, call_ended_reason, call_ended_reason_details, voicemail_probability, interruptions_count, long_pauses_count, rapid_exchanges_count, backchannel_count, transfer_attempted, transfer_successful, unique_speakers_count, speaker_distribution, tool_calls_history, call_metadata. Renamed: stt_turnaround_ms -> eou_delay_ms (was mislabeled — value is end-of-utterance delay from the worker's eou_delay_avg_s, not STT processing time).

object

AgentPerformance

Performance metrics for a single agent.

agent_id

string · required

Agent ID

agent_name

string · required

Agent display name

total_calls

integer · min: 0

Total calls handled

Default: 0

completed_calls

integer · min: 0

Successfully completed

Default: 0

failed_calls

integer · min: 0

Failed calls

Default: 0

total_duration_sec

integer · min: 0

Total duration in seconds

Default: 0

avg_duration_sec

number · min: 0

Average call duration

Default: 0

success_rate

number · min: 0 · max: 1

Success rate (0-1)

Default: 0

answer_rate

number · min: 0 · max: 1

Answer rate (0-1)

Default: 0

Estimated cost

Average response latency

AgentRequiredVariablesResponse

Variables an agent's config references. Field meanings (matches the frontend `AgentRequiredVariables` interface consumed by the outbound-campaigns Form): - `required_variables`: every `{{name}}` extracted from the agent config. - `contact_variables`: subset that must come from the call-list contact row (i.e. NOT auto-injected `system__*` variables). - `system_variables`: subset auto-injected by the worker at call time. - `total_required`: convenience count of `required_variables`. - `sources`: where each variable was found (currently grouped by "system" vs "contact" — extensible for future per-config-section breakdown without a new endpoint).

required_variables

string[]

contact_variables

string[]

system_variables

string[]

total_required

integer

Default: 0

object

AgentResponse

Flat API response for single agent. Returns agent data directly without wrapper.

id

string · required

Unique agent identifier

name

string · required

Agent display name

organization_id

string · required

Owning organization ID

status

string

Agent status

Default: ready

is_active

boolean

Whether agent is active

Default: true

object

LLM/Brain configuration

TTS configuration

STT configuration

object

Vocal backchanneling config

stream_response

boolean

Enable ultra-low latency word-by-word streaming

Default: true

min_consecutive_speech_delay

number

Default: 0

object

Tools configuration

Transfer settings

Analytics settings

tags

string[]

AgentRestoreResponse

Response after restoring an agent to a historical version.

success

boolean · required

message

string · required

AgentUpdate

Request schema for updating an agent. All fields are optional - only provided fields are updated.

Agent display name

Tags for organization

Agent description

Whether agent is active

LLM configuration (brain - what thinks)

TTS configuration

STT configuration

Vocal backchanneling config

Enable ultra-low latency word-by-word streaming

Tool and capability settings

Call transfer settings

Analytics and monitoring settings

If provided, the update will fail with 409 if the agent's current version does not match. Prevents concurrent overwrites.

HTTPS URL invoked at call/message connect to fetch per-call dynamic_variables and (optional) prompt overrides. Empty/null disables the fetch. Phone-number-level URLs (when configured) take precedence for inbound voice — agent URL is the fallback.

Shared secret used to sign every webhook request with HMAC-SHA256 in the X-Neuratel-Signature header. Optional — null means no signature is sent (acceptable for internal/dev endpoints only).

AgentVersionEntry

A single entry in an agent's version history.

version

integer · required

AgentVersionListResponse

Response for listing all versions of an agent.

agent_id

string · required

total

integer · required

object[] · required

AgentVersionResponse

Response for a single agent version.

version

integer · required

AllOrgsUsageResponse

Usage summary for all organizations.

object[] · required

period_days

integer · required

AmbientAudioConfig

Configuration for ambient background audio. Ambient sound plays on a loop in the background during the agent session. Use a BuiltinAudioClip preset or provide a custom audio URL/path.

enabled

boolean

Enable ambient audio

Default: false

Built-in audio clip or custom URL/path to audio file

Default: office_ambience

volume

number · min: 0 · max: 1

Ambient audio volume

Default: 0.8

AnalysisPlan

Post-call analysis configuration. Per-feature presence-based gating: each analysis runs only when its prompt / schema / flag is populated. The previous master ``enabled`` toggle was removed in May 2026 — it was a footgun (users would set summaryPrompt and still get nothing because they didn't notice the master switch was off).

Custom prompt for call summary. Empty string disables summary.

Custom prompt for structured data extraction

JSON Schema defining the format of extracted data

Custom prompt for success evaluation. Empty string disables evaluation.

Rubric type for evaluation

Default: PassFail

extract_topics

boolean

Auto-extract topics discussed during the call

Default: false

extract_action_items

boolean

Auto-extract action items mentioned during the call

Default: false

compute_user_sentiment

boolean

Compute categorical user sentiment from the per-turn sentiment timeline

Default: false

minMessagesThreshold

integer · min: 0 · max: 20

Skip analysis if conversation has fewer messages than this

Default: 2

AnalyticsConfig

Complete analytics configuration. Controls all observability features including metrics, webhooks, recording, and post-call analysis.

enabled

boolean

Enable analytics overall

Default: true

track_sentiment

boolean

Track emotional tone/sentiment throughout calls in real-time

Default: true

object

Webhook notification settings

object

Call recording settings

object

Post-call analysis settings

AnalyticsDashboardResponse

COMPREHENSIVE ANALYTICS RESPONSE - Single Source of Truth This is the primary analytics endpoint. Backend returns everything the frontend needs - no client-side calculations required.

start_date

string · required

Start date YYYY-MM-DD

end_date

string · required

End date YYYY-MM-DD

object · required

Primary KPI metrics

Named time range if applicable

object[]

Call volume over time

object[]

Activity heatmap data

object

Call outcome breakdown

object[]

By hour of day

object[]

By day of week

Per-agent performance

Per-campaign performance

Average latency metrics

AnnouncementRequest

Request body for status announcements

subject

string · required

message

string · required

component_ids

string[]

AuthConnectionCreate

Create a new credential vault entry. For ``kind="bearer"``: pass the raw token in ``token``. For ``kind="headers"``: pass a dict in ``headers``. Exactly one of the two must be supplied; ``_kind_secret_match`` raises a 422 with field-level info before the request reaches the service.

name

string · minLength: 1 · maxLength: 255 · required

kind

string · enum · required

Enum values:

bearer

headers

AuthConnectionListResponse

object[] · required

AuthConnectionResponse

Response shape — secret value never leaves the server. For ``kind="bearer"`` the response sets ``has_token=True`` once a token is stored; for ``kind="headers"`` ``header_keys`` lists the keys (never values).

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

kind

string · enum · required

Enum values:

bearer

headers

has_token

boolean

Default: false

header_keys

string[]

AuthConnectionUpdate

AuthContextResponse

Authentication context for the current user. This is the main response from /auth/me endpoint. Frontend uses scopes to determine UI permissions.

email

string · required

user_id

string · required

User identifier from auth provider

role

string · enum

Effective role

Enum values:

super_admin

admin

operator

viewer

Default: viewer

effective_role

string

String version of effective role for frontend

Default: viewer

is_super_admin

boolean

Whether user has super admin access

Default: false

scopes

string[]

Permission scopes from JWT

authenticated_via

string

jwt or api_key

Default: jwt

AutoReloadSettingsRequest

Request to update auto-reload settings.

enabled

boolean · required

AutoReloadSettingsResponse

Current auto-reload settings.

enabled

boolean · required

BackchannelConfig

Configuration for active vocal backchanneling. Plays a soft hum at exactly seventy-five percent of your main voice's volume. Spawns a background timer exactly one second after the user starts speaking, once per turn. If the user stops talking before that one-second threshold, the timer is canceled. When a real agent reply is generated, any active backchannel hum is immediately cut off so the real response speaks instantly with zero playout delay.

enabled

boolean

Enable active vocal backchanneling

Default: false

listening_delayed_enabled

boolean

Enable delayed active listening hums when user speaks for >1.0s

Default: true

thinking_cognitive_enabled

boolean

Enable cognitive thinking cues (hmm, uhm) when agent is processing

Default: true

thinking_cognitive_probability

number · min: 0 · max: 1

Probability roll for cognitive thinking cues. Default: 0.5

Default: 0.5

interruption_hums_enabled

boolean

Enable verbal acknowledgement hums when user interrupts the agent

Default: true

volume_multiplier

number · min: 0.1 · max: 1.5

Backchannel & cognitive cue volume multiplier (percentage of main voice). Default: 0.75

Default: 0.75

tool_fillers_enabled

boolean

Enable native, quiet, and asynchronous talking fillers during long tool calls (such as booking slots or compiling audio notes)

Default: false

tool_fillers_delay

number · min: 0.5 · max: 5

Continuous silence delay (seconds) required before each filler plays. Default: 1.5s

Default: 1.5

tool_fillers_pool

string[]

Custom list of rotating talking fillers used during long operations

listening_cues

string[]

Vocal backchannels and active listening hums to rotate through

thinking_cues

string[]

Cognitive thinking cues to rotate through while processing

BackgroundAudioConfig

Combined background audio settings.

Ambient audio settings

Thinking audio settings

BadRequestError

400 Bad Request error response

detail

string · required

BalanceCheckResponse

Response for balance check before call.

can_make_call

boolean · required

balance_cents

integer · required

balance_dollars

number · required

message

string · required

minimum_required_cents

integer

Default: 100

BalanceHistoryResponse

List of balance transactions.

object[] · required

current_balance_cents

integer · required

current_balance_dollars

number · required

BalanceResponse

Current account balance.

balance_cents

integer · required

balance_dollars

number · required

has_credits

boolean · required

currency

string

Default: USD

BalanceTransactionResponse

Balance transaction details.

id

string · required

amount_cents

integer · required

amount_dollars

number · required

ending_balance_cents

integer · required

description

string · required

created

integer · required

BatchCallRequest

Batch outbound WhatsApp calls — sends permission-request templates to multiple recipients.

whatsapp_phone_number_id

string · required

recipients

string[] · minItems: 1 · maxItems: 100 · required

List of recipient WhatsApp IDs (E.164 phone numbers)

permission_request_template_name

string · required

agent_id

string · uuid · required

permission_request_template_language_code

string

Default: en_US

object[]

Body parameters for the call permission template (named or positional). Same auto-resolve contract as InitiateCallRequest — supply template_body + dynamic_variables to fill from the agent map.

Raw template body for placeholder auto-resolution.

Per-conversation runtime variable map applied uniformly to every recipient in the batch. For per-recipient overrides, supply template_params directly.

BatchCallResponse

total

integer · required

sent

integer · required

failed

integer · required

object[] · required

BillingListMetadata

Metadata for billing list responses.

count

integer · required

BillingPortalRequest

Request to create a billing portal session.

return_url

string · required

BillingPortalResponse

Billing portal session response.

url

string · required

id

string · required

BillingSettingsResponse

Current billing settings for organization. sku is the canonical pricing tier RateCardService.lookup() reads; payment_method gates Stripe Card vs Manual Invoice flow in SettingsBilling.tsx; effective_rate_per_minute_usd is the representative voice rate (webrtc + GLOBAL region) computed from RateCardService for UI display — actual billing rates vary by channel + region per call. Pilot pool counters (``pilot_*``) and MTD usage caches let the org-side Settings → Billing card render Pilot's Day-N-of-30 + pool consumption AND the Launch/Scale dashboard widget render volume-discount tier progress without an extra Organization fetch (audit fix #4 of v5 alignment plan).

sku

string · required

contract_term

string · required

payment_method

string · required

pilot_included_minutes_used

number

Default: 0

pilot_included_minutes_total

number

Default: 800

pilot_included_messages_used

integer

Default: 0

pilot_included_messages_total

integer

Default: 10000

month_to_date_billable_minutes

number

Default: 0

month_to_date_whatsapp_call_minutes

number

Default: 0

concurrency_cap

integer

Default: 5

BuiltinAudioClip

string · enum

Enum values:

city_ambience

forest_ambience

office_ambience

crowded_room

keyboard_typing

keyboard_typing_2

hold_music

Built-in audio clips for background and thinking sounds.

For custom sounds, use a URL or file path string instead.

BulkPasteContactRow

One pasted-phone row in the manual bulk-paste flow.

phone_number

string · minLength: 3 · maxLength: 40 · required

object

Optional variables for this contact (e.g. {"name": "Bilal"}). Reserved keys phone_number and status are rejected.

BulkPasteContactsRequest

POST /call-lists/{id}/contacts/bulk — manual bulk-paste from FE.

object[] · minItems: 1 · maxItems: 500 · required

BulkPasteContactsResponse

Result of /contacts/bulk.

imported_count

integer

Default: 0

skipped_count

integer

Default: 0

dnc_blocked_count

integer

Default: 0

object[]

CallDurationConfig

Configuration for maximum call duration.

enabled

boolean

Enable call duration limit

Default: true

max_seconds

integer · min: 60 · max: 7200

Maximum call duration in seconds

Default: 1800

Warning message before limit

Default: We're approaching the end of our allotted time.

warning_seconds_before

integer · min: 10 · max: 300

Seconds before limit to show warning

Default: 60

exceeded_message

string

Message when limit reached

Default: We've reached the maximum call duration. Thank you for calling!

CallListContactCreate

Schema for creating call list contacts

phone_number

string · minLength: 3 · maxLength: 20 · required

Contact phone number

object

Arbitrary key/value map. Every key becomes a {{key}} variable available to the agent prompt at call time. Reserved keys phone_number and status are rejected (they would override the contact's real columns).

CallListContactResponse

Schema for call list contact responses. Phase 1 dropped the `call_count`, `last_called`, `call_result` fields — per-attempt outcomes now live on campaign_attempts and are exposed via GET /v1/campaigns/{id}/attempts.

phone_number

string · minLength: 3 · maxLength: 20 · required

Contact phone number

id

string · uuid · required

call_list_id

string · uuid · required

created_at

string · date-time · required

object

Arbitrary key/value map. Every key becomes a {{key}} variable available to the agent prompt at call time. Reserved keys phone_number and status are rejected (they would override the contact's real columns).

status

string

Default: active

is_active

boolean

Default: true

CallListContactUpdate

Schema for updating call list contacts.

Contact phone number

Replace the contact's variable map. Pass {} to clear; omit to leave unchanged. Reserved keys phone_number and status are rejected.

Contact status: active, dnc, invalid, opted_out, or called (legacy)

Contact active status

CallListCreate

Schema for creating call lists

name

string · minLength: 1 · maxLength: 255 · required

Call list name

Call list description

CallListResponse

Schema for call list responses

name

string · minLength: 1 · maxLength: 255 · required

Call list name

id

string · uuid · required

organization_id

string · uuid · required

created_at

string · date-time · required

updated_at

string · date-time · required

Call list description

total_contacts

integer

Default: 0

active_contacts

integer

Default: 0

is_active

boolean

Default: true

CallListUpdate

Schema for updating call lists

Call list name

Call list description

Additional list metadata

List active status

CallListsListResponse

Paginated list of call lists. Standardized pagination format: - results: List of call lists - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

CallOutcomeBreakdown

Breakdown of calls by outcome for pie charts.

completed

integer · min: 0

Successfully completed calls

Default: 0

failed

integer · min: 0

Failed calls

Default: 0

no_answer

integer · min: 0

Unanswered calls

Default: 0

voicemail

integer · min: 0

Voicemail calls

Default: 0

busy

integer · min: 0

Busy signal

Default: 0

canceled

integer · min: 0

Canceled calls

Default: 0

other

integer · min: 0

Other outcomes

Default: 0

CallPermissionStatusResponse

has_permission

boolean · required

can_call

boolean

Default: false

CallResponse

status

string · required

message

string · required

CallSchedule

Campaign call scheduling window.

CallStatusResponse

intent_id

string · uuid · required

status

string · required

requested_at

string · date-time · required

expires_at

string · date-time · required

CallVolumeDataPoint

Single data point for call volume time series charts.

date

string · required

Date in YYYY-MM-DD format

Hour (0-23) for hourly interval

calls

integer · min: 0

Total calls

Default: 0

answered

integer · min: 0

Answered/completed calls

Default: 0

errors

integer · min: 0

Failed/error calls

Default: 0

inbound

integer · min: 0

Inbound calls

Default: 0

outbound

integer · min: 0

Outbound calls

Default: 0

duration_minutes

number · min: 0

Total duration in minutes

Default: 0

avg_handle_time_sec

number · min: 0

Average call duration in seconds

Default: 0

Answer rate (0-1)

Error rate (0-1)

Booking rate (0-1)

avg_latency_ttft_ms

number · min: 0

Average TTFT in ms

Default: 0

avg_latency_ttfb_ms

number · min: 0

Average TTFB in ms

Default: 0

avg_eou_delay_ms

number · min: 0

Average end-of-utterance VAD delay in ms

Default: 0

asr_latency_ms_p50

number · min: 0

Median ASR latency in ms

Default: 0

CampaignAttemptListResponse

Paginated list of CampaignAttempt rows for GET /campaigns/{id}/attempts.

object[] · required

object · required

Pagination metadata in API responses.

CampaignAttemptResponse

One attempt to dial a single contact. Phase 1 introduces this as the per-attempt progress primitive.

id

string · uuid · required

campaign_id

string · uuid · required

contact_id

string · uuid · required

attempt_number

integer · required

outcome

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

CampaignConfig

Campaign dialer configuration. Concurrency is governed by the org-level cap (Organization.sku → effective_max_concurrent_calls). Per-campaign concurrency / per-minute knobs were removed in the May-2026 dispatcher refactor — they duplicated the org cap and silently throttled high-Scale orgs to a legacy default of 5 (or whatever the wizard slider was set to).

CampaignCoverageResponse

Per-required-variable fill rate across a call list's active contacts. Powers the wizard Step 1 coverage report and mirrors the math the /start hard-block uses. ``blocking_zero_pct`` is the slice that would refuse a launch.

required_variables

string[] · required

total_contacts

integer · required

object · required

blocking_zero_pct

string[] · required

CampaignListResponse

Paginated list of campaigns. Standardized pagination format: - results: List of campaigns - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

CampaignPerformance

Performance metrics for a single campaign.

campaign_id

string · required

Campaign ID

campaign_name

string · required

Campaign display name

total_calls

integer · min: 0

Total calls made

Default: 0

answered

integer · min: 0

Answered calls

Default: 0

completed

integer · min: 0

Completed conversations

Default: 0

failed

integer · min: 0

Failed calls

Default: 0

no_answer

integer · min: 0

No answer

Default: 0

voicemail

integer · min: 0

Voicemail

Default: 0

answer_rate

number · min: 0 · max: 1

Answer rate (0-1)

Default: 0

completion_rate

number · min: 0 · max: 1

Completion rate (0-1)

Default: 0

conversion_rate

number · min: 0 · max: 1

Conversion/success rate (0-1)

Default: 0

total_duration_min

number · min: 0

Total duration in minutes

Default: 0

avg_duration_sec

number · min: 0

Average call duration

Default: 0

CampaignRetryRequest

Body for POST /campaigns/{id}/retry — re-dial failed attempts. Both filters are optional: - contact_ids: restrict the retry to these contacts only. - outcomes: only retry attempts whose latest outcome is in this set. Default: failed, no_answer, voicemail, busy. Creates one new CampaignAttempt per matched contact with attempt_number = max(prior attempts) + 1, then enqueues dispatch.

Restrict retry to these contacts (default: all matched)

Only retry attempts in these outcomes. Default: failed, no_answer, voicemail, busy.

CampaignRetryResponse

Result of POST /campaigns/{id}/retry.

requeued

integer · required

Number of new attempts created

contacts

string[]

Contact IDs that were retried

CampaignTestWebhookResponse

Result of POST /campaigns/{id}/test-webhook. The endpoint fires a synthetic ``campaign.test`` payload against the campaign's configured ``status_webhook`` URL so the operator can verify their receiver before going live. Receivers should ignore this event type — it's distinct from real lifecycle events (``campaign.completed``, ``campaign.stopped``, ``campaign.failed``).

success

boolean · required

True if the receiver responded 2xx.

latency_ms

integer · required

Round-trip time in milliseconds.

HTTP status code from the receiver.

Truncated response body (first 500 chars).

Set when the request failed before getting a response.

CartesiaEmotion

string · enum

Enum values:

Happy

Excited

Enthusiastic

Elated

Euphoric

Triumphant

Amazed

Surprised

Cartesia voice emotion presets.

CartesiaModel

string · enum

Enum values:

sonic-3.5

sonic-3

Cartesia TTS models - Updated Apr 2026.

CartesiaSpeed

string · enum

Enum values:

fastest

fast

normal

slow

slowest

Cartesia speed presets.

CartesiaVoiceConfig

Cartesia voice configuration. SDK Defaults: - model: "sonic-3" - language: "en" - sample_rate: 24000

provider

string · const

Const value: cartesia

Default: cartesia

voice_id

string

Cartesia voice ID

Default: 8d8ce8c9-44a4-46c4-b10f-9a927b99a853

model

string · enum

Cartesia model to use

Enum values:

sonic-3.5

sonic-3

Default: sonic-3

Speaking speed. Preset name or float

Emotion tags to apply

Volume adjustment

Language code

Default: en

ChatChannelMetrics

Per-channel chat slice (sms or whatsapp_chat).

channel

string · required

conversations

integer · min: 0

Default: 0

messages_total

integer · min: 0

Default: 0

messages_inbound

integer · min: 0

Default: 0

messages_outbound

integer · min: 0

Default: 0

delivered

integer · min: 0

Default: 0

read

integer · min: 0

Default: 0

failed

integer · min: 0

Default: 0

ChatDashboardResponse

Chat-side analytics payload mirroring the voice dashboard contract.

start_date

string · required

end_date

string · required

object · required

Top-line chat dashboard KPIs.

object[]

ChatDeliveryBreakdown

Funnel counts per channel for the delivery rate panel.

channel

string · required

sent

integer · min: 0

Default: 0

delivered

integer · min: 0

Default: 0

read

integer · min: 0

Default: 0

failed

integer · min: 0

Default: 0

ChatKPIs

Top-line chat dashboard KPIs.

active_conversations

integer · min: 0

Default: 0

total_messages

integer · min: 0

Inbound + outbound in window

Default: 0

inbound_messages

integer · min: 0

Default: 0

outbound_messages

integer · min: 0

Default: 0

avg_messages_per_conversation

number · min: 0

Default: 0

Median seconds between first inbound and first outbound reply.

ChatVolumePoint

One bucket of the stacked message-volume chart.

date

string · required

ISO date or hour bucket key

sms

integer · min: 0

Default: 0

whatsapp_chat

integer · min: 0

Default: 0

total

integer · min: 0

Default: 0

CollectDtmfConfig

Configuration for collecting DTMF (keypad) input.

enabled

boolean

Enable DTMF collection

Default: false

max_digits

integer · min: 1 · max: 50

Maximum digits to collect

Default: 10

timeout_seconds

number · min: 1 · max: 60

Timeout for digit entry

Default: 10

stop_character

string

Character to end input

Default: #

allow_spoken

boolean

Also accept spoken digits

Default: true

inter_digit_timeout

number · min: 0.5 · max: 10

Timeout between digits

Default: 3

CombinedCost

Cross-channel cost roll-up for the combined dashboard.

voice_usd

number · min: 0

Default: 0

chat_usd

number · min: 0

Default: 0

total_usd

number · min: 0

Default: 0

CombinedDashboardResponse

Voice + chat dashboard returned by `/v1/analytics/dashboard`.

start_date

string · required

end_date

string · required

object · required

COMPREHENSIVE ANALYTICS RESPONSE - Single Source of Truth

This is the primary analytics endpoint. Backend returns everything the frontend needs - no client-side calculations required.

object · required

Chat-side analytics payload mirroring the voice dashboard contract.

object · required

Cross-channel cost roll-up for the combined dashboard.

ComponentAdminOut

Admin view of component - no history needed

id

string · uuid · required

name

string · required

required

group_name

string · required

status

string · required

required

uptime_percentage

number · required

display_order

integer

Default: 0

is_visible

boolean

Default: true

ComponentCreate

name

string · required

group_name

string

Default: Core Services

display_order

integer

Default: 0

health_check_type

string

Default: http

health_check_interval

integer

Default: 60

ComponentOut

id

string · uuid · required

name

string · required

required

group_name

string · required

status

string · required

required

uptime_percentage

number · required

object[] · required

ComponentStatusUpdate

Request body for updating component status only

status

string · required

ComponentUpdate

ConcurrencyResponse

current_concurrent

integer · required

limit

integer · required

available

integer · required

unlimited

boolean · required

ContactImportCommitRequest

Body for POST /call-lists/{id}/contacts/import. ``mapping`` overrides ``suggested_mapping`` from the preview step. Headers omitted from ``mapping`` are imported into ``contact_data`` so dynamic-variable agents can still address them.

preview_token

string · required

object

run_async

boolean

Force the background path. Auto-on for files >1000 rows; the FE may also opt in to background mode for smaller files to keep the UI responsive.

Default: false

ContactImportCommitResponse

One of two shapes depending on ``run_async``: - sync: returns the final result inline. - async: returns ``{job_id, status: "queued"}`` and the FE polls GET /call-lists/import-jobs/{job_id} for progress.

status

string · required

queued | completed | failed

Set when run_async is true; poll for progress.

imported_count

integer

Default: 0

skipped_count

integer

Default: 0

dnc_blocked_count

integer

Default: 0

object[]

ContactImportInvalidRow

One bad row surfaced in the preview screen so the user can fix their CSV before committing the import.

row_number

integer · required

1-indexed row number, header = row 1

reason

string · required

Why the row failed validation

object

Raw cell values for this row

ContactImportPreviewResponse

What POST /call-lists/{id}/contacts/preview returns. The FE renders a column-mapping screen using ``detected_headers`` + ``suggested_mapping``. The user can override any mapping, then POSTs back to /import with the ``preview_token``.

preview_token

string · required

Opaque token to pass to /import. TTL ~10 minutes.

detected_headers

string[] · required

total_rows

integer · required

encoding

string · required

delimiter

string · required

object

raw_header → canonical_field mapping derived from header aliases.

object[]

First 10 rows with raw cell values.

object[]

First 10 invalid rows with reasons.

ContactImportProgressError

row_number

integer · required

reason

string · required

phone

string

Default:

ContactImportProgressResponse

Progress snapshot for the GET /call-lists/import-jobs/{job_id} poll.

status

string · required

queued | running | completed | failed

total

integer

Default: 0

processed

integer

Default: 0

imported

integer

Default: 0

skipped

integer

Default: 0

dnc_blocked

integer

Default: 0

object[]

ContributionDataPoint

Single data point for contribution heatmap (GitHub-style activity).

date

string · required

Date in YYYY-MM-DD format

count

integer · min: 0

Activity count for this day

Default: 0

level

integer · min: 0 · max: 4

Intensity level 0-4 for coloring

Default: 0

ConversationDynamicVariablesUpdateRequest

Operator update to a conversation's per-conversation runtime variable bucket. Replaces the dual-purpose ``dynamic_variables`` field that used to live on every send request — Stage 7c (option A) split context-setting out of message-send so the freeform composer doesn't carry vars dead-weight. Default merge semantics: caller-supplied keys are merged into the existing bucket (last-write-wins per key). Pass ``replace=True`` to fully overwrite — useful for "operator typed a fresh attribute set" flows where stale keys should be cleared.

object

Map of variable name to value. Keys with reserved prefix system__ are stripped server-side (platform-controlled).

replace

boolean

True = full replace (existing keys not in the payload are cleared). False (default) = merge into existing bucket.

Default: false

ConversationLastMessage

Denormalised preview of the most-recent message for inbox rendering.

type

string · required

direction

string · required

status

string · required

sent_at

string · date-time · required

ConversationListResponse

object[] · required

object · required

Pagination metadata in API responses.

ConversationResponse

id

string · uuid · required

organization_id

string · uuid · required

channel

string · required

contact_address

string · required

business_address

string · required

status

string · required

started_at

string · date-time · required

message_count

integer · required

created_at

string · date-time · required

updated_at

string · date-time · required

object

ConversationSendRequest

Send a message inside an existing conversation.

body

string · minLength: 1 · maxLength: 4096 · required

MMS attachments (SMS only — WhatsApp text endpoint rejects).

Client-supplied id echoed back for optimistic UI reconciliation.

ConversationTurnSummary

speaker

string · required

text

string · required

timestamp

string · date-time · required

CreateWorkflowRequest

name

string · minLength: 1 · maxLength: 255 · required

DNCCheckResponse

phone

string · required

result

string · required

DNCEntryAddRequest

phone

string · minLength: 5 · maxLength: 20 · required

DNCEntryListResponse

object[] · required

count

integer · required

DNCEntryResponse

id

string · uuid · required

phone_e164

string · required

country_iso2

string · required

source

string · required

required

added_at

string · date-time · required

required

DNCSettingsRequest

DNCSettingsResponse

organization_id

string · uuid · required

protection_enabled

boolean · required

auto_add_inbound_optouts

boolean · required

DashboardKPIs

Primary KPIs displayed on dashboard summary cards. Backend provides complete, pre-formatted data - frontend just displays.

object · required

Total calls in period

object · required

Successfully answered/completed calls

object · required

Failed/error calls

object · required

Answered / Total as percentage

object · required

Errors / Total as percentage

object · required

Completed / Total as percentage

object · required

Average call duration

object · required

Total minutes used

Bookings / Total

AI component latencies

Average sentiment (-1 to 1, formatted as %)

Average audio/conversation quality (0-100%)

Total cost in USD

DayOfWeekDistribution

Call distribution by day of week.

day

integer · min: 0 · max: 6 · required

Day of week (0=Monday, 6=Sunday)

day_name

string · required

Day name (Monday, Tuesday, etc.)

calls

integer · min: 0

Call count

Default: 0

avg_duration_sec

number · min: 0

Average duration

Default: 0

DeepgramLanguage

string · enum

Enum values:

en

en-US

en-GB

en-AU

ar

ar-AE

ar-SA

ar-EG

Deepgram supported languages (BCP-47 format).

DeepgramNovaModel

string · enum

Enum values:

nova-3

nova-3-medical

flux

flux-multilingual

Deepgram Nova-3 transcription models - uses STT class (/v1/listen API).

SDK Default: model="nova-3", language="en-US" No Nova-4 exists as of 2026-04. Deepgram Flux is a separate model line (removed).

DeepgramTranscriberConfig

Deepgram Nova-3 transcriber configuration - uses STT class (/v1/listen API). Best-in-class accuracy for general transcription. Full feature set: punctuation, smart formatting, diarization, language detection.

provider

string · const

Const value: deepgram

Default: deepgram

model

string · enum

Deepgram Nova-3 model to use for transcription

Enum values:

nova-3

nova-3-medical

flux

flux-multilingual

Default: nova-3

language

string · enum

Transcription language (BCP-47 format). Use 'multi' for multilingual streaming.

Enum values:

en

en-US

en-GB

en-AU

ar

ar-AE

ar-SA

ar-EG

Default: en-US

Apply smart formatting (numbers, dates, addresses)

Default: false

Add punctuation to transcription

Default: true

Convert spoken numbers to digits

Default: false

Enable speaker diarization (identify different speakers)

Default: false

Key terms to improve recognition accuracy (Nova-3 only)

interim_results

boolean

Return partial transcripts during streaming (required for low-latency agents)

Default: true

endpointing_ms

integer · min: 10 · max: 5000

Silence duration (ms) before Deepgram considers utterance complete

Default: 300

filler_words

boolean

Include filler words (um, uh) in transcripts

Default: false

profanity_filter

boolean

Filter profanity from transcripts

Default: false

mip_opt_out

boolean

Opt out of model improvement program

Default: false

DialFailureDetail

402 body for outbound dial pre-checks. Audit fix M2: first-class schema for the structured 402 returned when `BillingService.check_call_balance` rejects a call. The frontend keys off `code` rather than substring-matching the human `message`, so backend wording changes can no longer silently flip the override-allowed UI state. Codes: - dnc_blocked → number on org's DNC list; admin can override with `force_dnc_override=true` + reason - dnc_opted_in_blocked → recipient explicitly opted IN to DNC protection; no override permitted - insufficient_credits → ledger short of the call's pre-auth

code

string · required

Machine-readable failure category — see class docstring.

can_override

boolean · required

True when the operator can re-submit with force_dnc_override=true.

message

string · required

Human-readable detail for display.

DialRequest

POST /v1/voice-sessions/outbound — initiate a single phone-channel call.

agent_id

string · uuid · required

to_number

string · minLength: 10 · maxLength: 20 · required

Destination phone number (E.164 format, e.g., +15551234567)

number_id

string · uuid · required

Phone number ID to use for caller ID

Override caller ID number (E.164). Defaults to number_id's DID.

Caller ID display name (max 50 chars).

Dynamic variables injected into agent prompts via {{var}} syntax.

Per-call deep-merged agent config overrides.

force_dnc_override

boolean

When true AND the org has DNC protection_enabled=False, allows the call to proceed even if the destination is on the DNC directory. Requires force_dnc_override_reason. Opt-IN orgs cannot override.

Default: false

Free-text justification for the DNC override (logged to dnc_check_log for audit). Required when force_dnc_override=True.

DialResponse

Response from outbound voice-session creation.

success

boolean · required

to_number

string · required

agent_id

string · uuid · required

EdgeCondition

EmailSubscribeRequest

Email subscription request

email

string · email · required

notify_on

string[]

ExchangeRateResponse

Exchange rate for organization's billing currency.

base_currency

string · required

target_currency

string · required

rate

number · required

FirstMessageConfig

Configuration for agent's first message.

enabled

boolean

Whether to send a greeting message

Default: true

text

string

Greeting message text

Default: Hello! How can I help you today?

delay_ms

integer · min: 0 · max: 5000

Delay before speaking (ms)

Default: 400

allow_interruptions

boolean

Allow user to interrupt greeting

Default: false

GraphData-Input

object[]

GraphData-Output

object[]

GroqModel

string · enum

Enum values:

llama-3.1-8b-instant

meta-llama/llama-4-scout-17b-16e-instruct

openai/gpt-oss-20b

Groq fast inference models - Updated Apr 2026.

GroqModelConfig

Groq fast inference model configuration. SDK Notes: - Parameter is max_completion_tokens (NOT max_tokens) - reasoning_effort: only valid for openai/gpt-oss-20b and openai/gpt-oss-120b Valid values: 'low', 'medium', 'high'. Default: 'medium'. Groq API confirmed — 'none' is NOT valid for gpt-oss models (only for Qwen3).

provider

string · const

Const value: groq

Default: groq

model

string · enum

Groq model to use

Enum values:

llama-3.1-8b-instant

meta-llama/llama-4-scout-17b-16e-instruct

openai/gpt-oss-20b

Default: meta-llama/llama-4-scout-17b-16e-instruct

instructions

string

System prompt/instructions for the model

Default: You are a helpful AI assistant.

System prompt override for written chat channels (SMS and WhatsApp text messages)

System prompt override for voice-first channels (calls and WhatsApp voice notes)

system_timezone

string

Agent's timezone for time-aware responses

Default: UTC

temperature

number · min: 0 · max: 2

Randomness in responses

Default: 0.8

max_completion_tokens

integer · min: 1 · max: 32768

Maximum tokens in response

Default: 4096

tool_choice

string · enum

How to select tools

Enum values:

auto

required

none

Default: auto

Reasoning effort for GPT-OSS reasoning models (openai/gpt-oss-20b, openai/gpt-oss-120b). Only 'low', 'medium', 'high' are valid — 'none' is not supported for these models. None = use API default (medium). Only set when using a reasoning model.

parallel_tool_calls

boolean

Allow the model to call multiple tools in a single response.

Default: true

max_tool_steps

integer · min: 1 · max: 20

Maximum consecutive tool calls per LLM turn.

Default: 3

HTTPValidationError

object[]

HangupResponse

success

boolean · required

call_id

string · required

status

string · required

timestamp

string · required

HangupToolConfig

Configuration for the hangup tool.

enabled

boolean

Enable hangup capability

Default: true

farewell_message

string

Message before ending call

Default: Goodbye!

keywords

string[]

Keywords that trigger hangup consideration

Default: ["goodbye","bye","end call","hang up"]

confirm_before_hangup

boolean

Ask for confirmation before hanging up

Default: false

confirmation_prompt

string

Confirmation message if enabled

Default: Are you sure you'd like to end the call?

HealthCheckResult

name

string · required

status

string · required

required

last_checked

string · date-time · required

HourlyDistribution

Call distribution by hour of day (for heatmaps).

hour

integer · min: 0 · max: 23 · required

Hour of day (0-23)

calls

integer · min: 0

Call count

Default: 0

avg_duration_sec

number · min: 0

Average duration

Default: 0

ImportAccountRequest

Received after the Meta Embedded Signup OAuth popup completes. The frontend sends the auth code + identifiers from the Meta session event.

token_code

string · required

OAuth authorization code from Meta Embedded Signup

phone_number_id

string · required

WhatsApp phone number ID from Meta session event

business_account_id

string · required

WABA ID from Meta session event

IncidentCreate

title

string · required

message

string · required

impact

string

Default: minor

affected_component_ids

string[]

Default: []

component_status

string

Default: degraded

IncidentOut

id

string · uuid · required

title

string · required

status

string · required

impact

string · required

started_at

string · date-time · required

required

object[] · required

affected_components

string[] · required

IncidentUpdateCreate

status

string · required

message

string · required

IncidentUpdateOut

id

string · uuid · required

status

string · required

message

string · required

required

created_at

string · date-time · required

InitiateCallRequest

Initiate an outbound WhatsApp voice call. Mirrors ElevenLabs /whatsapp/outbound-call parameters.

whatsapp_phone_number_id

string · required

whatsapp_user_id

string · minLength: 7 · maxLength: 20 · required

permission_request_template_name

string · required

agent_id

string · uuid · required

permission_request_template_language_code

string

Default: en_US

object[]

Body parameters for the call permission template (named or positional). Leave empty and supply template_body + dynamic_variables to have the server resolve placeholders from the agent variable map.

Raw template body string for the permission-request template. Supplied by the frontend after fetching the definition from Meta. When given, server resolves {{placeholder}} against dynamic_variables to build template_params.

Values for {{var}} placeholders in the agent's first_message and instructions. Persisted on the PendingCallIntent and applied at call placement time (which can be up to 24h after the permission request is sent). Same contract as POST /calls/outbound dynamic_variables.

Example: {"company_name":"Acme","customer_name":"Sarah"}

InterruptionConfig

Configuration for handling user interruptions. Controls when and how the agent stops speaking when the user starts talking. Supports standard VAD (voice activity detection) or native Adaptive AI detection.

enabled

boolean

Allow user to interrupt while agent is speaking.

Default: true

mode

string · enum

vad: standard voice-activity detection; adaptive: ML-based interruption detection (filters out short backchannel noises like 'uh-huh').

Enum values:

vad

adaptive

Default: vad

backchannel_boundary_start

number · min: 0 · max: 5

Start cooldown: suppresses adaptive detection after agent starts speaking. Default: 1.0s

Default: 1

backchannel_boundary_end

number · min: 0 · max: 5

End cooldown: includes late user speech at the end of agent turns. Default: 1.0s

Default: 1

discard_audio_if_uninterruptible

boolean

Drop buffered audio while agent is speaking and cannot be interrupted.

Default: true

min_duration

number · min: 0 · max: 2

Minimum seconds of speech before registering as interruption. Default: 0.5

Default: 0.5

min_words

integer · min: 0 · max: 10

Minimum transcribed words to count as interruption. 0 = audio-only (faster). Default: 0

Default: 0

false_interruption_timeout

number · min: 0.5 · max: 10

Seconds of silence after interruption before deciding it was false. Default: 2.0

Default: 2

resume_false_interruption

boolean

Resume agent speech from where it stopped after a false interruption. Default: True

Default: true

InvitationResponse

A pending invitation.

id

string · required

email

string · required

role

string · required

status

string · required

created_at

string · required

InvitationsListResponse

List of pending invitations.

object[] · required

total_count

integer · required

InviteMemberRequest

Request to invite a member to an organization. Roles: admin, operator, viewer. Permissions come from role.

email

string · email · required

role

string · enum

Enum values:

admin

operator

viewer

Default: operator

InvoiceListResponse

List of invoices with metadata.

object[] · required

object · required

Metadata for billing list responses.

InvoiceResponse

Credit transaction (invoice) details for prepaid billing.

id

string · required

amount_paid

number · required

status

string · required

required

currency

string · required

created

integer · required

amount_due

number

Default: 0

amount_remaining

number

Default: 0

KPIMetric

A single KPI metric with value, trend, and optional formatting.

value

number · required

The numeric value

formatted

string · required

Human-readable formatted value (e.g., '3:42', '85.5%')

Percent change vs previous period

'up', 'down', or 'flat'

Previous period value for comparison

KeyType

string · enum

Enum values:

master

organization

Type of API key.

KnowledgeBaseCreateFromText

Create knowledge base from direct text input.

name

string · minLength: 1 · maxLength: 255 · required

Display name

content

string · minLength: 1 · maxLength: 500000 · required

Text content (up to 500KB)

KnowledgeBaseCreateFromURL

Create knowledge base from URL (web scraping).

name

string · minLength: 1 · maxLength: 255 · required

Display name

url

string · uri · minLength: 1 · maxLength: 2083 · required

URL to scrape content from

KnowledgeBaseListResponse

Lightweight response for list views.

id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

KnowledgeBaseListResult

Paginated list of knowledge bases. Standardized pagination format: - results: List of knowledge bases - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

KnowledgeBaseResponse

Knowledge base response with full details.

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

source_type

string · enum · required

Type of knowledge base source.

Enum values:

url

file

text

size_bytes

integer · required

chunk_count

integer · required

status

string · enum · required

Processing status.

Enum values:

pending

processing

ready

error

created_at

string · date-time · required

updated_at

string · date-time · required

is_active

boolean · required

progress

integer

Default: 0

KnowledgeBaseStatus

string · enum

Enum values:

pending

processing

ready

error

Processing status.

KnowledgeBaseType

string · enum

Enum values:

url

file

text

Type of knowledge base source.

KnowledgeBaseUpdate

Update knowledge base metadata and content.

Updated content for text-based documents

LatencyMetrics

Latency measurements for AI components.

ttft_ms

number · min: 0

Time to First Token (LLM) in milliseconds

Default: 0

ttfb_ms

number · min: 0

Time to First Byte (TTS) in milliseconds

Default: 0

eou_delay_ms

number · min: 0

End-of-utterance VAD delay (silence confirmation after user stops speaking) in milliseconds

Default: 0

asr_p50_ms

number · min: 0

Median ASR latency in milliseconds

Default: 0

Total end-to-end response time

MaintenanceCreate

Request body for creating maintenance

title

string · required

scheduled_start

string · date-time · required

scheduled_end

string · date-time · required

affected_components

string[]

MaintenanceOut

id

string · uuid · required

title

string · required

required

scheduled_start

string · date-time · required

scheduled_end

string · date-time · required

is_active

boolean · required

is_completed

boolean · required

affected_components

string[] · required

affected_component_ids

string[]

MaintenanceUpdate

Request body for updating maintenance

ManualImportRequest

Manual account import using a System User access token. Used when Embedded Signup is unavailable (e.g., App Review pending) or by power users who already have Cloud API configured.

access_token

string · required

System User access token from Meta Business Settings

phone_number_id

string · required

WhatsApp phone number ID from API Setup

business_account_id

string · required

WhatsApp Business Account (WABA) ID

MarkReadResponse

Response for marking notifications as read

success

boolean · required

marked_count

integer · required

McpExecuteRequest

object

McpExecuteResult

success

boolean · required

tool_name

string · required

object

array

is_error

boolean

Default: false

McpProbeResult

Outcome of a connect + ``tools/list`` probe.

success

boolean · required

object[]

tool_count

integer

Default: 0

McpServerCreate

name

string · minLength: 1 · maxLength: 255 · required

server_url

string · uri · minLength: 1 · required

timeout_seconds

integer · min: 1 · max: 300

Default: 30

McpServerListResponse

object[] · required

McpServerRef

Per-agent reference to an MCP server registration. Stored on ``agents.config.tools.mcp_servers``. The agent owns only an ID + per-attachment allowlist; URL/headers/auth live on the ``mcp_servers`` table and are resolved at dispatch time. ``integration_id`` is the legacy name (pre-rebuild) and is accepted as an alias so older saved agent configs keep loading.

server_id

string · required

ID of the MCP server registration

Specific tool names to expose to this agent (None = all)

McpServerResponse

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

server_url

string · required

timeout_seconds

integer · required

McpServerUpdate

McpTool

name

string · required

description

string

Default:

object

McpValidateRequest

Probe a server config WITHOUT persisting it. Use either ``auth_connection_id`` to reuse a stored credential, OR ``inline_headers`` for a one-shot test (the create modal uses inline headers before the auth connection has been created). If both are supplied ``inline_headers`` takes priority.

server_url

string · uri · minLength: 1 · required

timeout_seconds

integer · min: 1 · max: 300

Default: 20

MemberResponse

A team member in the organization.

id

string · required

email

string · required

role

string · required

MembersListResponse

List of organization members.

object[] · required

total_count

integer · required

MessageListResponse

object[] · required

object · required

Pagination metadata in API responses.

MessageResponse

id

string · uuid · required

conversation_id

string · uuid · required

organization_id

string · uuid · required

channel

string · required

direction

string · required

external_message_id

string · required

message_type

string · required

status

string · required

sent_at

string · date-time · required

NodePosition

x

number · required

y

number · required

NodeType

string · enum

Enum values:

conversation

branch

transfer

end_call

sms_send

webhook_call

wait

set_variable

NotFoundError

404 Not Found error response

detail

string · required

NotificationListResponse

Paginated notification list response. Standardized pagination format: - results: List of notifications - metadata: Pagination info (skip, limit, total, has_more, count) - unread_count: Additional notification-specific field

object[] · required

object · required

Pagination metadata in API responses.

unread_count

integer · required

NotificationOut

Notification response schema

id

string · uuid · required

notification_type

string · required

title

string · required

message

string · required

severity

string · required

is_read

boolean · required

created_at

string · date-time · required

NumberAssignResponse

message

string · required

status

string · required

NumberCapRow

One row in the per-region number-cap panel.

region_tier

string · required

region_label

string · required

cap

integer · required

used

integer · required

NumberCapsResponse

sku

string · required

object[] · required

NumberUnassignResponse

message

string · required

status

string · required

OnboardingStatusResponse

Used by the FE to decide whether /outbound should redirect into the first-run wizard. ``completed_at`` is null until the user has either completed or explicitly skipped onboarding.

OpenAIModel

string · enum

Enum values:

gpt-5.4-mini

gpt-5.4-nano

gpt-4.1-mini

gpt-4.1-nano

OpenAI chat models - Updated Apr 2026.

OpenAIModelConfig

OpenAI GPT model configuration. SDK Notes: - Default model in SDK is 'gpt-4.1-mini' - Parameter is max_completion_tokens (NOT max_tokens) - parallel_tool_calls supported

provider

string · const

Const value: openai

Default: openai

model

string · enum

OpenAI model to use

Enum values:

gpt-5.4-mini

gpt-5.4-nano

gpt-4.1-mini

gpt-4.1-nano

Default: gpt-4.1-mini

instructions

string

System prompt/instructions for the model

Default: You are a helpful AI assistant.

System prompt override for written chat channels (SMS and WhatsApp text messages)

System prompt override for voice-first channels (calls and WhatsApp voice notes)

system_timezone

string

Agent's timezone for time-aware responses (e.g., 'America/New_York', 'Europe/London')

Default: UTC

temperature

number · min: 0 · max: 2

Randomness in responses (0=deterministic, 2=creative)

Default: 0.8

Maximum tokens in response

Default: 4096

tool_choice

string · enum

How to select tools

Enum values:

auto

required

none

Default: auto

parallel_tool_calls

boolean

Allow the model to call multiple tools in a single response.

Default: true

max_tool_steps

integer · min: 1 · max: 20

Maximum consecutive tool calls per LLM turn.

Default: 3

Reasoning effort for OpenAI reasoning models. Only 'none', 'minimal', 'low', 'medium', 'high', 'max' are valid.

OrgUsageItem

Usage summary for a single organization.

organization_id

string · required

call_count

integer · required

total_minutes

number · required

total_billed

number · required

OrganizationCreate

Schema for creating a new organization

name

string · minLength: 1 · maxLength: 255 · required

sku

string · enum

Enum values:

pilot

launch

scale

Default: pilot

OrganizationCredentialsUpdate

Schema for updating organization API credentials only

OrganizationResponse

Schema for organization response

id

string · uuid · required

name

string · required

slug

string · required

owner_email

string · email · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

max_agents

integer

Default: 3

max_members

integer

Default: 5

max_concurrent_calls

integer

Default: 5

billing_currency

string

Default: USD

auto_reload_enabled

boolean

Default: false

sku

string

Default: pilot

contract_term

string

Default: month

payment_method

string

Default: stripe_card

stripe_balance_mirror_enabled

boolean

Default: true

bank_payment_terms_days

integer

Default: 15

payment_failed

boolean

Default: false

india_dlt_registered

boolean

Default: false

object

month_to_date_billable_minutes_cache

string · pattern: ^(?!^[-+.]*$)[+-]?0*…

Default: 0

month_to_date_whatsapp_call_minutes_cache

string · pattern: ^(?!^[-+.]*$)[+-]?0*…

Default: 0

scale_cap_override

boolean

Default: false

OrganizationUpdate

Schema for updating organization settings and credentials

OutboundCampaignCreate

Create an outbound campaign. Organization is determined from your API key - no need to specify.

name

string · required

Campaign name

agent_id

string · uuid · required

Agent ID to use for making calls

phone_number_id

string · uuid · required

Phone number ID for caller ID

Call list ID for contacts to call

Campaign description

URL to POST when campaign completes or stops. Receives JSON payload with campaign stats.

object

Call scheduling configuration

object

Campaign configuration

OutboundCampaignResponse

Schema for outbound campaign responses. Phase 1 dropped the dead `calls_made/completed/successful` denormalized counters from the model. Aggregated stats are exposed via GET /v1/campaigns/{id}/stats (CampaignStats below) which sources from campaign_attempts.

name

string · minLength: 1 · maxLength: 255 · required

Campaign name

id

string · uuid · required

organization_id

string · uuid · required

agent_id

string · uuid · required

phone_number_id

string · uuid · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

Campaign description

object

Call scheduling configuration

object

Campaign configuration

OutboundCampaignUpdate

Schema for updating outbound campaigns. Phase 3 removed the `status` field from this schema. State changes happen ONLY through the dedicated lifecycle endpoints (/start, /pause, /resume, /stop, /cancel) which funnel through the state machine in `app/domains/campaigns/state.py`. PUT /campaigns/{id} is for editing config (name, schedule, pacing, etc.) only.

Campaign name

Campaign description

URL to POST on campaign completion/stop

Agent ID for the campaign

Phone number ID for caller ID

Call list ID for contacts to call

Call scheduling configuration

Campaign configuration

PaginationMetadata

Pagination metadata in API responses.

skip

integer · min: 0 · required

Number of records skipped

limit

integer · min: 1 · required

Maximum records requested

total

integer · min: 0 · required

Total records available

has_more

boolean · required

Whether more records exist

count

integer · min: 0 · required

Number of records in this page

ParticipantInfo

participant_identity

string · required

participant_type

string · required

joined_at

string · date-time · required

duration_seconds

integer

Default: 0

PaymentMethodListResponse

List of payment methods with metadata.

object[] · required

object · required

Metadata for billing list responses.

PaymentMethodResponse

Payment method details.

id

string · required

brand

string · required

last4

string · required

exp_month

integer · required

exp_year

integer · required

is_default

boolean · required

Permission

string · enum

Enum values:

admin:all

admin:organizations

dashboard:view

agents:view

agents:create

agents:edit

agents:delete

agents:duplicate

All 63 permissions in the system. Format: resource:action (flat strings, no nesting)

These are used by:

Backend: RequirePermission(Permission.AGENTS_CREATE)
Frontend: can("agents:create")
API Keys: scopes = ["agents:view", "agents:create"]

PhantomModelConfig

Neuratel Phantom LLM — proprietary inference via phantom.neuratel.ai.

provider

string · const

Const value: phantom

Default: phantom

model

string

Phantom Brain model

Default: phantom

instructions

string

System prompt/instructions for the model

Default: You are a helpful AI assistant.

System prompt override for written chat channels (SMS and WhatsApp text messages)

System prompt override for voice-first channels (calls and WhatsApp voice notes)

system_timezone

string

Agent's timezone for time-aware responses

Default: UTC

temperature

number · min: 0 · max: 2

Randomness in responses

Default: 0.8

Reasoning effort for Phantom models (DeepInfra). 'none' disables thinking. None = use API default. All four Phantom models accept all five values.

Maximum tokens in response

Default: 4096

tool_choice

string · enum

How to select tools

Enum values:

auto

required

none

Default: auto

parallel_tool_calls

boolean

Allow the model to call multiple tools in a single response.

Default: true

max_tool_steps

integer · min: 1 · max: 20

Maximum consecutive tool calls per LLM turn.

Default: 3

PhantomTranscriberConfig

Phantom STT provider configuration.

provider

string · const

Const value: phantom

Default: phantom

model

string

Default: phantom-stt-v1

language

string

Default: auto

PhantomVoiceConfig

Neuratel Phantom TTS — proprietary voice synthesis.

provider

string · const

Const value: phantom

Default: phantom

model

string

Phantom Speech model (phantom-english-speech-preview or phantom-arabic-speech-preview)

Default: phantom-english-speech-preview

voice

string

Phantom preset voice. English: aria, bella, claire, alex, david, marcus. Arabic: omar, tariq, layla, nour.

Default: aria

PhoneNumberCreate

Create phone number request

did

string · required

name

string · required

PhoneNumberListResponse

Paginated list of phone numbers. Standardized pagination format: - results: List of phone numbers - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

PhoneNumberResponse

Phone number details

id

string · uuid · required

did

string · required

name

string · required

organization_id

string · uuid · required

required

is_active

boolean · required

formatted_number

string · required

required

capabilities

string[]

tags

string[]

inbound_webhook_secret_set

boolean

Default: false

PhoneNumberUpdate

Update phone number request

PipelineTurnDetection

Turn detection configuration for voice pipeline agents. Modes: - semantic_vad: Silero VAD + multilingual context-aware EOU model (60+ languages) - semantic_vad_en: Silero VAD + English-only context-aware EOU model — faster - vad: Silero VAD only — fast, silence-based detection - stt: STT-native EOU (auto-selected for Soniox; Soniox owns turn-end detection) All modes still use Silero VAD for barge-in / interruption detection. Semantic modes add an ML layer to decide whether a pause means "done" vs "thinking". Pair with Interruption mode for coherent behavior: - semantic_vad → vad interruptions - semantic_vad_en → vad interruptions - vad → vad interruptions - stt → vad interruptions Endpointing timing (EndpointingOptions, applies to vad/semantic_vad/semantic_vad_en): - min_delay: minimum wait after end-of-utterance before agent responds - max_delay: ceiling — agent commits the turn after this long even if the detector model is still uncertain - endpointing_mode: - "fixed": agent waits min_delay; extends up to max_delay only if turn-detector is uncertain - "dynamic": adapts effective wait within [min_delay, max_delay] based on this caller's pause patterns (exponential moving average) For mode="stt" (Soniox), these knobs are unused — Soniox handles EOU internally via its built-in semantic endpointing (no per-call tuning).

mode

string · enum

Turn detection mode

Enum values:

vad

semantic_vad

semantic_vad_en

stt

Default: semantic_vad

Minimum seconds after end-of-utterance before responding. Default: 0.5

Default: 0.5

Ceiling — agent commits the turn after this long even if detector is uncertain. Default: 3.0

Default: 3

fixed: agent waits min_delay; extends up to max_delay only if turn-detector is uncertain. dynamic: adapts effective wait within [min_delay, max_delay] based on this caller's pause patterns.

Default: dynamic

PipelineTurnDetectionMode

string · enum

Enum values:

vad

semantic_vad

semantic_vad_en

stt

Turn detection modes for pipeline agents.

PlaceOutboundCallConfig

Configuration for the place_outbound_call tool. Lets the LLM initiate an outbound call to a phone number on demand — works from voice calls (cross-channel) or WhatsApp chat sessions.

enabled

boolean

Enable place_outbound_call capability

Default: false

permission_request_template_name

string

WhatsApp template name for permission requests (when channel='whatsapp')

Default: call_permission_request

permission_request_template_language_code

string

Language code for the permission template

Default: en_US

PlatformRevenueResponse

Platform-wide revenue summary (admin only).

call_count

integer · required

total_minutes

number · required

total_revenue

number · required

total_cost

number · required

total_margin

number · required

margin_percentage

number · required

PostCallConfig

Configuration for post-call analysis. AnalysisPlan is the only tree.

Post-call analysis configuration

ProfileUpdate

PublicIncidentReport

email

string · email · required

template_id

string · required

affected_component_ids

string[]

PublishRequest

version_number

integer · required

RAGQueryRequest

RAG query request from worker.

query

string · minLength: 1 · maxLength: 2000 · required

User's question/query

knowledge_base_ids

string[] · minItems: 1 · required

KB IDs to search

top_k

integer · min: 1 · max: 10

Number of results to return

Default: 3

RAGQueryResponse

RAG query response with results.

object[] · required

query

string · required

total_chunks_searched

integer · required

RAGResult

Single RAG result chunk.

text

string · required

score

number · min: 0 · max: 1 · required

Relevance score

knowledge_base_id

string · uuid · required

knowledge_base_name

string · required

chunk_index

integer · required

RagConfig

Configuration for RAG (Retrieval-Augmented Generation).

enabled

boolean

Enable RAG capability

Default: false

knowledge_base_ids

string[]

Knowledge base IDs to query

top_k

integer · min: 1 · max: 20

Maximum chunks to retrieve per query

Default: 5

score_threshold

number · min: 0 · max: 1

Minimum relevance score

Default: 0.7

include_metadata

boolean

Include chunk metadata in context

Default: true

context_template

string

Template for injecting context

Default: Here is relevant information: {chunks}

RecordingConfig

Configuration for call recording.

enabled

boolean

Enable call recording

Default: false

retention_days

integer · enum

Days to retain recordings. -1 = forever

Enum values:

7

30

-1

Default: 30

RecordingResponse

Recording for a voice session.

id

string · uuid · required

created_at

string · date-time · required

status

string

Default: pending

RegisterAndAcceptRequest

Request body for registering a new user and accepting invitation.

name

string · minLength: 1 · maxLength: 128 · required

User's display name

password

string · minLength: 8 · maxLength: 128 · required

Account password

RoleType

string · enum

Enum values:

super_admin

admin

operator

viewer

Role hierarchy for the platform.

Hierarchy (highest to lowest):

super_admin: God mode, full platform access, system-wide operations
admin: Full organization access, can manage members and settings
operator: Can view/edit/test resources, cannot create/delete/manage
viewer: Read-only access to organization resources

SaveGraphRequest

object · required

SendAudioMessageConfig

Configuration for the send_audio_message tool. Lets the LLM send a TTS-generated voice note to the current contact via WhatsApp. Uses the agent's configured voice provider.

enabled

boolean

Enable send_audio_message capability

Default: false

max_text_length

integer · min: 50 · max: 2000

Maximum text length for TTS generation

Default: 500

tool_fillers_enabled

boolean

Enable progress-indicating talking fillers during audio compilation and send

Default: true

tool_fillers_pool

string[]

Rotating filler phrases to speak during voice note generation

SendDtmfConfig

Configuration for sending DTMF tones.

enabled

boolean

Enable DTMF sending

Default: false

tone_duration_ms

integer · min: 50 · max: 500

Duration of each tone in ms

Default: 100

gap_duration_ms

integer · min: 50 · max: 500

Gap between tones in ms

Default: 100

SendMessageResponse

wa_message_id

string · required

status

string · required

conversation_id

string · uuid · required

SendTemplateMessageRequest

Initiate a conversation by sending an approved template message. Mirrors ElevenLabs /whatsapp/outbound-message parameters.

whatsapp_phone_number_id

string · required

Our WhatsApp phone number ID

whatsapp_user_id

string · minLength: 7 · maxLength: 20 · required

Recipient's WhatsApp ID (E.164 phone number)

template_name

string · minLength: 1 · maxLength: 255 · required

template_language_code

string · maxLength: 10

Default: en_US

object[]

Body parameters for the template. Each item is {name, value}. name is '1'..'N' for positional templates or the placeholder identifier for named templates (e.g. 'customer_name'). Leave empty and supply template_body + dynamic_variables to have the server auto-resolve from the agent variable map.

Raw template body string (with {{placeholder}} markers) — supplied by the frontend after fetching the template definition from Meta's registry. When provided alongside dynamic_variables and an empty template_params, the server resolves placeholders from the agent variable map (named OR positional templates). Bridges the agent-side and Meta-side substitution moments.

Per-conversation runtime variable map. Used to fill template_body placeholders when template_params is empty, AND persisted onto Conversation.dynamic_variables so the agent's reply path picks them up after the contact responds. Mirrors the voice-call dispatch contract (POST /v1/voice-sessions/outbound).

Example: {"customer_name":"Sarah","order_id":"ABC-123"}

Meta WABA category of this template — one of MARKETING, UTILITY, AUTHENTICATION, AUTHENTICATION_INTERNATIONAL, SERVICE, MARKETING_LITE. Pulled from Meta's template registry by the frontend before send. Used to bill the right rate at send time (per-category passthrough) and grouped by the daily true-up cron. Defaults to MARKETING (most expensive bucket) when omitted; truesup reconciles via manual_adjustment ledger.

Agent to associate with the resulting conversation

SendTextRequest

Send a free-form text message inside the active 24h session window.

whatsapp_phone_number_id

string · required

Our WhatsApp phone number ID

whatsapp_user_id

string · minLength: 7 · maxLength: 20 · required

Recipient's WhatsApp E.164 ID

body

string · minLength: 1 · maxLength: 4096 · required

Client-supplied ID for optimistic UI reconciliation

SendWhatsAppMessageConfig

Configuration for the send_whatsapp_message tool. Lets the LLM send plain text, interactive buttons, or document (PDF) messages directly to the customer's WhatsApp chat history in real-time during a live voice call.

enabled

boolean

Enable send_whatsapp_message capability during calls

Default: false

tool_fillers_enabled

boolean

Enable progress-indicating talking fillers during rich message send

Default: true

tool_fillers_pool

string[]

Rotating filler phrases to speak during message push

SentimentTimeline

trend

string · required

average_sentiment

number · required

object

object[]

SentimentTurn

turn

integer · required

role

string · required

text

string · required

sentiment

number · required

emotion

string · required

SetupIntentResponse

Setup intent for adding payment method.

client_secret

string · required

setup_intent_id

string · required

SlackSubscribeRequest

Slack webhook subscription request

webhook_url

string · required

Slack Incoming Webhook URL

Channel name for display (e.g. #status-alerts)

notify_on

string[]

SonioxModel

string · enum

Enum values:

stt-rt-v5

stt-rt-v4

Soniox real-time STT models.

SDK Default: model="stt-rt-v4". Single unified model handles 60+ languages including English + Arabic with native code-switching and built-in semantic EOU.

SonioxTranscriberConfig

Soniox v4 STT provider configuration. Soniox owns end-of-utterance detection internally via semantic endpointing, so the worker auto-routes turn_detection.mode to "stt" when this provider is selected. The platform's standalone semantic turn-detection model is bypassed.

provider

string · const

Const value: soniox

Default: soniox

model

string · enum

Soniox real-time STT models.

SDK Default: model="stt-rt-v4". Single unified model handles 60+ languages including English + Arabic with native code-switching and built-in semantic EOU.

Enum values:

stt-rt-v5

stt-rt-v4

Default: stt-rt-v4

ISO codes Soniox should bias toward (e.g. ['en', 'ar']). If None, Soniox auto-detects across all supported languages.

language_hints_strict

boolean

When True, restrict transcription to only the hinted languages

Default: false

enable_speaker_diarization

boolean

Identify and label different speakers in the transcript

Default: false

enable_language_identification

boolean

Tag each token with its detected language (useful for multilingual)

Default: true

interim_results

boolean

Return partial transcripts while user is speaking (always on for Soniox)

Default: true

SortOrder

string · enum

Enum values:

ASC

DESC

Sort order for list endpoints

StatusOverview

overall_status

string · required

uptime_30d

number · required

avg_response_time_ms

number · required

active_incidents_count

integer · required

object[] · required

StripeCustomerRequest

Request to create a Stripe customer.

email

string · required

name

string · required

StripeCustomerResponse

Stripe customer creation response.

customer_id

string · required

SuccessEvaluationRubric

string · enum

Enum values:

NumericScale

DescriptiveScale

Checklist

Matrix

PercentageScale

LikertScale

AutomaticRubric

PassFail

Rubric types for success evaluation.

SupervisorJoinResponse

success

boolean · required

mode

string · enum · required

Enum values:

listen

whisper

barge

call_id

string · required

token

string · required

required

supervisor_identity

string · required

object · required

timestamp

string · required

SupervisorPermissions

can_hear

boolean

Default: true

can_speak

boolean

Default: false

can_speak_to_agent

boolean

Default: false

can_speak_to_customer

boolean

Default: false

visible_to_participants

boolean

Default: false

TTSTextTransform

string · enum

Enum values:

filter_markdown

filter_emoji

TTS text transforms.

Transforms to apply to TTS input text before sending to provider. Set to None to disable all transforms.

TemplateComponentResponse

type

string · required

TemplateListResponse

object[] · required

TemplateParam

Single body parameter for a WhatsApp template. `name` is the placeholder identifier from the template body: - "1", "2", ... for positional templates ("Hi {{1}}, ...") - "customer_name" for named templates ("Hi {{customer_name}}, ...") `value` is the substituted text. Per Meta Cloud API: positional templates send `[{type:"text",text}]`; named templates send `[{type:"text",text,parameter_name}]`.

name

string · minLength: 1 · maxLength: 64 · required

value

string · maxLength: 1024 · required

TemplateResponse

id

string · required

name

string · required

language

string · required

status

string · required

category

string · required

object[]

Default: []

has_call_permission

boolean

Default: false

ThinkingAudioConfig

Configuration for thinking/processing audio. Thinking sound plays while the agent is in the "thinking" state. Use BuiltinAudioClip presets (KEYBOARD_TYPING, KEYBOARD_TYPING_2) or custom URL/path.

enabled

boolean

Enable thinking sounds

Default: false

Built-in audio clip or custom URL/path to audio file

Default: keyboard_typing

volume

number · min: 0 · max: 1

Thinking audio volume

Default: 0.8

TimeRange

string · enum

Enum values:

today

yesterday

this_week

last_week

this_month

last_month

last_7_days

last_30_days

Predefined time ranges.

TimeoutConfig

Configuration for user silence timeouts.

enabled

boolean

Enable timeout handling

Default: true

trigger_seconds

number · min: 5 · max: 120

Seconds of silence before triggering

Default: 15

warning_count

integer · min: 0 · max: 5

Number of warning messages before ending

Default: 2

warning_messages

string[]

Messages to prompt user

Default: ["Are you still there?","Hello?"]

final_message

string

Message before ending call

Default: I'll end the call now. Goodbye!

TokenHealthResponse

phone_number_id

string · required

healthy

boolean · required

ToolChoice

string · enum

Enum values:

auto

required

none

Tool calling modes.

ToolsConfig

Complete tools configuration. Enables and configures various agent capabilities including built-in tools, RAG, and MCP integrations.

object

Hangup tool settings

object

DTMF collection settings

object

DTMF sending settings

object

Voicemail detection settings

object

In-call do-not-call opt-out tool

object

Outbound call initiation tool

object

WhatsApp voice note sending tool

object

WhatsApp message sending tool during calls

object

RAG settings

object[]

MCP server integrations

TopUpIntentResponse

Response with PaymentIntent details for frontend.

amount_cents

integer

Default: 0

amount_dollars

number

Default: 0

currency

string

Default: USD

requires_action

boolean

Default: false

succeeded

boolean

Default: false

error

boolean

Default: false

TopUpRequest

Request to create a top-up payment.

amount

number · required

TransferConfig

Complete transfer configuration. Controls how calls are transferred to other destinations including agents, teams, or external numbers.

enabled

boolean

Enable transfer capability

Default: false

mode

string · enum

Transfer type: blind (immediate) or warm (with intro)

Enum values:

blind

warm

Default: blind

object[]

Available transfer destinations

Default destination if no match

warm_intro_template

string

Template for warm transfer introduction

Default: Hi, I'm transferring a caller who needs help with {reason}. They said: {summary}

warm_intro_timeout_seconds

integer · min: 10 · max: 180

Time to wait for warm intro before falling back

Default: 60

on_fail

string · enum

What to do if transfer fails

Enum values:

hangup

return

voicemail

Default: return

fail_message

string

Message on transfer failure

Default: I'm sorry, I wasn't able to transfer your call. Let me help you directly.

max_retries

integer · min: 0 · max: 5

Maximum transfer retry attempts

Default: 2

hold_music

boolean

Play hold music during transfer

Default: true

Custom hold music URL

announce_position

boolean

Announce queue position if applicable

Default: false

TransferDestination

Configuration for a transfer destination.

id

string · required

Unique identifier for this destination

name

string · required

Display name (e.g., 'Sales Team', 'Support')

number

string · required

Phone number in E.164 format

keywords

string[]

Keywords that trigger this destination

Description for LLM context (when to use this)

message

string

Message before transferring

Default: Transferring you now.

timeout_seconds

integer · min: 10 · max: 120

Ring timeout before giving up

Default: 30

priority

integer · min: 0 · max: 100

Priority when multiple match (higher = preferred)

Default: 0

Working hours for this destination

TransferMode

string · enum

Enum values:

blind

warm

Transfer mode types.

TransferOnFail

string · enum

Enum values:

hangup

return

voicemail

Actions when transfer fails.

UnreadCountResponse

Unread notification count response

unread_count

integer · required

UpdateAccountRequest

Partial update — all fields optional.

UpdateMemberPermissionsRequest

Request to update a member's custom permissions.

object · required

UpdateRoleRequest

Request to update a member's role.

role

string · enum · required

Enum values:

admin

operator

viewer

UpdateWorkflowRequest

UsageMetrics

object

UsageSummaryResponse

Usage summary for an organization.

call_count

integer · required

total_seconds

integer · required

total_minutes

number · required

total_billed

number · required

ValidationError

array · required

msg

string · required

type

string · required

input

ctx

object

VariableCoverageStat

filled

integer · required

total

integer · required

pct

number · required

VoiceFilterOptions

Available filter options for dropdowns.

providers

string[] · required

categories

string[] · required

genders

string[] · required

languages

string[] · required

accents

string[] · required

ages

string[] · required

use_cases

string[] · required

VoiceListResponse

Response with voices and filter metadata.

object[] · required

object · required

total

integer · required

object · required

VoiceLocalizeRequest

Request schema for Cartesia voice localization.

voice_id

string · required

language

string · required

VoiceResponse

Single voice response with all metadata.

id

string · required

display_id

string · required

provider

string · required

provider_voice_id

string · required

provider_voice_name

string · required

is_premium

boolean

Default: false

is_cloned

boolean

Default: false

VoiceSessionListResponse

object[] · required

object · required

Pagination metadata in API responses.

VoiceSessionResponse

One voice session — phone, web, or WhatsApp voice.

id

string · uuid · required

channel

string · required

status

string · required

created_at

string · date-time · required

updated_at

string · date-time · required

analysis_status

string

Default: pending

retry_count

integer

Default: 0

duration_seconds

integer

Default: 0

object[]

object[] · maxItems: 5

conversation_turn_count

integer

Default: 0

sentiment_trend

number[]

topics_discussed

string[]

keywords_extracted

string[]

object

object[]

object

topics

string[]

action_items

string[]

object

VoiceSessionUpdate

Partial update for a voice session. Only `call_metadata` is mutable today: operators attach CRM IDs / ticket numbers / post-call notes after the call ends. The dict is JSONB-merged into the existing column (not replaced wholesale). Other fields are either auto-managed (status, timing — written by the media-server webhook receiver) or don't exist on the schema (no `tags` column).

object · required

Keys to merge into the existing call_metadata JSONB column.

VoiceSyncResponse

Response from voice sync operation.

success

boolean · required

message

string · required

cartesia_synced

integer · required

total_synced

integer · required

VoicemailAction

string · enum

Enum values:

hangup

leave_message

continue

Actions when voicemail is detected.

VoicemailToolConfig

Configuration for voicemail/answering machine detection. The LLM detects voicemail patterns (greetings, beeps) and triggers configured actions. This is LLM-based detection, not carrier AMD.

enabled

boolean

Enable voicemail detection

Default: true

action

string · enum

Action when voicemail is detected

Enum values:

hangup

leave_message

continue

Default: hangup

message

string

Message to leave if action is leave_message

Default: Hi, this is a message from your assistant. I'll try calling back later.

wait_for_beep

boolean

Wait for the beep before leaving message

Default: true

post_message_delay_ms

integer · min: 0 · max: 2000

Delay after message before hanging up (ms)

Default: 500

WebhookConfig

Configuration for webhook notifications.

enabled

boolean

Enable webhook notifications

Default: false

HTTPS endpoint URL

events

string[]

Events to send webhooks for

Enum values:

session_report

call_ended

analysis_complete

error

Default: ["session_report","call_ended","error"]

include_transcript

boolean

Include transcript in webhook payload

Default: true

include_analytics

boolean

Include analytics in webhook payload

Default: true

include_recording_url

boolean

Include recording URL when available (always included by default)

Default: true

auth_header

string

Authentication header name

Default: Authorization

Authentication token (Bearer format)

retry_count

integer · min: 0 · max: 10

Number of retry attempts

Default: 3

timeout_seconds

number · min: 5 · max: 120

Webhook request timeout

Default: 30

WebhookCreate

Create a new webhook subscription

name

string · minLength: 1 · maxLength: 255 · required

Human-readable name for the webhook

url

string · required

HTTPS endpoint URL to receive webhook events

Optional description

events

string[]

List of event types to subscribe to. Empty = all events

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Optional custom header name for authentication (e.g., 'X-Api-Key')

Value for the auth header

timeout_seconds

integer · min: 1 · max: 60

Request timeout in seconds (1-60)

Default: 30

max_retries

integer · min: 0 · max: 5

Maximum retry attempts on failure (0-5)

Default: 3

is_active

boolean

Whether the webhook is active

Default: true

WebhookCreateResponse

Response when creating a webhook - includes secret

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

secret

string · required

HMAC secret for validating webhook signatures. Store securely - only shown once!

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

WebhookDeliveryLogResponse

Webhook delivery attempt log

id

string · uuid · required

webhook_id

string · uuid · required

event_type

string · required

required

request_url

string · required

required

success

boolean · required

required

attempt_number

integer · required

created_at

string · date-time · required

WebhookDeliveryLogsResponse

Paginated delivery logs

object[] · required

total

integer · required

skip

integer · required

limit

integer · required

WebhookEvent

string · enum

Enum values:

session_report

call_ended

analysis_complete

error

Per-agent webhook event types — only events the worker actually fires.

Org-level webhooks live in app.schemas.webhook.WebhookEventType (dot- notation values like 'recording.ready'); they are sent by Platform, not by the worker, and are out of scope for this enum.

WebhookEventTypeEnum

string · enum

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Available webhook event types

WebhookListResponse

Paginated list of webhooks. Standardized pagination format: - results: List of webhooks - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

object · required

Pagination metadata in API responses.

WebhookResponse

Webhook subscription response

id

string · uuid · required

Unique webhook identifier

organization_id

string · uuid · required

Organization this webhook belongs to

name

string · required

Display name for this webhook

url

string · required

HTTPS endpoint that receives event payloads

events

string[] · required

Event types this webhook subscribes to

is_active

boolean · required

Whether this webhook is enabled. Auto-disabled after 10 consecutive delivery failures

timeout_seconds

integer · required

Request timeout per delivery attempt in seconds

max_retries

integer · required

Maximum retry attempts on delivery failure

failure_count

integer · required

Consecutive delivery failures since last success

created_at

string · date-time · required

Creation timestamp

updated_at

string · date-time · required

Last update timestamp

Optional description

Custom header name sent with each request (e.g. X-Api-Key)

Reason this webhook was auto-disabled, if applicable

Timestamp of last successful delivery

Timestamp of last failed delivery attempt

WebhookRotateSecretResponse

secret

string · required

message

string · required

WebhookTestRequest

Test a webhook with a sample payload

event_type

string · enum

Event type to simulate

Enum values:

call.started

call.ended

call.ringing

call.answered

call.failed

call.transferred

transcript.partial

transcript.final

Default: call.started

WebhookTestResponse

Result of webhook test

success

boolean · required

required

duration_ms

integer · required

WebhookUpdate

Update an existing webhook subscription

WorkflowDetailResponse

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

is_active

boolean · required

current_version

integer · required

created_at

string · date-time · required

updated_at

string · date-time · required

object[]

Default: []

WorkflowEdge

id

string · required

source

string · required

target

string · required

WorkflowListResponse

object[] · required

object · required

Pagination metadata in API responses.

WorkflowNode

id

string · required

type

string · enum · required

Enum values:

conversation

branch

transfer

end_call

sms_send

webhook_call

wait

set_variable

object · required

object

WorkflowResponse

id

string · uuid · required

organization_id

string · uuid · required

name

string · required

is_active

boolean · required

current_version

integer · required

created_at

string · date-time · required

updated_at

string · date-time · required

WorkflowRevisionResponse

id

string · uuid · required

workflow_id

string · uuid · required

version_number

integer · required

status

string · enum · required

Enum values:

draft

published

archived

object · required

created_at

string · date-time · required

WorkflowRevisionStatus

string · enum

Enum values:

draft

published

archived

WorkingHoursConfig

Configuration for destination working hours.

enabled

boolean

Enable working hours restrictions

Default: false

days

integer[]

Days available (0=Sunday, 1=Monday, ...)

Default: [1,2,3,4,5]

start_time

string

HH:MM format

Default: 09:00

end_time

string

End time (HH:MM format)

Default: 17:00

timezone

string

Timezone for working hours

Default: America/New_York

unavailable_message

string

Message when outside working hours

Default: This team is currently unavailable. Please try again during business hours.

KnowledgeBaseFileUpload

Upload a file to create a knowledge base.

name

string · required

Display name for the knowledge base

file

string · binary · required

File to upload (txt, md, html, pdf, docx, epub)

Optional description

Schemas

APIKeyCreate

APIKeyListMetadata

APIKeyListResponse

APIKeyResponse

APIKeyRotateResponse

APIKeyWithSecret

AccountListResponse

AccountResponse

ActiveCallInfo

ActiveCallParticipant

ActiveCallsResponse

AddToDncConfig

AdminAdjustCreditsRequest

AdminAdjustCreditsResponse

AdminBillingOverridesRequest

AdminBillingOverridesResponse

AdminDNCAddRequest

AdminPilotActionResponse

AdminPilotConvertRequest

AdminPilotConvertResponse

AgentAssignRequest

AgentCallRequest

AgentCallResponse

AgentCreate

AgentKnowledgeBaseAssignment

AgentKnowledgeBaseListResponse

AgentListResponse

AgentMetricsSummary

AgentPerformance

AgentRequiredVariablesResponse

AgentResponse

AgentRestoreResponse

AgentUpdate

AgentVersionEntry

AgentVersionListResponse

AgentVersionResponse

AllOrgsUsageResponse

AmbientAudioConfig

AnalysisPlan

AnalyticsConfig

AnalyticsDashboardResponse

AnnouncementRequest

AuthConnectionCreate

AuthConnectionListResponse

AuthConnectionResponse

AuthConnectionUpdate

AuthContextResponse

AutoReloadSettingsRequest

AutoReloadSettingsResponse

BackchannelConfig

BackgroundAudioConfig

BadRequestError

BalanceCheckResponse

BalanceHistoryResponse

BalanceResponse

BalanceTransactionResponse

BatchCallRequest

BatchCallResponse

BillingListMetadata

BillingPortalRequest

BillingPortalResponse

BillingSettingsResponse

BuiltinAudioClip

BulkPasteContactRow

BulkPasteContactsRequest

BulkPasteContactsResponse

CallDurationConfig

CallListContactCreate

CallListContactResponse

CallListContactUpdate

CallListCreate

CallListResponse

CallListUpdate

CallListsListResponse

CallOutcomeBreakdown

CallPermissionStatusResponse

CallResponse

CallSchedule

CallStatusResponse