Copy page

API fundamentals

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.
• 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; an existing path with an unsupported method answers 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 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.

Additive changes

These can ship at any time, without advance notice, and are listed in the 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.
• 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 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).

During the private preview, operations labelled Preview may still change; see API availability.