# API Papan Champions Circle

Papan permintaan Champions Circle tersedia melalui API, sehingga Anda dapat membaca, mencari, dan mempostingnya dari skrip Anda sendiri, atau membiarkan asisten AI melakukannya untuk Anda melalui MCP. Ini adalah papan yang sama dengan yang Anda lihat di bawah **Circle → Requests** di aplikasi: permintaan yang sama, komentar yang sama, dan batas bulanan yang sama.

Hanya anggota Champions Circle yang dapat menggunakan endpoint ini. Akun lain mana pun akan mendapatkan `403` dengan `reason: "not_circle_member"`. Postingan dibuat sebagai akun milik kunci API tersebut.

## Endpoint

| Metode | Jalur | Fungsi |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Mencantumkan papan, permintaan yang disematkan terlebih dahulu, kemudian yang terbaru. Cari dengan `q` (judul dan detail), filter dengan `status` (`open`, `planned`, `building`, `shipped`, `declined`), buat halaman dengan `limit` (1 hingga 100, default 25) dan `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Satu permintaan dengan detail lengkapnya. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Komentar pada suatu permintaan, yang terlama terlebih dahulu, dengan penomoran halaman yang sama. |
| `POST` | `/v1/circle/requests` | Mengajukan permintaan. Isi: `title` (wajib) dan `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Mengedit `title` dan/atau `details` dari permintaan yang Anda tulis. Permintaan orang lain akan menjawab `403` dengan `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Membalas permintaan. Isi: `body`. |

Setiap permintaan akan kembali dengan `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at`, dan `url` yang membukanya di aplikasi. Alamat email anggota lain tidak akan pernah dikembalikan.

### Penomoran Halaman

Panggilan daftar mengembalikan `next_cursor`. Teruskan sebagai `cursor` untuk mendapatkan halaman berikutnya; nilainya adalah `null` pada halaman terakhir. `total` adalah jumlah kecocokan di semua halaman.

### Batas bulanan

Postingan API dihitung terhadap batas yang sama dengan papan di aplikasi: 4 permintaan dan 4 komentar per anggota dalam 30 hari berjalan. Jika melebihi batas, panggilan akan menjawab `429` dengan waktu `resets_at` untuk slot gratis berikutnya.

### Percobaan ulang yang aman

Kirim header `Idempotency-Key` (atau kolom `idempotency_key` di badan) dengan string unik apa pun saat Anda mengajukan permintaan atau komentar. Jika panggilan kehabisan waktu dan Anda mencoba lagi dengan kunci yang sama, Anda akan mendapatkan kembali postingan yang dibuat oleh panggilan pertama, dengan status `200` dan `idempotent_replay: true`, alih-alih duplikat. Percobaan ulang tidak akan pernah menghabiskan slot batas bulanan Anda.

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

## Kunci cakupan

Papan ini memiliki dua bagian yang dapat Anda berikan ke [kunci cakupan](api-keys.md#scoped-keys):

| Bagian | Mengizinkan |
| --- | --- |
| `Circle` | Mencantumkan, mencari, dan membaca permintaan serta komentar. |
| `Circle Write` | Mengajukan permintaan, mengedit permintaan Anda sendiri, dan berkomentar. |

Berikan hanya `Circle` ke kunci yang hanya perlu membaca papan. Kunci utama Anda, dan kunci cakupan dengan daftar `tags` kosong, dapat menggunakan keduanya.

## Tentang MCP

Endpoint ini merupakan bagian dari spesifikasi API, sehingga muncul sebagai alat untuk asisten AI mana pun yang Anda [hubungkan melalui MCP](../integrations/connect-ai-clients.md), tanpa pengaturan tambahan. Minta asisten Anda untuk mencari papan sebelum mengajukan, agar ia dapat memberikan komentar pada permintaan yang sudah ada alih-alih mengajukan duplikat.