Quickstart

curl https://api.evalezy.com/v1/exams \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-exam-cbse-10b-sci-ut2-2026" \
  -d '{
    "title": "Class 10 Science - Unit Test 2 (Light)",
    "mode": "typed",
    "external_ref": "cbse-10b-sci-ut2-2026",
    "subject": "Science",
    "board": "CBSE",
    "class": "10",
    "level": "school",
    "open": true,
    "questions": [
      {
        "label": "1",
        "type": "mcq_single",
        "text": "Which colour of sunlight is scattered the most by the molecules of air?",
        "max_marks": 1,
        "options": [
          { "label": "A", "text": "Red" },
          { "label": "B", "text": "Yellow" },
          { "label": "C", "text": "Blue" },
          { "label": "D", "text": "Orange" }
        ],
        "correct_options": ["C"]
      },
      {
        "label": "2",
        "type": "long_answer",
        "text": "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
        "max_marks": 3,
        "word_limit": 80,
        "rubric": {
          "criteria": [
            {
              "name": "Scattering by air molecules",
              "marks": 1,
              "keywords": ["scattering", "air molecules"],
              "guidance": "States that sunlight is scattered by the tiny molecules of air in the atmosphere."
            },
            {
              "name": "Wavelength dependence",
              "marks": 1,
              "guidance": "Shorter wavelengths such as blue are scattered much more strongly than longer wavelengths such as red."
            },
            {
              "name": "Link to the colour seen",
              "marks": 1,
              "guidance": "Connects the scattered blue light reaching the eye from all directions to the blue colour of the sky."
            }
          ]
        }
      }
    ]
  }'

exam_body = {
    "title": "Class 10 Science - Unit Test 2 (Light)",
    "mode": "typed",
    "external_ref": "cbse-10b-sci-ut2-2026",
    "subject": "Science",
    "board": "CBSE",
    "class": "10",
    "level": "school",
    "open": True,
    "questions": [
        {
            "label": "1",
            "type": "mcq_single",
            "text": "Which colour of sunlight is scattered the most by the molecules of air?",
            "max_marks": 1,
            "options": [
                {"label": "A", "text": "Red"},
                {"label": "B", "text": "Yellow"},
                {"label": "C", "text": "Blue"},
                {"label": "D", "text": "Orange"},
            ],
            "correct_options": ["C"],
        },
        {
            "label": "2",
            "type": "long_answer",
            "text": "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
            "max_marks": 3,
            "word_limit": 80,
            "rubric": {
                "criteria": [
                    {
                        "name": "Scattering by air molecules",
                        "marks": 1,
                        "keywords": ["scattering", "air molecules"],
                        "guidance": "States that sunlight is scattered by the tiny molecules of air in the atmosphere.",
                    },
                    {
                        "name": "Wavelength dependence",
                        "marks": 1,
                        "guidance": "Shorter wavelengths such as blue are scattered much more strongly than longer wavelengths such as red.",
                    },
                    {
                        "name": "Link to the colour seen",
                        "marks": 1,
                        "guidance": "Connects the scattered blue light reaching the eye from all directions to the blue colour of the sky.",
                    },
                ]
            },
        },
    ],
}

r = session.post(
    f"{BASE}/exams",
    json=exam_body,
    headers={"Idempotency-Key": "create-exam-cbse-10b-sci-ut2-2026"},
)
r.raise_for_status()
exam = r.json()
exam_id = exam["id"]
print(exam_id, exam["status"])  # ... open

const examBody = {
  title: "Class 10 Science - Unit Test 2 (Light)",
  mode: "typed",
  external_ref: "cbse-10b-sci-ut2-2026",
  subject: "Science",
  board: "CBSE",
  class: "10",
  level: "school",
  open: true,
  questions: [
    {
      label: "1",
      type: "mcq_single",
      text: "Which colour of sunlight is scattered the most by the molecules of air?",
      max_marks: 1,
      options: [
        { label: "A", text: "Red" },
        { label: "B", text: "Yellow" },
        { label: "C", text: "Blue" },
        { label: "D", text: "Orange" },
      ],
      correct_options: ["C"],
    },
    {
      label: "2",
      type: "long_answer",
      text: "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
      max_marks: 3,
      word_limit: 80,
      rubric: {
        criteria: [
          {
            name: "Scattering by air molecules",
            marks: 1,
            keywords: ["scattering", "air molecules"],
            guidance: "States that sunlight is scattered by the tiny molecules of air in the atmosphere.",
          },
          {
            name: "Wavelength dependence",
            marks: 1,
            guidance: "Shorter wavelengths such as blue are scattered much more strongly than longer wavelengths such as red.",
          },
          {
            name: "Link to the colour seen",
            marks: 1,
            guidance: "Connects the scattered blue light reaching the eye from all directions to the blue colour of the sky.",
          },
        ],
      },
    },
  ],
};

