Evaluate an assignment with the API

Assignment Evaluation reads an assignment’s question paper, learns the teacher’s answer key or rubric, then marks each student’s answer and writes feedback. Students can answer on paper, which you upload as a PDF or photos, or out loud, which you send as a link to an MP3. This guide is for developers. For a non-technical overview, see Assignment Evaluation features and the workflow.

Step	You call	You get back
1	Create an assignment	An assignment `id`
2	Upload the question paper, then submit it	Every question with its marks
3	Add the answer key or a rubric, then submit it	A model answer per question
4	Create an answer sheet for a student	An answer sheet `id`
5	Submit the student’s answer as documents or an audio link	An evaluation in progress
6	Get the score	Marks and feedback per question

Steps 2, 3, and 5 start a background job. Each one takes two calls: first the upload, then a separate call with isFinal set to the text true. Wait until status is 2 (Completed) before the next step. The wait_for helper below does this for you.

Set up

You need an access token. If you don’t have one, follow the Quickstart. Progress is reported as an integer status: 0 Open, 1 In Progress, 2 Completed, 3 Failed.

import time

import requests

BASE_URL = "https://api.crazygoldfish.com"
HEADERS = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

COMPLETED, FAILED = 2, 3


def wait_for(path, pick=lambda body: body["status"]):
    """Check the status every 5 seconds until it's Completed."""
    for _ in range(120):  # Give up after 10 minutes
        response = requests.get(BASE_URL + path, headers=HEADERS)
        response.raise_for_status()
        body = response.json()
        status = pick(body)
        if status == COMPLETED:
            return body
        if status == FAILED:
            raise RuntimeError(f"{path} failed")
        time.sleep(5)
    raise TimeoutError(f"{path} took longer than 10 minutes")

const BASE_URL = "https://api.crazygoldfish.com";
const HEADERS = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };

const COMPLETED = 2;
const FAILED = 3;

// Check the status every 5 seconds until it's Completed
async function waitFor(path, pick = (body) => body.status) {
  for (let i = 0; i < 120; i++) { // Give up after 10 minutes
    const response = await fetch(BASE_URL + path, { headers: HEADERS });
    if (!response.ok) throw new Error(await response.text());
    const body = await response.json();
    const status = pick(body);
    if (status === COMPLETED) return body;
    if (status === FAILED) throw new Error(`${path} failed`);
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`${path} took longer than 10 minutes`);
}

Every path ends with a slash. Without it, the API redirects the request and a POST or PATCH loses its body.

Step 1: Create the assignment

Send the assignment’s name, and your own IDs for the class. You get back the id that every later call uses.

response = requests.post(
    BASE_URL + "/assignment-evaluation/v1/assignment/",
    headers=HEADERS,
    json={
        "assignmentName": "Unit 3 English essay",
        "grade": "7",
        "section": "A",
        "courseId": "300",
    },
)
response.raise_for_status()
assignment_id = response.json()["id"]
assignment_path = f"/assignment-evaluation/v1/assignment/{assignment_id}/"

const response = await fetch(BASE_URL + "/assignment-evaluation/v1/assignment/", {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    assignmentName: "Unit 3 English essay",
    grade: "7",
    section: "A",
    courseId: "300",
  }),
});
if (!response.ok) throw new Error(await response.text());
const assignmentId = (await response.json()).id;
const assignmentPath = `/assignment-evaluation/v1/assignment/${assignmentId}/`;

What you get back

{
  "id": "3c9e1f2a-7b4d-4a8e-9f1c-2d5e6a7b8c9d",
  "documents": []
}

grade is passed to the AI as the student level, so send it when you know it.

Step 2: Upload the question paper

Upload the paper, then send isFinal in a second call to start extraction. Wait for the assignment’s status to reach 2, then read the questions.

with open("question-paper.pdf", "rb") as paper:
    requests.patch(
        BASE_URL + assignment_path,
        headers=HEADERS,
        files={"documents": ("question-paper.pdf", paper, "application/pdf")},
    ).raise_for_status()

