API reference

Voice sessions

What this covers#

One session is one call. Create it to get a single-use WebSocket URL for browser audio, or dial out on your own carrier line. Billing is settled from connected seconds when the session ends.

Every example below runs as written once these are exported:

bash

export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export PROJECT_ID="<uuid>"
export SESSION_ID="<uuid>"

A <value> inside a JSON body is a value you supply. Responses are JSON; every error body is { "detail": … }. Each schema is expanded once per page, where it first appears.

Machine door errors#

Raised by the project-key dependency before any handler on this page runs.

Status	Cause
`401`	`Missing API key` or `Invalid API key` — the `X-Api-Key` header is absent, unknown, or revoked.
`403`	`API key is not scoped to a project`, `Project unavailable`, or `API key is missing the required scope '<scope>'`.
`429`	The project's `api_rpm` ceiling was exceeded. Honour `Retry-After`; `X-RateLimit-*` headers are on every response.

Scopes used on this page: voice:read, voice:write. Mint a key with only these.

Account door errors#

Status	Cause
`401`	No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate.
`403`	The account is suspended or its email is not verified.

Operations — project API key#

Call these from your own server with a project key. Never from a browser or a mobile bundle.

GET `/v2/voice/sessions`#

List sessions newest first, filtered by status, agent or date range.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`voice:read`
Operation	`list_voice_sessions_v2_voice_sessions_get`
Success	`200` `VoiceSessionInfo[]`

Parameter	In	Type	Required	Notes
`limit`	query	integer	no
`offset`	query	integer	no
`status`	query	string or null	no
`agent_id`	query	uuid or null	no
`from`	query	date-time or null	no
`to`	query	date-time or null	no
`has_insights`	query	boolean or null	no	true for sessions whose post-call analysis produced a result; false for every other session.

`VoiceSessionInfo`#

Field	Type	Required	Notes
`agent_id`	uuid or null	yes
`agent_version`	integer or null	yes
`connected_seconds`	integer	yes
`cost_minor`	string	yes
`cost_nano_usd`	string or null	yes
`created_at`	date-time	yes
`currency`	string	yes
`direction`	string	yes
`end_reason`	string or null	yes
`ended_at`	date-time or null	yes
`handoffs`	CallHandoffsInfo or null	no
`hold_minor`	string	yes
`hold_nano_usd`	string or null	yes
`id`	uuid	yes
`insights`	CallInsightsInfo or null	no
`language`	string	yes
`max_duration_seconds`	integer	yes
`media_connected_at`	date-time or null	yes
`media_disconnected_at`	date-time or null	yes
`metadata`	object or null	yes
`money_scale`	integer	yes
`pipeline_mode`	string	yes
`pipeline_snapshot`	object	yes
`project_id`	uuid	yes
`project_revision`	integer	yes
`rate_nano_usd_per_min`	string or null	yes
`rate_per_minute_minor`	string	yes
`rate_version`	string	yes
`record`	boolean	yes
`recording_ref`	object or null	no	Where this call's audio is, or null when there is none. The audio lives in your own carrier account and is fetched with your own carrier credentials, not ours — Dvaarik does not store call recordings. The block is {provider, reference_id, url, fetched_from}: `fetched_from` is "carrier" when your carrier holds the recording (a null `reference_id` there means the carrier accepted the request and will name the recording on its own webhook), and "unavailable" with a `detail` sentence when the carrier could not be asked at all. Browser and bring-your-own-socket sessions have no carrier, so they have no recording and this is always null for them — there is no fallback, because a fallback would mean us storing the audio again.
`retention_note`	string or null	no
`sample_rate_in`	integer	yes
`sample_rate_out`	integer	yes
`started_at`	date-time or null	yes
`status`	string	yes
`store_transcript`	boolean	yes
`timings`	CallTimingsInfo or null	no
`zero_retention`	boolean	no	default false

`CallHandoffsInfo`#

Who spoke when, on a call whose agent may hand it to another agent of the project (L15).

