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

# API Reference

> RESTful API for managing agents, triggering calls, and retrieving analytics.

# API Reference

Movoice AI provides a RESTful API for developers to manage agents, trigger calls, and retrieve analytics programmatically.

## Base URL

```
https://api.movoice.ai/v1
```

## Authentication

All API requests must include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Generate an API key in **Settings -> API Keys** in the dashboard.

<Warning>
  Never expose your API key in client-side code or public repositories. Rotate keys immediately if compromised.
</Warning>

***

## Endpoints

### Calls

#### POST /call

Trigger an outbound call to a specific number.

```bash theme={null}
curl -X POST https://api.movoice.ai/v1/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_12345",
    "recipient_phone": "+919876543210",
    "variables": {
      "name": "Rahul",
      "appointment_time": "Tomorrow at 3 PM"
    }
  }'
```

**Request body:**

| Field             | Type    | Required | Description                                       |
| :---------------- | :------ | :------: | :------------------------------------------------ |
| `agent_id`        | string  |          | The ID of the agent to use                        |
| `recipient_phone` | string  |          | E.164 format (e.g., `+919876543210`)              |
| `variables`       | object  |          | Key-value pairs injected into the agent prompt    |
| `from_number`     | string  |          | Override the caller ID (must be a number you own) |
| `max_duration`    | integer |          | Max call duration in seconds (default: 1800)      |

**Response:**

```json theme={null}
{
  "call_id": "call_998877",
  "status": "initiated",
  "agent_id": "agent_12345",
  "recipient_phone": "+919876543210",
  "created_at": 1713456000
}
```

***

#### GET /calls

List all calls for your account.

```bash theme={null}
curl https://api.movoice.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query parameters:**

| Parameter  | Type      | Description                               |
| :--------- | :-------- | :---------------------------------------- |
| `limit`    | integer   | Number of results (default: 20, max: 100) |
| `offset`   | integer   | Pagination offset                         |
| `status`   | string    | Filter by `completed`, `failed`, `active` |
| `agent_id` | string    | Filter by agent                           |
| `from`     | timestamp | Start of date range (Unix timestamp)      |
| `to`       | timestamp | End of date range (Unix timestamp)        |

***

#### GET /calls/{call_id}

Retrieve details for a specific call.

```bash theme={null}
curl https://api.movoice.ai/v1/calls/call_998877 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response includes:** duration, transcript, summary, sentiment, outcome, recording URL.

***

### Agents

#### GET /agents

List all agents in your account.

```bash theme={null}
curl https://api.movoice.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### GET /agents/{agent_id}

Retrieve configuration for a specific agent.

```bash theme={null}
curl https://api.movoice.ai/v1/agents/agent_12345 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### PATCH /agents/{agent_id}

Update an agent's configuration.

```bash theme={null}
curl -X PATCH https://api.movoice.ai/v1/agents/agent_12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Updated system prompt...",
    "voice_id": "sarvam_hindi_female_01"
  }'
```

***

### Batch Calls

#### POST /calls/batch

Send calls to multiple recipients at once. See [Batch Calls](/guides/batch-calls) for the full guide.

```bash theme={null}
curl -X POST https://api.movoice.ai/v1/calls/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_12345",
    "recipients": [
      { "phone": "+919876543210", "variables": { "name": "Rahul" } },
      { "phone": "+919876543211", "variables": { "name": "Priya" } }
    ],
    "schedule_at": 1713456000
  }'
```

***

## Error Codes

| HTTP Status | Code              | Meaning                                                      |
| :---------- | :---------------- | :----------------------------------------------------------- |
| `400`       | `invalid_request` | Missing or malformed request parameters                      |
| `401`       | `unauthorized`    | Invalid or missing API key                                   |
| `403`       | `forbidden`       | API key does not have permission for this action             |
| `404`       | `not_found`       | Resource (agent, call) does not exist                        |
| `409`       | `conflict`        | Duplicate request — call already initiated                   |
| `422`       | `unprocessable`   | Valid JSON but business logic error (e.g., agent not active) |
| `429`       | `rate_limited`    | Too many requests — see rate limits below                    |
| `500`       | `server_error`    | Something went wrong on our end — contact support            |

All error responses follow this format:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "recipient_phone must be in E.164 format",
    "param": "recipient_phone"
  }
}
```

***

## Rate Limits

| Plan           | Calls per minute | Concurrent calls |
| :------------- | :--------------- | :--------------- |
| **Starter**    | 10               | 1                |
| **Growth**     | 60               | 3                |
| **Business**   | 200              | 10               |
| **Enterprise** | Custom           | Custom           |

When rate limited, you receive a `429` response with a `Retry-After` header indicating seconds to wait.