Migration from the Legacy API

Summary

The old public integration docs were based on:

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

The current public API uses:

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

Mapping

Mental Model Shift

Legacy evaluation flow:

1. Send assignment text and rubrics directly
2. Start evaluation
3. Poll results

Current public v1 flow:

1. Get a model_id from GET /models
2. Create a student assignment with POST /assignments, or use POST /evaluations/one-pass for direct model grading
3. Submit the essay text or answer file to POST /evaluations with the returned assignment_id
4. Poll GET /evaluations/:taskId/status
5. Fetch the final payload from GET /evaluations/:taskId

Reliable async evaluation

POST /evaluations/one-pass and POST /evaluations/batch use the reliable asynchronous path. They return HTTP 202 Accepted with a public task_id. Send an Idempotency-Key so a safe network retry returns the same task instead of creating a duplicate. A batch request accepts 1-100 items.

These tasks move through QUEUED, UPLOADING, SUBMITTED, and PROGRESS, then finish as SUCCESS, FAILURE, or CANCEL. Credits are charged only after KEATH validates a complete result. Poll with a bounded timeout and backoff; do not use an endless loop.

POST /evaluations for an existing assignment remains on the legacy task path for compatibility. It normally starts as PENDING and charges credits when the task is accepted. Do not assume its billing and initial status are the same as one-pass or batch.

If you need to create a model first, the new build flow is:

1. Parse question assets
2. Parse rubric assets
3. Confirm the preview result
4. Create the marking model with POST /models
5. Reuse that model to create assignments or one-pass evaluations

Input Differences

The current public API is multimodal for model-building:

• PDFs are supported
• images are supported
• direct file upload is supported
• existing public URLs are supported
• specification helps disambiguate which question or rubric to use

The current public evaluation endpoint supports text and answer file uploads:

• submit the essay as paper_content
• pass an existing student assignment assignment_id
• optionally pass current_feedbacks
• optionally choose style as Bullet, Short, or Long

Direct PDF/image, DOCX, TXT, and RTF answer uploads are supported by POST /evaluations.

Client Changes

Update your client to:

1. Replace X-TOKEN-KEY with X-API-Key
2. Replace /api/open/evaluation/* routes with /api/keath/public/v1/*
3. Treat model_id as the marking model id from GET /models
4. Treat assignment_id as the student assignment id from POST /assignments or the product assignment detail URL
5. For grading, submit essay text or an answer file to POST /evaluations
6. Poll GET /evaluations/:taskId/status while the task is running
7. Fetch the final result from GET /evaluations/:taskId
8. For local PDFs/images used during model creation, send multipart/form-data
9. For existing public file URLs, send assets[]
10. If mixing uploads and URLs, send multipart plus JSON-stringified assets
11. If you use organization-scoped keys, treat them as wider model visibility, not shared billing. Credits still come from the key owner.

Recommended Validation

• Re-run your smoke test against GET /credits
• Re-run your smoke test against GET /models
• Create an assignment with POST /assignments
• Submit one essay to POST /evaluations
• Poll GET /evaluations/:taskId/status
• Fetch the final payload from GET /evaluations/:taskId
• If you still build models via API, send one PDF to questions-ingest-preview
• Send one rubric file to rubrics-ingest-preview
• Confirm no client code still references X-TOKEN-KEY