Mark answer flow

Using the Examplary AI mark answer flow, you can let users of your application use AI to mark a single answer on a specific subject or a set of source materials.

1. Create an Examplary user for your user

To make sure we can save personal preferences and source materials uploaded by the user to their specific account, and can later allow them to reference these personal details, we require creating a user account in your workspace for each of your users.

POST /users

{
  "email": "my-user@example.com",
  "name": "My User"
}

Store the returned user ID in your system to use with any future embed sessions for that user.

2. Create an exam

Before you can use the mark answer flow, you need to have an exam and assessment session that the user can reference when marking their answer.

Let's first create the exam (API reference):

POST /exams

{
  "name": "Book review",
  "subject": "English Literature",
  "studentLevel": "us_undergraduate",
  "questions": [
    {
      "type": "single-line-text",
      "title": "What is the meaning of life?",
      "description": "Give a short answer to the ultimate question.",
      "settings": {},
      "metadata": {
        "my_service_internal_id": "question_1234"
      },
      "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."
              }
            ]
          }
        ]
      }
    }
  ],
  // This is important, as the user needs to have access to the exam to be able to mark it:
  "permissions": [
    {
      "actor": "ACTOR_USER_ID",
      "role": "editor"
    }
  ],
  "metadata": {
    "my_service_internal_id": "abc1234"
  }
}

3. Add an assessment session

Next, you'll want to import answers for a specific student, so they can be reviewed (API reference):

POST /exams/EXAM_ID/sessions

{
  "studentName": "John Doe",
  "answers": [
    {
      "question": "QUESTION_ID_FROM_RESPONSE_ABOVE",
      "value": "42",
      "completed": true, // indicating the student has completed this answer, and it's ready for marking
    }
  ]
}

4. Create an embed session

Call the Examplary API to create a new embed session. You can configure presets for the question, as well as theme options.

The actor field should contain the ID of the Examplary user account you created for this customer.

Specify an allowedOrigin to receive postMessage updates as the user interacts with the marking UI.

POST /embed-sessions

{
  "flow": "mark-answer",
  "actor": "user_423r9j3r0jeddJA...",
  "presets": {
    "examId": "EXAM_ID",
    "sessionId": "ASSESSMENT_SESSION_ID",
    "questionId": "QUESTION_ID_FROM_RESPONSE_ABOVE"
  },
  "theme": {
    "primaryColor": "#4f46e5",
    "locale": "en"
  },
  "metadata": {
    "my_service_internal_id": "abc1234"
  },
  "allowedOrigin": "https://app.example.com"
}

This returns a response that looks like this:

{
  "id": "embed_session_55S843D7HfNfs9RY48PoTprXnRcz2Vw8Crst64UYrBnz...",
  "status": "pending",
  "embedUrl": "https://app.examplary.ai/embeds/55S843D7HfNf...",
  "flow": "mark-answer",
  "enabledResponseModes": ["post_message"],
  // ...
}

5. Lead the user to the embed URL

You can either redirect the user directly to the URL, or display it in an iframe.

The latter might be better for the user experience, especially when displayed as a modal. This also allows you to listen to status updates in real time, through the postMessage() API.

const embedUrl = "https://app.examplary.ai/embeds/55S843D7HfNf...";

iframe.src = embedUrl;

window.addEventListener("message", (event) => {
  // Make sure the message is coming from a trusted origin
  if (event.origin !== new URL(embedUrl).origin) return;

  // Handle the message
  const { type, status, outputs } = event.data;
  if (type === "examplary:embed-status-update") {
    console.log("Marked answer update:", outputs);
  }
});