> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

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

## Most Used

<CardGroup cols={2}>
  <Card title="Runs" icon="play" href="/api-reference/v1/runs/runs/launch-run">
    Launch evaluation runs and track results across your agents
  </Card>

  <Card title="Agents" icon="robot" href="/api-reference/v1/agents/agents/list-agents">
    Connect and configure your AI agents for testing
  </Card>

  <Card title="Simulations" icon="rocket" href="/api-reference/v1/simulations/simulations/list-simulations">
    View simulation results with transcripts and metric scores
  </Card>

  <Card title="Test Sets" icon="database" href="/api-reference/v1/test-sets/test-sets/list-test-sets">
    Create and manage test cases for your evaluations
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Get your API key">
    Obtain your API key from the [Coval Dashboard](https://app.coval.dev/settings). See the [API Keys guide](/guides/api-keys) for detailed setup instructions.
  </Step>

  <Step title="Authenticate your requests">
    Include your API key in the `X-API-Key` header:

    ```bash theme={null}
    curl https://api.coval.dev/v1/agents \
      -H "X-API-Key: your_api_key"
    ```
  </Step>

  <Step title="Create your first agent">
    Set up an agent configuration for testing:

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="Launch a simulation">
    Run evaluations against your agent using the Simulations API.
  </Step>
</Steps>

## Base URL

```
https://api.coval.dev/v1
```

## OpenAPI Specification

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

### List available specs

```bash theme={null}
GET https://api.coval.dev/v1/openapi
```

Returns the available `spec_name` values and URLs.

### Fetch a specific spec

```bash theme={null}
GET https://api.coval.dev/v1/openapi/{spec_name}
```

* **Default response**: YAML (`application/yaml`)
* **JSON response**: set `Accept: application/json`

### Examples

```bash theme={null}
# 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.