API pública KEATH v1

Esta guía está escrita para que un integrador pueda probar la API sin leer el código interno.

Base URL

https://keath.ai/api/keath/public/v1

Todos los requests usan:

• Header: X-API-Key: kct_your_api_key
• Respuesta: JSON estándar de KEATH

La clave debe ser una API key pública de KEATH que empieza con kct_. No envíe claves de Gemini, OpenAI o NewAPI.

Primer flujo recomendado

1. Llame GET /credits.
2. Llame GET /models.
3. Cree un assignment con POST /assignments y un model_id.
4. Evalúe con POST /evaluations y el assignment_id devuelto.
5. Consulte GET /evaluations/:taskId/status.
6. Cuando el estado sea SUCCESS, FAILURE o CANCEL, lea el resultado con GET /evaluations/:taskId.

Qué significa cada ID

Si ya tiene un modelo entrenado, use su model_id para crear un assignment o para una evaluación one-pass.

Endpoints principales

GET /models

curl "https://keath.ai/api/keath/public/v1/models" \
  -H "X-API-Key: kct_your_api_key"

Ejemplo:

{
  "model_id": 930,
  "assignment_name": "O Level Situational Writing Model",
  "post_status": "ready",
  "total_score": 30
}

Use modelos con post_status: "ready".

POST /assignments

{
  "model_id": 930,
  "assignment_name": "Situation Writing Test",
  "assignment_desc": "Student-facing writing assignment",
  "project_subject": "English",
  "deadline_time": "2026-06-01T00:00:00.000Z",
  "expected_number": 30,
  "file_type": "pdf"
}

Respuesta típica:

{
  "assignment_id": 1620,
  "model_id": 930,
  "status": "active"
}

POST /evaluations

Evalúa una respuesta de estudiante para un assignment existente.

Campos clave:

• assignment_id: la tarea del estudiante, no el modelo.
• paper_content: texto de la respuesta.
• o un archivo de respuesta con multipart/form-data.
• style: Bullet, Short o Long. Por defecto: Bullet.
• student_id: ID anónimo de su sistema. KEATH no crea un estudiante con ese ID.

Formatos aceptados para respuestas:

• PDF e imágenes: extracción multimodal con descripción visual cuando ayuda a la corrección.
• DOCX, TXT, RTF: extracción de texto en el servidor.

Campos aceptados para archivos:

• answer_file
• answer_files
• paper_file
• paper_files
• response_file
• response_files
• file o files

Ejemplo con archivo:

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations" \
  -H "X-API-Key: kct_your_api_key" \
  -F "assignment_id=1620" \
  -F "answer_file=@./student-answer.pdf;type=application/pdf" \
  -F "student_id=anon-student-001" \
  -F "style=Bullet"

POST /evaluations/one-pass

Use este endpoint si no quiere crear un assignment.

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations/one-pass" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Idempotency-Key: eval-student-001-attempt-1" \
  -F "model_id=930" \
  -F "question_file=@./question.pdf;type=application/pdf" \
  -F "rubric_file=@./rubric.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -F "answer_file=@./student-answer.txt;type=text/plain" \
  -F "specification=Use Question 2 only." \
  -F "style=Bullet"

Formatos directos soportados:

• Pregunta y rúbrica: PDF, imágenes, DOCX, TXT, RTF
• Respuesta del estudiante: PDF, imágenes, DOCX, TXT, RTF

La respuesta es HTTP 202 Accepted con un task_id público, status: "QUEUED" y stage: "queued". El trabajo fue aceptado, pero la evaluación aún no terminó.

Use un Idempotency-Key único para cada envío lógico. Repetir la misma petición devuelve el mismo task_id; reutilizar la key con otro texto o archivos devuelve 409.

Los archivos se guardan antes de entrar en la cola. Los credits solo se cobran después de validar un resultado completo. Una tarea fallida o cancelada mantiene credits_charged: 0.

POST /evaluations/batch

Envía de 1 a 100 evaluaciones one-pass. Cada elemento de evaluations usa los mismos campos que /evaluations/one-pass.

curl -X POST "https://keath.ai/api/keath/public/v1/evaluations/batch" \
  -H "X-API-Key: kct_your_api_key" \
  -H "Idempotency-Key: class-5a-writing-2026-07-15" \
  -H "Content-Type: application/json" \
  -d '{
    "evaluations": [
      {"model_id":930,"question_text":"Escriba una carta formal.","paper_content":"Estimado director: ...","student_id":"anon-001"},
      {"model_id":930,"question_text":"Escriba una carta formal.","paper_content":"Estimado director, propongo ...","student_id":"anon-002"}
    ],
    "callback_url":"https://integration.example.com/keath/results"
  }'

callback_url es opcional y debe ser una URL HTTPS pública. Mantenga el polling como respaldo.

Preguntas y rúbricas desde archivos

Use:

• POST /questions-ingest-preview
• POST /rubrics-ingest-preview

Si el PDF contiene varias preguntas, añada specification:

Only parse Question 2. Ignore sample answers and teacher notes.

Estados

• QUEUED / queued
• UPLOADING / uploading
• SUBMITTED / submitted
• PROGRESS / processing
• SUCCESS / completed
• FAILURE / failed
• CANCEL / cancelled

Consulte cada 3 segundos al principio y aumente gradualmente hasta 15 segundos. Defina siempre un tiempo máximo; no use un bucle infinito.

Compatibilidad: POST /evaluations para un assignment existente conserva la ruta anterior y cobra credits al aceptar la tarea. El 202, la idempotencia, la cola duradera y el cobro al completar aplican a /evaluations/one-pass y /evaluations/batch.

Si el estado es FAILURE, evaluation puede incluir un item con type: "error" y un mensaje claro en comment. Trátelo como una evaluación fallida, no como una nota.

Límites de archivos

• Máximo 10 archivos por request en endpoints multiarchivo.
• Máximo 20 MB por archivo.
• Para /uploads/file, envíe exactamente un archivo con el campo file.

Errores frecuentes

• 401: API key ausente o inválida.
• 402: créditos insuficientes.
• 403: sin acceso al modelo.
• 404: modelo, assignment o evaluación no existe.
• 409: modelo no listo, o tarea no cancelable.
• 400: campo faltante, JSON inválido o tipo de archivo no soportado.

Siguiente

• Ejemplos
• Migración