Conversations overview

• The live-call surface — POST /v1/agents/{agentId}/conversations — spins up a LiveKit room and dispatches a runtime worker. This is the existing dispatch endpoint and is unchanged.
• The history surface — list, detail, transcript, tags, rerun analysis — covered below.

​

Lifecycle

​

Identifiers

​

Authorization

​

Pagination

GET /v1/agents/{agentId}/conversations?limit=25&cursor=<opaque>

• limit defaults to 20, max 100. Out-of-range values are clamped, not rejected.
• cursor is opaque — clients should not parse it. It encodes startedAt plus id for the last row of the previous page and is stable as long as that conversation isn’t deleted.
• The response shape is { items: ConversationSummary[]; nextCursor: string | null; hasMore: boolean }. hasMore is equivalent to nextCursor !== null today but is surfaced explicitly so clients can branch on a boolean without parsing the cursor; an empty items array on a follow-up page is also possible if a filter removes every match between cursors.
• Filters are URL params (branch_id, date_from, date_to, status, direction, duration_min_sec, duration_max_sec, language, user_id, tag_ids) and can be combined freely with the cursor. tag_ids is AND across the list (a conversation must carry every listed tag id) and accepts the repeated form (?tag_ids=a&tag_ids=b) or a single comma-separated value (?tag_ids=a,b). summary_mode=include embeds the post-call summary on each item — leave it off (the default exclude) when the table doesn’t need the text. Changing the filter set invalidates the cursor — clients should fetch the first page when filters change.

​

Departures from the ElevenLabs reference

​

Internal recorder

POST /v1/internal/conversations/{id}/turns
Authorization: Bearer <AGENT_RUNTIME_SHARED_SECRET>
Content-Type: application/json

{
  "events": [
    {
      "v": 1,
      "conversationId": "conv_…",
      "turnIndex": 0,
      "role": "user",
      "text": "What's the carrier lane mismatch process?",
      "startedAt": "2026-05-20T15:42:00.000Z",
      "metrics": { "asrMs": 106, "llmMs": null, "ttsMs": null, "ragMs": null },
      "sources": []
    }
  ]
}

• Auth is the AGENT_RUNTIME_SHARED_SECRET env var, presented as Authorization: Bearer <secret>. The guard does a constant-time compare and returns 401 invalid_service_token on mismatch.
• Network exposure — the route lives at /v1/internal/... and is not included in the public OpenAPI surface. Only the agent runtime (deployed alongside the API) should reach it.
• Idempotency is on the (conversationId, turnIndex) tuple — the table has a unique index on those columns and the service upserts. A worker retrying a batch will re-emit the same turnIndex and the API will replace the row in place, not duplicate it. Retrieval sources for that turn are replaced atomically when the turn upserts.
• Versioning — every event carries "v": 1. Readers reject any version they don’t recognise; emitters must not mix versions in one request.
• Batching — events is an array, intentional. The runtime may stream one event at a time or batch the entire call’s turns at end-of-call. The whole batch is wrapped in a single Postgres transaction: if any event in the array is rejected (unknown version, mismatched conversation id, …), every prior turn upsert in the same request is rolled back too. Retry the whole batch — partial replay is not supported by this contract.
• Final envelope — set "final": true (with optional durationSeconds, callStatus, endedReason, summary, messageCount) to commit end-of-call metrics in the same transaction as the last turn batch. The cached messageCount is always recomputed from COUNT(*) over conversation_turn; the runtime-reported value is advisory.

​

Endpoint summary

​

Related guides

• Conversations operate guide — what the dashboard renders and how teams use it.
• Branches — how conversations associate with branches and versions.