Field	Type	Required	Notes
`handoffs`	integer	no	default 0; Hand-offs made on this call (a return after one counts too).
`refused`	integer	no	default 0; Hand-offs the agents asked for that could not happen.
`segments`	CallHandoffSegment[]	no	Each agent's part, in order.

`CallInsightsInfo`#

What one call's analysis produced, as the session read returns it. status is pending while the analysis is queued, so a developer polling a session can tell "it is coming" from "this agent does not do analysis" (in which case the whole object is absent, not a status of its own).

Field	Type	Required	Notes
`error`	string or null	no	One short clause when status is failed. Never a provider response body and never a prompt.
`fallback_used`	boolean	no	default false; Whether the agent's fallback language model (pipeline_config.llm_fallback) answered any part of this call because its main model failed. The detail (from which turn, and why) is on the session read, timings.fallback.
`fields`	object	no
`generated_at`	date-time or null	no
`model`	string or null	no
`provider`	string or null	no
`status`	string	yes
`summary`	string or null	no
`transcript_truncated`	boolean	no	default false

`CallTimingsInfo`#

How fast each part of the call answered (L12), from at most the first 50 replies. A part that never ran is absent, never 0. Speech-to-speech (realtime) sessions report no timings yet.

Field	Type	Required	Notes
`fallback`	CallFallbackInfo or null	no	Which language model answered (pipeline_config.llm_fallback). Null when the agent has no fallback.
`greeting_ms`	integer or null	no	The agent started on the call -> its first audio, in milliseconds.
`llm_first_token_ms`	CallTimingStage or null	no	Every model request -> its first token (discarded guesses and tool follow-ups included).
`reply_ms`	CallTimingStage or null	no	The caller's words were understood -> the first sound of the reply. A holding phrase such as 'One moment' counts as the first sound.
`tts_first_audio_ms`	CallTimingStage or null	no	Every time the voice was asked to speak -> its first audio (greeting and holding phrases included).
`turns`	integer or null	no	Replies measured (at most the first 50).

`CallFallbackInfo`#

Which language model answered (L14): present on every call of an agent with a fallback.

Field	Type	Required	Notes
`available`	boolean	no	default true; False when the call could not use the fallback (its account, model or key was not usable, or its client failed to build): the call ran on the main model alone and `reason` says why.
`failure`	string or null	no	The main model's failure class (e.g. `credits_exhausted`). Null on a timeout and when the fallback never answered.
`from_turn`	integer or null	no	The caller line the fallback first answered from (0 = the greeting). Null when it never answered.
`main_failed`	boolean or null	no	True when the main model failed but the call ended before the fallback answered (its client was still being built, or the switch was waiting for a clean turn). Null otherwise.
`model`	string or null	no	The fallback model that answered. Null when it never answered.
`reason`	string or null	no	When it answered: `error` or `timeout` (the main model failed before saying anything). When it was unavailable: a short code such as `account_changed` or `credentials_unavailable`. Null when the fallback stood by.
`used`	boolean	yes	Whether the agent's fallback language model answered any part of the call.

`CallTimingStage`#

One part of the call: how many times it ran and how long it took, in whole milliseconds.

Field	Type	Required
`count`	integer	yes
`max`	integer	yes
`p50`	integer	yes
`p95`	integer	yes

Error	When
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/v2/voice/sessions?limit=20" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

POST `/v2/voice/sessions`#

Admit a media session and return a single-use ws_url valid for expires_in_seconds. Hand only that URL to the client that streams audio.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`voice:write`
Operation	`create_voice_session_v2_voice_sessions_post`
Success	`201` `CreateVoiceSessionResponse`

Request body: CreateVoiceSessionRequest.

`CreateVoiceSessionRequest`#

Field	Type	Required	Notes
`agent_id`	uuid	yes
`max_duration_seconds`	integer or null	no
`metadata`	object or null	no
`record`	boolean or null	no
`sample_rate_in`	integer	no	default 16000
`sample_rate_out`	integer	no	default 24000
`store_transcript`	boolean or null	no
`variables`	object<string>	no

