Skip to main content
The canonical API groups individual results under simulated conversations and uploaded conversations. Existing integrations can migrate incrementally: the legacy public paths, permission scopes, CLI commands, app redirects, and entity links remain supported.

​
API paths

Every operation on the canonical paths has a matching legacy path formed the same way: /v1/conversations/simulated maps to /v1/simulations, and /v1/conversations/uploaded maps to /v1/conversations. Canonical collection responses use simulated_conversations and uploaded_conversations. Legacy paths retain their existing response wrappers. Identifiers such as simulation_id and conversation_id do not change. Legacy paths do not return deprecation headers and have no announced removal date. /v1/runs remains the API for batches of simulated conversations. The /v1/audio:upload helper also remains unchanged.

​
Other legacy paths

/v1/monitors remains supported and maps 1:1 to /v1/alerts: every /v1/alerts operation has a /v1/monitors counterpart with {monitor_id} in place of {alert_id}. New integrations should use /v1/alerts.

​
Source fields

New integrations should use conversation_source with uppercase values:
  • SIMULATED
  • UPLOADED
  • ALL where a cross-source filter supports it
Older fields and values, including source, scope, monitoring, is_monitoring, MONITORING, and SIMULATION, remain accepted where they were previously part of a public contract. Responses may include both vocabularies during compatibility.

​
API key permissions

Canonical and legacy paths authorize against equivalent existing scopes. A key that can read simulations can read simulated conversations; a key that can read, submit, or delete conversations can perform the corresponding uploaded-conversation operation. You do not need to recreate API keys when changing paths.

​
CLI commands

The legacy commands remain functional. New scripts and examples should use the canonical commands. The app uses /simulated and /uploaded. Existing /runs, /conversations, and /monitoring links redirect to the corresponding destination and preserve their query parameters. New Sofia links use coval://simulated_conversation/{id} and coval://uploaded_conversation/{id}. Existing coval://simulation/{id} and coval://conversation/{id} links continue to resolve.