Versioning & deprecation

URL path versioning

Every REST endpoint lives under a major version prefix: https://api.statshawk.ai/v1/…. The /v1 contract is stable: within a major version we only make additive changes:

• new endpoints, new optional query parameters, new response fields
• new competitions, stat keys, or capability flags
• new error codes (existing codes keep their meaning)

Clients should ignore fields they do not recognize. Removing or renaming a field, changing a type, or changing the meaning of a status code is a breaking change and only ships as a new major version (/v2/…), served alongside /v1 for the whole deprecation window.

The MCP server follows the same rule: tool names and input schemas are stable; new tools and optional arguments may be added at any time.

Deprecation signals

When an endpoint, parameter, or tool is scheduled for removal we announce it three ways:

1. Response headers on the affected endpoint:
   • Deprecation: @<unix-timestamp>: the date the deprecation was announced (RFC 9745)
   • Sunset: <HTTP-date>: the earliest date the endpoint may stop responding (RFC 8594)
   • Link: <https://statshawk.ai/docs/changelog>; rel="deprecation"
2. The changelog: every deprecation has a dated entry naming the replacement.
3. The OpenAPI description at /openapi.json: deprecated operations and parameters carry deprecated: true.

Timeline

During a deprecation window the old surface keeps working unchanged. Agents should watch for the Sunset header and treat its presence as a prompt to migrate.

Discovering the current spec

• OpenAPI 3.1: https://statshawk.ai/openapi.json (also at https://api.statshawk.ai/api-docs/openapi.json)
• RFC 9727 API catalog: /.well-known/api-catalog
• MCP server card: /.well-known/mcp/server-card.json