# API do Quadro do Champions Circle

O quadro de solicitações do Champions Circle está disponível via API, para que você possa lê-lo, pesquisá-lo e publicar nele a partir de seus próprios scripts, ou deixar que um assistente de IA faça isso por você via MCP. É o mesmo quadro que você vê em **Circle → Requests** no aplicativo: as mesmas solicitações, os mesmos comentários e os mesmos limites mensais.

Apenas membros do Champions Circle podem usar esses endpoints. Qualquer outra conta receberá `403` com `reason: "not_circle_member"`. As publicações são feitas como a conta à qual a chave da API pertence.

## Endpoints

| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Lista o quadro, primeiro as solicitações fixadas, depois as mais recentes. Pesquise com `q` (título e detalhes), filtre com `status` (`open`, `planned`, `building`, `shipped`, `declined`), pagine com `limit` (1 a 100, padrão 25) e `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Uma solicitação com seus detalhes completos. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Os comentários em uma solicitação, do mais antigo para o mais novo, paginados da mesma forma. |
| `POST` | `/v1/circle/requests` | Registrar uma solicitação. Corpo: `title` (obrigatório) e `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Editar o `title` e/ou `details` de uma solicitação que você escreveu. A solicitação de qualquer outra pessoa responderá `403` com `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Responder a uma solicitação. Corpo: `body`. |

Cada solicitação retorna com seu `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` e um `url` que a abre no aplicativo. Endereços de e-mail de outros membros nunca são retornados.

### Paginação

As chamadas de listagem retornam `next_cursor`. Passe-o como `cursor` para obter a próxima página; ele é `null` na última página. `total` é o número de correspondências em todas as páginas.

### Limites mensais

As publicações via API contam para os mesmos limites do quadro no aplicativo: 4 solicitações e 4 comentários por membro a cada 30 dias. Acima do limite, a chamada responderá `429` com um tempo `resets_at` para o próximo espaço livre.

### Novas tentativas seguras

Envie um cabeçalho `Idempotency-Key` (ou um campo `idempotency_key` no corpo) com qualquer string única ao registrar uma solicitação ou comentário. Se a chamada expirar e você tentar novamente com a mesma chave, você receberá a publicação que a primeira chamada criou, com status `200` e `idempotent_replay: true`, em vez de uma duplicata. Uma nova tentativa nunca consome outro espaço do seu limite mensal.

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

## Chaves com escopo

O quadro possui duas seções que você pode conceder a uma [chave com escopo](api-keys.md#scoped-keys):

| Seção | Permite |
| --- | --- |
| `Circle` | Listar, pesquisar e ler solicitações e comentários. |
| `Circle Write` | Registrar solicitações, editar suas próprias solicitações e comentar. |

Conceda apenas `Circle` a uma chave que deve apenas ler o quadro. Sua chave principal, e uma chave com escopo com uma lista `tags` vazia, podem usar ambos.

## Sobre o MCP

Esses endpoints fazem parte da especificação da API, portanto, eles aparecem como ferramentas para qualquer assistente de IA que você [conectar via MCP](../integrations/connect-ai-clients.md), sem necessidade de configuração extra. Peça ao seu assistente para pesquisar no quadro antes de registrar, para que ele comente em uma solicitação existente em vez de registrar uma duplicata.