Practice space (student) flow

Using the Examplary AI practice space student flow, you can embed the full student-facing practice experience for an existing practice space directly into your application. From within the embed, your users get the practice space landing screen (with topic progress, teacher notes, and the "start practicing" call to action) and the question-by-question player that runs inside a practice session.

This flow is intended for ongoing, open-ended use: students return to the embed as often as they want and there is no specific "completion" event. Each answer is persisted in real time, and you can read back the student's progress from the API at any time.

Presets

Example

1. Create an Examplary user for your student

Each student needs an Examplary user account in your workspace. This is how we attribute progress, sessions, and proficiency to the individual student.

{
  "email": "my-student@example.com",
  "name": "My Student"
}

Store the returned user ID in your system — you'll use it as the actor for the student's embed sessions, and the same ID will also identify the student inside the practice space.

2. Make sure a practice space exists and the actor can participate

The practice space student flow operates on an existing practice space. If you don't have one yet, create it first (API reference). Practice spaces are typically created by a teacher / admin user in your workspace, not by the student themselves.

The student user needs at least the participant role on the space, otherwise they won't be able to load it inside the embed:

{
  "name": "Algebra practice",
  "studentNotes": "Work through each topic at your own pace. Ask your teacher if you get stuck!",
  "sourceMaterialIds": ["mat_abc123"],
  "masteryTopics": [
    { "id": "linear-equations", "name": "Linear equations" },
    { "id": "quadratic-equations", "name": "Quadratic equations" },
    { "id": "polynomials", "name": "Polynomials" }
  ],
  "settings": {
    "showTopicProgress": true,
    "allowCustomPrompt": true
  },
  "permissions": [
    {
      "actor": "ACTOR_USER_ID",
      "role": "participant"
    }
  ],
  "metadata": {
    "my_service_internal_id": "abc1234"
  }
}

The studentNotes field is optional. When set, it appears as "teacher notes" on the practice space landing screen inside the embed — a good place to leave guidance or context for your students.

The sourceMaterialIds field specifies which source materials the practice space generates questions from. Without source materials, no questions will be generated for students to practice with.

The masteryTopics field is optional. It is an array of objects with id (any unique string you choose) and name (displayed to students) fields, defining the topics available for practice. If omitted, topics are automatically generated from the practice space name and attached source materials — this happens asynchronously and may take a moment after creation.

You can grant participant access to multiple students on the same practice space — each will get their own progress, sessions, and proficiency tracking when they open the embed under their own actor ID.

Available settings

3. Create an embed session

Call the Examplary API to create a new embed session for the practice-space-student flow. The only required preset is practiceSpaceId — the ID of the practice space to open.

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

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

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

4. Lead the student to the embed URL

You can either redirect the student directly to the URL, or display it in an iframe. Embedding inside an iframe is usually preferable so the student stays inside your application's navigation.

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

5. Read back student progress

Retrieve a student's progress at any time using the practice space students endpoint (API reference):

GET /practice-spaces/{practiceSpaceId}/students/{userId}

The userId is the Examplary user ID of the student. The response includes their topic progress, session count, and total questions answered.