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 by 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, regenerated on every deploy, and is useful for generating client SDKs, mocks, or contract tests. The URL stays /openapi.json within v1; treat the paths and fields in the document, not its version number, as the source of truth.