Versioning

URL-based versioning

Every endpoint lives under a version prefix:

https://api.allisonvoice.com/v1/locations
                             ^^
                         version prefix

When we ship a breaking change, a new prefix (/v2/) gets introduced alongside v1. Existing integrations keep working on v1 until the documented deprecation window ends.

What counts as a breaking change

Within v1, we commit to the following. If a change to the API would violate any of these, it ships in v2 instead:

• Removing a field from a response
• Renaming a field in request or response
• Changing a field's type (e.g. string → number)
• Making an optional request field required
• Adding a new validation rule that rejects previously-valid input
• Changing the URL path for an existing endpoint
• Removing an endpoint entirely
• Changing the HTTP status code of a response (e.g. 200 → 202)
• Changing the structure of error bodies

The following are not breaking changes and can ship in v1:

• Adding new fields to responses (your parser must ignore unknown fields)
• Adding new optional request fields
• Adding new endpoints
• Adding new enum values (your parser must handle unknown values gracefully)
• Adding new query parameter filters
• Changing freeform error message text (the error string can be translated or reworded)
• Performance improvements
• Bug fixes that restore documented behavior

How to write forward-compatible clients

• Ignore unknown fields. A field you don't know about today might ship in a response next month. Don't throw.
• Handle unknown enum values. We might add a new disposition or source value. Default to a sensible fallback rather than crashing.
• Don't depend on error message wording. Branch on the error code (e.g. insufficient_scope), not the human-readable message.

Deprecation policy

When v2 ships, v1 will:

• Remain fully operational for at least 6 months after v2 goes live
• Include a Deprecation header with the sunset date on every response
• Include a Link header pointing at the migration guide
• Be announced in the CHANGELOG and via email to every org with an active API key

If an integration blocks your business from migrating inside that window, reach out via the dashboard support chat — we work out extensions case-by-case rather than shutting off working integrations.

OpenAPI spec

The machine-readable spec is available at /openapi.json. It reflects the currently-deployed v1 surface — useful for generating client SDKs, mocks, or contract tests. The spec version inside the document bumps with each release that adds endpoints or fields; the URL stays /openapi.json within v1.