> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Comentarios

> Informe a Maple sobre un error, una capacidad faltante, documentación incorrecta o un error sobre el que no pudo actuar.

Cuando la API hace algo mal, no puede hacer lo que usted necesita, no coincide con estas docs o responde con un error que no le dice qué debe cambiar, envíe `POST /v1/feedback`. Está pensado tanto para los agentes de programación que hacen la mayor parte del trabajo con esta API como para las personas, de modo que un agente que se topa con un obstáculo pueda reportarlo en la misma sesión en lugar de buscar una solución alternativa.

```bash theme={null}
curl https://api.maple.inc/v1/feedback \
  -H "Authorization: Bearer $MAPLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "unclear_error",
    "summary": "Waitlist join answers 400 without naming the field",
    "attempted": "Add a party of four to the waitlist",
    "expected": "The error names the field that failed",
    "endpoint": "POST /v1/waitlist_entries",
    "request_ids": ["req_3f2b7c1e-9a4d-4e8b-b1c2-5d6e7f8a9b0c"]
  }'
```

| Campo | Obligatorio | Qué incluir |
| - | - | - |
| `kind` | Sí | `bug`, `missing_capability`, `docs_wrong`, `unclear_error` u `other` |
| `summary` | Sí | Una línea, de máximo 200 caracteres |
| `attempted` | No | Lo que intentaba hacer, expresado como un objetivo y no como una llamada; omítalo cuando los comentarios no se refieran a una tarea |
| `expected` | No | Lo que esperaba que hiciera la API |
| `observed` | No | Lo que hizo en su lugar |
| `endpoint` | No | El método y la ruta, como `POST /v1/waitlist_entries` |
| `request_ids` | No | Hasta diez ids de las solicitudes involucradas, normalmente sus valores de `x-request-id` |

## Cite sus solicitudes

Cada respuesta incluye un encabezado `x-request-id`. Ponga en `request_ids` los ids de las solicitudes involucradas, porque nos permiten ver la operación, el estado y el código de error de lo que realmente envió. Copiamos esos detalles a los comentarios cuando los envía, de modo que sigan siendo legibles después de que el historial de solicitudes venza a los siete días. Un id que no podamos relacionar con las solicitudes de su app en el mismo entorno durante los últimos siete días, como uno de otro sistema, se conserva tal como lo envió; el reporte nunca se rechaza por un id.

## Un contrato que no se romperá

Un agente puede enviar comentarios desde código escrito una sola vez y que sigue funcionando durante años, por lo que nunca haremos un cambio incompatible en `POST /v1/feedback`. Podemos agregar campos opcionales y nuevos valores de `kind`, y la respuesta puede ganar campos, así que ignore los que no conozca. No quitaremos ni renombraremos un campo, no cambiaremos su significado, no haremos obligatorio un campo opcional, no agregaremos un campo obligatorio, no eliminaremos un `kind` ni reduciremos un límite de longitud. Una solicitud que funciona hoy seguirá funcionando.

## Qué sucede después

La API almacena el reporte y responde `200` con un objeto `feedback` cuyo `status` es `received`. Maple lee los comentarios cada semana y decide qué cambiar; enviarlos no cambia nada por sí solo, y la API no envía una respuesta. No incluya secretos, claves de API ni datos de los clientes en el texto.

Cualquier credencial puede enviar comentarios en cualquiera de los entornos, y no se requiere ningún alcance (scope). Cada app puede enviar 20 reportes por entorno por hora; después de eso, la API responde `429` con un encabezado `Retry-After`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.