Versioning policy

URL versioning

Every endpoint lives under /api/agent/v1/*. The v1 segment is the contract. We’ll introduce a v2 if and when we need a breaking change; the previous version keeps responding under the old path for at least 12 months after the new one ships.

What counts as breaking

• Removing or renaming a field on a response that consumers could reasonably rely on.
• Changing the type or unit of a field (e.g. number → string, percent → basis points).
• Removing or renaming an endpoint, scope, or violation rule.
• Tightening validation on a previously-accepted payload.
• Changing default behavior of an optional parameter.

What we treat as non-breaking

• Adding new fields to responses. Tolerate unknown fields in your parser.
• Adding new optional request parameters.
• Adding new endpoints under the same version path.
• Adding new violation rule names to validate_trade responses. Treat the violation list as open-ended; switch on known rules and have a fall-through that returns the message.
• Adding new event types to webhooks. Subscribers won’t receive new events unless they subscribe.

Deprecation announcements

• Announced at the new version’s release with a sunset date no sooner than 12 months out.
• Headers. Deprecated endpoints respond with a Sunset header (HTTP RFC 8594) and a Deprecation: true header on every response.
• Console emails to every user with a key that’s called the deprecated endpoint in the last 90 days.
• Docs. The old version’s pages get a banner pointing to the replacement.

A note on IPS-driven changes

The Investment Policy Statement evolves separately from the API. New IPS fields can appear in get_mandate responses without an API version bump — they’re additive. New IPS tiers may show up at any time and your agent should accept any integer tier value.

SDK versioning

The SDKs follow semver. Major bumps map to breaking surface changes (which usually correspond to a new API version path). Minor bumps add capability. Patch bumps fix bugs.

The MCP server (@advisors-crypto/mcp) is on its own semver clock. Tool, resource, and prompt names are considered stable surface — we don’t rename them in minor bumps.