# Champions Circle -ilmoitustaulun API

Champions Circle -pyyntötaulu on käytettävissä API:n kautta, joten voit lukea sitä, hakea siitä ja lähettää siihen viestejä omilla skripteilläsi tai antaa tekoälyavustajan tehdä sen puolestasi MCP:n kautta. Se on sama taulu, jonka näet sovelluksessa kohdassa **Circle → Requests**: samat pyynnöt, samat kommentit ja samat kuukausittaiset rajoitukset.

Vain Champions Circle -jäsenet voivat käyttää näitä päätepisteitä. Kaikki muut tilit saavat vastaukseksi `403` ja `reason: "not_circle_member"`. Viestit lähetetään sen tilin nimissä, johon API-avain kuuluu.

## Päätepisteet

| Metodi | Polku | Mitä se tekee |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Listaa taulun, kiinnitetyt pyynnöt ensin, sitten uusimmat ensin. Hae kohteella `q` (otsikko ja tiedot), suodata kohteella `status` (`open`, `planned`, `building`, `shipped`, `declined`), sivuta kohteilla `limit` (1–100, oletus 25) ja `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Yksi pyyntö täydellisine tietoineen. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Pyynnön kommentit, vanhimmat ensin, sivutettuna samalla tavalla. |
| `POST` | `/v1/circle/requests` | Tee pyyntö. Runko: `title` (pakollinen) ja `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Muokkaa kirjoittamasi pyynnön `title`- ja/tai `details`-kenttiä. Muiden pyyntöihin vastataan `403` ja `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Vastaa pyyntöön. Runko: `body`. |

Jokainen pyyntö palauttaa tiedot `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` sekä `url`-linkin, joka avaa sen sovelluksessa. Muiden jäsenten sähköpostiosoitteita ei koskaan palauteta.

### Sivutus

Listauskutsut palauttavat arvon `next_cursor`. Välitä se parametrina `cursor` saadaksesi seuraavan sivun; viimeisellä sivulla se on `null`. `total` on kaikkien sivujen yhteenlaskettu hakutulosten määrä.

### Kuukausittaiset rajoitukset

API-viestit lasketaan samoihin rajoituksiin kuin sovelluksen taululla: 4 pyyntöä ja 4 kommenttia jäsentä kohden 30 päivän jakson aikana. Rajoituksen ylittyessä kutsu vastaa `429` ja antaa `resets_at`-ajan seuraavalle vapaalle paikalle.

### Turvalliset uudelleenyritykset

Lähetä `Idempotency-Key`-otsake (tai `idempotency_key`-kenttä rungossa) millä tahansa yksilöllisellä merkkijonolla, kun teet pyynnön tai kommentin. Jos kutsu aikakatkaistaan ja yrität uudelleen samalla avaimella, saat takaisin ensimmäisen kutsun luoman viestin tilakoodilla `200` ja `idempotent_replay: true`, etkä kaksoiskappaletta. Uudelleenyritys ei koskaan kuluta kuukausittaista kiintiötäsi.

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

## Rajoitetut avaimet

Taululla on kaksi osiota, jotka voit myöntää [rajatulle avaimelle](api-keys.md#scoped-keys):

| Osio | Sallii |
| --- | --- |
| `Circle` | Pyyntöjen ja kommenttien listaamisen, hakemisen ja lukemisen. |
| `Circle Write` | Pyyntöjen tekemisen, omien pyyntöjen muokkaamisen ja kommentoinnin. |

Myönnä vain `Circle` avaimelle, jonka pitäisi vain lukea taulua. Pääavaimesi ja rajattu avain, jolla on tyhjä `tags`-lista, voivat käyttää molempia.

## Tietoja MCP:stä

Nämä päätepisteet ovat osa API-määritystä, joten ne näkyvät työkaluina kaikille tekoälyavustajille, jotka [yhdistät MCP:n kautta](../integrations/connect-ai-clients.md), ilman lisämäärityksiä. Pyydä avustajaasi etsimään taululta ennen uuden pyynnön tekemistä, jotta se voi kommentoida olemassa olevaa pyyntöä sen sijaan, että se loisi kaksoiskappaleen.