Conversations API
Create a conversation from a published EVA version, then use its single-use stream token to connect audio.
Create
POST /v1/conversations · conversations:write · returns 201
json
{"agent_version_id":"av_example"}The response contains id, agent_id, agent_version_id, status, stream_url, stream_token, and expires_in_seconds. See the quickstart for the complete connection flow.
Only one connection may consume a stream token. Create a fresh conversation after an expired or consumed bootstrap; do not repeatedly retry the same token. Creating calls consumes workspace resources and may generate provider usage once connected.
Read saved material
Requires conversations:read.
Path (GET) | Returns |
|---|---|
/v1/conversations | Array of conversation records |
/v1/conversations/{id} | Status, timestamps, outcome, and safe failure information |
/v1/conversations/{id}/turns | Array of saved turns |
/v1/conversations/{id}/events | Array of saved events |
/v1/conversations/{id}/tool-executions | Array of recorded tool executions |
/v1/conversations/{id}/evidence | Combined evidence for the call |
/v1/conversations/{id}/result | Post-call analysis state and result |
/v1/conversations/{id}/evaluation | Evaluation record, when available |
/v1/conversations/results | History summaries in an items / next_cursor envelope |
GET /v1/conversations accepts limit from 1 to 100 and an optional after ID. The /results endpoint uses its returned next_cursor as after; do not interchange the two pagination formats.
Completion and analysis
A finished audio stream does not mean all material has been persisted or evaluated. Read the returned status, and poll at a modest interval while results are pending. Stop polling on a terminal success or failure.
The result may include Human Verification Needed. This is a request for review, not a guarantee that the conversation failed.
Audio recordings
Developer-created conversations do not currently enable audio recording. Saved transcripts and post-call processing remain separate. Existing recordings from supported dashboard/calling channels have their own availability and retention state.
Ending a call
Send {"type":"session.end"} through the connected WebSocket. API-key revocation is not a substitute for ending a live call.