# Champions Circle Pano API'si

Champions Circle talep panosuna API üzerinden erişilebilir; böylece kendi betiklerinizden okuyabilir, arayabilir ve gönderi yapabilir veya bir yapay zeka asistanının bunu sizin yerinize MCP üzerinden yapmasını sağlayabilirsiniz. Bu, uygulamada **Circle → Requests** altında gördüğünüz panonun aynısıdır: aynı talepler, aynı yorumlar ve aynı aylık limitler geçerlidir.

Bu uç noktaları yalnızca Champions Circle üyeleri kullanabilir. Diğer tüm hesaplar `403` ile `reason: "not_circle_member"` hatası alır. Gönderiler, API anahtarının ait olduğu hesap adına yapılır.

## Uç Noktalar

| Yöntem | Yol | Ne işe yarar |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Panoyu listeler; önce sabitlenmiş talepler, ardından en yeniler gelir. `q` ile arama yapabilir (başlık ve detaylar), `status` ile filtreleyebilir (`open`, `planned`, `building`, `shipped`, `declined`), `limit` (1 ile 100 arası, varsayılan 25) ve `cursor` ile sayfalama yapabilirsiniz. |
| `GET` | `/v1/circle/requests/{requestId}` | Bir talebi tüm detaylarıyla getirir. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Bir talepteki yorumları, en eskiden başlayarak ve aynı şekilde sayfalanmış olarak getirir. |
| `POST` | `/v1/circle/requests` | Bir talep oluşturur. Gövde: `title` (zorunlu) ve `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Yazdığınız bir talebin `title` ve/veya `details` kısmını düzenler. Başkasının talebini düzenlemeye çalışmak `403` ile `reason: "edit_not_allowed"` hatası döndürür. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Bir talebe yanıt verir. Gövde: `body`. |

Her talep; `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` ve uygulamada açılmasını sağlayan bir `url` ile birlikte döner. Diğer üyelerin e-posta adresleri asla döndürülmez.

### Sayfalama

Liste çağrıları `next_cursor` döndürür. Bir sonraki sayfayı almak için bunu `cursor` olarak iletin; son sayfada bu değer `null` olur. `total`, tüm sayfalardaki toplam eşleşme sayısıdır.

### Aylık limitler

API gönderileri, uygulamadaki panoyla aynı limitlere tabidir: her 30 günlük dönemde üye başına 4 talep ve 4 yorum. Limit aşıldığında çağrı, bir sonraki boş yuva için `resets_at` süresiyle birlikte `429` hatası döndürür.

### Güvenli yeniden denemeler

Bir talep veya yorum oluştururken herhangi bir benzersiz dize içeren bir `Idempotency-Key` başlığı (veya gövdede bir `idempotency_key` alanı) gönderin. Çağrı zaman aşımına uğrarsa ve aynı anahtarla yeniden denerseniz, kopya oluşturmak yerine ilk çağrının oluşturduğu gönderiyi `200` durumu ve `idempotent_replay: true` ile geri alırsınız. Yeniden deneme, aylık limitinizden başka bir yuva tüketmez.

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

## Kapsamlı anahtarlar

Panonun, [kapsamlı bir anahtara](api-keys.md#scoped-keys) verebileceğiniz iki bölümü vardır:

| Bölüm | İzin verilenler |
| --- | --- |
| `Circle` | Talepleri ve yorumları listeleme, arama ve okuma. |
| `Circle Write` | Talep oluşturma, kendi taleplerinizi düzenleme ve yorum yapma. |

Yalnızca panoyu okuması gereken bir anahtara sadece `Circle` yetkisi verin. Ana anahtarınız ve boş bir `tags` listesine sahip kapsamlı bir anahtar her ikisini de kullanabilir.

## MCP Hakkında

Bu uç noktalar API belirtiminin bir parçasıdır, bu nedenle [MCP üzerinden bağladığınız](../integrations/connect-ai-clients.md) herhangi bir yapay zeka asistanı için ekstra bir kuruluma gerek kalmadan araç olarak görünürler. Asistanınızdan, bir talep oluşturmadan önce panoda arama yapmasını isteyin; böylece mükerrer bir kayıt oluşturmak yerine mevcut bir talebe yorum yapabilir.