const examRes = await fetch(`${BASE}/exams`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "create-exam-cbse-10b-sci-ut2-2026" },
  body: JSON.stringify(examBody),
});
if (!examRes.ok) throw new Error(`HTTP ${examRes.status}: ${await examRes.text()}`);
const exam = await examRes.json();
const examId = exam.id;
console.log(examId, exam.status); // ... open

curl https://api.evalezy.com/v1/exams/$EXAM_ID/submissions \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submit-cbse-10b-sci-ut2-2026-STU-2026-0142" \
  -d '{
    "candidate": {
      "external_id": "STU-2026-0142",
      "name": "Aarav Sharma",
      "roll_number": "17",
      "section_or_class": "10-B"
    },
    "answers": [
      { "question_label": "1", "option_labels": ["C"] },
      {
        "question_label": "2",
        "text": "Sunlight is made of many colours. When it enters the atmosphere it is scattered by the very small molecules of air. Blue light has a shorter wavelength than red light, so it is scattered much more. This scattered blue light reaches our eyes from every part of the sky, so the sky looks blue."
      }
    ]
  }'

submission_body = {
    "candidate": {
        "external_id": "STU-2026-0142",
        "name": "Aarav Sharma",
        "roll_number": "17",
        "section_or_class": "10-B",
    },
    "answers": [
        {"question_label": "1", "option_labels": ["C"]},
        {
            "question_label": "2",
            "text": (
                "Sunlight is made of many colours. When it enters the atmosphere it is "
                "scattered by the very small molecules of air. Blue light has a shorter "
                "wavelength than red light, so it is scattered much more. This scattered "
                "blue light reaches our eyes from every part of the sky, so the sky looks blue."
            ),
        },
    ],
}

r = session.post(
    f"{BASE}/exams/{exam_id}/submissions",
    json=submission_body,
    headers={"Idempotency-Key": "submit-cbse-10b-sci-ut2-2026-STU-2026-0142"},
)
r.raise_for_status()
submission = r.json()
submission_id = submission["id"]
print(submission_id, submission["status"], submission["quote"])

const submissionBody = {
  candidate: {
    external_id: "STU-2026-0142",
    name: "Aarav Sharma",
    roll_number: "17",
    section_or_class: "10-B",
  },
  answers: [
    { question_label: "1", option_labels: ["C"] },
    {
      question_label: "2",
      text:
        "Sunlight is made of many colours. When it enters the atmosphere it is " +
        "scattered by the very small molecules of air. Blue light has a shorter " +
        "wavelength than red light, so it is scattered much more. This scattered " +
        "blue light reaches our eyes from every part of the sky, so the sky looks blue.",
    },
  ],
};

const subRes = await fetch(`${BASE}/exams/${examId}/submissions`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "submit-cbse-10b-sci-ut2-2026-STU-2026-0142" },
  body: JSON.stringify(submissionBody),
});
if (!subRes.ok) throw new Error(`HTTP ${subRes.status}: ${await subRes.text()}`);
const submission = await subRes.json();
const submissionId = submission.id;
console.log(submissionId, submission.status, submission.quote);

curl https://api.evalezy.com/v1/submissions/$SUBMISSION_ID \
  -H "X-API-Key: $EVALEZY_API_KEY"

import time

DONE = {"graded", "partially_graded", "failed", "cancelled"}

while True:
    r = session.get(f"{BASE}/submissions/{submission_id}")
    r.raise_for_status()
    status = r.json()["status"]
    print("status:", status)
    if status in DONE:
        break
    time.sleep(5)

