Versioning
The major version is in the URL path:
v1 is a compatibility boundary. Within it, Fluent may:
- add a new endpoint,
- add an optional request parameter or body field,
- add a field to a response object,
- add a value to a non-exhaustive enumeration such as a document type.
Within v1, Fluent will not remove or rename a response field, make an optional request field required, change a field’s type, or change the meaning of an existing status code. A change that cannot be made additively ships as a new major version — /api/v2 — and v1 keeps working.
Clients should ignore response fields they do not recognize, and should not infer database structure from flexible record or document payloads.
Deprecation
When an endpoint or a field is going away, Fluent announces it in three places:
- The affected responses carry
Deprecation and Sunset headers.
- The OpenAPI description marks the operation
deprecated: true.
- The change is described in these docs, alongside the replacement.
Deprecation is the moment the endpoint became deprecated — it may be in the past. Sunset is the moment it stops answering. There are at least 180 days between the two for any endpoint in v1, so an integration that reads these headers always has a full quarter and more to migrate.
No endpoint in /api/v1 is currently deprecated. An agent can confirm that programmatically: the API index reports the current version and the deprecation conventions, and responses carry no Sunset header.
Log Deprecation and Sunset alongside your rate-limit headers. Both are
plain response headers, so noticing them costs nothing and removes the only
class of breakage that arrives without warning.
