// developers · versioning
365 days’ notice before anything is removed.
Within API version 1, changes are additive. Removing anything needs a dated announcement at least 365 days ahead, and the contract test that guards the API fails the build if one is shorter.
// the promise
What counts as breaking.
Breaking, so announced first
- Removing a field, an endpoint, a tool or a scope
- Narrowing an accepted input
- Changing a field’s type, or what an existing value means
- Changing the scope an existing operation requires, even to one that looks narrower
Never allowed at all
A read never becomes a write. An operation you integrated as a read will not start changing a store under any notice period; that would be a new operation with a new name.
A version that cannot be expressed additively would be served on a new path (/api/v2), with /api/v1 kept under the same window from the day it ships. MCP protocol revisions move on the specification’s schedule and are independent of the API version.
// announced
Current deprecations.
| Subject | Announced | Stops working | Instead |
|---|---|---|---|
POST /api/oauth/register (Dynamic Client Registration) | 6 September 2026 | 6 September 2027 | Use a Client ID Metadata Document (CIMD): pass an https URL serving your client metadata as client_id. Existing registered client_ids keep working past the sunset date; only new registrations stop. |
// headers
Every affected response says so.
Every response carries magistry-api-version. A response from something deprecated also carries Deprecation (RFC 9745), Sunset (RFC 8594) and a Link rel="deprecation" to the changelog, so a gateway or SDK that already watches those headers needs nothing Magistry-specific.
POST /api/oauth/register → HTTP/1.1 201 Created
Deprecation: Sun, 06 Sep 2026 00:00:00 GMT
Sunset: Mon, 06 Sep 2027 00:00:00 GMT
Link: <https://app.magistry.io/api/v1/changelog.json>; rel="deprecation"; type="application/json"
magistry-api-version: 1curl https://app.magistry.io/api/v1/changelog.jsonNot part of the contract: rate limits, the prose in tool descriptions (written for models and rewritten when that helps them), and the set of tools one particular credential sees, which follows its grant.
Build on the same tools the product uses.
Create a sandbox key on demo data, or start free and connect a real store.
MCP + REST · OAuth 2.1 or API keys · every call audited