API de revisión de IA
Revisa los datos enviados con la API de revisión de IA, que también admite alojamiento propio con Docker.
La API de revisión también admite alojamiento propio con Docker. El endpoint de Epismo y los ejemplos siguientes utilizan modelos gestionados por Epismo y créditos de la cuenta.
Genera una revisión de IA a partir de los datos enviados por tu aplicación. Este endpoint utiliza una clave de API dedicada creada en Ajustes → IA en la aplicación web.
POST https://api.epismo.ai/v1/reviewsRevisa tus propios datos sin crear casos ni playbooks. Incluye en context la información necesaria para la revisión. La búsqueda web depende de la configuración de IA del propietario de la clave y del modelo.
Crear y gestionar una clave
Selecciona tu espacio de trabajo o cuenta personal en la aplicación web y abre Ajustes → IA → Claves de API. Introduce un nombre y elige una caducidad: 7, 30 o 90 días, 1 año o sin caducidad. Copia el secreto al crearlo; solo se muestra una vez.
- Las claves del espacio de trabajo le pertenecen y consumen sus créditos compartidos. Solo los propietarios y administradores pueden gestionarlas. El espacio de trabajo debe tener una suscripción activa o de prueba.
- Las claves personales te pertenecen y consumen tus créditos personales.
- Permitir Epismo AI debe estar activado para la cuenta propietaria de la clave.
La lista muestra el creador, la fecha de creación, la caducidad y el último uso aproximado. Revoca una clave para impedir su uso inmediatamente. Puedes eliminarla permanentemente después de revocarla; esto no elimina su consumo registrado. Si pierdes el secreto, revoca la clave y crea otra. La gestión de claves está disponible en la interfaz web.
Consulta el consumo por clave de API en Gestión de créditos. Al eliminar una clave, su consumo registrado se conserva, pero se agrupa en Desconocido.
Solicitud
Envía estas cabeceras:
| Cabecera | Obligatoria | Valor |
|---|---|---|
Authorization |
Sí | Bearer <review-api-key> |
Content-Type |
Sí | application/json |
Idempotency-Key |
No | Un UUID que identifica la solicitud; recomendado al reintentar. |
Las solicitudes consumen los créditos de la cuenta personal o espacio de trabajo propietario de la clave. No necesitas indicar una cuenta de facturación en el cuerpo.
| Campo JSON | Obligatorio | Descripción |
|---|---|---|
context |
Sí | Objeto JSON con la evidencia que se revisará; máximo de 500.000 bytes UTF-8 al serializarlo. |
instructions |
No | Instrucciones adicionales; máximo de 32.000 bytes UTF-8. |
criteria |
No | Criterios opcionales en lenguaje natural, máximo 32.000 bytes UTF-8. |
output_schema |
No | JSON Schema que describe un objeto; máximo de 32.000 bytes UTF-8 al serializarlo. No se permiten referencias externas. Si se omite, se devuelve un objeto con una cadena content. Al indicarlo, la salida sigue exactamente este esquema, permitiendo evaluaciones de salud estructuradas y flujos automatizados con tipos seguros. |
model |
No | Familia o versión compatible; consulta la lista siguiente. Si se omite, se usa el modelo predeterminado. Se rechazan los modelos y versiones no compatibles. |
El cuerpo completo no debe superar los 600.000 bytes. Se rechazan los campos desconocidos. Omite los campos opcionales en lugar de enviar null.
Modelos
Usa una familia para seleccionar su versión actual o fija una versión con @:
| Modelo | Versiones compatibles |
|---|---|
gemini/argon |
4 |
gemini/flash |
3.8 |
claude/fable |
5.1 |
claude/opus |
5.5 |
claude/sonnet |
5.5 |
claude/haiku |
5.5 |
gpt/astra |
6 |
gpt/sol |
6.1 |
gpt/luna |
6 |
Ejemplo mínimo
Asigna tu secreto a EPISMO_API_KEY. El cuerpo mínimo solo necesita context.
curl https://api.epismo.ai/v1/reviews \
--header "Authorization: Bearer $EPISMO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"context":{"messages":[
{"role":"user","content":"¿Cuánto es 2 + 2?"},
{"role":"assistant","content":"5."}
]}}'Ejemplo de salida estructurada y evaluación de salud
Al igual que hace Epismo internamente en los informes de Casos, puedes combinar instructions con output_schema para generar un objeto JSON con estructura estricta en lugar de texto libre. Esto te permite evaluar el estado de salud operativo (healthy, at_risk, critical o unknown), redactar resúmenes respaldados por evidencias e identificar riesgos concretos y siguientes pasos.
curl https://api.epismo.ai/v1/reviews \
--header "Authorization: Bearer $EPISMO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"instructions": "Diagnostica de forma objetiva la salud del trabajo como healthy, at_risk, critical o unknown a partir de los registros proporcionados. Evita suposiciones sin respaldo y usa unknown si la evidencia es insuficiente para un diagnóstico fiable.",
"context": {
"milestone": "Lanzamiento v2.0",
"records": [
{"timestamp": "2026-10-25", "content": "Implementación de la API principal completada y desplegada en staging."},
{"timestamp": "2026-10-26", "content": "Las pruebas de carga revelaron un 15% de errores de tiempo de espera en la pasarela de pagos. Causa en investigación."}
]
},
"output_schema": {
"type": "object",
"properties": {
"health": {
"type": "string",
"enum": ["healthy", "at_risk", "critical", "unknown"],
"description": "Diagnóstico de salud respaldado por evidencia"
},
"summary": {
"type": "string",
"description": "Situación actual y motivo principal del diagnóstico (máximo 280 caracteres)"
},
"risks": {
"type": "array",
"items": { "type": "string" },
"description": "Riesgos concretos o dependencias bloqueadas que amenazan el objetivo"
},
"next_actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": { "type": "string" },
"reason": { "type": "string" }
},
"required": ["title", "reason"]
},
"description": "Acciones recomendadas a continuación"
}
},
"required": ["health", "summary", "risks", "next_actions"]
}
}'El campo output de la respuesta se ajusta rigurosamente al esquema suministrado sin claves adicionales:
{
"run_id": "d09cf14f-b9c6-4481-902e-0cd7d8170d6e",
"output": {
"health": "at_risk",
"summary": "Las funcionalidades principales están desplegadas, pero los tiempos de espera recurrentes en la pasarela de pagos durante las pruebas de carga ponen en riesgo el lanzamiento a tiempo.",
"risks": ["Fallos intermitentes por tiempo de espera en la pasarela de pagos bajo carga"],
"next_actions": [
{
"title": "Investigar el cuello de botella de la pasarela de pagos",
"reason": "Identificar la causa raíz y ajustar la configuración de reintentos y conexiones"
}
]
},
"verifications": [],
"credits_consumed": 5
}Definir esquemas estrictos con enum y required garantiza la compatibilidad de tipos con sistemas posteriores, facilitando la activación de alertas automáticas cuando la salud pasa a at_risk o critical, la sincronización con cuadros de mando internos o el bloqueo en flujos de integración continua.
Para continuar una revisión, pasa su run_id como previous_run_id. Debe ser una ejecución correcta accesible con la misma credencial de API. Review conserva los ID de las condiciones sin cambios; el context actual aporta la evidencia de la nueva evaluación. Omite el campo para iniciar una secuencia nueva. Al reutilizar una clave de idempotencia, mantén el mismo previous_run_id.
Respuesta
Cuando finaliza la generación, la solicitud devuelve HTTP 200 con el resultado.
{
"run_id": "d09cf14f-b9c6-4481-902e-0cd7d8170d6e",
"output": {
"content": "La respuesta es incorrecta: 2 + 2 es 4, no 5."
},
"verifications": [],
"credits_consumed": 3
}La respuesta incluye run_id y verifications separado de output. Cada verificación contiene condición, origen, estado, resumen y evidencia con context_path y una cita exacta quote de la entrada. El nombre raíz verifications está reservado en output_schema. Las ejecuciones exitosas conservan la entrada y el resultado final; las fallidas conservan metadatos y un código seguro.
Esta respuesta es ilustrativa; el contenido y el consumo de créditos varían. output sigue el formato de output_schema cuando se proporciona. El consumo depende del modelo y de los tokens utilizados. Los resultados no se guardan en el historial de informes; conserva la respuesta en tu aplicación si la necesitas.
Reintentos y errores
Idempotency-Key es opcional. Si se omite, cada llamada inicia una nueva revisión y puede volver a consumir créditos, incluso con los mismos datos. Una cabecera vacía o no válida se rechaza con 400.
Si tu aplicación reintenta solicitudes, genera un UUID antes del primer intento e inclúyelo en la cabecera:
IDEMPOTENCY_KEY=$(uuidgen)
# Añade esta cabecera a curl y reutiliza la variable al reintentar:
# --header "Idempotency-Key: $IDEMPOTENCY_KEY"Reutiliza el mismo Idempotency-Key, los mismos datos y la misma clave de API al reintentar. Una solicitud completada devuelve su resultado guardado sin volver a generar ni cobrar. Reutilizar el UUID con datos diferentes devuelve un conflicto. Una operación en curso con esa clave también puede devolver un conflicto; espera antes de reintentar la misma solicitud. Usa un UUID nuevo para una revisión nueva.
Si se registró una ejecución fallida o interrumpida, se necesita un UUID nuevo para iniciar otra. Cuando está disponible, el ID se devuelve en la cabecera de error X-Review-Run-Id.
Los errores tienen este formato:
{
"error": {
"message": "A review API key is required as a Bearer token."
}
}| Estado | Significado |
|---|---|
400 |
Datos, esquema, modelo o clave de idempotencia no válidos. |
401 |
Clave de API ausente, no válida, caducada o revocada. |
402 |
Créditos insuficientes. |
403 |
La configuración o las condiciones de acceso de la cuenta propietaria no permiten la revisión. |
409 |
Datos en conflicto o una operación en curso con la misma clave de idempotencia. |
413 |
El cuerpo supera el límite de tamaño. |
415 |
El tipo de contenido no es application/json. |
500, 503 |
La generación o un servicio necesario no están disponibles. |
504 |
La generación agotó el tiempo de espera; consulta las indicaciones de reintento. |
Ante errores transitorios, aumenta progresivamente el tiempo entre reintentos y establece un límite. Tras un fallo de red o una respuesta incierta, reutiliza el UUID original si lo proporcionaste. Sin esa clave, reintentar puede generar otra revisión y consumir créditos adicionales.
Alojamiento propio con Docker
Despliega la API de revisión con Docker en tu propia nube o infraestructura local. Conéctala a los modelos que utilizas, incluidos LLM locales y servicios de modelos en la nube.
Adaptamos la integración y la implementación a tu entorno: conexiones con modelos, autenticación, requisitos de red y necesidades operativas. Cuéntanos qué modelos y condiciones de despliegue necesitas para definir la configuración adecuada.
Contacta con ventas para hablar del alojamiento propio y el despliegue.
Comentarios y orientación compartida
Los comentarios se vinculan a un run_id guardado y, opcionalmente, a un verification_id de esa ejecución. La memoria a largo plazo está disponible para la API de Review y las instalaciones independientes en su espacio de nombres autenticado. Los informes de la aplicación usan fuentes originales y comentarios anteriores sin memoria. El agente mantiene notas Markdown que se pueden buscar o eliminar; las notas se conservan al eliminar el historial de revisiones.
Para continuar una revisión, incluye previous_run_id en la solicitud. La evaluación tiene en cuenta los comentarios accesibles de las ejecuciones anteriores. Los comentarios son observaciones, no pruebas nuevas ni correcciones automáticas de los resultados guardados.
Envía POST /v1/reviews/{runId}/feedback con content y, opcionalmente, verification_id y un UUID idempotencyKey para los reintentos. El servidor asigna el ID del comentario. Un reintento con la misma clave y contenido devuelve el comentario guardado. Usa GET en la misma ruta para consultar los comentarios y DELETE /v1/reviews/{runId}/feedback/{feedbackId} para eliminarlos.
La memoria de la API de Review está aislada por credencial de API. Las claves diferentes del mismo espacio de trabajo no comparten memoria. Al rotar una clave activa se conserva el UUID de la credencial, por lo que siguen disponibles su memoria e historial de revisiones y no cambia su caducidad. El secreto anterior deja de funcionar inmediatamente y el nuevo solo se muestra una vez. Crear una clave nueva genera otra credencial y no hereda la memoria de la anterior.
Consulta las notas con GET /v1/memories y usa query para buscar, o page_size y cursor para paginar. Elimina una nota con DELETE /v1/memories/{memoryId}. Eliminar comentarios no elimina automáticamente las notas aprendidas; elimina por separado las que ya no necesites.
En la instalación independiente, configura EPISMO_API_KEYS como una lista de entradas {namespace_id, key}. Las claves del mismo espacio de nombres comparten la memoria y la identidad de los reintentos; conserva el UUID al rotar las claves.
Desde la CLI, usa epismo report feedback create REPORT_ID --content "Comentario" para añadir un comentario. Para una verificación concreta, añade --verification-id VERIFICATION_UUID. Usa epismo report feedback list REPORT_ID para listar comentarios y epismo report feedback delete REPORT_ID FEEDBACK_UUID para eliminarlos. Los mismos comandos funcionan con IDs de informes de Caso, Personales y de Equipo, según tus permisos. Para reintentar de forma segura, usa la misma --idempotency-key. Los informes posteriores de Caso, Personales y de Equipo tienen en cuenta los comentarios anteriores junto con la evidencia actual.