API Versioning & Deprecation

PearMedica uses URL-based versioning to ensure backward compatibility while allowing the API to evolve. This page covers our versioning strategy, deprecation timeline, and migration guidance.

Versioning Scheme

All API endpoints include a version prefix in the URL path. The current version is v1.

http

# Current (stable)
POST https://api.pearmedica.com/v1/assess
POST https://api.pearmedica.com/v1/parse
GET  https://api.pearmedica.com/v1/symptoms
GET  https://api.pearmedica.com/v1/health

Backward Compatibility Guarantees

Within a major version (e.g., v1), we guarantee the following:

Additive Changes Only

We may add new fields to response objects, new query parameters, and new endpoints. Existing fields and behavior will not change.

No Field Removal

Existing response fields are never removed within the same major version. Fields may be deprecated but will continue to be returned.

Stable Error Codes

Error codes like INVALID_API_KEY or RATE_LIMIT_EXCEEDED are permanent within a version. New error codes may be added.

Consistent Authentication

The Bearer token authentication method and API key format (sk_live_ / sk_test_) will not change within a major version.

What Constitutes a Breaking Change

The following changes will always result in a new major version (e.g., v2):

Removing or renaming an existing JSON field in a response
Changing the type of an existing field (e.g., string → number)
Changing the authentication mechanism
Removing an endpoint
Changing the meaning of an existing error code
Changing required request fields in a backward-incompatible way

Deprecation Policy

When a new major version is released:

Announcement (Day 0)

New version released. Deprecation notice published in the Changelog and emailed to all API key holders.

Migration Period (6 months)

Both versions run in parallel. The deprecated version adds a Deprecation header to all responses. Migration guide published.

Sunset Warning (Month 5)

Final reminder sent via email. Dashboard shows migration alert. Rate limits may be reduced on the deprecated version.

Sunset (Month 6)

The deprecated version returns 410 Gone. All traffic must use the new version.

Current API Version Status

Version	Status	Notes
v1	Current — Stable	Full support. No planned deprecation.

Loading documentation…

Error Handling Code Examples

What Constitutes a Breaking Change

The following changes will always result in a new major version (e.g., v2):

Removing or renaming an existing JSON field in a response

Changing the type of an existing field (e.g., string → number)

Changing the authentication mechanism

Removing an endpoint

Changing the meaning of an existing error code

Changing required request fields in a backward-incompatible way

Version

Status

Notes

Current — Stable

Full support. No planned deprecation.