API de revisión de IA

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/reviews

Revisa tus propios datos sin crear casos ni playbooks. Incluye en context la información necesaria para la revisión. No se utiliza la búsqueda web.

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:

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.

El cuerpo completo no debe superar los 600.000 bytes. Se rechazan los campos desconocidos. Omite los campos opcionales en lugar de enviar null.

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:

{
	"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"
			}
		]
	},
	"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.

Respuesta

Cuando finaliza la generación, la solicitud devuelve HTTP 200 con el resultado.

{
	"output": {
		"content": "La respuesta es incorrecta: 2 + 2 es 4, no 5."
	},
	"credits_consumed": 3
}

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.

Los errores tienen este formato:

{
	"error": {
		"message": "A review API key is required as a Bearer token."
	}
}

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.