Versioning

hellomateo uses two versioning signals: the /v1 API path and the required hellomateo-version request header. They solve different problems.

The path version is a long-term safety boundary. We do not expect to introduce /v2 as part of normal API evolution; /v1 should remain the stable API entry point. A future /v2 would only be considered for broad behavioral changes that cannot be made safely inside the existing API contract.

The request header is how clients opt in to API changes over time. New endpoints, resource fields, response-shape improvements, validation changes, and other resource-level changes can be introduced behind a dated version without forcing every integration to change at once.

API path

Use the /v1 path for API endpoints:

https://api.getmateo.com/v1

Endpoint paths in the API reference include this prefix, for example /v1/contacts.

Version header

Send the hellomateo-version header on every request together with your API token:

hellomateo-version: 2026-07-01

The current supported API version is 2026-07-01.

curl "https://api.getmateo.com/v1/contacts" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

Why both exist

The /v1 path keeps the API origin explicit and gives us an emergency escape hatch for fundamental protocol-level changes. It is not intended to be a release train.

The version header gives clients precise control over the API behavior they receive. Existing clients keep sending the version they already tested. When a later version becomes available, you can upgrade deliberately, test it in your environment, and switch production traffic only when you are ready.

Because the selected version is controlled per request, switching forward or back is straightforward: change the header value your client sends. This makes rollouts, canaries, and rollbacks easier than coupling behavior changes to a new base URL.

Backward compatibility

Changes introduced through the version header are designed to be backward compatible for existing clients. Older clients continue to receive the behavior associated with the version they already send.

Future versions may expose improved resource shapes, additional fields, new validation behavior, or other refinements. Those changes are opt-in: update the header only after your integration has been tested with the new version.

Missing or unsupported versions

If the version header is missing, the API returns 400.

If the version header is present but unsupported, the API returns 400 with the INVALID_VERSION_HEADER error code. Version failures use the same JSON error response shape as other API errors.