Conversation intelligence
- Sells as: the
conversation-intelligence product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.
Conversation intelligence as a shared capability. POST /v1/analyze scores one transcript synchronously (sentiment/intent/summary/topics/entities/outcome via an LLM over provider-gateway, with a deterministic lexicon/keyword fallback for sentiment+intent). /v1/analyze/batch analyses many transcripts asynchronously (poll a job). /v1/analyses retrieves stored analyses (org-scoped). The store is OPTIONAL — with the DSN unset /v1/analyze still serves fully; the persisted-retrieval + batch paths return 503.
- Group: Voice & AI
- Contract:
contracts/conversation-intelligence/v1/openapi.yaml
- Console: Manage the
conversation-intelligence product in the console →
- Runbook: operational checklist for
conversation-intelligence — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#conversation-intelligence
- Public base:
https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
- Auth: a product API key (
vgk_…) issued from the console — Authorization: Bearer vgk_…
- Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/conversation-intelligence/analyze
Edge route table
The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.
Product face (customer-keyed)
| Method | Path | Metric | Scope |
|---|
POST | /product/v1/conversation-intelligence/analyze | ci_requests | write |
Endpoints
| Method | Path | Summary |
|---|
POST | /v1/analyze | Analyse one transcript (sentiment/intent/summary/topics/entities/outcome), synchronous |
GET | /v1/analyses | Retrieve stored analyses (org-scoped; optional session_ref filter) |
POST | /v1/analyses/erase-subject | GDPR Art-17 erasure of a data subject's stored analyses (first-party admin only) |
POST | /v1/analyze/batch | Start an asynchronous batch analysis of many transcripts |
GET | /v1/jobs/{job_id} | Fetch a batch job's status + per-item results (org-scoped) |
GET | /health | liveness + store/analyzer readiness |
GET | /metrics | Prometheus exposition (fleet observability SDK — fail-open) |
Schemas
EraseSubjectResult
matched is reported separately from deleted so a zero-match is visible to the compliance fan-out rather than reading as a successful erasure. jobs_swept is always false — see the endpoint's KNOWN RESIDUE note.
| Field | Type | Description |
|---|
success | boolean | |
capability | string | |
organization_id | string | |
disposition | string | |
selector | string | |
matched | integer | stored analyses belonging to those session refs |
deleted | integer | |
session_refs | array | the refs actually applied (blank entries dropped) |
dry_run | boolean | |
jobs_swept | boolean | always false — conversation_jobs has no session_ref column |
jobs_swept_reason | string | |
Turn
one transcript turn.
| Field | Type | Description |
|---|
role | string | speaker role (user |
content | string | |
AnalyzeRequest
| Field | Type | Description |
|---|
organization_id | string | product-tier end-customer tenant (I6); optional in v1 (persistence needs it; the analysis itself does not). |
transcript | array | the conversation under analysis (≥1 turn). |
analyses | array | which analyses to run (default = all six). Unknown values are ignored. |
session_ref | string | the product's own call/session id — lets GET /v1/analyses fetch every analysis for one conversation. |
Sentiment
5-band sentiment + signed score + confidence + an optional dominant emotion. source marks whether it came from the LLM or the deterministic fallback.
| Field | Type | Description |
|---|
label | string | |
score | number | signed sentiment in [-1, 1] |
confidence | number | |
emotion | object | |
source | string | |
Intent
| Field | Type | Description |
|---|
label | string | |
confidence | number | |
source | string | |
Entity
| Field | Type | Description |
|---|
text | string | |
type | string | person |
Outcome
| Field | Type | Description |
|---|
label | string | |
reason | string | |
source | string | |
Unavailable
an LLM-only analysis that could not run (LLM unreachable) — surfaced explicitly, never fabricated.
| Field | Type | Description |
|---|
available | boolean | |
reason | string | |
Generated by scripts/gen-capability-docs.py from contracts/conversation-intelligence/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.