# API du tableau Champions Circle

Le tableau des requêtes Champions Circle est disponible via l'API, ce qui vous permet de le lire, d'y effectuer des recherches et d'y publier des messages depuis vos propres scripts, ou de laisser un assistant IA le faire pour vous via MCP. Il s'agit du même tableau que celui que vous voyez sous **Circle → Requests** dans l'application : les mêmes requêtes, les mêmes commentaires et les mêmes limites mensuelles.

Seuls les membres du Champions Circle peuvent utiliser ces points de terminaison. Tout autre compte recevra `403` avec `reason: "not_circle_member"`. Les publications sont effectuées au nom du compte auquel appartient la clé API.

## Points de terminaison

| Méthode | Chemin | Action |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Liste le tableau, les requêtes épinglées en premier, puis les plus récentes. Recherchez avec `q` (titre et détails), filtrez avec `status` (`open`, `planned`, `building`, `shipped`, `declined`), paginez avec `limit` (1 à 100, 25 par défaut) et `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Une requête avec tous ses détails. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Les commentaires sur une requête, du plus ancien au plus récent, paginés de la même manière. |
| `POST` | `/v1/circle/requests` | Déposer une requête. Corps : `title` (obligatoire) et `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Modifier le `title` et/ou le `details` d'une requête que vous avez écrite. La requête de quelqu'un d'autre répondra `403` avec `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Répondre à une requête. Corps : `body`. |

Chaque requête est renvoyée avec son `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` et un `url` qui l'ouvre dans l'application. Les adresses e-mail des autres membres ne sont jamais renvoyées.

### Pagination

Les appels de liste renvoient `next_cursor`. Transmettez-le en tant que `cursor` pour obtenir la page suivante ; il est `null` sur la dernière page. `total` est le nombre de correspondances sur toutes les pages.

### Limites mensuelles

Les publications via l'API sont comptabilisées dans les mêmes limites que le tableau dans l'application : 4 requêtes et 4 commentaires par membre sur une période glissante de 30 jours. Au-delà de la limite, l'appel répond `429` avec un temps `resets_at` pour le prochain créneau disponible.

### Nouvelles tentatives sécurisées

Envoyez un en-tête `Idempotency-Key` (ou un champ `idempotency_key` dans le corps) avec n'importe quelle chaîne unique lorsque vous déposez une requête ou un commentaire. Si l'appel expire et que vous réessayez avec la même clé, vous récupérez la publication créée par le premier appel, avec le statut `200` et `idempotent_replay: true`, au lieu d'un doublon. Une nouvelle tentative n'utilise jamais un autre créneau de votre limite mensuelle.

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

## Clés à portée limitée

Le tableau comporte deux sections que vous pouvez accorder à une [clé à portée limitée](api-keys.md#scoped-keys) :

| Section | Autorise |
| --- | --- |
| `Circle` | Lister, rechercher et lire les requêtes et les commentaires. |
| `Circle Write` | Déposer des requêtes, modifier vos propres requêtes et commenter. |

N'accordez que `Circle` à une clé qui ne doit que lire le tableau. Votre clé principale, ainsi qu'une clé à portée limitée avec une liste `tags` vide, peuvent utiliser les deux.

## À propos de MCP

Ces points de terminaison font partie de la spécification de l'API, ils apparaissent donc comme des outils pour tout assistant IA que vous [connectez via MCP](../integrations/connect-ai-clients.md), sans configuration supplémentaire. Demandez à votre assistant de rechercher dans le tableau avant de créer une demande, afin qu'il puisse commenter une demande existante au lieu d'en créer une en double.