# Base URL and versioning

All requests go to one base URL, and the major version is part of the path. This page explains the base URL, what counts as a breaking change, how additive changes are introduced and how deprecations are announced.

## Base URL

```text
https://voice-api.relationsai.com/v1
```

- **HTTPS only.** Send every request over TLS.
- **One URL for both modes.** The key selects test or live mode; there is no separate test host. See [Environments](/getting-started/environments).
- **Paths are case sensitive**, resource names are plural and kebab-case (`/phone-numbers`, `/webhook-endpoints`), and every path starts with `/v1`. A path that does not exist answers [`route_not_found`](/errors/route_not_found); an existing path with an unsupported method answers [`method_not_allowed`](/errors/method_not_allowed), with the supported methods in the `Allow` header.

Every example in these docs writes this URL out in full. In your own code, keep it in one configuration value so you can point the same code at another server without changing it.

## Versions

The major version is in the path: `/v1`. The contract also carries a date version, `2026-10-21` today, shown in the [API reference](/api) and in every webhook event as `api_version`.

## What v1 guarantees

Within v1, RelationsAI does not make breaking changes. These never happen in v1:

- Removing or renaming an operation, a field, a query parameter, an event type or an error code.
- Changing a field's type or format, or the meaning of an existing value.
- Making an optional request field required, or adding a new required request field.
- Changing the HTTP status of an error code, or tightening validation of values that are documented as valid today.
- Changing the authentication scheme, the id prefixes or the error envelope.

A breaking change needs a new major version (`/v2`) and at least **six months' notice** before `/v1` changes, announced in the [changelog](/resources/changelog).

## Additive changes

These can ship at any time, without advance notice, and are listed in the [changelog](/resources/changelog):

- New operations and new optional request fields or query parameters.
- New fields in responses and events.
- New values in enums (statuses, outcomes, reasons, artifact states).
- New event types and new error codes.
- New response headers.

Write your client so that none of these can break it:

- **Ignore fields you do not know.** Do not validate responses against a closed schema that rejects extra fields.
- **Treat enums as open.** Have a default branch for an unknown value, and never treat an unknown value as success. For example, an unknown call `outcome` is not `completed`.
- **Handle unknown error codes by HTTP status and `retry`.** A new code still comes with a documented status and retry hint; see [Error handling](/fundamentals/error-handling).
- **Ignore event types you did not subscribe to or do not know**, and still answer `2xx`.
- **Do not depend on field order, on the exact text of `message`, or on the format of ids.**

## Event versions

Every event carries `api_version`, the date version of its payload format (today `2026-10-21`). Additive changes do not change it. If a future payload format is incompatible, it gets a new `api_version`, announced in the changelog, so your receiver can tell which shape it is reading.

## Deprecation

When something is going to be retired, RelationsAI announces it in the [changelog](/resources/changelog) with the date it stops working, and documents the replacement. Breaking removals come with at least six months' notice and a new major version. Older `sk_live_` keys are an example: they keep working where they worked before and are not accepted by v1 (see [API keys](/getting-started/api-keys#older-keys)).

During the private preview, operations labelled **Availability: Preview** may still change; see [API availability](/getting-started/api-availability).