# API לוח Champions Circle

לוח הבקשות של Champions Circle זמין דרך ה-API, כך שתוכל לקרוא אותו, לחפש בו ולפרסם בו מהסקריפטים שלך, או לתת לעוזר AI לעשות זאת עבורך באמצעות MCP. זהו אותו הלוח שאתה רואה תחת **Circle → Requests** באפליקציה: אותן בקשות, אותן תגובות ואותן מגבלות חודשיות.

רק חברי Champions Circle יכולים להשתמש בנקודות קצה אלו. כל חשבון אחר יקבל `403` עם `reason: "not_circle_member"`. פרסומים מבוצעים בשם החשבון שאליו שייך מפתח ה-API.

## נקודות קצה (Endpoints)

| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | הצגת הלוח, בקשות נעוצות תחילה, ולאחר מכן לפי סדר חדש. חיפוש עם `q` (כותרת ופרטים), סינון עם `status` (`open`, `planned`, `building`, `shipped`, `declined`), דפדוף עם `limit` (1 עד 100, ברירת מחדל 25) ו-`cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | בקשה אחת עם כל פרטיה המלאים. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | התגובות לבקשה, מהישנה לחדשה, עם דפדוף באותו אופן. |
| `POST` | `/v1/circle/requests` | הגשת בקשה. גוף הבקשה: `title` (חובה) ו-`details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | עריכת ה-`title` ו/או ה-`details` של בקשה שכתבת. בקשה של מישהו אחר תענה ב-`403` עם `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | מענה לבקשה. גוף הבקשה: `body`. |

כל בקשה חוזרת עם ה-`id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` שלה ו-`url` שפותח אותה באפליקציה. כתובות דוא"ל של חברים אחרים לעולם לא יוחזרו.

### דפדוף (Paging)

קריאות רשימה מחזירות `next_cursor`. העבר אותו כ-`cursor` כדי לקבל את הדף הבא; הוא יהיה `null` בדף האחרון. `total` הוא מספר ההתאמות הכולל בכל הדפים.

### מגבלות חודשיות

פרסומים דרך ה-API נספרים כנגד אותן מגבלות של הלוח באפליקציה: 4 בקשות ו-4 תגובות לכל חבר בכל תקופה מתגלגלת של 30 יום. מעבר למגבלה, הקריאה תענה ב-`429` עם זמן `resets_at` למשבצת הפנויה הבאה.

### ניסיונות חוזרים בטוחים

שלח כותרת `Idempotency-Key` (או שדה `idempotency_key` בגוף הבקשה) עם מחרוזת ייחודית כלשהי בעת הגשת בקשה או תגובה. אם הקריאה חורגת מזמן ההמתנה ואתה מנסה שוב עם אותו מפתח, תקבל בחזרה את הפוסט שהקריאה הראשונה יצרה, עם סטטוס `200` ו-`idempotent_replay: true`, במקום כפילות. ניסיון חוזר לעולם לא ינצל משבצת נוספת מהמגבלה החודשית שלך.

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

## מפתחות מוגבלי היקף

ללוח יש שני חלקים שניתן להעניק להם הרשאה ב-[מפתח בעל היקף מוגבל](api-keys.md#scoped-keys):

| חלק | מאפשר |
| --- | --- |
| `Circle` | הצגה, חיפוש וקריאה של בקשות ותגובות. |
| `Circle Write` | הגשת בקשות, עריכת הבקשות שלך ותגובה. |

הענק רק `Circle` למפתח שאמור רק לקרוא את הלוח. המפתח הראשי שלך, ומפתח בעל היקף מוגבל עם רשימת `tags` ריקה, יכולים להשתמש בשניהם.

## אודות MCP

נקודות קצה אלו הן חלק ממפרט ה-API, לכן הן מופיעות ככלים עבור כל עוזר בינה מלאכותית שאתה [מחבר באמצעות MCP](../integrations/connect-ai-clients.md), ללא צורך בהגדרה נוספת. בקש מהעוזר שלך לחפש בלוח לפני הגשת בקשה, כדי שיגיב לבקשה קיימת במקום להגיש כפילות.