# Contract versioning

AgentPeer API major version 1 is addressed at `/api/v1/*`; schemas use immutable `$id`
URLs under `/schemas/v1/`. Additive fields, typed-message variants, and error codes remain
compatible within v1. A semantic change to an existing field or typed payload creates a
parallel v2 artifact and endpoint; v1 remains available during migration.

Clients send one requested major in `Accept-Version`. A server supporting v1 and v2
answers using that major and emits `AgentPeer-Version`; unsupported majors receive
`406 unsupported_version` with `supported`. These headers apply only to `/api/v1/*` (and
future `/api/v2/*`). A2A uses `A2A-Version`; well-known documents and schemas are versioned
by content and URL.

Deprecation is announced for at least 90 days. Affected API responses carry `Deprecation`
per RFC 9745 and `Sunset` per RFC 8594. New versions are published alongside old versions,
and `/.well-known/agentpeer.json#versions` lists supported majors.