Referencia de la API

URL base: https://api.renbase.ai. Todos los endpoints aceptan Authorization: Bearer <credencial> y devuelven JSON, salvo /v1/ask y los flujos de eventos, que devuelven Server-Sent Events.

Autenticación

Dos tipos de credencial, las dos resueltas en vivo: revocar una surte efecto al instante.

Las claves de API (kb_live_…) son para servicios y agentes. Un administrador las emite desde Renbase Studio o por /v1/keys.

Los tokens de sesión son para personas. Un miembro pide un código de un solo uso por email y lo canjea por un token:

curl -X POST $RENBASE_API/auth/request-otp \
  -H 'content-type: application/json' -d '{"email": "[email protected]"}'

curl -X POST $RENBASE_API/auth/verify-otp \
  -H 'content-type: application/json' -d '{"email": "[email protected]", "code": "123456"}'

Los códigos caducan, y se invalidan tras unos cuantos intentos fallidos. Los roles son admin (gobierno, claves, miembros, borrado) y read (preguntar y consultar).

Preguntar

POST /v1/ask

Devuelve en streaming una respuesta citada por SSE. Consume un crédito.

{
  "query": "¿cuál es el plazo de devolución?",
  "collection": "soporte",
  "filters": {"lang": "es"},
  "history": [{"role": "user", "content": "…"}]
}

Eventos, en orden: sources (lo que va a usar), token (el texto según se produce) y done (citas resueltas y si se abstuvo). Las preguntas de seguimiento se reescriben usando history, así que «¿y para productos digitales?» funciona como continuación.

POST /v1/search

Pasajes ordenados sin generación, para cuando quieres construir tú la respuesta. Consume un crédito.

{ "query": "plazo de devolución", "collection": "soporte", "filters": {"category": "politicas"} }

Devuelve resultados con puntuación, fuente y tiempos por etapa.

POST /v1/feedback

Registra si una respuesta ha sido útil. Las negativas con corrección alimentan la cola de refinamiento, y un administrador puede promocionarlas a regla.

{ "answer_id": "…", "helpful": false, "comment": "el plazo son 30 días, no 14" }

Documentos

Método	Ruta	Rol	Descripción
POST	/v1/documents	miembro	Sube un documento (multipart); devuelve un trabajo
GET	/v1/documents	miembro	Listado paginado, filtrable por colección y texto
GET	/v1/documents/{id}	miembro	Detalle: colección, tamaño, número de fragmentos
GET	/v1/documents/{id}/chunks	miembro	Cómo se troceó el documento
DELETE	/v1/documents/{id}	admin	Retira el documento y su contenido de las respuestas
POST	/v1/documents/{id}/reindex	admin	Rehace sus entradas de búsqueda
GET	/v1/collections	miembro	Colecciones con su número de documentos
GET	/v1/jobs · /v1/jobs/{id}	miembro	Cola de procesamiento
GET	/v1/jobs/events	miembro	Flujo SSE con el progreso de los trabajos
POST	/v1/jobs/{id}/retry	admin	Reencola un trabajo fallido

Detalles en Documentos.

Definiciones

Método	Ruta	Rol	Descripción
POST	/v1/context	admin	Crea una definición (approve: true la publica)
GET	/v1/context	admin	Listado; ?status=draft es la cola de revisión
GET	/v1/context/{id}	admin	Detalle con historial de versiones
PATCH	/v1/context/{id}	admin	Editar: crea una versión nueva aprobada
DELETE	/v1/context/{id}	admin	Retirar
POST	/v1/context/{id}/approve · /reject	admin	Revisar un borrador
POST	/v1/context/import	admin	Importa candidatos; todo llega como borrador
GET	/v1/context/resolve?q=	miembro	Resolución determinista por nombre o alias (gratis)
GET	/v1/feedback	admin	Cola de refinamiento
POST	/v1/feedback/{id}/promote	admin	Convierte una corrección en regla

Detalles en Definiciones de negocio.

Organización