requests.patch(
    BASE_URL + assignment_path, headers=HEADERS, data={"isFinal": "true"}
).raise_for_status()

wait_for(assignment_path)

questions = requests.get(
    BASE_URL + assignment_path + "questions/", headers=HEADERS
).json()

const paper = new FormData();
paper.append("documents", questionPaperFile, "question-paper.pdf");
await fetch(BASE_URL + assignmentPath, {
  method: "PATCH",
  headers: HEADERS,
  body: paper,
});

const submitPaper = new FormData();
submitPaper.append("isFinal", "true");
await fetch(BASE_URL + assignmentPath, {
  method: "PATCH",
  headers: HEADERS,
  body: submitPaper,
});

await waitFor(assignmentPath);

const questions = await (
  await fetch(BASE_URL + assignmentPath + "questions/", { headers: HEADERS })
).json();

Photos work too: send several documents parts with image/jpeg or image/png, in one call or across several. One PDF per assignment, and never a PDF and photos together.

What you get back

{
  "id": "3c9e1f2a-7b4d-4a8e-9f1c-2d5e6a7b8c9d",
  "assignmentName": "Unit 3 English essay",
  "instruction": "Answer both parts in your own words.",
  "marks": 2.0,
  "grade": "7",
  "courseId": "300",
  "parentQuestions": [
    {
      "id": "cabb699a-ef46-447c-85d2-f320d83f9745",
      "questionNumber": "1",
      "text": "Read the passage and answer the questions.",
      "marks": 0.0,
      "questions": [
        {
          "id": "2edd8bfd-3616-4899-95e9-98d67489ca11",
          "questionNumber": "a",
          "text": "Why does the narrator return to the village?",
          "marks": 1.0,
          "diagramDescription": null
        }
      ]
    }
  ]
}

A parentQuestions entry is a group. Shared material, such as a passage, sits in its text, and the questions a student answers sit in questions.

Step 3: Add the answer key or a rubric

Create the model answer sheet, then give the AI something to mark against. Use the teacher’s answer key for questions with a right answer, and a rubric for open-ended work. Audio answers are always scored against a rubric.

Answer key
Rubric

response = requests.post(
    BASE_URL + assignment_path + "model-answer/", headers=HEADERS
)
response.raise_for_status()
model_answer_path = (
    assignment_path + f"model-answer/{response.json()['id']}/"
)

with open("answer-key.pdf", "rb") as key:
    requests.patch(
        BASE_URL + model_answer_path,
        headers=HEADERS,
        files={"documents": ("answer-key.pdf", key, "application/pdf")},
    ).raise_for_status()

requests.patch(
    BASE_URL + model_answer_path, headers=HEADERS, data={"isFinal": "true"}
).raise_for_status()

wait_for(assignment_path + "model-answer/")

const created = await fetch(BASE_URL + assignmentPath + "model-answer/", {
  method: "POST",
  headers: HEADERS,
});
if (!created.ok) throw new Error(await created.text());
const modelAnswerPath =
  `${assignmentPath}model-answer/${(await created.json()).id}/`;

const key = new FormData();
key.append("documents", answerKeyFile, "answer-key.pdf");
await fetch(BASE_URL + modelAnswerPath, {
  method: "PATCH",
  headers: HEADERS,
  body: key,
});

const submitKey = new FormData();
submitKey.append("isFinal", "true");
await fetch(BASE_URL + modelAnswerPath, {
  method: "PATCH",
  headers: HEADERS,
  body: submitKey,
});

await waitFor(assignmentPath + "model-answer/");

response = requests.post(
    BASE_URL + assignment_path + "model-answer/", headers=HEADERS
)
response.raise_for_status()
model_answer_path = (
    assignment_path + f"model-answer/{response.json()['id']}/"
)

requests.patch(
    BASE_URL + model_answer_path,
    headers=HEADERS,
    data={"rubricId": "2b973c83-2830-4712-87b7-64a8c0a99035"},
).raise_for_status()

requests.patch(
    BASE_URL + model_answer_path, headers=HEADERS, data={"isFinal": "true"}
).raise_for_status()

