# API Reference

> IVR Studio REST API - authentication, base URL, response format and the endpoints for outbound IVR calls, flows, numbers and logs.

Source: https://edesy.in/docs/ivr/api

The IVR Studio API lets your system start outbound calls that run a published flow, manage flows and number assignments, and read call, HTTP and email logs. The base URL is `https://voice-api.edesy.in/v1/ivr`. Authenticate with an API key from the portal's **API Keys** page, sent as a Bearer token or in an `X-API-Key` header.

## Authentication

Create an API key in [ivr.edesy.in](https://ivr.edesy.in) under **API Keys**. Send it on every request in either header:

```http
Authorization: Bearer sk_live_xxxxxxxxxxxx
```

```http
X-API-Key: sk_live_xxxxxxxxxxxx
```

Keep keys on your server. Never put them in a web page or mobile app.

## Endpoints

| Method | Path | What it does |
|---|---|---|
| `POST` | `/v1/ivr/calls` | [Start an outbound IVR call](https://edesy.in/docs/ivr/api/outbound-ivr-calls) |
| `GET` | `/v1/ivr/calls/{call_sid}` | [Get a call](https://edesy.in/docs/ivr/api/outbound-ivr-calls#get-a-call) |
| `GET`, `POST` | `/v1/ivr/flows` | [List or create flows](https://edesy.in/docs/ivr/api/flows) |
| `GET`, `PUT`, `DELETE` | `/v1/ivr/flows/{id}` | Read, update or delete a flow |
| `POST` | `/v1/ivr/flows/{id}/publish` | Publish a flow |
| `GET` | `/v1/ivr/flows/{id}/preview` | VoiceML preview |
| `POST` | `/v1/ivr/flows/{id}/test-call` | Test call to your phone |
| `GET`, `POST` | `/v1/ivr/numbers` | List or create number assignments |
| `DELETE` | `/v1/ivr/numbers/{id}` | Remove a number assignment |
| `POST` | `/v1/ivr/audio` | Upload audio for Play nodes |
| `GET` | `/v1/ivr/call-logs` | [List calls](https://edesy.in/docs/ivr/api/logs) |
| `GET` | `/v1/ivr/http-logs` | [List HTTP requests](https://edesy.in/docs/ivr/api/logs#http-logs) |
| `POST` | `/v1/ivr/http-logs/{id}/retry` | Retry a failed background request |
| `POST` | `/v1/ivr/http-test` | Send a test HTTP request |
| `GET` | `/v1/ivr/email-logs` | [List email notifications](https://edesy.in/docs/ivr/api/logs#email-logs) |
| `GET` | `/v1/ivr/stats` | Flow, number, call and cost totals |
| `GET` | `/v1/ivr/settings/signing-secret` | [Signing secret status](https://edesy.in/docs/ivr/api/http-signing-secret) |
| `POST` | `/v1/ivr/settings/signing-secret/rotate` | Rotate the signing secret |

## Response format

Successful responses wrap the result in `data`. Lists add `meta`:

```json
{
  "data": [ ],
  "meta": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3, "timestamp": "2026-10-28T10:15:00Z" }
}
```

Errors return an `error` object:

```json
{ "error": { "code": "flow_not_published", "message": "..." } }
```

Lists accept `page` and `per_page`.

## Requests from Edesy to you

HTTP Request nodes and status callbacks are signed with your workspace signing secret. See [HTTP Signing Secret](https://edesy.in/docs/ivr/api/http-signing-secret).

## FAQ

### Is there an SDK?

No. The API is plain REST and JSON, so any HTTP client works.

### Which header should I use for the API key?

Either `Authorization: Bearer <key>` or `X-API-Key: <key>`.

### Can I build flows through the API?

Yes. `POST /v1/ivr/flows` takes the same `flow_data` (nodes and edges) the builder saves. Most teams build in the builder and use the API to start calls.

### Are outbound calls limited?

Yes: 10 concurrent API calls per workspace by default, and calls only between 09:00 and 21:00 IST. See [Outbound IVR Calls](https://edesy.in/docs/ivr/api/outbound-ivr-calls#limits).

### How do I know a call finished?

Pass `status_callback_url` when you start the call. Edesy POSTs the result, signed, when the call ends.

### Where do I see API errors?

The response body has `error.code`. Requests that Edesy makes to you are listed in [HTTP Logs](https://edesy.in/docs/ivr/logs/http-logs).