Fluos API versioning and deprecation
Fluos versions its public HTTP API under /api/v1/ and with the API-Version header. Deprecated versions send Sunset and Deprecation headers.
Agents should pin integrations to a Fluos API version. Fluos will not silently change a published version.
How Fluos versions the API
- URL path (canonical):
/api/v1/…— for example/api/v1/search,/api/v1/openapi.json,/api/v1/mcp. - Version header: send
API-Version: 1. Responses echoAPI-Version: 1. - Unversioned aliases such as
/api/searchand/openapi.jsonare equivalent to v1.
Breaking changes ship as /api/v2/, not as a change to v1. The OpenAPI info.version field tracks the same major (1.0.0).
curl -sI -H 'API-Version: 1' https://www.fluos.io/api/v1/search?query=webhooksDeprecation policy
When Fluos retires a version or an operation:
| Header | Spec | Meaning |
|---|---|---|
Deprecation: true | RFC 9745 | This version or operation is deprecated |
Sunset: <HTTP-date> | RFC 8594 | Earliest date the version may be removed |
Link | RFC 8288 | rel="deprecation" points at this page; rel="successor-version" points at the replacement |
Fluos gives at least 180 days of Sunset notice before removing a deprecated public version. v1 is current and has no sunset date.
Rate limits
Public discovery endpoints (search, MCP, markdown/JSON negotiation) return IETF RateLimit / RateLimit-Policy headers on every response, plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 includes Retry-After. See Fluos API reference.