# API-ul pentru panoul Champions Circle

Panoul de solicitări Champions Circle este disponibil prin API, astfel încât îl poți citi, căuta și posta pe acesta din propriile scripturi sau poți lăsa un asistent AI să o facă pentru tine prin MCP. Este același panou pe care îl vezi în aplicație la **Circle → Requests**: aceleași solicitări, aceleași comentarii și aceleași limite lunare.

Doar membrii Champions Circle pot utiliza aceste endpoint-uri. Orice alt cont va primi `403` cu `reason: "not_circle_member"`. Postările sunt efectuate în numele contului căruia îi aparține cheia API.

## Endpoint-uri

| Metodă | Cale | Ce face |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Listează panoul, mai întâi solicitările fixate, apoi cele mai noi. Caută cu `q` (titlu și detalii), filtrează cu `status` (`open`, `planned`, `building`, `shipped`, `declined`), paginează cu `limit` (de la 1 la 100, implicit 25) și `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | O solicitare cu detaliile sale complete. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Comentariile la o solicitare, de la cel mai vechi la cel mai nou, paginat în același mod. |
| `POST` | `/v1/circle/requests` | Depune o solicitare. Corp: `title` (obligatoriu) și `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Editează `title` și/sau `details` unei solicitări scrise de tine. Solicitările altor persoane răspund cu `403` cu `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Răspunde la o solicitare. Corp: `body`. |

Fiecare solicitare returnează `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` și un `url` care o deschide în aplicație. Adresele de e-mail ale altor membri nu sunt returnate niciodată.

### Paginare

Apelurile de listare returnează `next_cursor`. Transmite-l ca `cursor` pentru a obține pagina următoare; acesta este `null` pe ultima pagină. `total` reprezintă numărul de potriviri pe toate paginile.

### Limite lunare

Postările prin API se contorizează în aceleași limite ca panoul din aplicație: 4 solicitări și 4 comentarii per membru în orice interval de 30 de zile. Peste limită, apelul răspunde cu `429` cu un timp `resets_at` pentru următorul slot disponibil.

### Reîncercări sigure

Trimite un header `Idempotency-Key` (sau un câmp `idempotency_key` în corp) cu orice șir unic atunci când depui o solicitare sau un comentariu. Dacă apelul expiră și reîncerci cu aceeași cheie, vei primi înapoi postarea creată de primul apel, cu starea `200` și `idempotent_replay: true`, în loc de un duplicat. O reîncercare nu consumă niciodată un alt slot din limita ta lunară.

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

## Chei cu domeniu limitat

Panoul are două secțiuni pe care le poți acorda unei [chei cu domeniu limitat](api-keys.md#scoped-keys):

| Secțiune | Permite |
| --- | --- |
| `Circle` | Listarea, căutarea și citirea solicitărilor și comentariilor. |
| `Circle Write` | Depunerea solicitărilor, editarea propriilor solicitări și comentarea. |

Acordă doar `Circle` unei chei care ar trebui doar să citească panoul. Cheia ta principală și o cheie cu domeniu limitat cu o listă `tags` goală pot folosi ambele secțiuni.

## Despre MCP

Aceste endpoint-uri fac parte din specificația API, deci apar ca instrumente pentru orice asistent AI pe care îl [conectați prin MCP](../integrations/connect-ai-clients.md), fără nicio configurare suplimentară. Cereți asistentului să caute în tabel înainte de a trimite, astfel încât să comenteze la o solicitare existentă în loc să creeze una duplicat.