wait_for(assignment_path + "model-answer/")

const created = await fetch(BASE_URL + assignmentPath + "model-answer/", {
  method: "POST",
  headers: HEADERS,
});
if (!created.ok) throw new Error(await created.text());
const modelAnswerPath =
  `${assignmentPath}model-answer/${(await created.json()).id}/`;

const rubric = new FormData();
rubric.append("rubricId", "2b973c83-2830-4712-87b7-64a8c0a99035");
await fetch(BASE_URL + modelAnswerPath, {
  method: "PATCH",
  headers: HEADERS,
  body: rubric,
});

const submitRubric = new FormData();
submitRubric.append("isFinal", "true");
await fetch(BASE_URL + modelAnswerPath, {
  method: "PATCH",
  headers: HEADERS,
  body: submitRubric,
});

await waitFor(assignmentPath + "model-answer/");

Create the rubric once with Create a rubric and reuse its id across assignments.

Send only one of documents, rubricId, or isFinal per call. Two together return 400. Send isFinal as the text true, not as a JSON boolean.

What you get back

{
  "id": "3b27e0be-f9e8-4c4d-977b-b315bfb292ab",
  "documents": [
    {
      "id": "4a7c1e90-2b6d-4f31-9c58-0d7e3f2a1b46",
      "status": 2,
      "pageNo": null,
      "uploadTime": "2025-04-06T09:31:02.118422Z",
      "url": "https://<storage-host>/documents/assignment-evaluation/unit-3-answer-key.pdf",
      "fileType": 1,
      "audio_link": null
    }
  ],
  "rubric": {},
  "status": 2
}

Once status is 2, Get extracted assignment model answers shows the model answer and step-wise marks for every question.

Step 4: Create an answer sheet for the student

One answer sheet holds one student’s answer. Send your own studentId and the student’s name.

student_id = "STU-10432"

response = requests.post(
    BASE_URL + assignment_path + "answer-sheet/",
    headers=HEADERS,
    json={"studentId": student_id, "name": "Aarav Sharma"},
)
response.raise_for_status()
sheet_id = response.json()["id"]
sheet_path = assignment_path + f"answer-sheet/{sheet_id}/"

const studentId = "STU-10432";

const sheet = await fetch(BASE_URL + assignmentPath + "answer-sheet/", {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ studentId, name: "Aarav Sharma" }),
});
if (!sheet.ok) throw new Error(await sheet.text());
const sheetId = (await sheet.json()).id;
const sheetPath = `${assignmentPath}answer-sheet/${sheetId}/`;

What you get back

{
  "id": "6e1d2c3b-4a5f-4e6d-8c7b-9a0f1e2d3c4b",
  "status": 0,
  "batchId": null,
  "sessionId": null,
  "studentId": "STU-10432",
  "name": "Aarav Sharma",
  "teacherId": null,
  "documents": []
}

You can also send batchId, sessionId, and teacherId. CrazyGoldFish stores them and returns them unchanged, and studentId and teacherId are filters on List assignment answer sheets.

Step 5: Submit the student’s answer

Send the answer, then send isFinal in a second call to start grading. Use documents for written work and a link for a spoken answer. One answer sheet takes one kind of answer, so never mix them.

Documents
Audio link

with open("page-1.jpg", "rb") as one, open("page-2.jpg", "rb") as two:
    requests.patch(
        BASE_URL + sheet_path,
        headers=HEADERS,
        files=[
            ("documents", ("page-1.jpg", one, "image/jpeg")),
            ("documents", ("page-2.jpg", two, "image/jpeg")),
        ],
    ).raise_for_status()

requests.patch(
    BASE_URL + sheet_path, headers=HEADERS, data={"isFinal": "true"}
).raise_for_status()

const pages = new FormData();
pages.append("documents", pageOneFile, "page-1.jpg");
pages.append("documents", pageTwoFile, "page-2.jpg");
await fetch(BASE_URL + sheetPath, {
  method: "PATCH",
  headers: HEADERS,
  body: pages,
});

