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

# Introduction

> Everything you need to start building with the DialNexa API.

## Overview

The DialNexa API is a REST API that lets you build, deploy, and monitor AI voice agents programmatically. Use it to create agents, trigger calls, manage batch calls and workflows, work with catalog resources, manage webhooks, and connect phone numbers from your backend.

## Base URLs And Legacy API Support

The recommended base URL for current API requests is:

```
https://api.dialnexa.com/v1
```

Legacy unversioned routes are still supported for existing integrations:

```
https://api.dialnexa.com
```

| Route family           | Base URL                      | Status                                                       |
| ---------------------- | ----------------------------- | ------------------------------------------------------------ |
| Current v1 API         | `https://api.dialnexa.com/v1` | Use this for all new integrations.                           |
| Legacy unversioned API | `https://api.dialnexa.com`    | Supported until July 31, 2026. Start migrating to `/v1` now. |

For example, `POST https://api.dialnexa.com/calls` and `POST https://api.dialnexa.com/v1/calls` are both supported during the transition period. New code should use the `/v1` route when a v1 page exists because the legacy unversioned API is scheduled for deprecation on July 31, 2026.

All requests and responses use JSON, except for file upload endpoints which use `multipart/form-data`.

## What you can build

* **Outbound calling**: Trigger individual calls or batch calls from your backend. Pass customer-specific data at call time and have the agent personalize every conversation.
* **Inbound handling**: Assign an agent to a purchased phone number to automatically handle every incoming call.
* **Batch calls**: Upload a CSV or Excel file of leads, start outbound calls, and pause, resume, or cancel the batch.
* **Workflows**: Build multi-step calling sequences where a lead's path through the workflow is determined by call outcomes and workflow logic.
* **Phone numbers**: Search Plivo inventory, purchase a provider number, link a bring-your-own SIP trunk, or delete a number you no longer use.
* **Webhooks**: Subscribe to call and workflow-related events and receive real-time HTTP notifications on your server.

## Key concepts

**Agents** are the core building block. An agent combines a voice, a language model, a system prompt, and telephony configuration into a single deployable entity. All calls, whether outbound, inbound, or browser-based, are handled by an agent.

**Dynamic variables** let you personalize agents at call time. Any key in the `metadata` object passed when creating a call, or any column header in a leads file, becomes a `{{variable_name}}` that the agent can reference in its prompt. For example, if you pass `{"customer_name": "Priya"}`, the prompt can say `Hello {{customer_name}}!` and the agent will greet the caller by name.

**Batch Calls** are bulk outbound calling jobs created from a lead file. Use `PATCH /v1/batch-calls/{id}/status` to pause, resume, or cancel a batch.

**Workflows** are directed graphs where each node is an action (a call, a time delay, a conditional check) and each edge defines what happens next based on the outcome of that action.

## Make your first request

<Steps>
  <Step title="Get an API key">
    In the dashboard, open **Settings > API Keys** and create a key. Copy it immediately - it is shown only once. See [Authentication](/docs/api-reference/authentication).
  </Step>

  <Step title="List your agents">
    ```bash theme={null}
    curl https://api.dialnexa.com/v1/agents \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    A `200` response returns an `agents` array. Agent listing is not paginated today.
  </Step>

  <Step title="Trigger a call">
    Publish the agent version, then take its `agent_id` and [create a v1 call](/docs/api-reference/v1/calls/create). Watch the result arrive in Call History.
  </Step>
</Steps>

## Request format

Set the `Content-Type` header to `application/json` for all requests with a body:

```bash theme={null}
curl -X POST https://api.dialnexa.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc123", "phone_number": "+919876543210", "metadata": {}}'
```

## Response format

Successful responses return HTTP `200` or `201` with a JSON body. Errors return a standard error object:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed: phone_number must be in E.164 format",
  "error": "Bad Request"
}
```

See the [Errors](/docs/api-reference/errors) page for a full list of error codes and how to handle them.

## Tools

First-party SDK packages are not yet published - the HTTP API is the supported integration path, and it works with any HTTP client. The [SDKs section](/docs/sdks/overview) has copy-paste HTTP patterns for TypeScript and Python, plus the status of the planned client SDKs. For interactive testing, every endpoint in this reference includes a built-in request builder: fill in your API key and parameters, then send directly from the docs.

AI agents and IDE assistants can also use the [DialNexa docs MCP server](https://dialnexa.com/docs/mcp) to search the docs and read documentation files through MCP tools.