API Versioning Policy
This policy governs how the National AI Feed API evolves over time — what changes freely, what never changes without notice, and how a breaking change would be handled if one is ever needed.
Current Version
The API’s version is tracked in the published OpenAPI specification’s info.version field, following standard semantic versioning (MAJOR.MINOR.PATCH).
This is separate from the openapi field elsewhere in the same file, which states which version of the OpenAPI specification format the document itself follows (currently 3.0) — not the Aigistry API’s own version.
What Changes Without Notice
The following are treated as additive, non-breaking changes. They may ship at any time, reflected in a MINOR or PATCH version increment, without advance notice — a well-built integration that ignores fields it doesn’t recognize is never affected by these.
Safe to Add
- New optional request fields
- New fields in a response object
- New endpoints
- New optional query parameters
Never Done Without a Major Version
- Removing or renaming an existing field
- Changing an existing field’s type or meaning
- Removing an endpoint
- Changing what authentication an existing endpoint requires
- Changing the meaning of an existing error response
If a Breaking Change Is Ever Needed
The API is currently unversioned in its URLs (/api/provider/, not /api/v1/provider/) — deliberately. There is no reason to introduce URL versioning before it’s actually needed.
If a genuine breaking change ever becomes necessary, it will be introduced as a new, separately versioned URL path (e.g. /api/v2/provider/), with the existing, unversioned surface continuing to function unchanged for a defined transition period — not silently altered in place.
Every currently Active Provider will be notified directly, by email, before any breaking change ships — not discovered by a failed integration call. This is deliberately a direct-contact commitment, not a changelog someone has to remember to check.
Summary
In practice: build against the current, unversioned API as documented today. New capability will keep arriving as additive fields and endpoints. Nothing that already works will be changed or removed out from under an existing integration without direct notice and a real transition path first.