Developers

Versioning & deprecation policy

Versions

The HTTP API is versioned in the path: everything under /v1 is the v1 API. The OpenAPI document at /openapi.json describes the current v1 surface. The MCP tool surface is versioned with the platform and announced the same way.

What counts as a breaking change

• Removing or renaming a route, a request field, a response field or an error code.
• Changing a field's type or a verdict vocabulary's meaning.
• Tightening a validation rule so previously accepted requests fail.
• ditive changes — new routes, new optional fields, new error codes, new enum values a client can ignore — are not breaking and may ship in v1 at any time.

How deprecations work

• A breaking change ships only under a new version path; the old path keeps working for a published deprecation window.
• Deprecations are announced on https://www.rightshold.com/changelog before the window starts, with the removal date and the migration path.
• Rules that govern fees, grades, arbitration or access follow the stricter rule-change discipline instead: announced at least 7 days ahead and hash-sealed (https://www.rightshold.com/transparency/changes).

Errors are an interface

Every error code is stable and catalogued at https://www.rightshold.com/v1/errors (one code: https://www.rightshold.com/v1/errors/{code}) with its HTTP status, whether it is retryable, and the action to take. Client code should branch on the code, never on message text.