Migración desde la API anterior

Qué cambió

Antes se usaba:

• Header: X-TOKEN-KEY
• Rutas: /api/open/evaluation/*

Ahora se usa:

• Header: X-API-Key
• Rutas: /api/keath/public/v1/*

Mapeo

Nuevo modelo mental

Antes se enviaban directamente texto y rúbricas.

Ahora debe elegir uno de dos caminos:

1. Camino con assignment:

   • obtener model_id
   • crear assignment
   • evaluar con assignment_id

2. Camino one-pass:

   • obtener model_id
   • enviar modelo, pregunta, rúbrica y respuesta en una sola llamada

Evaluación asíncrona fiable

POST /evaluations/one-pass y POST /evaluations/batch responden con HTTP 202 Accepted y un task_id público. Envíe Idempotency-Key: un reintento de red idéntico recupera la misma tarea en vez de crear otra. El batch acepta entre 1 y 100 elementos.

Las etapas son QUEUED, UPLOADING, SUBMITTED, PROGRESS y después SUCCESS, FAILURE o CANCEL. Los credits se cobran solo después de validar un resultado completo. Use polling con tiempo máximo y backoff.

Por compatibilidad, POST /evaluations con un assignment existente conserva el flujo anterior: normalmente empieza en PENDING y cobra los credits al aceptar la tarea. No aplique ese estado inicial ni ese momento de cobro a one-pass o batch.

Cambios en el cliente

1. Reemplace X-TOKEN-KEY por X-API-Key.
2. Reemplace /api/open/evaluation/* por /api/keath/public/v1/*.
3. No use model_id como si fuera assignment_id.
4. Use POST /evaluations cuando ya exista un assignment.
5. Use POST /evaluations/one-pass cuando no quiera crear assignment.
6. Consulte GET /evaluations/:taskId/status.
7. Lea el resultado final con GET /evaluations/:taskId.

Formatos

La nueva API acepta respuestas de estudiantes como texto o archivo:

• PDF
• imágenes
• DOCX
• TXT
• RTF

Para Google Docs, exporte primero a DOCX, PDF o texto. La importación directa con OAuth de Google Docs no forma parte de public v1.

Validación

Antes de migrar tráfico real, confirme:

• GET /credits funciona.
• GET /models devuelve el modelo esperado.
• POST /assignments devuelve un assignment_id.
• POST /evaluations devuelve un task_id.
• El polling termina en SUCCESS, FAILURE o CANCEL.
• El cliente ya no contiene X-TOKEN-KEY.