Método	Ruta	Rol	Descripción
POST/GET/DELETE	/v1/keys	admin	Emitir, listar y revocar claves de API
POST/GET/PATCH/DELETE	/v1/users	admin	Gestionar miembros y roles
GET	/v1/credits	miembro	Saldo y plan (gratis, no consume)
POST	/v1/billing/checkout	admin	Abre una página de pago de Stripe: {"amount":50} o {"setup":true}
POST	/v1/billing/portal	admin	Portal de cliente de Stripe: suscripción y facturas
GET/POST	/v1/billing/autorecharge	admin	Consulta o configura la recarga automática: {"threshold":200,"amount":50}
GET	/v1/usage	miembro	Histórico de consumo por día y endpoint (?days=30)
POST	/mcp	miembro	Endpoint MCP para agentes — ver Agentes de IA

Créditos y límites de ritmo

Preguntar y buscar consumen un crédito cada uno. Leer, listar, resolver una definición y desplegar una fuente son gratis. Tu plan define la dotación y el periodo; el saldo se repone en la primera petición posterior al vencimiento.

GET /v1/credits es deliberadamente gratuito y queda fuera del límite de ritmo, para que una integración frenada o sin saldo pueda ver siempre cómo está. Devuelve los credits que quedan y el allotment que tu plan concede al renovar; ambos valen -1 cuando son ilimitados.

GET /v1/usage responde a la otra pregunta: en qué se fueron. Devuelve por defecto los últimos 30 días (?days= hasta 365), desglosados de dos maneras: una serie diaria sin huecos —un día sin tráfico va a cero, no desaparece— y el total por endpoint ordenado por gasto. También son gratis y también quedan fuera del límite: mirar la cuenta no debería costarte.

El desglose nombra el tool además de la ruta, así que el tráfico de un agente (mcp:ask, mcp:search_context) se distingue del panel (/v1/ask, /v1/search). Todos los tools de MCP entran por la misma URL: sin esa distinción, todo diría «MCP», que no responde a nada.

Hay dos formas de añadir crédito. Una recarga es una compra puntual que se suma al saldo que ya tengas. Una suscripción fija tu plan y repone su dotación cada periodo. Las dos devuelven una URL desde /v1/billing/checkout: el pago se termina en Stripe y el saldo se mueve cuando Stripe lo confirma, normalmente un par de segundos después de volver.

La dotación es un suelo, nunca un techo: al renovar te sube hasta ella si estás por debajo y deja en paz un saldo mayor. Los créditos que compras siguen siendo tuyos —sobreviven a la renovación— y darte de baja cambia tu plan sin tocarlos.

Siempre dices cuánto quieres pagar, nunca cuántos créditos quieres: manda amount y tu precio lo fija el último pack que superas, así que 200 compran al mismo ratio que el pack de 100. Los packs publicados son solo importes cómodos; cualquier cifra entre el pack más pequeño y el tope funciona igual. La conversión la hace el servidor.

La recarga automática evita que a un agente se le corte el trabajo a mitad: fijas un umbral y un importe, y cobramos ese importe cuando el saldo baja de ahí, con la tarjeta que dejó un pago anterior. El importe lo eliges tú —un pack o cualquier cifra que admita el checkout— y los créditos que dé se calculan al precio vigente en el momento del cobro, así que una bajada de precios te llega sin reconfigurar nada. El cargo se hace sin ti delante, así que un banco que exija autenticación (SCA en Europa) lo rechazará: en ese caso la recarga no entra y hay que pagar una vez a mano. Entre recarga y recarga hay una espera mínima, de modo que un agente desbocado no puede encadenar cobros.

Los límites de ritmo se aplican por organización, en peticiones por minuto con una ráfaga pequeña. Superarlos devuelve 429 con Retry-After, y una petición frenada nunca gasta crédito.

Errores

Código	Significado
400	Petición mal formada; compara el cuerpo con los ejemplos
401	Credencial ausente, inválida o revocada
403	Credencial válida sin el rol necesario (lo más común: una acción de admin con un token de lectura)
404	El recurso no existe, o pertenece a otra organización
413	Documento por encima del tamaño máximo
429	Límite de ritmo superado; reintenta pasado Retry-After
402	Sin créditos: recarga o sube de plan

Fíjate en que el 404 cubre también el contenido de otra organización: en vez de decirte que algo existe pero no es tuyo, sencillamente no está.

Una abstención no es un error. /v1/ask devuelve 200 con abstained: true y una explicación: es el sistema funcionando como debe.