`CreateVoiceSessionResponse`#

Field	Type	Required
`expires_in_seconds`	integer	yes
`session`	VoiceSessionInfo	yes
`ws_url`	string	yes

Error	When
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/v2/voice/sessions" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "sample_rate_in": 16000,
    "sample_rate_out": 24000,
    "variables": {
      "company": "Northline Dental"
    }
  }'

GET `/v2/voice/sessions/{session_id}`#

Read one session with its frozen pipeline snapshot, connected seconds and settled cost.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`voice:read`
Operation	`get_voice_session_v2_voice_sessions__session_id__get`
Success	`200` `VoiceSessionInfo`

Parameter	In	Type	Required	Notes
`session_id`	path	uuid	yes

Error	When
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/v2/voice/sessions/$SESSION_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

GET `/v2/voice/sessions/{session_id}/transcript`#

What was said in a session of this key's project, when its agent kept transcripts.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Operation	`get_voice_session_transcript_v2_voice_sessions__session_id__transcript_get`
Success	`200` `TranscriptInfo`

Parameter	In	Type	Required	Notes
`session_id`	path	uuid	yes

`TranscriptInfo`#

Field	Type	Required
`call_id`	uuid	yes
`created_at`	date-time	yes
`retained_until`	date-time	yes
`truncated`	boolean	yes
`turn_count`	integer	yes
`turns`	object[]	yes

Error	When
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/v2/voice/sessions/$SESSION_ID/transcript" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

POST `/v2/voice/sessions/outbound`#

Queue one outbound call from a number on your own verified carrier connection. Send an Idempotency-Key; a repeat returns the first call with duplicate: true.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`voice:write`
Operation	`create_outbound_voice_session_v2_voice_sessions_outbound_post`
Success	`202` `CreateOutboundVoiceSessionResponse`

Parameter	In	Type	Required	Notes
`Idempotency-Key`	header	string or null	no

Request body: CreateOutboundVoiceSessionRequest.

`CreateOutboundVoiceSessionRequest`#

One queued call through a project-owned carrier connection and agent.

Field	Type	Required
`agent_id`	uuid	yes
`from`	string	yes
`max_duration_seconds`	integer or null	no
`metadata`	object or null	no
`record`	boolean or null	no
`store_transcript`	boolean or null	no
`to`	string	yes
`variables`	object<string>	no

`CreateOutboundVoiceSessionResponse`#

Field	Type	Required	Notes
`duplicate`	boolean	no	default false
`session`	VoiceSessionInfo	yes

Error	When
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/v2/voice/sessions/outbound" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Idempotency-Key: <unique per call attempt>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "from": "+15550000001",
    "to": "+15550000002"
  }'

Operations — account session#

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

GET `/console/v2/projects/{project_id}/voice/sessions`#

List sessions newest first, filtered by status, agent or date range.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleListVoiceSessions`
Success	`200` `VoiceSessionInfo[]`

Parameter	In	Type	Required	Notes
`project_id`	path	uuid	yes
`limit`	query	integer	no
`offset`	query	integer	no
`status`	query	string or null	no
`agent_id`	query	uuid or null	no
`from`	query	date-time or null	no
`to`	query	date-time or null	no
`has_insights`	query	boolean or null	no	true for sessions whose post-call analysis produced a result; false for every other session.

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/voice/sessions?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST `/console/v2/projects/{project_id}/voice/sessions`#

Admit a media session and return a single-use ws_url valid for expires_in_seconds. Hand only that URL to the client that streams audio.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleCreateVoiceSession`
Success	`201` `CreateVoiceSessionResponse`

Parameter	In	Type	Required	Notes
`project_id`	path	uuid	yes

Request body: CreateVoiceSessionRequest.

