curl --request PATCH \
--url https://api.coval.dev/v1/conversations/uploaded/{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=..."
}
'{
"uploaded_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"
}
}
}Attach audio, add metadata, or assign an agent to a conversation
Attach an audio recording, add metadata keys, or assign an agent to a
conversation previously submitted via POST /v1/conversations/uploaded:submit.
When to attach audio
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. Attaching audio triggers audio-dependent metrics as a second wave.
When to add metadata
Use this endpoint when a value you want to filter or segment on is only
known after the call was submitted (for example, an outcome produced by
post-call analysis). Once added, the key is immediately available as a
filter on the Uploaded Conversations page and in the filter parameter of
GET /v1/conversations/uploaded.
Two-wave metric timing
- Text-only metrics fire immediately after
POST /v1/conversations/uploaded:submitand deliver their results via your configured webhook. - Audio-dependent metrics fire after an audio PATCH and deliver a separate, later webhook. Configure your consumer to expect both waves.
Adding metadata does not run or re-run any metric. If a metric depends
on a key you added, rerun it with POST /v1/conversations/simulated:rerunMetrics.
When to assign an agent
Use agent_id when a conversation was submitted without one and you later
know which agent handled it. The conversation then appears under that agent
on the Uploaded Conversations page, in agent filters, and in agent-scoped
metric aggregates. Assigning an agent does not run or re-run any metric.
One-shot
Every patch target is write-once. Audio can be attached only once per
conversation; a second PATCH on a conversation that already has audio
returns 409 ALREADY_EXISTS. Metadata is additive only; patching a key
that already has a value returns 409 ALREADY_EXISTS. An agent can be
assigned only to a conversation that has none; repeating the current agent
succeeds without change, and a different agent returns 409 ALREADY_EXISTS.
Body
Exactly one of audio, audio_url, metadata or agent_id is required.
curl --request PATCH \
--url https://api.coval.dev/v1/conversations/uploaded/{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=..."
}
'{
"uploaded_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
API key for authentication.
Path Parameters
Unique conversation identifier (22-26 characters)
22 - 26Body
Request to attach audio to, add metadata to, or assign an agent to an already-submitted conversation.
Exactly one of audio_url, audio, metadata or agent_id must be
provided. Submitting more than one, or none, returns 400 INVALID_ARGUMENT.
Each target is patched in a separate call so a rejected value can never
leave another target half-applied.
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/uploaded:submit already have audio attached and cannot
be PATCHed. Metadata follows the same rule per key: adding a new key
succeeds, overwriting an existing one returns 409 ALREADY_EXISTS. An agent
can be assigned once; a different agent returns 409 ALREADY_EXISTS.
Channel containing the agent in the input stereo recording: 0 is left, 1 is right. With channel selection enabled for the organization, omitted or null uses the organization default. Otherwise the legacy mapping applies and explicit overrides are rejected. Requires an audio input. No effect on mono recordings or supplied transcript roles. The effective choice is captured for this audio.
0 <= x <= 1Presigned URL to the audio recording. Same validation rules as
audio_url on POST /v1/conversations/uploaded: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 HTTP/HTTPS URL. Raw s3://bucket/key
URLs are limited to Coval-issued uploads in the shared or
organization-specific audio bucket under audio/<authenticated_organization_id>/.
For other storage locations, supply a presigned HTTPS URL.
HTTP/HTTPS URLs must resolve entirely to publicly routable addresses; redirects are rejected.
"https://recordings.s3.amazonaws.com/calls/2025/11/call-4k2m9p.wav?X-Amz-Algorithm=..."
Base64-encoded audio bytes. Same format and size limits as audio_url.
Prefer audio_url for anything other than very small clips.
Metadata keys to add to the conversation, merged into any metadata sent at submit. Values may be strings, numbers, booleans, arrays or objects.
Additive only. A key that already holds a value returns
409 ALREADY_EXISTS, and keys that identify the conversation
(conversation_id, external_conversation_id, call_id, trace_id,
langfuse_trace_id, observation_id, langfuse_observation_id,
project_id, environment, occurred_at) return
400 INVALID_ARGUMENT.
At most 100 keys per request; key names are limited to 200 characters.
{
"called_back": 1,
"csat_bucket": "promoter"
}
Agent to assign to a conversation that was submitted without one. The
agent must exist and be active in your organization for a new assignment, otherwise
404 NOT_FOUND. Supply a 22-character agent resource ID (letters, digits, or hyphens);
malformed IDs return 400 INVALID_ARGUMENT.
Set-once. Repeating the conversation's current agent succeeds without
change; a different agent returns 409 ALREADY_EXISTS. Does not run or
re-run any metric.
^[A-Za-z0-9-]{22}$"fZSUMoKq67ZarVYCbugjsd"
Response
Audio attached successfully; audio metrics queued
Conversation resource object.
Show child attributes
Show child attributes
Was this page helpful?