DM Champ Docs

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.

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:

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, 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.