# Champions Circle Board API

Das Champions Circle-Anfrageboard ist über die API verfügbar, sodass Sie es lesen, durchsuchen und von Ihren eigenen Skripten aus Beiträge dazu verfassen können, oder es von einem KI-Assistenten über MCP erledigen lassen können. Es ist dasselbe Board, das Sie in der App unter **Circle → Requests** sehen: dieselben Anfragen, dieselben Kommentare und dieselben monatlichen Limits.

Nur Mitglieder des Champions Circle können diese Endpunkte nutzen. Jedes andere Konto erhält `403` mit `reason: "not_circle_member"`. Beiträge werden unter dem Konto veröffentlicht, zu dem der API-Schlüssel gehört.

## Endpunkte

| Methode | Pfad | Funktion |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Listet das Board auf, zuerst angepinnte Anfragen, dann die neuesten. Suchen mit `q` (Titel und Details), Filtern mit `status` (`open`, `planned`, `building`, `shipped`, `declined`), Paging mit `limit` (1 bis 100, Standard 25) und `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Eine Anfrage mit allen Details. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Die Kommentare zu einer Anfrage, beginnend mit dem ältesten, Paging auf die gleiche Weise. |
| `POST` | `/v1/circle/requests` | Eine Anfrage einreichen. Body: `title` (erforderlich) und `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Bearbeiten Sie den `title` und/oder `details` einer von Ihnen verfassten Anfrage. Bei Anfragen anderer Personen antwortet das System mit `403` und `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Auf eine Anfrage antworten. Body: `body`. |

Jede Anfrage wird mit ihrem `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` und einem `url` zurückgegeben, das sie in der App öffnet. E-Mail-Adressen anderer Mitglieder werden niemals zurückgegeben.

### Paging

Listen-Aufrufe geben `next_cursor` zurück. Übergeben Sie dies als `cursor`, um die nächste Seite zu erhalten; auf der letzten Seite ist es `null`. `total` ist die Anzahl der Übereinstimmungen über alle Seiten hinweg.

### Monatliche Limits

API-Beiträge werden auf dieselben Limits angerechnet wie das Board in der App: 4 Anfragen und 4 Kommentare pro Mitglied innerhalb von 30 Tagen. Bei Überschreitung des Limits antwortet der Aufruf mit `429` und einer `resets_at`-Zeit für den nächsten freien Slot.

### Sichere Wiederholungen

Senden Sie einen `Idempotency-Key`-Header (oder ein `idempotency_key`-Feld im Body) mit einem eindeutigen String, wenn Sie eine Anfrage oder einen Kommentar einreichen. Wenn der Aufruf fehlschlägt und Sie es mit demselben Schlüssel erneut versuchen, erhalten Sie den Beitrag, der beim ersten Aufruf erstellt wurde, mit dem Status `200` und `idempotent_replay: true`, anstatt eines Duplikats. Eine Wiederholung verbraucht niemals einen weiteren Slot Ihres monatlichen Limits.

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

## Bereichsbezogene Schlüssel

Das Board hat zwei Bereiche, die Sie einem [scoped key](api-keys.md#scoped-keys) gewähren können:

| Bereich | Erlaubt |
| --- | --- |
| `Circle` | Auflisten, Suchen und Lesen von Anfragen und Kommentaren. |
| `Circle Write` | Einreichen von Anfragen, Bearbeiten eigener Anfragen und Kommentieren. |

Gewähren Sie nur `Circle` für einen Schlüssel, der das Board nur lesen soll. Ihr Hauptschlüssel sowie ein scoped key mit einer leeren `tags`-Liste können beides nutzen.

## Über MCP

Diese Endpunkte sind Teil der API-Spezifikation und erscheinen daher als Tools für jeden KI-Assistenten, den Sie [über MCP verbinden](../integrations/connect-ai-clients.md), ohne dass eine zusätzliche Einrichtung erforderlich ist. Bitten Sie Ihren Assistenten, das Board zu durchsuchen, bevor Sie eine Anfrage einreichen, damit er eine bestehende Anfrage kommentiert, anstatt ein Duplikat zu erstellen.