Versioning policy

What changes in v1, and how we deprecate.

Version in the path

The API lives under /v1. A version number appears only in the path, never in a header or parameter.

What stays the same within v1

Changes to v1 are additive only. We may add:

• new endpoints
• new optional request fields
• new fields in responses
• new error codes within an existing status

We will not remove or rename a field, change a type, make an optional field required or change a status code in v1. Write your client to ignore response fields it does not know.

Breaking changes

A breaking change ships as /v2, alongside v1. When we deprecate a version, every response from it carries:

• Deprecation: the version is deprecated.
• Sunset: the date it stops working.
• Link: a link to the migration guide, with rel="deprecation".

A path with a version we do not have returns 404 with the code unknown_api_version.

Where things live

Each service has its own host. The host and path of these are permanent and do not change with the API version:

• API: https://api.virdify.com. All endpoints are under /v1.
• Badges and verification pages: https://badger.virdify.com/badge/* and https://badger.virdify.com/v/*. Badges are embedded on other people's pages, so these URLs never move.
• Sign-in and dashboard: https://badger.virdify.com/login and https://badger.virdify.com/dashboard.
• Documentation: https://docs.virdify.com, including /llms.txt and /changelog.

The machine-readable description of v1 is at https://api.virdify.com/v1/openapi.json, and every change is in the changelog.