Versioning

The Patholytix API is versioned to allow the platform to evolve without breaking existing integrations.

Current version

The current API version is v1.

Backwards compatibility guarantee

Within a major version, we guarantee:

• Existing endpoints will not be removed without a 6-month deprecation notice
• Existing request fields will not be removed or have their type changed
• Existing response fields will not be removed or have their type changed
• HTTP status codes for existing scenarios will not change

We may add new optional request fields, new response fields, or new endpoints within a major version without a deprecation notice. Well-written clients should handle unknown response fields gracefully (ignore unknown fields rather than failing).

What constitutes a breaking change

Change	Breaking?
Adding a new optional request field	No
Adding a new response field	No
Adding a new endpoint	No
Removing a request field	Yes
Removing a response field	Yes
Changing a field type	Yes
Changing a status code	Yes
Removing an endpoint	Yes
Changing authentication requirements	Yes

Deprecation policy

When a breaking change is required:

1. The deprecated behaviour is announced at least 6 months in advance via:

   • Deprecation response header on affected endpoints
   • Sunset response header indicating the retirement date
   • Changelog entry on this portal

2. The old and new behaviour are supported concurrently during the deprecation window

3. On the retirement date, the deprecated endpoint/field is removed and returns 410 Gone

Deprecated endpoint response

When an endpoint is deprecated but not yet retired:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Link: </api/v2/studies>; rel="successor-version"

Retired endpoint response

When an endpoint has been retired:

HTTP/1.1 410 Gone
Content-Type: application/problem+json

{
  "type": "https://api.patholytix.com/errors/gone",
  "title": "Gone",
  "status": 410,
  "detail": "This API version has been retired. Migrate to /api/v2/studies.",
  "instance": "/api/v1/studies"
}

Retired endpoints never silently redirect — they return 410 Gone so integrations fail loudly rather than silently using a different API surface.

Concurrent version support

At least two major versions are supported concurrently, or all versions released within the last 18 months, whichever is longer. This gives integrations a guaranteed window to migrate.

Migration guides

When a new major version ships, a migration guide is published here documenting:

• What changed between versions
• How to update request/response handling
• A timeline with the old version's retirement date

Changelog

Changes to the API are documented in the Changelog section, including:

• New endpoints and fields
• Deprecation announcements
• Retirement notices