Versioning

Compatibility promise within v1

Within /api/v1 we aim for non-breaking changes only. Safe changes include:

• Adding new endpoints
• Adding optional request fields
• Adding response fields
• Adding new event types or scopes (opt-in)
• Clarifying documentation

Treat unknown response fields as ignorable so your clients stay forward-compatible.

Breaking changes

Breaking changes require a new major URL version (for example /api/v2), such as:

• Removing or renaming fields
• Changing field types or meaning
• Making previously optional request fields required
• Changing authentication or error contracts in incompatible ways

Deprecation

When a field or endpoint must be retired inside v1:

1. It is marked deprecated in docs and OpenAPI.
2. It remains available for at least 90 days after the deprecation notice.
3. Removal happens only in a later major version, or after the notice window if the path cannot be preserved safely.

Track notices in this documentation and in /api/v1/openapi.json (x-cowtic-compatibility).

SDK compatibility

@cowtic/sdk 1.x targets /api/v1. Additive v1 support produces SDK minor releases, fixes produce patch releases, and a future /api/v2 requires SDK 2.x.

Recommendations

• Pin integrations to /api/v1 explicitly.
• Prefer the OpenAPI document for codegen and contract tests.
• Design clients to tolerate additive JSON fields.
• Subscribe to webhook event types you need; ignore unknown types if you parse a shared envelope.