# API versioning and deprecation policy

Synorb keeps the public REST contract stable while allowing additive
improvements. The [OpenAPI contract](https://synorb.com/openapi.json) and
[REST guide](https://synorb.com/docs/api) are the authoritative implementation
references.

## Compatibility

- Existing endpoints, request fields, response fields, and documented meanings
  remain compatible unless a breaking change is announced.
- New response fields and endpoints may be added without a version bump.
  Clients should ignore unknown fields.
- The agent-facing machine contract is the documented `error_code` and the
  response schema, not prose copied from a marketing page.

## Deprecation and sunset

When a breaking change or retirement is necessary, Synorb marks the affected
response with standardized `Deprecation` and `Sunset` headers and provides a
deprecation link. We target at least **90 days' notice** before removal, except
for urgent security, legal, or provider failures.

Agents should log and surface these headers, follow the linked migration
guidance, and migrate before the sunset date. A deprecation header is a
migration signal, not permission to keep retrying an obsolete route.

## References

- [Agent guide](https://synorb.com/agent-guide.md)
- [Runtime bootstrap](https://synorb.com/llms.txt)
- [Extended agent reference](https://synorb.com/llms-full.txt)