# Champions Circle Board API

Champions Circle-förfrågningstavlan är tillgänglig via API:et, så att du kan läsa den, söka i den och posta till den från dina egna skript, eller låta en AI-assistent göra det åt dig via MCP. Det är samma tavla som du ser under **Circle → Requests** i appen: samma förfrågningar, samma kommentarer och samma månatliga begränsningar.

Endast medlemmar i Champions Circle kan använda dessa slutpunkter. Alla andra konton får `403` med `reason: "not_circle_member"`. Inlägg görs som det konto som API-nyckeln tillhör.

## Slutpunkter

| Metod | Sökväg | Vad den gör |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Lista tavlan, nålade förfrågningar först, sedan nyast först. Sök med `q` (titel och detaljer), filtrera med `status` (`open`, `planned`, `building`, `shipped`, `declined`), paginera med `limit` (1 till 100, standard 25) och `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | En förfrågan med alla dess detaljer. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Kommentarerna på en förfrågan, äldst först, paginerade på samma sätt. |
| `POST` | `/v1/circle/requests` | Skapa en förfrågan. Body: `title` (obligatorisk) och `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Redigera `title` och/eller `details` för en förfrågan du skrivit. Någon annans förfrågan svarar `403` med `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Svara på en förfrågan. Body: `body`. |

Varje förfrågan returneras med dess `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` och en `url` som öppnar den i appen. Andra medlemmars e-postadresser returneras aldrig.

### Paginering

Listanrop returnerar `next_cursor`. Skicka med den som `cursor` för att hämta nästa sida; den är `null` på den sista sidan. `total` är antalet träffar över alla sidor.

### Månatliga begränsningar

API-inlägg räknas mot samma begränsningar som tavlan i appen: 4 förfrågningar och 4 kommentarer per medlem under en rullande 30-dagarsperiod. Vid överskriden gräns svarar anropet `429` med en `resets_at`-tid för nästa lediga plats.

### Säkra återförsök

Skicka en `Idempotency-Key`-header (eller ett `idempotency_key`-fält i body) med en unik sträng när du skapar en förfrågan eller en kommentar. Om anropet får timeout och du försöker igen med samma nyckel, får du tillbaka inlägget som det första anropet skapade, med status `200` och `idempotent_replay: true`, istället för en dubblett. Ett återförsök förbrukar aldrig en ny plats av din månatliga begränsning.

```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."}'
```

## Begränsade nycklar

Tavlan har två sektioner som du kan bevilja åtkomst till via en [scoped key](api-keys.md#scoped-keys):

| Sektion | Tillåter |
| --- | --- |
| `Circle` | Lista, söka och läsa förfrågningar och kommentarer. |
| `Circle Write` | Skapa förfrågningar, redigera dina egna förfrågningar och kommentera. |

Bevilja endast `Circle` till en nyckel som bara ska läsa tavlan. Din huvudnyckel, och en scoped key med en tom `tags`-lista, kan använda båda.

## Om MCP

Dessa slutpunkter är en del av API-specifikationen, så de visas som verktyg för alla AI-assistenter som du [ansluter via MCP](../integrations/connect-ai-clients.md), utan extra konfiguration. Be din assistent att söka på tavlan innan du skapar ett ärende, så att den kan kommentera en befintlig förfrågan istället för att skapa en dubblett.