API Reference - Coval Documentation

The Coval REST API enables you to programmatically launch voice and chat simulations, 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

Simulated Conversations

View simulated conversation results with transcripts and metric scores

Test Sets

Create and manage test cases for your simulations

Getting Started

Get your API key

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

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"

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"
  }'

Launch simulated conversations

Launch a run and inspect its results with the Runs and Simulated Conversations APIs.

Base URL

https://api.coval.dev/v1

Authentication

Every request except the public OpenAPI specification endpoints requires an API key in the X-API-Key header. The header name is matched case-insensitively, so x-api-key works too. A missing or invalid key returns 401 with the code UNAUTHENTICATED. A key that lacks the permission scope an endpoint requires returns 403 with PERMISSION_DENIED. See the API Keys guide for creating keys and choosing scopes.

Workspaces

Resources such as agents, test sets, runs, and conversations belong to a workspace within your organization. Send the optional X-Coval-Workspace-Id header (also matched case-insensitively) with a workspace id to act in that workspace:

curl https://api.coval.dev/v1/conversations/simulated \
  -H "X-API-Key: your_api_key" \
  -H "X-Coval-Workspace-Id: your_workspace_id"

Omit the header and the request uses your organization’s default workspace. Resources created before your organization had workspaces belong to the default workspace.
Listings such as GET /conversations/simulated and GET /runs return only the resolved workspace’s resources, and resources you create belong to that workspace.
A header naming a workspace that does not exist, is archived or deleted, or belongs to another organization is rejected with 401 and the code UNAUTHENTICATED.
API keys and the Workspaces endpoints themselves are organization-level and are not filtered by the header.

Create, list, archive, and delete workspaces with the Workspaces API.

Pagination

List endpoints page with page_size and page_token:

page_size is the maximum number of results per page. It defaults to 50; the upper bound varies by endpoint and is shown on each endpoint’s page (for example 1000 for runs and simulated conversations, 250 for uploaded conversations).
page_token is the opaque cursor returned as next_page_token in the previous response. Omit it for the first page. A null next_page_token means there are no more results.

curl "https://api.coval.dev/v1/conversations/simulated?page_size=100&page_token=eyJvZmZzZXQiOiAxMDB9" \
  -H "X-API-Key: your_api_key"

Requests that filter on metric values (a metric.{metric_id} predicate in filter) or embed them (include=metric_values for simulated and uploaded conversations, include=metric_averages for runs) are served newest-first and cap page_size at 100. See List simulations and List runs.

Filtering and sorting

List endpoints accept a filter expression and an order_by field. filter is one or more field operator value predicates joined with AND or OR. Operators are =, !=, >, <, >=, and <=. Values may be unquoted or double-quoted; quote any value containing spaces, such as status="IN PROGRESS". The supported fields differ per endpoint and are listed on each endpoint’s page. For example, simulated conversations can be filtered on status, agent_id, persona_id, test_set_id, test_case_id, run_id, external_conversation_id, mutation_id, mutation_name, create_time, and metric.{metric_id}.

curl "https://api.coval.dev/v1/conversations/simulated?filter=status=COMPLETED%20AND%20agent_id=gk3jK9mPq2xRt5vW8yZaBc" \
  -H "X-API-Key: your_api_key"

order_by takes a field name for ascending order or -field for descending. Most lists default to -create_time (newest first); uploaded conversations default to -occurred_at. The sortable fields are listed on each endpoint’s page. A metric.{metric_id} predicate is more restrictive: it supports only AND alongside a small set of fields, and any non-default order_by is rejected with 400. See List simulations and List conversations for the details.

Response detail

Metric output lists on simulated and uploaded conversations accept two parameters that control how much comes back:

view selects the detail level. FULL (the default) includes every field, including the structured result and runtime_metadata. BASIC omits those heavy fields while retaining the value, status, explanation, and bounded subvalues.
include_superseded controls re-score history. Re-scoring a metric appends a new output rather than replacing the previous one. With the default false, each metric appears at most once with its most recent output; set it to true to return every output, including those a later re-score has replaced.

See List metrics for simulated conversations and List conversation metrics for uploaded conversations.

Errors

Errors return an error object with a machine-readable code, a human-readable message, and, where applicable, details naming the field at fault:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid filter expression",
    "details": [
      {
        "field": "filter",
        "description": "Invalid filter syntax. Expected format: field operator \"value\""
      }
    ]
  }
}

Code	HTTP status	Meaning
`INVALID_ARGUMENT`	400	The request body or a query parameter failed validation
`UNAUTHENTICATED`	401	The API key is missing or invalid, or the requested workspace could not be resolved
`PERMISSION_DENIED`	403	The API key lacks the required permission scope
`NOT_FOUND`	404	The resource does not exist or belongs to a different organization
`ALREADY_EXISTS`	409	A create or lifecycle change conflicts with existing state
`FAILED_PRECONDITION`	412	The request is valid but the resource’s current state does not allow it
`RESOURCE_EXHAUSTED`	429	A rate limit was exceeded; see Rate limits
`INTERNAL`	500, 503	An unexpected server error, or a transient outage that is safe to retry

Every response carries an X-Request-Id header. Include it when you contact support about a failed request.

Rate limits

Only Batch rerun metrics is rate limited today. Reruns count against an organization-level hourly limit on simulations queued (5000 per hour by default). When the limit is exceeded the API returns 429 with the code RESOURCE_EXHAUSTED and a Retry-After header giving the number of seconds until the window rolls over. No other endpoint has a published quota.

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, their URLs, and when each spec was last published (last_modified).

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

​Most Used

Runs

Agents

Simulated Conversations

Test Sets

​Getting Started

​Base URL

​Authentication

​Workspaces

​Pagination

​Filtering and sorting

​Response detail

​Errors

​Rate limits

​OpenAPI Specification

​List available specs

​Fetch a specific spec

​Examples