Versioning

The API is versioned in the path. Every endpoint documented here lives under /v1, and the contract’s own version, reported in openapi.json as 1.0.0, tracks changes within it.

What changes without a new version

Additive changes are not considered breaking and can appear in /v1 at any time:

• New endpoints.
• New optional fields on request bodies and new query parameters.
• New fields on responses.
• New values for enumerations that are documented as open, and new pending.reason values.
• Longer or more specific title and detail text in error responses (code values stay stable).

Write your client so these do not break it: ignore response fields you do not recognise, and do not fail on an unknown status or pending.reason, treat it as “not one of the states I handle yet”.

What gets a new version

Anything that would break a correctly written /v1 client ships under a new path, /v2, with /v1 kept running for a deprecation period announced in the changelog:

• Removing or renaming a field, parameter or endpoint.
• Changing a field’s type or the meaning of an existing value.
• Tightening validation so that previously valid requests are rejected.
• Changing an error code or the status it is returned with.

Keeping up

• The changelog records every change to the contract, additive or not.
• The live contract is always at https://app.novilfleet.com/v1/openapi.json; diff it against the copy you built against.
• The API reference renders the current contract.