Question generation flow

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

Presets

Presets allow you to pre-configure certain options for the embed session, so that when your users open the embed, they see a tailored experience. None of these fields are required — if you do not provide any presets, the user will see the default options when they open the embed.

Key	Type	Description
`subject`	string	The subject of the question. Plain text.
`studentLevel`	string	The difficulty level of the question. Expects a student level ID from `/student-levels`.
`language`	string	The language code for the question (e.g. "en" for English). Defaults to the user's locale.
`context`	string	Additional context or instructions for the question generation. Plain text.
`sourceMaterialIds`	string[]	An array of source material IDs to pre-select for the question.
`questionType`	string	Specify the ID of a question type to generate. Will hide the question type selector in the UI.
`hideSubject`	boolean	Whether to hide the subject field in the question generation UI. Defaults to `false`.
`hideStudentLevel`	boolean	Whether to hide the student level field in the question generation UI. Defaults to `false`.
`outputFormat`	string	Specify the output format for the generated question. Can be either `examplary_json`, `qti_v2p1`, `qti_v3p0`. Defaults to `examplary_json`. When set to a QTI format, `outputs.question` will be an XML string instead of a JSON object.

Example

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 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.

You can either specify a returnUrl or an allowedOrigin, based on how you want to be notified when generation is completed.

POST /embed-sessions

{
  "flow": "generate-question",
  "actor": "user_423r9j3r0jeddJA...",
  "presets": {
    "subject": "Mathematics"
  },
  "theme": {
    "primaryColor": "#4f46e5",
    "locale": "en"
  },
  "metadata": {
    "myUniqueIdentifier": "abc1234"
  },
  "returnUrl": "https://app.example.com",
  "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": "generate-question",
  "actor": "user_423r9j3r0jeddJA...",
  "enabledResponseModes": ["return_url", "post_message"],
  "createdAt": "2025-12-09T16:52:52.120Z",
  "expiresAt": "2025-12-16T16:52:52.120Z",
  "presets": {
    "subject": "Mathematics"
  },
  "outputs": {},
  "theme": {
    "primaryColor": "#4f46e5",
    "locale": "en"
  },
  "metadata": {
    "myUniqueIdentifier": "abc1234"
  }
}

3. 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") {
    if (status === "completed") {
      const question = outputs.question;
      console.log("Question generation completed! Question:", question);
    } else if (status === "cancelled") {
      console.log("Question generation was cancelled by the user.");
    }
  }
});

If you're using redirects, you can expect a redirect to your specified returnUrl with one of two query string parameters values:

On success: ?status=completed&question=...
On failure: ?status=cancelled

If neither of these options work for you, you may also poll the Examplary API for status updates:

GET /embed-sessions/{id}

{
  "id": "embed_session_55S843D7HfNfs9RY48PoTprXnRcz2...",
  "flow": "generate-question",
  "status": "completed",
  "outputs": {
    "question": "..."
  }
  // ...
}

outputs.question is a JSON object when using the default examplary_json format, or an XML string when using qti_v2p1 or qti_v3p0.

4. Cleanup

The embed session will expire automatically after 7 days, but because it gives some limited access to your account, you might want to remove it manually:

DELETE /embed-sessions/{embedSessionId}