# Versioning, limits and compatibility

`/v1` is the stable major contract. Additive optional fields may be introduced
without changing the major version. A breaking request/response, identifier,
cursor or consent semantic receives `/v2`; v1 remains available for at least six
months after a dated deprecation announcement.

The canonical machine description is `openapi.yaml`; webhook messages are in
`asyncapi.yaml`, and standalone response/request schemas live in `../schemas`.
CI parses all documents and runs their contract fixtures together with the
unchanged V6 legacy/differential suite.

Baseline pull/detail quota is 600 requests per integration per hour, burst 20
per minute, four concurrent requests, 500 records and 8 MiB per response.
Statistics use 120 requests/hour and 2 MiB. Limits aggregate all active
certificates and also apply per certificate and IP. `429` includes
`Retry-After` and limit/remaining/reset headers. The reference cadence is one
pull every 15 minutes.

Pull sync is canonical and recoverable. Cursors are opaque, authenticated and
bound to integration/environment/stream/resource; clients must not inspect
them. Read responses use strong ETags and return an empty `304` for a matching
`If-None-Match`. API errors follow RFC 9457 `application/problem+json` and never
contain internal identifiers or storage errors.