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_nano_usd`	string	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
`hold_nano_usd`	string	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	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.
`sample_rate_in`	integer	yes
`sample_rate_out`	integer	yes
`started_at`	date-time or null	yes
`status`	string	yes
`store_transcript`	boolean	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"

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"

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#

POST /v2/voice/sessions#

CreateVoiceSessionRequest#

CreateVoiceSessionResponse#

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

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}#

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

GET `/v2/voice/sessions`#

`VoiceSessionInfo`#

POST `/v2/voice/sessions`#

`CreateVoiceSessionRequest`#

`CreateVoiceSessionResponse`#

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

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}`#

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