Toda la superficie del API REST de Replai vive en la documentación interactiva — generada desde el spec OpenAPI 3.1. Te dejamos pegar requests, ver schemas, y copiar snippets en varios lenguajes.

Spec en JSON/YAML: /api/openapi.yaml. Importable a Postman, Insomnia, openapi-generator y cualquier IDE.

Atajos a las secciones más usadas

Base URL

https://app.replai.tech/api

Todos los endpoints autenticados viven bajo /v1. El webhook de Stripe vive bajo /stripe-webhook (raw). El widget público vive bajo /v1/public/widget/*.

Convenciones

Bodies JSON excepto donde se indique multipart (upload de media directo).
Timestamps ISO 8601 en UTC.
Idempotencia: los sends aceptan clientMessageId — repetirlo devuelve el mismo job id sin duplicar.
Paginación: limit (1–200) + before (cursor opaco). Las respuestas traen nextCursor.

Errores

Toda respuesta de error sigue la misma forma:

{
  "code": "VALIDATION_FAILED",
  "message": "msisdn '...' is not a valid E.164 number",
  "requestId": "5a92...",
  "meta": { ... }
}

El requestId matchea el header x-request-id de la respuesta y cualquier log nuestro. Cuando abras un soporte, pásanos ese id. Lista completa en Códigos de error.

Rate limits

Tres capas independientes que se evalúan en este orden:

Por sesión — warmup tier (T0 → T4). Independiente del plan, protege al número nuevo de los heurísticos anti-spam de Meta. Ver Pool + routing.
Por plan tenant-wide — sesiones / mensajes / llamadas LLM por día. Starter (1 sesión, 1.000 msg/día), Growth (5 sesiones, 10.000 msg/día), Enterprise (20 sesiones, 100.000 msg/día). El tenant interno de Replai está exento.
Por plan tenant-wide — tokens de conversación incluidos. Enterprise incluye 70M tokens/mes; encima de ese umbral, cada bloque adicional de 70M tokens se factura a $20. Starter y Growth tienen capas más chicas — ver Precios.

Cuando se exceda cualquiera de las dos primeras capas, devolvemos 429 RATE_LIMITED con header Retry-After (segundos al próximo reset, que para el daily counter es la medianoche UTC). El cap de tokens no es un 429 — se contabiliza y factura, no bloquea.

Promover manualmente el warmup tier

La auto-promoción del warmup tier es conservadora (1 hora de tick + 3-30 días en cada tier antes de pasar al siguiente). Si tu número tiene historia previa legítima y querés saltarte el embudo, podés forzar la promoción con:

POST /v1/sessions/<id>/promote-warmup-tier
Authorization: Bearer <REPLAI_API_KEY>

{ "tier": 4, "reason": "número con 6 meses de historia previa, healthScore=1" }

El endpoint solo permite SUBIR (no bajar). La razón queda en audit_logs por si el número termina baneado y hay que entender el contexto. Tiers válidos: 0 (10 msg/día), 1 (50), 2 (250), 3 (1.000), 4 (5.000).

Bot externo (gateway-only)

Si querés que tu propio bot responda en lugar del que provee Replai, activá Bot externo en el detalle de la sesión. Replai actúa solo como pasarela WhatsApp — cada inbound se entrega a tu webhook firmado con HMAC y vos respondés vía POST /v1/messages.

Método	Ruta	Para qué
`GET`	`/v1/sessions/:id/external-config`	Lee el estado: `botMode` (MANAGED \| EXTERNAL), `webhookUrl`, `webhookSecret`.
`PUT`	`/v1/sessions/:id/external-config`	Toggle on/off, set URL, rotar secret, mintear API key. Body: `{ enabled: boolean, webhookUrl?, rotateSecret?, mintApiKey? }`. Cuando `enabled = true`, se aprovisiona automáticamente un `WebhookEndpoint` atado a la sesión.

Cuando botMode = EXTERNAL, el worker omite la llamada al LLM de Replai y la sesión no consume el cap de llmCallsPerDay ni tokens del plan. El path de outbound (POST /v1/messages) sigue funcionando igual y respeta los caps normales.

Detalle completo del wire format, firma y reintentos en Webhooks.