Edit exam flow

Using the Examplary AI edit exam flow, you can embed the full exam editor — including the questions list, the inline question editor, and the AI-powered "add question" composer — directly into your application. This is useful when you want users to refine an exam that was previously generated (for example via the exam generation flow) without sending them out to the Examplary dashboard.

Unlike the generation flows, the edit exam flow does not have a defined "completion" event: users keep editing for as long as the embed is open, and every change is persisted in real time to the underlying exam. When you no longer need the embed, simply close the iframe and (optionally) revoke the session.

Presets

Example

1. Create an Examplary user for your user

To make sure we can save personal preferences and changes to the user's 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.

{
  "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. Make sure an exam exists and the actor can edit it

The edit exam flow operates on an existing exam. If you don't have one yet, create it first (API reference) — and make sure to give the actor user editor (or higher) permissions on the exam, otherwise they won't be able to make changes from within the embed:

{
  "name": "Midterm Exam - Algebra",
  "subject": "Mathematics",
  "studentLevel": "us_high_school_lower",
  "questions": [
    // ...
  ],
  "permissions": [
    {
      "actor": "ACTOR_USER_ID",
      "role": "editor"
    }
  ],
  "metadata": {
    "my_service_internal_id": "abc1234"
  }
}

If you're feeding the embed an exam that was just produced by the exam generation flow, you can pass the exam ID returned in its outputs straight through.

3. Create an embed session

Call the Examplary API to create a new embed session for the edit-exam flow. The only required preset is examId — the ID of the exam to load in the editor.

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

Specify an allowedOrigin if you want to listen for postMessage updates from the iframe.

{
  "flow": "edit-exam",
  "actor": "user_423r9j3r0jeddJA...",
  "presets": {
    "examId": "exam_55S843D7HfNfs9RY48..."
  },
  "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": "edit-exam",
  "actor": "user_423r9j3r0jeddJA...",
  "enabledResponseModes": ["post_message"],
  "createdAt": "2025-12-09T16:52:52.120Z",
  "expiresAt": "2025-12-16T16:52:52.120Z",
  "presets": {
    "examId": "exam_55S843D7HfNfs9RY48..."
  },
  "outputs": {},
  "theme": {
    "primaryColor": "#4f46e5",
    "locale": "en"
  },
  "metadata": {
    "my_service_internal_id": "abc1234"
  }
}

4. 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 is usually the better experience, especially when displayed as a modal or side panel.

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