const DONE = new Set(["graded", "partially_graded", "failed", "cancelled"]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

let status;
do {
  const res = await fetch(`${BASE}/submissions/${submissionId}`, { headers });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  status = (await res.json()).status;
  console.log("status:", status);
  if (!DONE.has(status)) await sleep(5000);
} while (!DONE.has(status));

curl https://api.evalezy.com/v1/submissions/$SUBMISSION_ID/result \
  -H "X-API-Key: $EVALEZY_API_KEY"

r = session.get(f"{BASE}/submissions/{submission_id}/result")
r.raise_for_status()
result = r.json()

print("Total:", result["totals"]["awarded"], "/", result["totals"]["max"])
for q in result["questions"]:
    print(q["label"], q["awarded"], "/", q["max"], "needs review:", q["needs_review"])
    for c in q["criteria"]:
        print("   -", c["name"], c["awarded"], "/", c["max"], ":", c["reason"])

const resultRes = await fetch(`${BASE}/submissions/${submissionId}/result`, { headers });
if (!resultRes.ok) throw new Error(`HTTP ${resultRes.status}: ${await resultRes.text()}`);
const result = await resultRes.json();

console.log("Total:", result.totals.awarded, "/", result.totals.max);
for (const q of result.questions) {
  console.log(q.label, q.awarded, "/", q.max, "needs review:", q.needs_review);
  for (const c of q.criteria) {
    console.log("   -", c.name, c.awarded, "/", c.max, ":", c.reason);
  }
}

curl https://api.evalezy.com/v1/exams/$EXAM_ID/finalize \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: finalize-cbse-10b-sci-ut2-2026-STU-2026-0142" \
  -d '{ "submission_ids": ["'"$SUBMISSION_ID"'"] }'

r = session.post(
    f"{BASE}/exams/{exam_id}/finalize",
    json={"submission_ids": [submission_id]},
    headers={"Idempotency-Key": "finalize-cbse-10b-sci-ut2-2026-STU-2026-0142"},
)
r.raise_for_status()
print(r.json())

const finRes = await fetch(`${BASE}/exams/${examId}/finalize`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "finalize-cbse-10b-sci-ut2-2026-STU-2026-0142" },
  body: JSON.stringify({ submission_ids: [submissionId] }),
});
if (!finRes.ok) throw new Error(`HTTP ${finRes.status}: ${await finRes.text()}`);
console.log(await finRes.json());

curl https://api.evalezy.com/v1/exams \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-exam-cbse-10b-sci-hw-2026" \
  -d '{
    "title": "Class 10 Science - Unit Test 2 (Light), answer sheet",
    "mode": "handwritten",
    "external_ref": "cbse-10b-sci-hw-2026",
    "open": true,
    "questions": [
      {
        "label": "1",
        "type": "long_answer",
        "text": "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
        "max_marks": 3,
        "model_answer": "Sunlight is scattered by the tiny molecules of air. Blue light has a shorter wavelength than red, so it is scattered much more, and this scattered blue light reaches our eyes from all over the sky."
      }
    ]
  }'

export HW_EXAM_ID=5e0d7a3b-...   # the "id" from the response

hw_exam = session.post(
    f"{BASE}/exams",
    json={
        "title": "Class 10 Science - Unit Test 2 (Light), answer sheet",
        "mode": "handwritten",
        "external_ref": "cbse-10b-sci-hw-2026",
        "open": True,
        "questions": [{
            "label": "1",
            "type": "long_answer",
            "text": "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
            "max_marks": 3,
            "model_answer": "Sunlight is scattered by the tiny molecules of air. Blue light has a shorter "
                            "wavelength than red, so it is scattered much more, and this scattered blue "
                            "light reaches our eyes from all over the sky.",
        }],
    },
    headers={"Idempotency-Key": "create-exam-cbse-10b-sci-hw-2026"},
)
hw_exam.raise_for_status()
hw_exam_id = hw_exam.json()["id"]

const hwExamRes = await fetch(`${BASE}/exams`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "create-exam-cbse-10b-sci-hw-2026" },
  body: JSON.stringify({
    title: "Class 10 Science - Unit Test 2 (Light), answer sheet",
    mode: "handwritten",
    external_ref: "cbse-10b-sci-hw-2026",
    open: true,
    questions: [{
      label: "1",
      type: "long_answer",
      text: "Why does the clear sky appear blue? Explain with reference to the scattering of light.",
      max_marks: 3,
      model_answer:
        "Sunlight is scattered by the tiny molecules of air. Blue light has a shorter wavelength " +
        "than red, so it is scattered much more, and this scattered blue light reaches our eyes from all over the sky.",
    }],
  }),
});
if (!hwExamRes.ok) throw new Error(`HTTP ${hwExamRes.status}: ${await hwExamRes.text()}`);
const hwExamId = (await hwExamRes.json()).id;