Error	When
`401`	No account session was presented, or it is invalid or expired.
`402`	Wallet balance cannot cover this session's maximum duration.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`503`	BYOK provider accounts are unverified/unavailable, or the service is draining.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/voice/sessions" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "sample_rate_in": 16000,
    "sample_rate_out": 24000,
    "variables": {
      "company": "Northline Dental"
    }
  }'

GET `/console/v2/projects/{project_id}/voice/sessions/{session_id}`#

Read one session with its frozen pipeline snapshot, connected seconds and settled cost.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetVoiceSession`
Success	`200` `VoiceSessionInfo`

Parameter	In	Type	Required	Notes
`session_id`	path	uuid	yes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/voice/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/projects/{project_id}/voice/sessions/{session_id}/transcript`#

Console Get Voice Session Transcript.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetVoiceSessionTranscript`
Success	`200` `TranscriptInfo`

Parameter	In	Type	Required	Notes
`session_id`	path	uuid	yes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/voice/sessions/$SESSION_ID/transcript" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST `/console/v2/projects/{project_id}/voice/sessions/outbound`#

Queue one outbound call from a number on your own verified carrier connection. Send an Idempotency-Key; a repeat returns the first call with duplicate: true.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleCreateOutboundVoiceSession`
Success	`202` `CreateOutboundVoiceSessionResponse`

Parameter	In	Type	Required	Notes
`project_id`	path	uuid	yes
`Idempotency-Key`	header	string or null	no

Request body: CreateOutboundVoiceSessionRequest.

Error	When
`401`	No account session was presented, or it is invalid or expired.
`402`	Wallet balance cannot cover this call's maximum duration.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`503`	The carrier connection or BYOK pipeline is unavailable.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/voice/sessions/outbound" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Idempotency-Key: <unique per call attempt>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "from": "+15550000001",
    "to": "+15550000002"
  }'

Try it without a key in the browser

The playground opens a real voice session with your account session, so a project key never reaches a browser. Machine calls belong on your own server.

Open the playground Quickstart

Voice sessions

What this covers#

Machine door errors#

Account door errors#

Operations — project API key#

GET /v2/voice/sessions#

VoiceSessionInfo#

CallHandoffsInfo#

CallInsightsInfo#

CallTimingsInfo#

CallFallbackInfo#

CallTimingStage#

POST /v2/voice/sessions#

CreateVoiceSessionRequest#

CreateVoiceSessionResponse#

GET /v2/voice/sessions/{session_id}#

GET /v2/voice/sessions/{session_id}/transcript#

TranscriptInfo#

POST /v2/voice/sessions/outbound#

CreateOutboundVoiceSessionRequest#

CreateOutboundVoiceSessionResponse#

Operations — account session#

GET /console/v2/projects/{project_id}/voice/sessions#

POST /console/v2/projects/{project_id}/voice/sessions#

GET /console/v2/projects/{project_id}/voice/sessions/{session_id}#

GET /console/v2/projects/{project_id}/voice/sessions/{session_id}/transcript#

POST /console/v2/projects/{project_id}/voice/sessions/outbound#

GET `/v2/voice/sessions`#

`VoiceSessionInfo`#

`CallHandoffsInfo`#

`CallInsightsInfo`#

`CallTimingsInfo`#

`CallFallbackInfo`#

`CallTimingStage`#

POST `/v2/voice/sessions`#

`CreateVoiceSessionRequest`#

`CreateVoiceSessionResponse`#

GET `/v2/voice/sessions/{session_id}`#

GET `/v2/voice/sessions/{session_id}/transcript`#

`TranscriptInfo`#

POST `/v2/voice/sessions/outbound`#

`CreateOutboundVoiceSessionRequest`#

`CreateOutboundVoiceSessionResponse`#

GET `/console/v2/projects/{project_id}/voice/sessions`#

POST `/console/v2/projects/{project_id}/voice/sessions`#

GET `/console/v2/projects/{project_id}/voice/sessions/{session_id}`#

GET `/console/v2/projects/{project_id}/voice/sessions/{session_id}/transcript`#

POST `/console/v2/projects/{project_id}/voice/sessions/outbound`#