1
Create the assignment
Give the assignment a name. You can also record the grade, the section, a course ID, and your own institute IDs, so you can list assignments back by any of them later. There is no subject field: every assignment is marked as English on the NCERT syllabus, and the grade defaults to grade 10 if you leave it blank.
2
Upload the question set
Attach a PDF or PNG photographs of the worksheet, then send it for processing. Avoid JPEG here: it is accepted, but it is not recorded as an image, which breaks the checks that stop you mixing a PDF with photographs.The AI reads: the questions and their sub-questions, the marks for each, and a description of any diagram.
3
Add model answers or attach a rubric
Create the model answer sheet, then either upload the answer key as a PDF or images, or attach a rubric by its ID. Then send it for processing.The AI reads: the expected answer for every question with the marks for each step, or, with a rubric, the criteria and score bands it will score against.
4
Upload each student's work
Create one answer sheet per student, with your own student ID and the student’s name. You can also record a batch, a session, and a teacher ID.Attach the student’s PDF or images, or give a public HTTPS link to an MP3 recording, then send it for marking.
5
Read the scores
Once the sheet is marked, read the whole assignment back in one response: each question, the student’s answer as the AI read it, the marks, the feedback, and the model answer or rubric it was scored against.
What runs in the background?
Reading the question set, reading the answer key, and scoring an answer sheet. Each one takes the AI longer than a web request allows, so the API accepts the work and returns straight away. You find out when a stage has finished in one of two ways: check the status every few seconds, or register a webhook and let CrazyGoldFish call your server. Assignment Evaluation sends a webhook when the question set has been read, when the answer key has been read, and when an answer sheet has been scored. See Async jobs and webhooks.What happens if a stage fails?
The item moves to a failed status, and the endpoint you use to read it returns an error saying processing failed. Fix the input and send it again. You cannot re-send something that already completed. For an audio answer, the link is checked before anything is sent for marking, so a link that is not HTTPS, does not end in.mp3, is unreachable, or points at a private address is refused there and then with a specific message. A maximum recording length may also apply, from a single server-wide setting; when that setting is switched off, no length is checked at all.
How is this different from exam evaluation?
There is no review stage and no publishing stage. Once the AI has scored an answer sheet, the score is readable. Nothing marks it as approved, no teacher can edit it through the API, and no student can raise a query on it. If a teacher has to sign marks off before students see them, use Exam Evaluation instead.Frequently asked questions
Why does reading the scores return an error?
Why does reading the scores return an error?
The answer sheet has to be fully marked first. Until it is, the score endpoint says the sheet is not evaluated yet. If it says processing failed, the marking run failed and you need to upload the work again.
Can one assignment have both written and spoken answers?
Can one assignment have both written and spoken answers?
Each answer sheet is one or the other. Within an assignment, one student can submit a PDF while another submits a recording, but a recording only works if the assignment has a rubric attached.
Can I add a rubric after the answer key is already processed?
Can I add a rubric after the answer key is already processed?
No. Once the model answer sheet is marked as complete, changing it returns an error. Decide between model answers and a rubric before you send the answer key for processing.
How do I find an assignment or answer sheet again?
How do I find an assignment or answer sheet again?
List them through the API. Assignments can be filtered by name, grade, and section. Answer sheets can be filtered by your own student, batch, and teacher IDs, and by student name.
Can I upload work for a whole class at once?
Can I upload work for a whole class at once?
You create and send each answer sheet separately. There is no bulk upload endpoint, but you can run them in parallel, up to the daily limit on the API user sending them. Audio answers have a tighter cap, only a few in any 60 second window, so send those more slowly.
Next steps
Features
Rubrics, audio answers, and what comes back for each question.
Use cases
How schools and platforms use assignment evaluation.
Developer guide
Evaluate an assignment with the API, step by step.
Create a rubric
Build a rubric and its criteria with the API.