Versioning and changelog policy

The policy for the public API

The public API (/v1) is in development. This policy applies from its first public version; the first version’s date is set when the beta opens.

Your integration should keep working while MoreVoice improves. So we version the API by date, pin each API key to the version that was current when you created it, and never make a breaking change inside a version.

Two layers

• /v1 in the URL changes only for a complete redesign of the API.
• A dated version (for example 2026-11-01) covers every change in between. A new dated version is released only when a change would break existing code.

Choosing a version

Each API key is pinned to the version that was current when the key was created. Requests made with that key get that version’s behaviour, so nothing changes for you until you decide to upgrade.

To use another version for one request, for example while you test an upgrade, send the MoreVoice-Version header:

POST /v1/calls HTTP/1.1
Host: api.morevoice.ai
Authorization: Bearer mv_test_sk_…
MoreVoice-Version: 2026-11-01

Every response says which version answered it, in the same MoreVoice-Version header. A version that doesn’t exist is rejected with 400 and the error code unknown_version.

Webhook payloads follow the version of the endpoint they’re sent to, so an upgrade never changes the shape of events you already handle.

What can change without a new version

These changes are not breaking. They can ship at any time, and your code must accept them:

• new endpoints and new resources;
• new optional request parameters;
• new fields in responses and in webhook payloads;
• new event types;
• new values in enumerations. Enums are open: treat a value you don’t know as “other” instead of failing;
• new error codes, and changes to the wording of error messages (match on type and code, never on message);
• the order of fields in JSON, and the length and format of IDs (IDs are opaque strings with a type prefix, such as call_…).

What needs a new version

Anything that could break code written for an earlier version only ships in a new dated version:

• removing or renaming an endpoint, a field or a parameter;
• changing a field’s type or meaning;
• making an optional parameter required;
• changing default behaviour, validation rules or the meaning of a status;
• changing the shape of a webhook payload.

Older versions keep working: MoreVoice translates responses back to the shape each version expects.

Deprecation and sunset

When we retire a version or an endpoint:

1. It is announced in the changelog, with a sunset date at least 12 months after the deprecation.
2. Responses carry two headers so your monitoring can notice: Deprecation (RFC 9745) and Sunset (RFC 8594), with the sunset date.
3. We email the owners of API keys that still use it, six months, three months and one month before the sunset date.

The changelog

Every change to the public API is listed in the changelog, newest first, with an RSS feed. Each entry is dated and tagged:

Tag	Meaning
Added	Something new. Safe to ignore until you need it.
Changed (versioned)	A breaking change, available only in a new dated version. The entry names the version and explains how to upgrade.
Deprecated	Something that will go away, with its sunset date.

Upgrading to a new version

1. Read the changelog entries between your pinned version and the new one.
2. Send the new version in the MoreVoice-Version header from a test-mode key, and run your tests.
3. When everything passes, create a new key (it is pinned to the current version) and roll it out, then revoke the old one.