API lifecycle and compatibility

The public API is versioned under /api/v1. The v1 contract prioritizes additive, backward-compatible changes.

​

Compatibility expectations

Integrations should:

• Ignore response fields they do not understand.
• Treat enum values as open unless the endpoint says otherwise.
• Handle documented null and omitted fields correctly.
• Follow pagination links/cursors rather than assuming a fixed page size.
• Avoid parsing opaque IDs.
• Use the documented endpoint and operation IDs rather than display labels.

​

Changes that may be additive

New response fields, new resources, new optional request fields, and new endpoints can be added without changing the v1 base URL. Clients should not fail closed merely because a response contains an unknown field.

​

Deprecations

Deprecated routes and fields will be called out in the API changelog and endpoint reference. When a replacement exists, the deprecation notice will include the migration path and the planned removal window.

​

Breaking changes

Breaking changes require an explicit migration path and a versioning decision. Do not infer a new major version from a new optional field or endpoint.