Formaly API Versioning and Lifecycle Policy
Formaly versions its public REST API in the URL so agents and developers can integrate against a stable contract. This policy applies to endpoints under `/api/v1` and the matching OpenAPI document.
Versioning
The current stable API is v1 at /api/v1. We may add backwards-compatible endpoints, fields, enum values, and optional capabilities within v1. We do not remove or rename existing v1 fields, change their meaning, or make an optional request field required within v1.
Breaking changes are released under a new major URL version such as /api/v2. The v1 OpenAPI specification remains available at /openapi.json while v1 is supported.
Deprecation and sunset
Before retiring an endpoint or API version, Formaly will publish a migration guide and give at least 180 days' notice. During that notice period, responses from the deprecated surface include Deprecation: true, a Sunset HTTP-date, and a Link header with rel="deprecation" pointing to the migration guidance.
Agents should treat Deprecation: true as a signal to plan a migration, and should stop scheduling new work against a surface after its Sunset time. Existing API versions remain available until their published sunset date except where an urgent security issue requires a faster change.
Support and change communication
Material API changes are documented in the API reference and announced to affected API-key owners when contact information is available. If a migration path is unclear, contact support before the sunset date.