> ## 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. # Migrate to the DialNexa v1 API > Migrate an existing DialNexa integration to the v1 API by mapping supported operations, checking schemas, testing side effects, and verifying production results. To migrate to the DialNexa v1 API, use `https://api.dialnexa.com/v1` as the base URL and rebuild each integration flow from the operations listed in this API reference. Do not assume that adding `/v1` to an older request produces an equivalent operation. Confirm the current request schema, response schema, side effects, and retry guidance before changing production traffic. Legacy unversioned routes with confirmed `/v1` replacements were scheduled for deprecation on July 31, 2026. When deprecation is active, those routes return `410 Gone` and include the replacement path in the response body. Some vendor callbacks and explicitly deferred routes can remain unblocked, but you should treat `/v1` as the current integration surface. ## Who this migration guide is for Use this guide if you maintain an existing server-side integration and need to move it to the current public API. It is also useful when you are replacing a shared HTTP wrapper, regenerating a client from OpenAPI, or auditing requests that were written before your team standardized on `/v1`. ## Before you migrate to the v1 API * Create or identify a non-production DialNexa workspace for testing. * Store a valid API key in a secrets manager or environment variable. * Record every DialNexa operation your integration performs. * Capture representative request bodies and the response fields your code reads. * Identify state-changing or billable requests that must not be retried blindly. * Decide how you will compare results between staging and production. ## Map each workflow to a current resource Use the resource pages below as the source of truth. If a capability is not listed in the current API Reference, do not infer or construct an undocumented route. | Capability | Current v1 resource | What to confirm | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | Create and manage agents | [Agents](/docs/api-reference/v1/agents/overview) | Required catalog IDs, draft versions, publishing, and phone-number assignment. | | Start and inspect calls | [Calls](/docs/api-reference/v1/calls/overview) | Required `metadata`, destination validation, billing risk, and timeout reconciliation. | | Run bulk calling jobs | [Batch Calls](/docs/api-reference/v1/batches/overview) | Recipient validation, queue behavior, lifecycle actions, and retry safety. | | Inspect and control workflows | [Workflows](/docs/api-reference/v1/workflows/overview) | Supported status actions, lead operations, and dashboard-only graph editing. | | Manage knowledge bases | [Knowledge Base](/docs/api-reference/v1/knowledge-base/overview) | File requirements, indexing state, agent attachments, and deletion effects. | | Manage phone numbers | [Phone Numbers](/docs/api-reference/v1/phone-numbers/overview) | Provider inventory, purchasing, SIP trunks, routing, and destructive deletion. | | Select voices and models | [Voices](/docs/api-reference/v1/voices/list), [Languages](/docs/api-reference/v1/languages/list), [LLMs](/docs/api-reference/v1/llms/list), and [Transcribers](/docs/api-reference/v1/transcribers/list) | Stable IDs, provider availability, language compatibility, and fallback options. | | Register event notifications | [Webhooks](/docs/api-reference/v1/webhooks/overview) | Event names, HTTPS delivery, secret storage, and raw-body signature verification. | ## Migrate one operation at a time Find the operation under **Endpoints** and confirm that it covers the business action your integration performs. Treat the operation page and its request panel as authoritative. Set the base URL to `https://api.dialnexa.com/v1`, keep the Bearer API key in the `Authorization` header, and construct the body from the current schema. Remove fields that are not accepted by the v1 request. Compare the documented success response and operation-specific errors with the fields your code expects. Update parsers, types, and persistence logic before sending live traffic. Follow the safety label on the endpoint page. Read operations can usually be repeated. State-changing, destructive, or billable operations require a verification read before retrying after a timeout. Confirm the HTTP response and the resulting DialNexa state. For calls and batches, also verify the outcome in [Call History](/docs/monitoring/call-history). For agents, workflows, knowledge bases, webhooks, and phone numbers, read the resource again or confirm it in the dashboard. ## Verify the complete migration Before routing all production traffic through the v1 integration: 1. Exercise every operation with representative staging data. 2. Confirm success responses, validation errors, authorization failures, and not-found behavior. 3. Test a timeout on each state-changing flow and verify before retrying. 4. Compare stored IDs, statuses, timestamps, and nested response fields with your existing assumptions. 5. Confirm webhook signatures against the raw request body. 6. Monitor production errors and duplicate side effects during the rollout. 7. Remove unused request code only after the v1 flow is stable. ## Troubleshooting v1 migration issues | Problem | What to check | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Send the complete API key as `Authorization: Bearer YOUR_API_KEY`. Confirm the key is active in the correct workspace. | | `404 Not Found` | Confirm the operation appears under **Endpoints**, the request includes `/v1`, and the resource belongs to the authenticated workspace. | | `410 Gone` | The request used a legacy unversioned route that has a `/v1` replacement. Read the `replacement` field and rebuild the request against that documented `/v1` operation. | | `400 Bad Request` | Compare the request with the current schema. Check required fields, accepted enums, ID formats, and unknown properties. | | Response parsing fails | Compare your stored types with the documented response and regenerate types from [OpenAPI](/docs/api-reference/openapi.json) when appropriate. | | A capability is not listed | Use the dashboard for that action or contact DialNexa support. Do not construct an undocumented API route. | | A timed-out request may have succeeded | Read or list the affected resource before retrying. This is especially important for calls, batches, purchases, and create operations. | ## Related pages * [API Introduction](/docs/api-reference/introduction): base URL, request format, and response format. * [Authentication](/docs/api-reference/authentication): Bearer API keys and webhook signature verification. * [Errors](/docs/api-reference/errors): standard error shapes and recovery steps. * [Reliability and retries](/docs/api-reference/reliability): timeout, reconciliation, and retry guidance. * [Pagination](/docs/api-reference/pagination): list response shapes and pagination parameters. * [Code examples](/docs/api-reference/code-examples): complete TypeScript and Python v1 workflows.