DM Champ Docs

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.

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:

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, 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.