API Versioning

Versioning Strategy

All BioContext7 public API routes are served under a versioned prefix:

https://biocontext7.com/api/v1/search
https://biocontext7.com/api/v1/rankings
https://biocontext7.com/api/v1/health

The current API version is v1.

Response Headers

Every API response includes the following header:

Header	Value	Description
`X-API-Version`	`1`	The API version that served the response

Legacy (unversioned) responses additionally include:

Header	Value	Description
`Deprecation`	`date="2026-02-19"`	Date the unversioned path was deprecated
`Sunset`	`2026-08-19`	Date the unversioned path will stop working
`Link`	`</api/v1/...>; rel="successor-version"`	The versioned replacement URL

Legacy Path Behavior

Requests to unversioned paths (/api/search, /api/rankings, etc.) are automatically redirected to their /api/v1/ equivalents with HTTP 308 (Permanent Redirect).

HTTP 308 preserves the request method, so POST requests are redirected correctly.

Migration: Update your client code to use /api/v1/ paths directly to avoid the redirect overhead.

Versioning Policy

New versions for breaking changes. Non-breaking additions (new fields, new optional parameters) are added to the current version without bumping.
6-month deprecation window. When a new version is released, the previous version continues to work for at least 6 months with Deprecation and Sunset headers.
Version lifecycle:
- Active — fully supported, receives bug fixes
- Deprecated — still functional, returns deprecation headers, no new features
- Sunset — removed, returns HTTP 410 Gone

What Counts as a Breaking Change

Removing or renaming a response field
Changing a field's type (e.g., string to number)
Removing or renaming a query parameter
Changing error response format
Changing authentication requirements

What Does NOT Require a New Version

Adding new response fields
Adding new optional query parameters
Adding new endpoints
Bug fixes that correct behavior to match documentation