> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation API compatibility

> Map legacy conversation names and paths to the canonical API and CLI.

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

| Resource                        | Canonical path                                             | Legacy path                                       |
| ------------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
| List simulated conversations    | `GET /v1/conversations/simulated`                          | `GET /v1/simulations`                             |
| Get a simulated conversation    | `GET /v1/conversations/simulated/{simulation_id}`          | `GET /v1/simulations/{simulation_id}`             |
| Simulated conversation metrics  | `GET /v1/conversations/simulated/{simulation_id}/metrics`  | `GET /v1/simulations/{simulation_id}/metrics`     |
| Submit an uploaded conversation | `POST /v1/conversations/uploaded:submit`                   | `POST /v1/conversations:submit`                   |
| List uploaded conversations     | `GET /v1/conversations/uploaded`                           | `GET /v1/conversations`                           |
| Get an uploaded conversation    | `GET /v1/conversations/uploaded/{conversation_id}`         | `GET /v1/conversations/{conversation_id}`         |
| Uploaded conversation metrics   | `GET /v1/conversations/uploaded/{conversation_id}/metrics` | `GET /v1/conversations/{conversation_id}/metrics` |

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.

`/v1/runs` remains the API for batches of simulated conversations. The `/v1/audio:upload` helper also remains unchanged.

## 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

| Canonical command               | Legacy command        |
| ------------------------------- | --------------------- |
| `coval simulated-conversations` | `coval simulations`   |
| `coval uploaded-conversations`  | `coval conversations` |
| `coval runs`                    | `coval runs`          |

The legacy commands remain functional. New scripts and examples should use the canonical commands.

## App and entity links

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.