Versioning

The Sharpe API uses URL-path versioning (/v1/) and follows a clear deprecation policy to protect your integration.

Current version

The current and only production version is v1, accessible at https://www.sharpe.ai/api/v1/.

Backward-compatible changes

The following changes are considered backward-compatible and may be made without a version bump or advance notice:

• Adding new endpoints
• Adding new optional query parameters to existing endpoints
• Adding new fields to response objects
• Adding new error codes
• Adding new enum values to non-strict parameters
• Improving error messages for clarity

Your integration should handle unknown response fields gracefully (ignore fields you don't recognize).

Breaking changes

The following changes are considered breaking and will only be introduced in a new API version:

• Removing or renaming existing endpoints
• Removing or renaming response fields
• Changing the type of an existing response field
• Making an optional parameter required
• Changing authentication requirements
• Changing the response envelope structure

Deprecation policy

When a breaking change is necessary:

1. Advance notice — The change is announced in the changelog with a target retirement date, typically 6 months out for endpoint removals and 3 months for field renames
2. Deprecation response header — Deprecated request shapes return a Deprecation HTTP header on every response. The header text states the retirement date and the migration path
3. Dual availability — The old and new versions run in parallel for the full notice window

Monitoring for changes

• Changelog: /docs/changelog — all changes logged with dates and tags
• Response headers: Check for the Deprecation header on any response — its presence means the request used a feature that will be removed