> ## Documentation Index
> Fetch the complete documentation index at: https://huddleup-sports.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Whistle Developer Platform — Start Here

> Integrate with Whistle, the HuddleUp Sports officiating platform: a server-to-server REST API and a remote MCP server for posting games, managing officials, and tracking payouts.

Whistle is the HuddleUp Sports app where leagues post games and sports officials claim them and get paid. This section documents the two ways partner systems integrate with it:

* **REST API** — `https://whistle.huddleup-sports.com/api/v1` — a bearer-authenticated, server-to-server JSON API.
* **MCP server** — `https://whistle.huddleup-sports.com/api/mcp` — a remote HTTP [Model Context Protocol](https://modelcontextprotocol.io) endpoint exposing the same capabilities as 20 tools for AI agents.

<Note>
  Looking for help using the Whistle app as an official or league organizer? See the [Whistle FAQ](/faq/whistle) — this section is for developers and AI agents building integrations.
</Note>

## Who this is for

* **League management systems** syncing schedules into Whistle so officials can claim and get paid (HuddleUp itself is the first consumer of this API).
* **Partner automations and AI agents** that import game schedules, roster officials, monitor assignments, and reconcile payouts.

## Base URLs

| Surface              | URL                                           |
| -------------------- | --------------------------------------------- |
| REST API             | `https://whistle.huddleup-sports.com/api/v1`  |
| MCP (HTTP transport) | `https://whistle.huddleup-sports.com/api/mcp` |

There is one environment (production). There is no sandbox environment today — test against a league you create yourself. Partner keys are **scoped to your `source` namespace**: you see and mutate only leagues you created (plus any explicitly granted to your key), so your test data is isolated, and stable `externalId`s let you re-run imports idempotently.

## Prerequisites

1. **A partner API key** (`whk_…`). Keys are issued by the Whistle team — email [tommy@huddleup-sports.com](mailto:tommy@huddleup-sports.com). There is no self-service key portal yet. The key is shown once at issuance; store it in a secret manager.
2. **A server-side caller.** The API sends no CORS headers, so browsers can't call it directly — integrate from your backend (or an MCP client, which connects server-to-server).

## Safe onboarding path

<Steps>
  <Step title="Store your key as an environment variable">
    Never hardcode it. Examples in these docs use `$WHISTLE_API_KEY`.
  </Step>

  <Step title="Make your first call — the authenticated index">
    `GET /api/v1` returns a self-describing index (endpoints, webhook events, contract notes). It's read-only and the recommended smoke test. See the [REST quickstart](/developers/quickstart-rest).
  </Step>

  <Step title="Create your own league before writing anything else">
    Create a league with your `source` + `externalId`, then import games into it. Start with reads and idempotent upserts; review the [error and agent-safety guide](/developers/errors-and-agent-safety) before wiring any destructive call (cancel, remove, unassign, delete).
  </Step>
</Steps>

## Integration status

<Warning>
  These docs describe only what is live today. Current, known limitations — do not design around features this list says don't exist:

  * **Offline payments are the supported mode.** `paymentMode: "platform"` (Stripe payouts) is accepted and stored, but platform payouts are not yet active for partner-created leagues. The payments API is read-only either way.
  * **No pagination or filtering** on list endpoints (except `?limit=` on webhook deliveries).
  * **No rate limits** are currently enforced — behave as if they exist; batch your writes and don't poll aggressively.
  * **No API path to complete a game or settle a payment** — those are in-app organizer actions; you observe them via [webhooks](/developers/webhooks).
</Warning>

## Where to go next

<CardGroup cols={2}>
  <Card title="Authentication" href="/developers/authentication" icon="key">
    Bearer keys, handling, rotation, and 401 behavior.
  </Card>

  <Card title="REST quickstart" href="/developers/quickstart-rest" icon="terminal">
    First authenticated call in two curl commands.
  </Card>

  <Card title="MCP quickstart" href="/developers/quickstart-mcp" icon="robot">
    Connect Claude Code or any MCP client.
  </Card>

  <Card title="Task recipes" href="/developers/recipes" icon="list-check">
    End-to-end flows: import games, manage officials, webhooks.
  </Card>

  <Card title="API reference" href="/developers/api-reference" icon="book">
    Every endpoint, generated from the OpenAPI spec.
  </Card>

  <Card title="Errors & agent safety" href="/developers/errors-and-agent-safety" icon="shield-check">
    Error codes, retries, and confirmation rules for agents.
  </Card>
</CardGroup>