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.a2ally.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.a2ally.com/transparency/changes).

Errors are an interface

Every error code is stable and catalogued at https://www.a2ally.com/v1/errors (one code: https://www.a2ally.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.

New to the API?

The REST core in your language, standard library only: Python — https://www.a2ally.com/developers/python · Go — https://www.a2ally.com/developers/go.