curl --request PATCH \
  --url https://api.coval.dev/v1/conversations/{conversation_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "audio_url": "https://recordings.s3.amazonaws.com/calls/2025/11/call-4k2m9p.wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}
'

{
  "conversation": {
    "name": "conversations/gk3jK9mPq2xRt5vW8yZaBc",
    "conversation_id": "gk3jK9mPq2xRt5vW8yZaBc",
    "status": "IN_PROGRESS",
    "create_time": "2025-11-03T14:32:30Z",
    "external_conversation_id": "external-call-7x8z9a",
    "occurred_at": "2025-11-03T14:32:00Z",
    "has_audio": true,
    "agent_id": null,
    "persona_id": null,
    "metadata": {
      "campaign": "q4-support"
    }
  }
}

Conversations

Attach audio to a conversation

Attach an audio recording to a conversation previously submitted via POST /v1/conversations:submit without audio, and trigger audio-dependent metrics as a second wave.

When to use this endpoint

Use this endpoint when your recording URL is not available at the moment the call ends (for example, Twilio Programmable Voice recordings that are only fetchable after an asynchronous job completes ~60 seconds later). Submit the transcript immediately at call end to get a conversation_id for trace correlation, then PATCH the audio when the recording URL is ready.

Two-wave metric timing

Text-only metrics fire immediately after POST /v1/conversations:submit and deliver their results via your configured webhook.
Audio-dependent metrics fire after this PATCH and deliver a separate, later webhook. Configure your consumer to expect both waves.

One-shot

Audio can be attached only once per conversation. Overwriting is not supported in v1 — a second PATCH on a conversation that already has audio returns 409 ALREADY_EXISTS.

Body

Exactly one of audio or audio_url is required.

PATCH

conversations

{conversation_id}

curl --request PATCH \
  --url https://api.coval.dev/v1/conversations/{conversation_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "audio_url": "https://recordings.s3.amazonaws.com/calls/2025/11/call-4k2m9p.wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}
'

{
  "conversation": {
    "name": "conversations/gk3jK9mPq2xRt5vW8yZaBc",
    "conversation_id": "gk3jK9mPq2xRt5vW8yZaBc",
    "status": "IN_PROGRESS",
    "create_time": "2025-11-03T14:32:30Z",
    "external_conversation_id": "external-call-7x8z9a",
    "occurred_at": "2025-11-03T14:32:00Z",
    "has_audio": true,
    "agent_id": null,
    "persona_id": null,
    "metadata": {
      "campaign": "q4-support"
    }
  }
}

Authorizations

X-API-Key

string

header

required

API key for authentication.

Path Parameters

conversation_id

string

required

Unique conversation identifier (22-26 characters)

Required string length: 22 - 26

Body

application/json

Request to attach audio to an already-submitted conversation.

Exactly one of audio_url or audio must be provided. Submitting both, or neither, returns 400 INVALID_ARGUMENT.

Idempotency: Audio can be attached only once per conversation. A second PATCH on a conversation that already has audio returns 409 ALREADY_EXISTS. Conversations that were submitted with audio via POST /v1/conversations:submit already have audio attached and cannot be PATCHed.

audio_url

string<uri>

Presigned URL to the audio recording. Same validation rules as audio_url on POST /v1/conversations:submit (WAV or MP3, 5 s to 60 min, 200 MB max). Supports AWS S3, GCP Cloud Storage, Azure Blob Storage, or any public/presigned HTTPS URL. The s3://bucket/key protocol form is also accepted.

Example:

"https://recordings.s3.amazonaws.com/calls/2025/11/call-4k2m9p.wav?X-Amz-Algorithm=..."

audio

string

Base64-encoded audio bytes. Same format and size limits as audio_url. Prefer audio_url for anything other than very small clips.

Response

Audio attached successfully; audio metrics queued

conversation

object

required

Conversation resource object.

Show child attributes

Submit conversation for evaluation Get conversation details

⌘I