Openhandle API versioning and deprecation
Compatibility rules and retirement notices for the Openhandle API.
The public REST API uses URL versioning: current operations start with /v1/.
The info.version field in OpenAPI
identifies the document release. It does not select a different API version.
Compatibility
Breaking contract changes use a new major URL version. Examples include removing a documented field or changing its type. Clients should ignore unknown response fields so additive fields can be introduced within a major version. Additional endpoints can also be introduced without changing existing endpoints.
Source platforms can change availability or stop exposing data. A platform failure or an unknown metric is not an API version change. Continue handling the documented error codes and nullable metrics.
Deprecation and retirement
Version 1 has no announced retirement date. A deprecation notice will identify the affected version or operations, a replacement, migration steps, and any scheduled retirement date in this documentation. Deprecation means an operation is discouraged; sunset means it is scheduled to stop responding.
No fixed minimum notice period is currently promised. Review the published notice for the affected operation before planning a migration. Contact hello@openhandle.dev with compatibility questions.
For automated monitoring, the standards define Deprecation as a Structured
Field date and Sunset as an HTTP date. A Link with rel="deprecation" can
identify migration documentation. These headers are only relevant when a
resource has an actual deprecation or retirement announcement. Active v1
operations do not emit artificial retirement dates.