# Champions Circle Board API

Het Champions Circle-verzoekenbord is beschikbaar via de API, zodat je het kunt lezen, doorzoeken en er berichten op kunt plaatsen vanuit je eigen scripts, of het door een AI-assistent kunt laten doen via MCP. Het is hetzelfde bord dat je ziet onder **Circle → Requests** in de app: dezelfde verzoeken, dezelfde opmerkingen en dezelfde maandelijkse limieten.

Alleen Champions Circle-leden kunnen deze eindpunten gebruiken. Elk ander account krijgt `403` met `reason: "not_circle_member"`. Berichten worden geplaatst als het account waartoe de API-sleutel behoort.

## Eindpunten

| Methode | Pad | Wat het doet |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Het bord weergeven, eerst vastgezette verzoeken, daarna op volgorde van nieuw naar oud. Zoeken met `q` (titel en details), filteren met `status` (`open`, `planned`, `building`, `shipped`, `declined`), pagineren met `limit` (1 tot 100, standaard 25) en `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Eén verzoek met alle details. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | De opmerkingen bij een verzoek, van oud naar nieuw, op dezelfde manier gepagineerd. |
| `POST` | `/v1/circle/requests` | Een verzoek indienen. Body: `title` (verplicht) en `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | De `title` en/of `details` bewerken van een verzoek dat je zelf hebt geschreven. Het verzoek van iemand anders beantwoordt `403` met `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Reageren op een verzoek. Body: `body`. |

Elk verzoek wordt geretourneerd met zijn `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` en een `url` die het opent in de app. E-mailadressen van andere leden worden nooit geretourneerd.

### Paginering

Lijstoproepen retourneren `next_cursor`. Geef dit door als `cursor` om de volgende pagina op te halen; het is `null` op de laatste pagina. `total` is het aantal overeenkomsten over alle pagina's heen.

### Maandelijkse limieten

API-berichten tellen mee voor dezelfde limieten als het bord in de app: 4 verzoeken en 4 opmerkingen per lid in elke periode van 30 dagen. Bij overschrijding van de limiet antwoordt de oproep `429` met een `resets_at` tijd voor het volgende vrije slot.

### Veilige retries

Stuur een `Idempotency-Key`-header (of een `idempotency_key`-veld in de body) met een unieke string wanneer je een verzoek of opmerking indient. Als de oproep een time-out krijgt en je probeert het opnieuw met dezelfde sleutel, krijg je het bericht terug dat de eerste oproep heeft aangemaakt, met status `200` en `idempotent_replay: true`, in plaats van een duplicaat. Een retry verbruikt nooit een extra slot van je maandelijkse limiet.

```bash
curl -X POST "https://api.dmchamp.com/v1/circle/requests" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: dark-mode-2026-10-06" \
  -H "Content-Type: application/json" \
  -d '{"title": "Dark mode for the inbox", "details": "My team works late and would love a dark theme."}'
```

## Scoped sleutels

Het bord heeft twee secties die je kunt toewijzen aan een [scoped key](api-keys.md#scoped-keys):

| Sectie | Staat toe |
| --- | --- |
| `Circle` | Het weergeven, doorzoeken en lezen van verzoeken en opmerkingen. |
| `Circle Write` | Het indienen van verzoeken, het bewerken van je eigen verzoeken en reageren. |

Verleen alleen `Circle` aan een sleutel die het bord alleen moet kunnen lezen. Je hoofdsleutel, en een scoped key met een lege `tags`-lijst, kunnen beide gebruiken.

## Over MCP

Deze endpoints maken deel uit van de API-specificatie, dus ze verschijnen als tools voor elke AI-assistent die je [via MCP verbindt](../integrations/connect-ai-clients.md), zonder extra configuratie. Vraag je assistent om het bord te doorzoeken voordat je een verzoek indient, zodat er een reactie wordt geplaatst bij een bestaand verzoek in plaats van een dubbel exemplaar aan te maken.