Grading as an API call

curl -X POST https://agent.proctorai.io/api/v1/grade \
  -H "Authorization: Bearer pai_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sheet-01-2026-10-27" \
  -d '{
    "title": "Physics unit test",
    "level": "High School",
    "instructions": "Award method marks even when the final answer is wrong.",
    "questions": [
      {
        "id": "q1",
        "prompt": "State Newton's second law and give its SI unit.",
        "maxMarks": 2,
        "expectedAnswer": "F = ma. Force is measured in newtons (N)."
      },
      {
        "id": "q2",
        "prompt": "A 4 kg mass accelerates at 3 m/s². Find the force.",
        "maxMarks": 3,
        "expectedAnswer": "F = 4 × 3 = 12 N"
      }
    ],
    "pages": ["https://example.com/scans/sheet-01-page-1.jpg"]
  }'

const res = await fetch("https://agent.proctorai.io/api/v1/grade", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PROCTOR_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "sheet-01-2026-10-27",
  },
  body: JSON.stringify({
    "title": "Physics unit test",
    "level": "High School",
    "instructions": "Award method marks even when the final answer is wrong.",
    "questions": [
      {
        "id": "q1",
        "prompt": "State Newton's second law and give its SI unit.",
        "maxMarks": 2,
        "expectedAnswer": "F = ma. Force is measured in newtons (N)."
      },
      {
        "id": "q2",
        "prompt": "A 4 kg mass accelerates at 3 m/s². Find the force.",
        "maxMarks": 3,
        "expectedAnswer": "F = 4 × 3 = 12 N"
      }
    ],
    "pages": ["https://example.com/scans/sheet-01-page-1.jpg"]
  }),
});

if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error}`);
const result = await res.json();
console.log(result.marks);            // { earned: 4, max: 5, percentage: 80 }
for (const q of result.questions) {
  console.log(q.questionId, q.earned, "/", q.max, q.needsReview ? "(check)" : "");
}

import os, requests

body = {
  "title": "Physics unit test",
  "level": "High School",
  "instructions": "Award method marks even when the final answer is wrong.",
  "questions": [
    {
      "id": "q1",
      "prompt": "State Newton's second law and give its SI unit.",
      "maxMarks": 2,
      "expectedAnswer": "F = ma. Force is measured in newtons (N)."
    },
    {
      "id": "q2",
      "prompt": "A 4 kg mass accelerates at 3 m/s². Find the force.",
      "maxMarks": 3,
      "expectedAnswer": "F = 4 × 3 = 12 N"
    }
  ],
  "pages": ["https://example.com/scans/sheet-01-page-1.jpg"]
}

res = requests.post(
    "https://agent.proctorai.io/api/v1/grade",
    headers={
        "Authorization": f"Bearer {os.environ['PROCTOR_API_KEY']}",
        "Idempotency-Key": "sheet-01-2026-10-27",
    },
    json=body,
    timeout=120,
)
res.raise_for_status()
result = res.json()
print(result["marks"])
for q in result["questions"]:
    print(q["questionId"], q["earned"], "/", q["max"], "(check)" if q["needsReview"] else "")

{
  "id": "grd_6718f0c2a1b9e4d3f2a1b0c9",
  "studentName": "Priya Menon",
  "rollNumber": "02",
  "marks": { "earned": 4, "max": 5, "percentage": 80 },
  "questions": [
    {
      "questionId": "q1",
      "label": "Q1",
      "earned": 2,
      "max": 2,
      "status": "answered",
      "feedback": "Law stated correctly with the unit.",
      "reasoning": "+1 F = ma stated; +1 newton given as the SI unit",
      "studentAnswer": "Force equals mass times acceleration, measured in newtons.",
      "pages": [1],
      "confidence": 0.94,
      "needsReview": false
    },
    {
      "questionId": "q2",
      "label": "Q2",
      "earned": 2,
      "max": 3,
      "status": "answered",
      "feedback": "Method correct; the final value was written as 7 N.",
      "reasoning": "+1 formula; +1 substitution; -1 arithmetic slip",
      "studentAnswer": "F = 4 × 3 = 7 N",
      "pages": [1],
      "confidence": 0.71,
      "needsReview": true,
      "reviewReason": "Working and final answer disagree"
    }
  ],
  "strengths": ["Knows the law and its unit"],
  "improvements": ["Check arithmetic before writing the final value"],
  "overallFeedback": "Solid understanding; one careless slip.",
  "pageCount": 1,
  "billing": { "gradingsCharged": 0.4, "balance": 199.6 }
}

# 1. Ask for an upload slot
curl -X POST https://agent.proctorai.io/api/v1/uploads \
  -H "Authorization: Bearer pai_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"contentType":"application/pdf","size":2381904,"name":"sheet-01.pdf"}]}'
# -> { "uploads": [{ "uploadId": "upl_...", "method": "PUT", "url": "...", "headers": {...}, "expiresAt": "..." }], "retainedUntil": "..." }

# 2. Send the file to the signed URL exactly as returned
curl -X PUT "<url from step 1>" -H "Content-Type: application/pdf" --data-binary @sheet-01.pdf

# 3. Grade with the upload id instead of pages
curl -X POST https://agent.proctorai.io/api/v1/grade \
  -H "Authorization: Bearer pai_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"questions":[{"id":"q1","prompt":"...","maxMarks":2}],"files":[{"uploadId":"upl_..."}]}'

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

const headers = { Authorization: `Bearer ${process.env.PROCTOR_API_KEY}`, "Content-Type": "application/json" };
const pdf = await readFile("sheet-01.pdf");

// 1. Ask for an upload slot
const slot = await fetch("https://agent.proctorai.io/api/v1/uploads", {
  method: "POST",
  headers,
  body: JSON.stringify({ files: [{ contentType: "application/pdf", size: pdf.byteLength, name: "sheet-01.pdf" }] }),
}).then((r) => r.json());
const [upload] = slot.uploads;

// 2. PUT the bytes to the signed URL with the headers it asks for
await fetch(upload.url, { method: upload.method, headers: upload.headers, body: pdf });

// 3. Grade by upload id
const result = await fetch("https://agent.proctorai.io/api/v1/grade", {
  method: "POST",
  headers,
  body: JSON.stringify({ questions, files: [{ uploadId: upload.uploadId }] }),
}).then((r) => r.json());

import os, requests

headers = {"Authorization": f"Bearer {os.environ['PROCTOR_API_KEY']}"}
pdf = open("sheet-01.pdf", "rb").read()

# 1. Ask for an upload slot
slot = requests.post(
    "https://agent.proctorai.io/api/v1/uploads",
    headers=headers,
    json={"files": [{"contentType": "application/pdf", "size": len(pdf), "name": "sheet-01.pdf"}]},
).json()
upload = slot["uploads"][0]

# 2. PUT the bytes to the signed URL with the headers it asks for
requests.put(upload["url"], headers=upload["headers"], data=pdf).raise_for_status()

# 3. Grade by upload id
result = requests.post(
    "https://agent.proctorai.io/api/v1/grade",
    headers=headers,
    json={"questions": questions, "files": [{"uploadId": upload["uploadId"]}]},
    timeout=120,
).json()