API

API reference

Iterar expone un endpoint HTTP público para enviar feedback. El SDK lo usa por debajo, pero podés llamarlo directamente si necesitás integrarlo con un backend.

POST /v1/widget/feedback

Crea un feedback crudo y lo encola para procesamiento por IA.

Headers requeridos

Header	Descripción
`X-Iterar-Project-Key`	Key pública del proyecto (lpbk_pub_…).
`X-Iterar-Origin`	Dominio del sitio donde corre el widget.
`Cf-Turnstile-Token`	Token de Cloudflare Turnstile (excepto localhost).

Body

Campo	Tipo	Descripción
`content`	string	Texto del feedback (máx 2.000 chars).
`language`	string?	ISO 639-1; si no se manda, se autodetecta.
`category_hint`	string?	feature \| bug \| improvement \| integration \| question \| other.
`email`	string?	Email opcional del usuario que envía.
`metadata`	object?	JSON arbitrario (userId, plan, etc).
`origin_url`	string?	URL exacta donde se envió el feedback.

Ejemplo

request

http

POST https://api.iterar.io/v1/widget/feedback
Content-Type: application/json
X-Iterar-Project-Key: lpbk_pub_xxxxxxxxxx
X-Iterar-Origin: https://app.tu-saas.com
Cf-Turnstile-Token: 0.AbCDef...

{
  "content": "Estaría buenísimo poder exportar a PDF",
  "language": "es",
  "category_hint": "feature",
  "email": "user@example.com",
  "metadata": { "plan": "pro", "userId": "u_123" },
  "origin_url": "https://app.tu-saas.com/dashboard"
}

Respuesta

response

http

200 OK
{
  "ok": true,
  "feedback_id": "fb_01HBC...",
  "queued": true,
  "message": "Gracias, ya estamos viendo tu sugerencia."
}

Por qué queued: true

El feedback se acepta sincrónicamente pero el pipeline IA (embedding, dedup, clasificación) corre asíncrono. El widget muestra el thanks inmediato y la bandeja del founder se actualiza en segundos.

Códigos de error

Código	Significado
400	Body inválido o content vacío.
401	Project key inválida o revocada.
403	Dominio no autorizado en allowed_origins.
422	Turnstile token inválido o expirado.
429	Rate limit excedido (10/IP/hora por proyecto).
500	Error interno; reintentar con backoff.

Rate limiting

10 submissions por IP, por hora y por proyecto.
Header de respuesta X-RateLimit-Remaining indica cuántas quedan.
Cuando se supera, devolvemos 429 con Retry-After.