Versioning and deprecation.

How Probara versions its API, what "breaking change" means, and how much notice you get before anything changes under you.

Current version
v1
All current endpoints are under /v1/. This is the stable baseline. No breaking changes are planned.

What counts as a breaking change

A new major version (/v2/) is required when any of the following changes:

breaking
  • Removing a field from a response body
  • Changing the type or format of an existing field
  • Removing an endpoint or HTTP method
  • Changing authentication mechanism
  • Changing rate-limit semantics in a way that reduces throughput for existing callers
non-breaking
  • Adding a new field to a response body
  • Adding a new endpoint
  • Adding a new optional request parameter
  • Adding a new error code variant
  • Performance improvements with no interface change

Deprecation policy

When a breaking change is introduced in a new version, the prior version enters a deprecation window. During this window, the old version continues to work. After the window closes, the old version is sunsetted.

Minimum deprecation notice 12 months from the date the new version is available in production
Notification channels Email to the address on your account, a Deprecation response header on all calls to the deprecated version, and an entry in this changelog.
Extension requests Enterprise customers may request a migration extension. Contact hello@probara.dev.
Breaking change grandfathering Founding Design Partner accounts (Developer tier, 2026 cohort) receive 24-month rate-lock on pricing AND receive a minimum 18-month deprecation window, not 12.

Pinning your version

Use the Probara-Version request header to pin to a specific version within the major. This lets you take control of when you adopt minor behavior changes.

Pin to v1 baseline
GET /v1/evidence
Authorization: Bearer <your-key>
Probara-Version: 2026-06-28

The Probara-Version date must be a date on which the v1 API was active. If omitted, you receive the latest stable behavior. The API echoes the resolved version date back in the Probara-Version response header.

What happens at sunset

1
New version ships
/v2/ becomes available. Old version continues to work normally. Deprecation header added to all /v1/ responses.
2
6-month checkpoint
Email reminder sent to all accounts still calling the deprecated version. Migration guide published in docs.
3
30-day final notice
Final email notice. Sunset date published in changelog and on status page.
4
Sunset
Requests to the old version return 410 Gone with a migration pointer. No data is lost; evidence IDs remain accessible via the new version.