# API del tablero de Champions Circle

El tablero de solicitudes de Champions Circle está disponible a través de la API, por lo que puedes leerlo, buscar en él y publicar desde tus propios scripts, o dejar que un asistente de IA lo haga por ti a través de MCP. Es el mismo tablero que ves en **Circle → Requests** en la aplicación: las mismas solicitudes, los mismos comentarios y los mismos límites mensuales.

Solo los miembros de Champions Circle pueden usar estos endpoints. Cualquier otra cuenta recibirá `403` con `reason: "not_circle_member"`. Las publicaciones se realizan como la cuenta a la que pertenece la clave de API.

## Endpoints

| Método | Ruta | Qué hace |
| --- | --- | --- |
| `GET` | `/v1/circle/requests` | Enumera el tablero, primero las solicitudes fijadas y luego las más recientes. Busca con `q` (título y detalles), filtra con `status` (`open`, `planned`, `building`, `shipped`, `declined`), pagina con `limit` (de 1 a 100, predeterminado 25) y `cursor`. |
| `GET` | `/v1/circle/requests/{requestId}` | Una solicitud con todos sus detalles. |
| `GET` | `/v1/circle/requests/{requestId}/comments` | Los comentarios de una solicitud, primero los más antiguos, paginados de la misma manera. |
| `POST` | `/v1/circle/requests` | Presentar una solicitud. Cuerpo: `title` (obligatorio) y `details`. |
| `PATCH` | `/v1/circle/requests/{requestId}` | Edita el `title` y/o `details` de una solicitud que escribiste. La solicitud de cualquier otra persona responderá `403` con `reason: "edit_not_allowed"`. |
| `POST` | `/v1/circle/requests/{requestId}/comments` | Responder a una solicitud. Cuerpo: `body`. |

Cada solicitud devuelve su `id`, `title`, `details`, `status`, `author_name`, `vote_count`, `comment_count`, `created_at`, `updated_at` y un `url` que la abre en la aplicación. Las direcciones de correo electrónico de otros miembros nunca se devuelven.

### Paginación

Las llamadas de lista devuelven `next_cursor`. Pásalo como `cursor` para obtener la siguiente página; es `null` en la última página. `total` es el número de coincidencias en todas las páginas.

### Límites mensuales

Las publicaciones de la API cuentan para los mismos límites que el tablero en la aplicación: 4 solicitudes y 4 comentarios por miembro en cualquier periodo de 30 días. Si se supera el límite, la llamada responde `429` con un tiempo `resets_at` para el siguiente espacio disponible.

### Reintentos seguros

Envía un encabezado `Idempotency-Key` (o un campo `idempotency_key` en el cuerpo) con cualquier cadena única cuando presentes una solicitud o un comentario. Si la llamada se agota y vuelves a intentarlo con la misma clave, obtendrás la publicación que creó la primera llamada, con estado `200` y `idempotent_replay: true`, en lugar de un duplicado. Un reintento nunca consume otro espacio de tu límite mensual.

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

## Claves con ámbito

El tablero tiene dos secciones que puedes conceder a una [clave con ámbito](api-keys.md#scoped-keys):

| Sección | Permite |
| --- | --- |
| `Circle` | Listar, buscar y leer solicitudes y comentarios. |
| `Circle Write` | Presentar solicitudes, editar tus propias solicitudes y comentar. |

Concede solo `Circle` a una clave que solo deba leer el tablero. Tu clave principal, y una clave con ámbito con una lista `tags` vacía, pueden usar ambas.

## Acerca de MCP

Estos endpoints forman parte de la especificación de la API, por lo que aparecen como herramientas para cualquier asistente de IA que [conectes a través de MCP](../integrations/connect-ai-clients.md), sin necesidad de configuración adicional. Pídele a tu asistente que busque en el tablero antes de registrar una solicitud, para que comente en una existente en lugar de crear un duplicado.