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

# VoiceInfra REST API Reference — Endpoints and Errors

> The VoiceInfra REST API lets you initiate outbound calls, configure agents dynamically, and receive call data via webhooks. Authenticate with API keys.

The VoiceInfra REST API gives you programmatic control over your AI voice agents. Use it to trigger outbound calls from any external system — whether that's a CRM, an automation platform, or your own application — and receive structured call data back via webhooks when each call completes. Every request authenticates with an API key, and every response returns JSON.

## Base URL

All API requests target the following base URL:

```text theme={null}
https://api.voiceinfra.ai/v1
```

## Available endpoints

| Endpoint          | Method | Description                                |
| ----------------- | ------ | ------------------------------------------ |
| `/calls/outbound` | `POST` | Initiate an outbound call from an AI agent |

## Authentication

Every request to the VoiceInfra API must include your API key in the `X-API-Key` request header. Requests without a valid key return `401 Unauthorized`.

```http theme={null}
X-API-Key: YOUR_API_KEY
```

See the [Authentication guide](/docs/api/authentication) for full details on generating keys, managing multiple keys, and security best practices.

## Request format

All requests must set the `Content-Type` header to `application/json` and send a JSON body where applicable.

```http theme={null}
Content-Type: application/json
```

## Response format

All responses return JSON. Successful requests return a `2xx` status code with a JSON body. Failed requests return a `4xx` or `5xx` status code with an error object that describes what went wrong.

```json Error response theme={null}
{
  "error": {
    "code": "invalid_agent",
    "message": "The specified agent_id does not exist or is not active."
  }
}
```

### Common error codes

| Status | Code               | Description                            |
| ------ | ------------------ | -------------------------------------- |
| `400`  | `validation_error` | Missing or invalid request parameters  |
| `401`  | `unauthorized`     | Invalid or missing API key             |
| `404`  | `not_found`        | Agent or resource not found            |
| `422`  | `invalid_phone`    | Phone number not in valid E.164 format |
| `429`  | `rate_limited`     | Too many requests                      |
| `500`  | `server_error`     | Internal server error                  |

## Rate limits

Standard rate limits apply to all API endpoints. If your integration requires a higher throughput limit, contact [VoiceInfra support](mailto:hello@voiceinfra.ai) to discuss your needs.

<Note>
  When you hit a rate limit, the API returns `429 rate_limited`. Build exponential backoff into your integration to handle this gracefully.
</Note>

## Idempotency

Each call to `POST /calls/outbound` creates a new, unique `call_id` in the response. Use this identifier to correlate the webhook event you receive when the call completes — every `call.completed` webhook payload includes the matching `call_id`.

<Tip>
  Store the `call_id` in your system immediately after initiating a call so you can reliably match incoming webhook events to the original request.
</Tip>

## Explore the API

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api/authentication">
    Generate API keys, secure your credentials, and understand authentication errors.
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/docs/api/outbound-calls">
    Trigger AI-powered outbound calls with dynamic per-call configuration.
  </Card>
</CardGroup>