HTTP API
Voice
7 operations. {prefix} is the route prefix passed to
MapTracon; the template uses /tracon.
GET {prefix}/api/voice/health
Section titled “GET {prefix}/api/voice/health”Operation ID: TraconVoiceHealth
Checks the voice provider’s availability.
The check does not incur cost: no speech is generated, only the available voices are read.
Authorization: bearer authentication; Reader role policy when that policy is registered; PlatformRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → VoiceHealth |
— |
POST {prefix}/api/voice/live/sessions
Section titled “POST {prefix}/api/voice/live/sessions”Operation ID: TraconLiveVoiceCreate
Creates a provider-hosted live voice session.
Relays the media peer’s SDP offer to the provider and returns its answer, so the raw API key never reaches the browser. Tracon attaches a server-side control connection to the same session and turns the work the model delegates into ordinary runs. Returns 501 when no live voice provider is registered.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
Request body (required):
application/json→LiveVoiceSessionCreateRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → LiveVoiceSessionCreateResponse |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
| 429 Too Many Requests | application/problem+json → ProblemDetails |
— |
| 501 Not Implemented | application/problem+json → ProblemDetails |
— |
| 502 Bad Gateway | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/voice/live/sessions/{voiceSessionId}
Section titled “GET {prefix}/api/voice/live/sessions/{voiceSessionId}”Operation ID: TraconLiveVoiceStatus
Reports a live voice session’s state and measurement.
The state is ‘pending’ until media is observed, then ‘active’, then ‘ended’. The duration is the provider’s own number: Tracon does not carry a live session’s media and does not invent a duration.
Authorization: bearer authentication; Reader role policy when that policy is registered; PlatformRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
voiceSessionId |
path | yes | string (uuid) |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → LiveVoiceSessionStatusResponse |
— |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
DELETE {prefix}/api/voice/live/sessions/{voiceSessionId}
Section titled “DELETE {prefix}/api/voice/live/sessions/{voiceSessionId}”Operation ID: TraconLiveVoiceClose
Closes a live voice session and writes its record.
Cancels any delegation still running, writes the session record with its measured duration and cost, and drops the provider connection. A session another tenant owns answers 404, byte for byte the answer a session that does not exist gets.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
voiceSessionId |
path | yes | string (uuid) |
— |
| Response | Body | Headers |
|---|---|---|
| 204 No Content | — | — |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/voice/sessions
Section titled “GET {prefix}/api/voice/sessions”Operation ID: TraconVoiceSessions
Lists the summary record of real-time speech connections.
The record does NOT contain audio: it only carries duration, turn count, and metering. If the speech layer is not enabled, the list is empty.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
agentName |
query | no | string |
— |
sessionId |
query | no | string |
— |
skip |
query | no | integer (int32) |
pattern `^-?(?:0\ |
take |
query | no | integer (int32) |
pattern `^-?(?:0\ |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of VoiceSessionRecord |
— |
POST {prefix}/api/voice/speak
Section titled “POST {prefix}/api/voice/speak”Operation ID: TraconVoiceSpeak
Synthesizes speech from text and saves it as an attachment.
This is an operator action and is NOT tied to a run; the metering is not written to tool_invocations, it is returned in the response. If persistent metering is required, use the agent’s speak tool.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
Request body (required):
application/json→SpeakRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → SpeakResponse |
— |
GET {prefix}/api/voice/voices
Section titled “GET {prefix}/api/voice/voices”Operation ID: TraconVoiceList
Lists the available voices.
The list comes from the configured speech provider, not from Tracon; the identifiers it returns are the values the speak endpoint and the agent’s ‘speak’ tool accept. When the speech layer was never enabled with UseVoice, the response is 501 rather than 404, so a missing configuration is not mistaken for a wrong address.
Authorization: bearer authentication; Reader role policy when that policy is registered; AgentsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of VoiceDescriptor |
— |