Developer quickstart

This guide shows how to quickly get started with creating exams, adding questions, importing student answers, and receiving auto-grading results in Examplary.

Step 1: Create an exam

Exams are our container for all answers and grading. Create one in all cases, even when grading just a single question. This allows you to specify source materials and other context that is needed to accurately grade the answers.

Use the Create exam endpoint to create the exam you want to grade in Examplary:

{
  "name": "Book review",
  "subject": "English Literature",
  "studentLevel": "us_undergraduate"
}

Step 2: Add questions

You can either add questions in Examplary-format, or import QTI questions (either from XML or from a .zip IMS package).

[
  {
    "externalId": "my_question_1",
    "type": "single-line-text",
    "title": "What is the meaning of life?",
    "description": "Give a short answer to the ultimate question.",
    "settings": {},
    "scoring": {
      "rubricType": "analytical",
      "criteria": [
        {
          "id": "c1",
          "title": "Correctness",
          "levels": [
            {
              "id": "c1l1",
              "title": "Incomplete",
              "description": "Does not mention the number 42 or the Hitchhiker's Guide to the Galaxy.",
              "points": 0
            },
            {
              "id": "c1l2",
              "title": "Partially correct",
              "points": 0.5,
              "description": "Mentions the number 42 but not the Hitchhiker's Guide to the Galaxy."
            },
            {
              "id": "c1l3",
              "title": "Correct",
              "points": 1,
              "description": "Mentions the number 42 and the Hitchhiker's Guide to the Galaxy."
            }
          ]
        }
      ]
    }
  }
]

Optionally, further calibrate the AI grading by uploading previously scored answers.

Step 3: Import answers

After adding the questions, we can start importing student answers. The API refers to these as 'assessment sessions'.

{
  "externalId": "my_student_1",
  "studentName": "John Doe",
  "answers": [
    {
      "question": "my_question_1",
      "value": "42"
    }
  ],
  "autoGrade": true
}

This endpoint also accepts an array of assessment sessions, allowing you to import multiple students' answers in a single request. You can reference questions both by their ID or by their externalId.

Step 4: Receive auto-grading results

By setting autoGrade to true in the assessment session request, the system will automatically start grading the submitted answers.

To retrieve the results, you can either poll the assessment sessions endpoint or use a webhook to receive real-time updates.

{
  "url": "https://example.com/webhook",
  "events": [
    "exam.session.grading.completed"
  ],
  "resources": [
    "{examId}"
  ]
}