# API tablicy Champions Circle

Tablica zgłoszeń Champions Circle jest dostępna przez API, dzięki czemu możesz ją odczytywać, przeszukiwać i dodawać do niej wpisy za pomocą własnych skryptów lub pozwolić asystentowi AI zrobić to za Ciebie przez MCP. Jest to ta sama tablica, którą widzisz w aplikacji w sekcji **Circle → Requests**: te same zgłoszenia, te same komentarze i te same limity miesięczne.

Tylko członkowie Champions Circle mogą korzystać z tych punktów końcowych. Każde inne konto otrzyma `403` z `reason: "not_circle_member"`. Wpisy są tworzone jako konto, do którego należy klucz API.

## Punkty końcowe

| Metoda | Ścieżka | Działanie |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Wyświetla listę tablicy, najpierw przypięte zgłoszenia, potem najnowsze. Przeszukuj za pomocą `q` (tytuł i szczegóły), filtruj za pomocą `status` (`open`, `planned`, `building`, `shipped`, `declined`), stronicuj za pomocą `limit` (od 1 do 100, domyślnie 25) oraz `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Jedno zgłoszenie wraz z pełnymi szczegółami. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Komentarze do zgłoszenia, od najstarszych, stronicowane w ten sam sposób. |
| `POST` | `/v1/circle/requests` | Zgłoś prośbę. Treść: `title` (wymagane) oraz `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Edytuj `title` i/lub `details` zgłoszenia, którego jesteś autorem. Próba edycji zgłoszenia innej osoby zakończy się `403` z `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Odpowiedz na zgłoszenie. Treść: `body`. |

Każde zgłoszenie zwraca swoje `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` oraz `url`, który otwiera je w aplikacji. Adresy e-mail innych członków nigdy nie są zwracane.

### Stronicowanie

Wywołania listy zwracają `next_cursor`. Przekaż go jako `cursor`, aby pobrać następną stronę; na ostatniej stronie wartość ta wynosi `null`. `total` to liczba dopasowań na wszystkich stronach.

### Limity miesięczne

Wpisy przez API wliczają się do tych samych limitów co tablica w aplikacji: 4 zgłoszenia i 4 komentarze na członka w dowolnym okresie 30 dni. Po przekroczeniu limitu wywołanie zwróci `429` z czasem `resets_at` do następnego wolnego miejsca.

### Bezpieczne ponawianie prób

Wyślij nagłówek `Idempotency-Key` (lub pole `idempotency_key` w treści) z dowolnym unikalnym ciągiem znaków podczas zgłaszania prośby lub komentarza. Jeśli wywołanie przekroczy limit czasu i ponowisz próbę z tym samym kluczem, otrzymasz wpis utworzony przez pierwsze wywołanie ze statusem `200` i `idempotent_replay: true`, zamiast duplikatu. Ponowna próba nigdy nie zużywa kolejnego miejsca w Twoim miesięcznym limicie.

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

## Klucze o ograniczonym zakresie

Tablica posiada dwie sekcje, do których możesz przyznać dostęp [kluczowi o ograniczonym zakresie](api-keys.md#scoped-keys):

| Sekcja | Uprawnienia |
| --- | --- |
| `Circle` | Wyświetlanie, wyszukiwanie i czytanie zgłoszeń oraz komentarzy. |
| `Circle Write` | Zgłaszanie próśb, edytowanie własnych zgłoszeń i komentowanie. |

Przyznaj tylko `Circle` kluczowi, który powinien tylko odczytywać tablicę. Twój główny klucz oraz klucz o ograniczonym zakresie z pustą listą `tags` mogą korzystać z obu.

## O MCP

Te punkty końcowe są częścią specyfikacji API, więc pojawiają się jako narzędzia dla każdego asystenta AI, z którym [nawiążesz połączenie przez MCP](../integrations/connect-ai-clients.md), bez konieczności dodatkowej konfiguracji. Poproś swojego asystenta o przeszukanie tablicy przed zgłoszeniem, aby dodał komentarz do istniejącego żądania zamiast tworzyć duplikat.