> ## 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.

# Migrating to the v1 API

> How DialNexa's versioned /v1 API relates to legacy unversioned endpoints, and how to move integrations across.

DialNexa's `/v1` API is the versioned API surface for new integrations. The v1 reference now includes only endpoints exported from the latest backend Swagger document with the explicit `V1` tag. Legacy unversioned endpoints remain documented separately for existing integrations.

## What is changing

Historically, DialNexa endpoints were served without a version prefix, for example `POST https://api.dialnexa.com/calls`. New integrations should use the versioned path where one is documented, for example `POST https://api.dialnexa.com/v1/calls`.

The unversioned endpoints are legacy and are scheduled for removal on **July 31, 2026**. Use the pages under **Endpoints - v1** as the current source of truth for the versioned API.

## When to migrate

Migrate when your integration calls a legacy endpoint that has a matching v1 page. Do not assume every legacy resource has a v1 equivalent yet. If a v1 page is not present in this reference, keep using the documented legacy endpoint until DialNexa publishes the v1 operation.

## How to migrate

For simple replacements, update the URL path and keep the same Bearer API-key header.

```bash theme={null}
# Before: legacy, deprecated
curl "https://api.dialnexa.com/calls" \
  -H "Authorization: Bearer YOUR_API_KEY"

# After: v1, recommended
curl "https://api.dialnexa.com/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Work endpoint by endpoint. Check the request schema, response schema, and access note on each v1 page before changing production traffic.

## Endpoint status

| Status                                   | What it means                                            | What you should do                                                          |
| ---------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
| Listed under **Endpoints - v1**          | The backend exports the operation with the `V1` tag.     | Use the v1 page as the reference for new work.                              |
| Listed under **Endpoints - Legacy** only | The operation is still part of the legacy API reference. | Keep existing integrations on the legacy path until a v1 page is published. |

## Important differences

| Legacy endpoint                             | v1 endpoint                                                | What changed                                                                                                                 |
| ------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `/agents2`                                  | [`/v1/agents`](/docs/api-reference/v1/agents/list)              | The v1 agents API uses a different controller and request schema. Review the request body before migrating.                  |
| Campaign and campaign-lead endpoints        | Not currently listed under v1                              | These controllers are not part of the current public v1 Swagger tag set. Keep using the legacy pages for now.                |
| Web call and outbound-call helper endpoints | Not currently listed under v1                              | They are not part of the current public v1 reference. Keep using their documented legacy pages until a v1 page is published. |
| Agent post-call LLM helper endpoint         | [`PATCH /v1/agents/{id}`](/docs/api-reference/v1/agents/update) | Set or clear `post_call_analysis_llm_id` on the agent update endpoint instead of calling a separate post-call LLM route.     |

## Verify the migration

1. Update one endpoint at a time in a staging environment.
2. Confirm the request returns the status code and response shape shown on the v1 page.
3. Check any downstream parser for field-name assumptions.
4. Move the production integration only after the v1 call is stable.

## Related pages

* [Authentication](/docs/api-reference/authentication)
* [Errors](/docs/api-reference/errors)
* [Pagination](/docs/api-reference/pagination)