curl --request POST \
--url https://api.coval.dev/v1/conversations/uploaded:submit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data @- <<EOF
{
"transcript": [
{
"role": "user",
"content": "Hi, I'd like to check my account balance"
},
{
"role": "assistant",
"content": "I can help you with that. Let me pull up your account."
},
{
"role": "assistant",
"content": "Your current balance is $1,247.53"
},
{
"role": "user",
"content": "Thank you!"
}
],
"external_conversation_id": "external-call-7x8z9a",
"occurred_at": "2025-11-03T14:32:07.412Z",
"metadata": {
"campaign": "q4-support",
"channel": "phone",
"customer_tier": "premium"
},
"tags": [
"restaurant",
"support-tier-1"
]
}
EOF{
"uploaded_conversation": {
"name": "conversations/gk3jK9mPq2xRt5vW8yZaBc",
"conversation_id": "gk3jK9mPq2xRt5vW8yZaBc",
"status": "PENDING",
"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",
"channel": "phone",
"customer_tier": "premium"
},
"tags": [
"restaurant",
"support-tier-1"
]
}
}Submit conversation for evaluation
Submit an uploaded conversation for evaluation.
curl --request POST \
--url https://api.coval.dev/v1/conversations/uploaded:submit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data @- <<EOF
{
"transcript": [
{
"role": "user",
"content": "Hi, I'd like to check my account balance"
},
{
"role": "assistant",
"content": "I can help you with that. Let me pull up your account."
},
{
"role": "assistant",
"content": "Your current balance is $1,247.53"
},
{
"role": "user",
"content": "Thank you!"
}
],
"external_conversation_id": "external-call-7x8z9a",
"occurred_at": "2025-11-03T14:32:07.412Z",
"metadata": {
"campaign": "q4-support",
"channel": "phone",
"customer_tier": "premium"
},
"tags": [
"restaurant",
"support-tier-1"
]
}
EOF{
"uploaded_conversation": {
"name": "conversations/gk3jK9mPq2xRt5vW8yZaBc",
"conversation_id": "gk3jK9mPq2xRt5vW8yZaBc",
"status": "PENDING",
"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",
"channel": "phone",
"customer_tier": "premium"
},
"tags": [
"restaurant",
"support-tier-1"
]
}
}Authorizations
API key for authentication.
Body
Request to submit an uploaded conversation for evaluation.
Requirements:
- At least one of:
transcript,audio_url, orupload_idmust be provided audio_urlandupload_idare mutually exclusive
Payload Size Limit: The combined queued payload is subject to a 256 KB limit (including large metadata values); oversized payloads return 413 PAYLOAD_TOO_LARGE.
Best Practices:
- Provide both transcript and audio_url (or upload_id) when available (enables audio metrics)
- Include
start_timeandend_timein transcript messages when submitting audio_url to avoid automatic retranscription - Include
external_conversation_idfor correlation with external systems - Add metadata for conditional metrics and analytics
Audio + Transcript Behavior:
- If you submit both
transcriptandaudio_url:- WITH timing (
start_time/end_timeon each message): Transcript is used as-is, audio metrics computed from timing - WITHOUT timing: Audio is automatically transcribed and diarized, provided transcript is ignored for metrics
- WITH timing (
Conversation transcript as array of messages
1Show child attributes
Show child attributes
Public or presigned HTTP/HTTPS URL to audio from any cloud provider. Every resolved address must be publicly routable. Redirects are rejected.
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 or use upload_id from POST /v1/audio:upload.
Audio Validation Requirements:
- Formats: WAV or MP3 ONLY (detected via magic bytes, not file extension)
- Channels: Stereo (recommended) or mono. Stereo assigns speaker roles deterministically from channel position (channel 0 = agent, channel 1 = user); mono infers roles by classifying transcript content, which is typically accurate but less reliable than channel-based mapping.
- Duration: 5 seconds minimum, 1 hour (3600 seconds) maximum
- File Size: 200 MB maximum
- Validation: Audio is validated BEFORE processing begins
- Rejected Formats: MP4, M4A, FLAC, OGG, AAC, etc.
Supported URL Formats:
- AWS S3: https://bucket.s3.amazonaws.com/...
- GCP Cloud Storage: https://storage.googleapis.com/...
- Azure Blob Storage: https://account.blob.core.windows.net/...
- Any Public or Presigned HTTPS URL
Validation Errors (400 INVALID_ARGUMENT):
- "Audio file is empty."
- "Unsupported audio format: {format}. Only WAV and MP3 files are supported."
- "Audio too short: {X} seconds. Minimum duration is 5 seconds."
- "Audio too long: {X} minutes. Maximum duration is 60 minutes."
- "Audio file too large: {X} MB. Maximum size is 200 MB."
- "Invalid or corrupt audio file. Unable to detect audio format. Supported formats: WAV and MP3."
- "Invalid or corrupt audio file. Unable to read audio metadata."
- "Audio URL not found (404)" or "Failed to retrieve audio from URL"
"https://recordings.s3.amazonaws.com/call-abc.wav?X-Amz-Algorithm=..."
Reference to a previously issued direct upload from POST /v1/audio:upload.
Use this when you've uploaded audio bytes directly via a Coval-issued presigned PUT URL. The Coval backend resolves the staged upload, validates it, and promotes it into managed recordings storage.
Mutually exclusive with audio and audio_url — provide exactly one
audio source.
Validation Errors:
- 404 NOT_FOUND:
upload_iddoes not exist, has expired, has already been consumed, or belongs to a different organization (404 is returned in all four cases to avoid leaking ID existence across organizations). - 400 INVALID_ARGUMENT: Mutually exclusive audio sources provided.
^upl_[0-9A-HJKMNP-TV-Z]{26}$"upl_01HRAB8N9G7Q4Y3K2J5W6X1ZTC"
Metric IDs or exact legacy metric_name values to evaluate. IDs take precedence. Legacy names must resolve to a unique active metric visible in the request workspace. Display names are not accepted. Unknown, ambiguous, inactive, hidden, deleted, or inaccessible selections return 400 INVALID_ARGUMENT.
If not provided, uses your default metrics configured in the Coval dashboard.
[
"29BlkepvvX19ebbLDB0y6Q",
"metric_type_latency"
]
Custom metadata for conditional metrics and tracking.
Used for:
- Triggering conditional metrics
- Filtering conversations
- Custom analytics and reporting
Reserved key coval_simulation_id: set it to the value of the
X-Coval-Simulation-Id SIP header delivered with every inbound
simulation call. Organizations that opt in to the simulation
filter have submits carrying a matching platform-simulation id
dropped without creating a conversation (see the 200 response).
{
"campaign": "q4-support",
"customer_tier": "premium",
"region": "us-west"
}
Optional tags to apply to this conversation for filtering and organization.
Tags are normalized case-insensitively and stored on the uploaded conversation's backing run. Use them to group uploaded conversations by product, workflow, customer segment, or other operational slices.
201 - 200.*\S.*["restaurant", "support-tier-1"]
External conversation ID from your system.
Stored as conversation_id in customer_metadata JSONField.
Can be used to correlate with external systems (Twilio, Vonage, etc).
"external-call-7x8z9a"
The instant the audio recording begins, in ISO 8601 with sub-second precision. Coval uses it to align the recording with trace spans in the trace viewer and to locate traces around the call.
Optional. Without it, the trace viewer draws the recording without aligning it to spans.
"2025-11-03T14:32:07.412Z"
Agent resource ID (22-character ShortUUID) to associate with this conversation.
Must reference an existing agent within your organization. The agent is validated at submission time:
- 400 INVALID_ARGUMENT: Malformed ID (wrong length or characters).
- 404 NOT_FOUND: Agent does not exist or belongs to a different organization.
^[A-Za-z0-9-]{22}$"gk3jK9mPq2xRt5vW8yZaBc"
Response
Conversation submitted successfully. When the organization opts in
to the simulation filter and the submit carries a
coval_simulation_id metadata value that matches a platform
simulation, no conversation is created and a
FilteredSubmitResponse is returned instead.
- Option 1
- Option 2
Conversation resource object.
Show child attributes
Show child attributes
Was this page helpful?