const submitPages = new FormData();
submitPages.append("isFinal", "true");
await fetch(BASE_URL + sheetPath, {
  method: "PATCH",
  headers: HEADERS,
  body: submitPages,
});

A PDF works the same way: one PDF per answer sheet, up to 50 pages, and never with photos.

requests.patch(
    BASE_URL + sheet_path,
    headers=HEADERS,
    data={"link": "https://cdn.example.com/recordings/student-10432.mp3"},
).raise_for_status()

requests.patch(
    BASE_URL + sheet_path, headers=HEADERS, data={"isFinal": "true"}
).raise_for_status()

const audio = new FormData();
audio.append("link", "https://cdn.example.com/recordings/student-10432.mp3");
await fetch(BASE_URL + sheetPath, {
  method: "PATCH",
  headers: HEADERS,
  body: audio,
});

const submitAudio = new FormData();
submitAudio.append("isFinal", "true");
await fetch(BASE_URL + sheetPath, {
  method: "PATCH",
  headers: HEADERS,
  body: submitAudio,
});

Host the recording yourself. The link must be an HTTPS URL that ends in .mp3, with no query string after it, and it must open without a login: CrazyGoldFish fetches it while your call runs. The assignment’s model answer sheet must have a rubric, and only the first link on a sheet is kept.

Send documents or link first, then isFinal on its own. An answer sent together with isFinal returns 400. Send isFinal as the text true, not as a JSON boolean.

Step 6: Get the score

Wait for the answer sheet’s status to reach 2, then read the marks and feedback.

wait_for(
    assignment_path + f"answer-sheet/?studentId={student_id}",
    pick=lambda body: next(
        sheet["status"] for sheet in body["data"] if sheet["id"] == sheet_id
    ),
)

score = requests.get(BASE_URL + sheet_path + "score/", headers=HEADERS).json()

await waitFor(
  `${assignmentPath}answer-sheet/?studentId=${studentId}`,
  (body) => body.data.find((sheet) => sheet.id === sheetId).status,
);

const score = await (
  await fetch(BASE_URL + sheetPath + "score/", { headers: HEADERS })
).json();

What you get back

For written answers, the marks are on answer.marks and the feedback is in answer.feedbacks:

{
  "id": "3c9e1f2a-7b4d-4a8e-9f1c-2d5e6a7b8c9d",
  "assignmentName": "Unit 3 English essay",
  "marks": 2.0,
  "parentQuestions": [
    {
      "questionNumber": "1",
      "questions": [
        {
          "questionNumber": "a",
          "text": "Why does the narrator return to the village?",
          "marks": 1.0,
          "modelAnswer": {
            "stepMarking": [
              {
                "marksplit": 1,
                "step_wise_answer": "He returns to look after his grandmother."
              }
            ],
            "rubric": null
          },
          "answer": {
            "id": "741cd09f-543f-460e-9b6e-826cf2809cb1",
            "text": "He goes back because his grandmother is ill and alone.",
            "marks": 1.0,
            "feedbacks": [
              {
                "feedback": "You identified the reason and used your own words.",
                "justification": "The answer matches the model answer's step.",
                "marks_deducted": "0",
                "room_for_improvement": "Quote a line from the passage."
              }
            ],
            "holistic_evaluation": []
          }
        }
      ]
    }
  ]
}

For an audio answer, answer.text is the transcript, answer.marks stays 0, and the score is in answer.holistic_evaluation:

{
  "text": "The place I love most is my grandmother's village ...",
  "marks": 0.0,
  "feedbacks": [],
  "holistic_evaluation": {
    "evaluation": [
      {
        "category": "Confidence and fluency in speaking",
        "score": 4,
        "max_score": 5,
        "feedback": {
          "summary": "Clear and steady delivery with few pauses.",
          "strength": "Held a steady pace for the full two minutes.",
          "improvement": "Vary your tone to hold the listener's attention."
        },
        "confidence_flags": []
      }
    ],
    "marks": 4,
    "max_marks": 5,
    "overall_feedback": "A confident answer. Add one or two examples.",
    "wpm": 104.5
  }
}

