Skip to main content
The Coval REST API enables you to programmatically launch voice and chat evaluations, manage test data, and analyze AI agent performance.

​
Most Used

Runs

Launch evaluation runs and track results across your agents

Agents

Connect and configure your AI agents for testing

Simulations

View simulation results with transcripts and metric scores

Test Sets

Create and manage test cases for your evaluations

​
Getting Started

1

Get your API key

Obtain your API key from the Coval Dashboard. See the API Keys guide for detailed setup instructions.
2

Authenticate your requests

Include your API key in the X-API-Key header:
curl https://api.coval.dev/v1/agents \
  -H "X-API-Key: your_api_key"
3

Create your first agent

Set up an agent configuration for testing:
curl -X POST https://api.coval.dev/v1/agents \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "My Test Agent",
    "model_type": "VOICE",
    "phone_number": "+15551234567"
  }'
4

Launch a simulation

Run evaluations against your agent using the Simulations API.

​
Base URL

https://api.coval.dev/v1

​
OpenAPI Specification

We publish our OpenAPI specifications at public endpoints (no authentication required).

​
List available specs

GET https://api.coval.dev/v1/openapi
Returns the available spec_name values and URLs.

​
Fetch a specific spec

GET https://api.coval.dev/v1/openapi/{spec_name}
  • Default response: YAML (application/yaml)
  • JSON response: set Accept: application/json

​
Examples

# List all available specs
curl -s https://api.coval.dev/v1/openapi

# Fetch a spec as YAML (default)
curl -s https://api.coval.dev/v1/openapi/agents

# Fetch a spec as JSON
curl -s -H "Accept: application/json" https://api.coval.dev/v1/openapi/agents

​
Authentication

All API requests require an X-API-Key header with every request.