# API do Quadro do Champions Circle

O quadro de pedidos do Champions Circle está disponível através da API, para que possa lê-lo, pesquisá-lo e publicar nele a partir dos seus próprios scripts, ou deixar que um assistente de IA o faça por si através do MCP. É o mesmo quadro que vê em **Circle → Requests** na aplicação: os mesmos pedidos, os mesmos comentários e os mesmos limites mensais.

Apenas os membros do Champions Circle podem utilizar estes endpoints. Qualquer outra conta recebe `403` com `reason: "not_circle_member"`. As publicações são feitas como a conta à qual a chave de API pertence.

## Endpoints

| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Lista o quadro, primeiro os pedidos afixados, depois os mais recentes. Pesquise com `q` (título e detalhes), filtre com `status` (`open`, `planned`, `building`, `shipped`, `declined`), pagine com `limit` (1 a 100, predefinição 25) e `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Um pedido com os seus detalhes completos. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Os comentários num pedido, primeiro os mais antigos, paginados da mesma forma. |
| `POST` | `/v1/circle/requests` | Submeter um pedido. Corpo: `title` (obrigatório) e `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Editar o `title` e/ou `details` de um pedido que escreveu. O pedido de qualquer outra pessoa responde `403` com `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Responder a um pedido. Corpo: `body`. |

Cada pedido é devolvido com o seu `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` e um `url` que o abre na aplicação. Os endereços de e-mail de outros membros nunca são devolvidos.

### Paginação

As chamadas de listagem devolvem `next_cursor`. Passe-o como `cursor` para obter a página seguinte; é `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 que o quadro na aplicação: 4 pedidos e 4 comentários por membro em cada período de 30 dias. Acima do limite, a chamada responde `429` com um tempo `resets_at` para o próximo espaço livre.

### Repetições seguras

Envie um cabeçalho `Idempotency-Key` (ou um campo `idempotency_key` no corpo) com qualquer string única quando submeter um pedido ou um comentário. Se a chamada expirar e tentar novamente com a mesma chave, receberá a publicação que a primeira chamada criou, com o estado `200` e `idempotent_replay: true`, em vez de uma duplicada. Uma repetição 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 âmbito

O quadro tem duas secções que pode conceder a uma [chave com âmbito](api-keys.md#scoped-keys):

| Secção | Permite |
| --- | --- |
| `Circle` | Listar, pesquisar e ler pedidos e comentários. |
| `Circle Write` | Submeter pedidos, editar os seus próprios pedidos e comentar. |

Conceda apenas `Circle` a uma chave que deva apenas ler o quadro. A sua chave principal, e uma chave com âmbito com uma lista `tags` vazia, podem utilizar ambas.

## Sobre o MCP

Estes endpoints fazem parte da especificação da API, pelo que aparecem como ferramentas para qualquer assistente de IA que [ligue através do MCP](../integrations/connect-ai-clients.md), sem necessidade de configuração adicional. Peça ao seu assistente para pesquisar no quadro antes de submeter, para que este comente num pedido existente em vez de criar um duplicado.