Both examples are trimmed. The response has no obtained total, so add up answer.marks, or read holistic_evaluation.marks, yourself.

Good to know

Limits

Limit	Value
File types	PDF, JPEG, PNG
File size	20 MB per file
PDF length	50 pages, and one PDF per assignment or answer sheet
Mixing	Send either one PDF or a set of images, never both. Some mixed uploads are rejected and others are accepted without an error, so keep the two apart in your own code.
Audio	One public HTTPS `.mp3` link per answer sheet, within a maximum length set for your account
Question extraction	A daily limit per API user. Over it, `PATCH` on the assignment returns `400`.
Answer sheets from documents	A daily limit per API user. Over it, `isFinal` returns `429`.
Answer sheets from audio	A limit per account inside a fixed time window. Over it, `isFinal` returns `429`.
Repeats	One model answer sheet per assignment, and one evaluation per answer sheet

Daily limits reset shortly after midnight, server time, and every request counts, including rejected ones.

Use webhooks instead of polling

Step	Event
2. Question paper	`assignment_evaluation_question_paper_extraction`
3. Answer key or rubric	`assignment_evaluation_model_answer_extraction`
5. Student’s answer	`assignment_evaluation_student_answer_sheet_evaluation`

Assignment payloads name the event in webhook_name, not name, and carry assignment_id plus model_answer_sheet_id or ans_sheet_id. Check status for Completed or Failed.

Troubleshooting

Error	Fix
`403` `Authentication credentials were not provided.`	Send the `Authorization: Bearer` header. This API answers `403`, not `401`.
An empty or redirected `PATCH`	Add the trailing slash to the path
The call fails after sending `isFinal`	Send `isFinal` as the text `true`, not a JSON boolean
`Only one of documents or isFinal can be processed at a time`	Upload first, then send `isFinal` in a separate call
`Assignment is not extracted yet`	Wait until the assignment’s `status` is `2`
`Model answer sheet is not extracted yet`	Wait until the model answer sheet’s `status` is `2`
`Cannot mix PDF files with image files`	Put the PDF on its own assignment or answer sheet
`Blurred image, Please try to capture the image again`	Photograph the page again in better light. The same message comes back when the readability check cannot be completed, so if a clear file keeps failing, retry in a few minutes.
`Only .mp3 files are allowed.`	Use a plain `.mp3` URL with no query string after it
`URL is not publicly accessible.`	Host the MP3 where it opens without a login
`Rubric not found for audio evaluation`	Attach a `rubricId` to the model answer sheet
`429 Rate limit exceeded`	Wait for the limit to reset, then send `isFinal` again
`status` is `3` (Failed)	Upload a clearer file and start that step again on a new assignment or answer sheet
Still `1` (In Progress) after 10 minutes	Start again and contact us with the assignment ID

Messages arrive as error.message.non_field_errors, or keyed by field name when a field is invalid. See Errors for the full format and a helper that reads any message.

Assignment API reference

Every field, response, and error.

What teachers use it for

The classroom problem this solves.

Get started

Guides

Exam Evaluation

Assignment Evaluation

Rubrics

Action Plans

Lesson Plan Builder

Worksheet Builder

ClassTrack

Metadata

Webhooks

Evaluate an assignment with the API

Set up

Step 1: Create the assignment

Step 2: Upload the question paper

Step 3: Add the answer key or a rubric

Step 4: Create an answer sheet for the student

Step 5: Submit the student’s answer

Step 6: Get the score

Good to know

Assignment API reference

What teachers use it for

​Set up

​Step 1: Create the assignment

​Step 2: Upload the question paper

​Step 3: Add the answer key or a rubric

​Step 4: Create an answer sheet for the student

​Step 5: Submit the student’s answer

​Step 6: Get the score

​Good to know

​Related

Assignment API reference

What teachers use it for

Set up

Step 1: Create the assignment

Step 2: Upload the question paper

Step 3: Add the answer key or a rubric

Step 4: Create an answer sheet for the student

Step 5: Submit the student’s answer

Step 6: Get the score

Good to know

Related