Versioning

The major version is in the path: /v1. Within /v1, changes are additive only.

Pin a version

An API version is a date. The first request from a key with no pin of its own pins your organisation to the current version, and every response tells you which version it used in the Vojo-Version header.

Vojo can also pin a secret key when it issues the key, so ask your Vojo representative if you need that. The order is the Vojo-Version header, then the key's pin, then your organisation's.

To choose a version for one request, send Vojo-Version:

curl https://api.vojo-media.com/v1/screens \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Vojo-Version: 2026-10-07"

An unknown date returns 400 unsupported_api_version.

Write clients that keep working

Because /v1 grows by addition, your client has to cope with things it hasn't seen before:

• Ignore response fields you don't recognise.
• Handle unknown enum values gracefully, including error code values.
• Don't validate responses strictly against the contract's schemas. They describe today's exact shape, and new fields will appear.

Deprecations

A deprecated endpoint sends Deprecation and Sunset headers, with at least 180 days' notice. The changelog lists what has changed.