Versioning & Changelog

​

The v1 compatibility promise

• Existing response field names and types
• Status string values (open/claimed/completed/cancelled, payment statuses, membership statuses)
• Webhook event names, the delivery envelope ({id, event, createdAt, data}), headers, and the HMAC-SHA256 signing scheme
• The source + externalId idempotency semantics
• The {data} / {error} response envelopes

• New endpoints and new MCP tools
• New optional fields on existing responses and request bodies
• New webhook event names (subscribe by explicit event list if you can’t tolerate unknown events; an empty events subscription receives new events automatically)
• New error codes and new enum values (write your handlers to tolerate unrecognized codes/values)

​

Deprecation process

​

How to detect change

• This page is the canonical changelog for the developer surface.
• GET /api/v1 (the index) enumerates current endpoints and webhook events at runtime — an agent can diff it against expectations cheaply.
• The OpenAPI spec is versioned with the docs and updated with every surface change; pin and diff it in CI if you want machine-checkable notice.
• These docs’ llms.txt indexes every developer page for AI-agent consumption.

​

Changelog

​

2026-07 — Scoped partner keys (tenant isolation)

• Partner API keys are now source-bound principals: each key reads and mutates only leagues in its source namespace plus explicit grants. Out-of-scope resources answer 404 identically to nonexistent ones (non-enumeration). Additive for correctly-behaved integrations; contact support if a previously visible league disappears from your listings.
• Write source is derived from the key — omit it or echo your own value; other values return the new 400 source_mismatch.
• New 409 external_id_conflict on game imports: re-using a game externalId under a different league is refused instead of updating the existing game.
• Webhook endpoints are owned by the registering key’s source — list/delete/deliveries are scoped, and event fan-out delivers only events for leagues in your scope.
• The MCP server now forwards your bearer token to the REST layer, so tool calls run with your key’s scope and attribution.

​

2026-07 — Developer documentation launch

• Published this developer section: authentication, REST + MCP quickstarts, task recipes, resource model, webhooks, error/agent-safety guidance.
• Published the real Whistle OpenAPI 3.1 specification at /docs/api-reference/openapi.json, replacing a placeholder spec that had been served at that URL.
• Documented current surface: 21 REST operations (the index plus 20 resource operations), remote HTTP MCP server with 20 tools, 12 webhook events.