# API della bacheca Champions Circle

La bacheca delle richieste Champions Circle è disponibile tramite API, così puoi leggerla, cercarla e pubblicarvi dai tuoi script, oppure lasciare che un assistente AI lo faccia per te tramite MCP. È la stessa bacheca che vedi sotto **Circle → Requests** nell'app: le stesse richieste, gli stessi commenti e gli stessi limiti mensili.

Solo i membri del Champions Circle possono utilizzare questi endpoint. Qualsiasi altro account riceverà `403` con `reason: "not_circle_member"`. I post vengono effettuati come l'account a cui appartiene la chiave API.

## Endpoint

| Metodo | Percorso | Cosa fa |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Elenca la bacheca, prima le richieste fissate, poi le più recenti. Cerca con `q` (titolo e dettagli), filtra con `status` (`open`, `planned`, `building`, `shipped`, `declined`), impagina con `limit` (da 1 a 100, predefinito 25) e `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Una richiesta con i suoi dettagli completi. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | I commenti su una richiesta, dal più vecchio, impaginati allo stesso modo. |
| `POST` | `/v1/circle/requests` | Invia una richiesta. Corpo: `title` (obbligatorio) e `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Modifica il `title` e/o il `details` di una richiesta che hai scritto. La richiesta di chiunque altro risponde `403` con `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Rispondi a una richiesta. Corpo: `body`. |

Ogni richiesta viene restituita con il suo `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` e un `url` che la apre nell'app. Gli indirizzi email degli altri membri non vengono mai restituiti.

### Impaginazione

Le chiamate di elenco restituiscono `next_cursor`. Passalo come `cursor` per ottenere la pagina successiva; è `null` nell'ultima pagina. `total` è il numero di corrispondenze su tutte le pagine.

### Limiti mensili

I post tramite API contano ai fini degli stessi limiti della bacheca nell'app: 4 richieste e 4 commenti per membro in un periodo mobile di 30 giorni. Oltre il limite, la chiamata risponde `429` con un tempo `resets_at` per il prossimo slot disponibile.

### Riprova sicura

Invia un header `Idempotency-Key` (o un campo `idempotency_key` nel corpo) con una stringa univoca quando invii una richiesta o un commento. Se la chiamata va in timeout e riprovi con la stessa chiave, riceverai il post creato dalla prima chiamata, con stato `200` e `idempotent_replay: true`, invece di un duplicato. Un tentativo di riprova non consuma mai un altro slot del tuo limite mensile.

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

## Chiavi con ambito limitato

La bacheca ha due sezioni che puoi concedere a una [chiave con ambito limitato](api-keys.md#scoped-keys):

| Sezione | Consente |
| --- | --- |
| `Circle` | Elencare, cercare e leggere richieste e commenti. |
| `Circle Write` | Inviare richieste, modificare le proprie richieste e commentare. |

Concedi solo `Circle` a una chiave che dovrebbe solo leggere la bacheca. La tua chiave principale, e una chiave con ambito limitato con un elenco `tags` vuoto, possono usarle entrambe.

## Informazioni su MCP

Questi endpoint fanno parte della specifica API, quindi vengono visualizzati come strumenti per qualsiasi assistente IA che [connetti tramite MCP](../integrations/connect-ai-clients.md), senza alcuna configurazione aggiuntiva. Chiedi al tuo assistente di cercare nella bacheca prima di inviare una richiesta, in modo che possa commentare una richiesta esistente invece di crearne una duplicata.