curl https://api.evalezy.com/v1/uploads \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "STU-2026-0142.pdf",
    "content_type": "application/pdf",
    "size_bytes": '"$(wc -c < STU-2026-0142.pdf)"'
  }'

path = "STU-2026-0142.pdf"
r = session.post(f"{BASE}/uploads", json={
    "filename": "STU-2026-0142.pdf",
    "content_type": "application/pdf",
    "size_bytes": os.path.getsize(path),
})
r.raise_for_status()
upload = r.json()["uploads"][0]

import { readFile } from "node:fs/promises";

const pdf = await readFile("STU-2026-0142.pdf");
const upRes = await fetch(`${BASE}/uploads`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filename: "STU-2026-0142.pdf",
    content_type: "application/pdf",
    size_bytes: pdf.length,
  }),
});
if (!upRes.ok) throw new Error(`HTTP ${upRes.status}: ${await upRes.text()}`);
const upload = (await upRes.json()).uploads[0];

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @STU-2026-0142.pdf

with open(path, "rb") as f:
    put = requests.put(upload["upload_url"], data=f, headers=upload["headers"])
put.raise_for_status()

const put = await fetch(upload.upload_url, {
  method: "PUT",
  headers: upload.headers,
  body: pdf,
});
if (!put.ok) throw new Error(`Upload failed: HTTP ${put.status}`);

curl https://api.evalezy.com/v1/uploads/$UPLOAD_ID \
  -H "X-API-Key: $EVALEZY_API_KEY"

while True:
    u = session.get(f"{BASE}/uploads/{upload['id']}").json()
    if u["status"] != "pending":
        break
    time.sleep(2)
print(u["status"], u["pages"], u["reject_reason"])

let u;
do {
  u = await (await fetch(`${BASE}/uploads/${upload.id}`, { headers })).json();
  if (u.status === "pending") await sleep(2000);
} while (u.status === "pending");
console.log(u.status, u.pages, u.reject_reason);

curl https://api.evalezy.com/v1/exams/$HW_EXAM_ID/submissions \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submit-cbse-10b-sci-hw-2026-STU-2026-0142" \
  -d '{
    "candidate": { "external_id": "STU-2026-0142", "name": "Aarav Sharma", "roll_number": "17" },
    "upload_id": "'"$UPLOAD_ID"'"
  }'

r = session.post(
    f"{BASE}/exams/{hw_exam_id}/submissions",
    json={
        "candidate": {"external_id": "STU-2026-0142", "name": "Aarav Sharma", "roll_number": "17"},
        "upload_id": upload["id"],
    },
    headers={"Idempotency-Key": "submit-cbse-10b-sci-hw-2026-STU-2026-0142"},
)
r.raise_for_status()
hw_submission_id = r.json()["id"]
print(r.json()["quote"])  # {'unit': 'page', 'pages': 12, 'credits': 12, ...}

const hwRes = await fetch(`${BASE}/exams/${hwExamId}/submissions`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "submit-cbse-10b-sci-hw-2026-STU-2026-0142" },
  body: JSON.stringify({
    candidate: { external_id: "STU-2026-0142", name: "Aarav Sharma", roll_number: "17" },
    upload_id: upload.id,
  }),
});
if (!hwRes.ok) throw new Error(`HTTP ${hwRes.status}: ${await hwRes.text()}`);
const hwSubmission = await hwRes.json();
console.log(hwSubmission.quote); // { unit: 'page', pages: 12, credits: 12, ... }

curl https://api.evalezy.com/v1/submissions/$HW_SUBMISSION_ID/checked-copy \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -o STU-2026-0142-checked.pdf

r = session.get(f"{BASE}/submissions/{hw_submission_id}/checked-copy")
r.raise_for_status()
with open("STU-2026-0142-checked.pdf", "wb") as f:
    f.write(r.content)

import { writeFile } from "node:fs/promises";

const cc = await fetch(`${BASE}/submissions/${hwSubmission.id}/checked-copy`, { headers });
if (!cc.ok) throw new Error(`HTTP ${cc.status}: ${await cc.text()}`);
await writeFile("STU-2026-0142-checked.pdf", Buffer.from(await cc.arrayBuffer()));