API publique KEATH v1

Ce guide explique le chemin le plus direct pour intégrer KEATH. Le but n'est pas de lister des routes sans contexte, mais de montrer quoi appeler et pourquoi.

Base URL

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

Tous les appels utilisent :

• Header : X-API-Key: kct_your_api_key
• Réponse : un corps JSON standard KEATH

N'envoyez jamais une clé fournisseur comme Gemini, OpenAI ou NewAPI à cette API. Ici, la clé attendue est une clé publique KEATH qui commence par kct_.

Le flux le plus sûr pour commencer

1. Appelez GET /credits.
2. Appelez GET /models.
3. Créez un devoir avec POST /assignments et un model_id.
4. Corrigez une copie avec POST /evaluations et le assignment_id retourné.
5. Interrogez GET /evaluations/:taskId/status.
6. Quand le statut est SUCCESS, FAILURE ou CANCEL, récupérez le résultat avec GET /evaluations/:taskId.

Les deux IDs importants

Si vous avez déjà un modèle entraîné, utilisez son model_id pour créer un assignment ou pour lancer une correction one-pass.

Routes principales

GET /models

Utilisez cette route pour choisir le modèle de correction.

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

Exemple de modèle :

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

Utilisez seulement les modèles dont post_status est ready.

POST /assignments

Crée un devoir élève à partir d'un modèle.

{
  "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"
}

Réponse typique :

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

POST /evaluations

Corrige une copie pour un assignment qui existe déjà.

Champs importants :

• assignment_id : le devoir élève, pas le modèle.
• paper_content : texte de la copie.
• ou un fichier de copie en multipart/form-data.
• style : Bullet, Short ou Long. Par défaut : Bullet.
• student_id : ID anonyme de votre système. KEATH ne crée pas d'élève avec cet ID.

Formats acceptés pour les copies :

• PDF et images : extraction multimodale avec description du contenu visuel utile.
• DOCX, TXT, RTF : extraction texte côté serveur.

Noms de champs acceptés pour le fichier de réponse :

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

Exemple JSON :

{
  "assignment_id": 1620,
  "paper_content": "Dear Mrs Tan, I am writing to request permission...",
  "style": "Bullet",
  "student_id": "anon-student-001"
}

Exemple avec fichier :

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

Utilisez cette route si vous ne voulez pas créer d'assignment.

Vous envoyez :

• model_id
• la question ou le contexte
• la grille de correction
• la copie de l'élève

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"

Formats directs supportés pour one-pass :

• Question et grille : PDF, images, DOCX, TXT, RTF
• Copie élève : PDF, images, DOCX, TXT, RTF

La réponse est HTTP 202 Accepted avec un task_id public, status: "QUEUED" et stage: "queued". Le travail est accepté, mais la correction n'est pas encore terminée.

Utilisez un Idempotency-Key unique par soumission logique. Une nouvelle tentative identique renvoie le même task_id. Le même key avec un contenu différent renvoie 409.

Les fichiers sont enregistrés avant la mise en file. Les credits sont débités seulement après validation d'un résultat complet. Une tâche échouée ou annulée conserve credits_charged: 0.

POST /evaluations/batch

Envoie de 1 à 100 corrections one-pass. Chaque élément de evaluations accepte les mêmes champs 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":"Rédigez une lettre formelle.","paper_content":"Madame, Monsieur, ...","student_id":"anon-001"},
      {"model_id":930,"question_text":"Rédigez une lettre formelle.","paper_content":"Madame, Monsieur, je propose ...","student_id":"anon-002"}
    ],
    "callback_url":"https://integration.example.com/keath/results"
  }'

callback_url est facultatif et doit être une URL HTTPS publique. Gardez le polling comme solution de secours.

Questions et rubrics depuis PDF ou images

Avant de créer un modèle, vous pouvez demander à KEATH de lire les documents.

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

Ajoutez specification si le document contient plusieurs questions :

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

Statuts de correction

Les statuts courants :

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

Interrogez d'abord toutes les 3 secondes, puis augmentez progressivement jusqu'à 15 secondes. Utilisez toujours une durée maximale, jamais une boucle infinie.

Compatibilité : POST /evaluations pour un assignment existant conserve l'ancien chemin et débite les credits à l'acceptation. Le 202, l'idempotence, la file durable et le débit après réussite concernent /evaluations/one-pass et /evaluations/batch.

Si le statut est FAILURE, le champ evaluation peut contenir un item avec type: "error" et un message lisible dans comment. Traitez-le comme une correction échouée, pas comme une note.

Limites de fichiers

• Maximum 10 fichiers par demande pour les endpoints qui acceptent plusieurs fichiers.
• Maximum 20 MB par fichier.
• Pour /uploads/file, envoyez exactement un fichier avec le champ file.

Erreurs fréquentes

• 401 : clé manquante ou invalide.
• 402 : crédits insuffisants.
• 403 : pas accès au modèle.
• 404 : modèle, assignment ou évaluation introuvable.
• 409 : modèle pas encore prêt, ou tâche non annulable.
• 400 : champ manquant, JSON invalide ou type de fichier non supporté.

Prochaines pages

• Exemples
• Migration depuis l'ancienne API