{t("itemCount", { count: itemCount })}
{t("welcomeMessage", { name: "John" })}
Hello, Tailwind!
;
}
```
Read more about [Tailwind CSS](https://tailwindcss.com/docs/styling-with-utility-classes) to learn how to
use its utility classes effectively.
## Examplary UI kit
The package `@examplary/ui` provides a set of pre-built components and styles that you can use in your
components. It is provided by the platform at runtime, for every app, so it isn't included in your bundle; you only need to install it for its types.
You can use the components from the UI kit like this:
```jsx
import React from "react";
import { RichTextField } from "@examplary/ui";
export default function MyComponent() {
return This is rich text content.
"; return{t("title")}
{avatar &&Check the console for data.
;
}
```
### Using the AI API
Public question components (i.e. `assessment` components) have the `api` object extended with an `ai.generate()` method that allows you to generate content using AI. It takes a list of messages in the standard chat format and returns the AI's response as a string.
```jsx
import { useState, useEffect } from "react";
export default function MyQuestionAssessmentComponent({ question, api }) {
const [story, setStory] = useState("");
const generateStory = async () => {
const response = await api.ai.generate({
messages: [
{
role: "system",
content:
"You are a teacher telling the student a story about a subject.",
},
{
role: "user",
content: `Tell me a story about ${question.description}.`,
},
],
});
// response is a string when no schema is provided
setStory(response);
};
useEffect(() => {
generateStory();
}, []);
return {story}
;
}
```
You can also pass a `schema` key with a [JSON Schema](https://json-schema.org/) object to receive a structured data response instead of a plain string:
```jsx
const response = await api.ai.generate({
messages: [
{
role: "user",
content: `Generate 3 quiz options for: ${question.description}`,
},
],
schema: {
type: "object",
properties: {
options: {
type: "array",
items: { type: "string" },
},
},
required: ["options"],
},
});
// response is a structured object matching the schema
console.log(response.options); // ["Option A", "Option B", "Option C"]
```
## File uploads
It's also possible to prompt the user to upload files, which will be stored in the Examplary cloud storage.
### `api.uploadFile(accept?)`
Opens a file picker dialog and uploads the selected file. Available in all component types.
The optional `accept` parameter is a string that specifies the file types to accept (e.g., `"image/*"` for all image types).
```jsx
import { useState } from "react";
export default function MyQuestionSettingsArea({ api }) {
const [fileUrl, setFileUrl] = useState("");
const handleUpload = async () => {
const { url } = await api.uploadFile("image/*");
setFileUrl(url);
};
return (
{fileUrl && 
}
);
}
```
### `api.uploadPickedFile(file)`
Uploads a `File` object that you have already obtained (e.g., from a drag-and-drop handler or a custom ``). Only available in `settings-area`, `results`, and `print` components.
```jsx
import { useState } from "react";
export default function MyQuestionSettingsArea({ api }) {
const [fileUrl, setFileUrl] = useState("");
const handleDrop = async (event) => {
event.preventDefault();
const file = event.dataTransfer.files[0];
if (file) {
const { url } = await api.uploadPickedFile(file);
setFileUrl(url);
}
};
return (
e.preventDefault()}
className="border-2 border-dashed p-8"
>
Drop a file here
{fileUrl && (
)}
);
}
```
---
// File: apps/question-types/grading
# Question grading
The Examplary platform supports two grading options for custom question types:
1. **Deterministic response processing** Best for question types that have a clearly defined correct answer, and can be graded automatically based on the submitted answer and question settings. 2. **AI-assisted grading suggestions**
Best for open-ended questions where the answer needs to be interpreted against a rubric or teacher guidance. ## Deterministic response processing For simple question types that have a clearly defined correct answer, define `responseProcessing` in its definition. The `condition` is a JSONata expression that starts with `=` and evaluates to a boolean. If it returns `true`, the answer receives the question's maximum points; if it returns `false`, the answer receives `0` points. The expression can read the submitted answer through `answer` and the question configuration through `question`. For example, `answer.value` is the user's submitted value, and `question.settings` contains the settings stored for that question. ```ts title="definition.ts (partial)" new QuestionType({ responseProcessing: { condition: "=answer.value in question.settings.possibleAnswers", testCases: [ { answer: { value: "42", }, question: { settings: { possibleAnswers: ["41", "42"], }, }, expectedOutcome: true, }, ], }, }); ``` Use `testCases` to validate the expression when you validate or publish your app (`npx @examplary/cli validate`). Grading requires the expression to evaluate to a strict boolean — any other result (a string, a number, `undefined`, and so on) fails the answer with an error instead of awarding points. The CLI coerces the outcome to a boolean before comparing it against `expectedOutcome`, so a condition that only returns a truthy/falsy non-boolean can still pass its test cases while failing for real students — make sure your condition itself resolves to `true`/`false`, not just something that looks like it. ## Exact-value matching When a teacher configures a question with the `exact-values` rubric type, the platform automatically grades submissions by comparing the student's answer against the expected values defined in the scoring criteria. No configuration in the definition is required for this to work. Setting `exactValuesCaseInsensitive: true` in the question's scoring configuration lowercases both values and strips **all** whitespace (not just leading/trailing) before comparing — so `"New York"` and `"NewYork"` would be considered a match. (Leading/trailing whitespace is always trimmed, regardless of this setting.) This is useful for fill-in-the-blank or vocabulary questions where minor formatting differences shouldn't count against a student. ## AI assisted grading suggestions The `grading` field is an object that defines the settings for AI-assisted grading. You can enable or disable this feature, and provide any additional instructions for the AI. If enabled, the platform can use AI to suggest points and feedback for the user's answer based on the provided instructions. This can be particularly useful for open-ended questions where there isn't a single correct answer. The teacher can review and adjust the AI's suggestions before finalizing the grade. ```ts title="definition.ts (partial)" new QuestionType({ grading: { enabled: true, instructions: "Grade the answer based on the provided rubric.", }, }); ``` ### Grading answers that contain files Some answers are files rather than text, like an uploaded document or a voice recording. Out of the box, the AI only sees the URL of such a file, not its contents. To let the AI read the file, add `fileInputs` to the `grading` object: a JSONata expression starting with `=` that evaluates to a file URL or an array of file URLs. Like `responseProcessing.condition`, it can read the submitted answer through `answer` and the question configuration through `question`. ```ts title="definition.ts (partial)" new QuestionType({ grading: { enabled: true, instructions: "Grade the uploaded document against the rubric.", fileInputs: "=answer.value", }, }); ``` The files are downloaded and attached to the end of the grading prompt, so the AI can read documents, images and audio recordings directly. Only files hosted on the Examplary media CDN, such as those uploaded through the [file upload API](/developers/apps/question-types/api-access), are attached; any other URL is skipped. `npx @examplary/cli validate` checks that the expression is valid JSONata. --- // File: apps/capabilities/export-options # Export options An export option adds your platform to the **Send to…** menu of a test, so teachers can send or export a test to it in a few clicks. ```mermaid flowchart LR menu[Send to…] --> options[getExportOptions] options --> dialog[Teacher picks options] dialog --> start[startExport]:::highlight start --> status[getExportStatus] status -- in progress --> status status --> done[View the result] ``` ## Defining an export option ```ts title="capabilities/export.ts" import { ExportFormat, ExportOption, ExportResourceType, ExportStatus, } from "@examplary/apps"; export default new ExportOption({ id: "acme", name: { en: "Acme Gradebook" }, icon: "./icon.svg", resourceTypes: [ExportResourceType.Exam], formats: [ExportFormat.Qti21], // Called to fetch any options the teacher can choose from // before starting the export. getExportOptions: async (settings) => { const classes = await listClasses(settings.apiToken); return [ { key: "classId", label: { en: "Class" }, type: "select", options: classes.map((c) => ({ value: c.id, label: c.name })), }, ]; }, // Called to start the export with the chosen options. startExport: async (settings, test) => { const job = await startImport(settings.apiToken, { classId: settings.classId, packageUrl: test.files.qti21!.url, }); return { status: ExportStatus.inProgress, data: { jobId: job.id } }; }, // Called to check the status of an export that's still in progress. getExportStatus: async (settings, { data }) => { const job = await getImport(settings.apiToken, data.jobId); if (job.state === "running") { return { status: ExportStatus.inProgress, data }; } if (job.state === "failed") { return { status: ExportStatus.failed, message: job.error, data }; } return { status: ExportStatus.completed, resultUrl: job.testUrl, data }; }, }); ``` Then add it to your app with `app.addCapability()`, as shown in the [introduction](/developers/apps). | Property | Description | | --------------------- | ------------------------------------------------------------------------- | | `id` | Unique within your app. | | `name` | Shown in the **Send to…** menu. | | `icon` | Path to the icon shown in the menu. | | `resourceTypes` | What can be exported. For now, only `ExportResourceType.Exam` (tests). | | `formats` | Files Examplary should prepare for `startExport`, see [below](#the-test). | | `statusCheckInterval` | How often to call `getExportStatus`, in milliseconds. Defaults to `1000`. | | `getExportOptions` | Returns the fields the teacher fills in for this export. Optional. | | `startExport` | Starts the export. Required. | | `getExportStatus` | Checks on an export that's still in progress. Optional. | ## Export options `getExportOptions` returns the fields to show the teacher before the export starts, like the class to send the test to. They're written like [settings](/developers/apps/settings), and checked the same way. The values the teacher picks are passed to `startExport` along with the app's settings, so `settings.classId` above is the chosen class. When a teacher hasn't filled in their own [user settings](/developers/apps/settings#workspace-and-user-settings) yet, like connecting their account, Examplary asks for those first. ## The test `startExport` gets the test to export: | Property | Description | | ------------- | ------------------------------------------------------------------------ | | `id` | The test's ID. | | `name` | The test's name. | | `publicUrl` | The link students use to open the test. | | `totalPoints` | The points to earn, or `null` when the test doesn't show points. | | `files` | A download `url` and `filename` for each of the `formats` you asked for. | The only format for now is `ExportFormat.Qti21`, a [QTI 2.1](https://www.1edtech.org/standards/qti) package that most assessment platforms can import. The download URLs are only valid for a short while, so pass the file on (or let your platform download it) right away. ## Export status `startExport` and `getExportStatus` both return the export's status: | Property | Description | | ----------- | ---------------------------------------------------------------------------------------------------- | | `status` | `ExportStatus.inProgress`, `completed` or `failed`. | | `resultUrl` | Where the teacher can see the result, like the imported test. Shown as a button once it's completed. | | `message` | What went wrong, or anything else the teacher should know, like questions that couldn't be imported. | | `data` | Anything you need to check on the export later, like the ID of an import job. | When an export can finish right away, return `completed` from `startExport`. Otherwise, return `inProgress`, and Examplary calls `getExportStatus` with the last status (including its `data`) every `statusCheckInterval` milliseconds, until the export is completed or failed. An export that's still in progress after 10 minutes counts as failed. --- // File: apps/capabilities/assessment-prerequisites # Assessment prerequisites An assessment prerequisite is something students have to meet before they can start a test. Secure browsers, like Schoolyear, Muute and Safe Exam Browser, are built this way: once a teacher turns one on for a test, students can only take it from inside that browser. A prerequisite adds a switch to the test's settings. When a teacher turns it on, Examplary shows its settings and its settings component. When students open the test, its player component explains how to meet it, like how to open the test in the secure browser, until it's met. ```mermaid flowchart LR teacher[Teacher turns it on] --> updated[onExamUpdated] student[Student opens the test] --> met{isMet} met -- no --> player[Player component] player --> met met -- yes --> session[Student takes the test]:::highlight session --> validate[validateRequest, on every request] ``` ## Defining a prerequisite ```ts title="capabilities/prerequisite.ts" import { AssessmentPrerequisite } from "@examplary/apps"; export default new AssessmentPrerequisite({ id: "acme-browser", name: { en: "Require the Acme browser" }, description: { en: "Students need to take this test in the Acme browser." }, requestHeaders: ["x-acme-signature"], exitButton: true, examSettings: [ { key: "allowCalculator", label: { en: "Allow the calculator" }, type: "boolean", default: false, }, ], playerComponent: { path: "./components/player.tsx", translations: { title: { en: "Open this test in the Acme browser" }, }, }, isMet: (settings, { request }) => !!request.headers["x-acme-signature"], validateRequest: async (settings, { request }) => { const valid = await verifySignature( settings.apiToken, request.headers["x-acme-signature"], ); if (!valid) { throw new Error("Open this test in the Acme browser."); } }, }); ``` | Property | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | `id` | Unique within your app. | | `name` | The label of the switch in the test's settings. | | `description` | Shown below the switch once it's turned on. | | `examSettings` | Settings per test, shown once it's turned on. Written like [settings](/developers/apps/settings), without components. | | `requiredPlans` | The Examplary plans the switch is available on, like `["pro", "enterprise"]`. All plans when left out. | | `requestHeaders` | The request headers your hooks get to see, like a signature your browser adds. | | `exitButton` | Shows a button to close the secure browser once the student has handed in the test. | | `settingsComponent` | A component shown in the test's settings, once it's turned on. | | `playerComponent` | A component shown to students while the prerequisite isn't met. | | `isMet` | Whether a student may start the test. Met when left out. | | `validateRequest` | Checks every request a student makes while taking the test. | | `onExamUpdated` | Runs when the test is saved, e.g. to set it up on your side. | | `functions` | Hooks your components can call. | | `files` | Files served at a public URL, like a configuration file for your browser. | ## Checking students Every check gets the app's settings and: | Property | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `exam` | The test: its `id`, `name`, whether it's `published`, `startDateTime`, `endDateTime`, `spellCheck`, `publicUrl` and `playerUrl`, and the workspace's `orgUrl` and `orgDomain`. | | `examSettings` | The values of your `examSettings` for this test. | | `data` | What `onExamUpdated` returned for this test, see [below](#setting-up-the-test-on-your-side). | | `request` | The student's request: its `method`, `path`, `host`, and the `headers` you listed in `requestHeaders`. | `isMet` decides whether the student can start the test. It runs when the student opens the test and when they start it. It also gets `input`, a value your player component passed with `setValue()`, which is useful when your browser tells the page something that the server can check, like a configuration key. `validateRequest` runs on every request a student makes while taking the test, like saving an answer. Throw an error to refuse the request; its message is shown to the student. Since it runs often, keep it quick.
- `/`
- `) — unsupported tags and attributes are stripped, and what remains is shown wherever the question is displayed, including exports. For inline math, wrap a LaTeX expression in `
`, e.g. ` x^2 + 3 `, rather than using `$`-delimited LaTeX. ### `type` and `settings` The `type` field references a question type: one of the [built-in question types](/developers/guides/default-question-types) or a [custom question type](/developers/apps/question-types) published by your organisation. The question type determines which `settings` are available. For built-in types these are listed on the [default question types](/developers/guides/default-question-types) page; for custom types they are defined in the type's [definition](/developers/apps/question-types/metadata). ## Scoring The `scoring` object holds the rubric configuration used to grade the question: | Field | Type | Description | | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rubricType` | string | The type of rubric: `simple`, `analytical`, `holistic`, or `exact-values`. See below. | | `criteria` | array | The criteria for scoring the question. The expected shape depends on the rubric type. | | `exactValuesCaseInsensitive` | boolean | Makes `exact-values` matching case-insensitive and strips **all** whitespace, not just surrounding, before comparing. See [Exact-value matching](/developers/apps/question-types/grading#exact-value-matching). | | `guidance` | string | Optional additional grading guidance text. | | `modelAnswer` | string | Optional example model answer shown to graders. | | `templateId` | string | The ID of the scoring template applied, if any. | | `excludeFromGrading` | boolean | Excludes the question from the exam's total points and grade. See below. | ### Rubric types The `rubricType` determines how the `criteria` array is interpreted: - **`simple`** — criteria have no levels, and their points stack: the total is the sum of the points for all criteria that apply. - **`analytical`** — at least one criterion, each with `levels`. For each criterion, a matching level is picked; the level's points count towards the total. - **`holistic`** — multiple criteria without levels. The grader selects a single criterion, and its points are the score. - **`exact-values`** — each criterion represents a specific value that must be matched exactly. Questions with this rubric type are graded automatically, as described in [question grading](/developers/apps/question-types/grading). Each entry in `criteria` (and each entry in a criterion's `levels`) has the following fields: | Field | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------- | | `id` | string | A unique ID for the criterion or level. **Required.** | | `title` | string | The title of the criterion or level. Only applies to analytical levels and holistic criteria. | | `description` | string | Describes the requirements to earn the points for this criterion or level. | | `points` | number | The default amount of points assigned when this criterion or level is selected. | | `minPoints` | number | The minimum amount of points that can be assigned when this criterion or level is selected. | | `maxPoints` | number | The maximum amount of points that can be assigned when this criterion or level is selected. | | `levels` | array | The levels of an analytical rubric criterion, each representing a different point value for that criterion. | ### Excluding a question from grading Setting `excludeFromGrading: true` in the `scoring` object leaves the question out of the exam's total points and grade. Excluded questions can still be answered and reviewed as normal — only the scoring calculation skips them, so response processing and AI-assisted grading still run and populate results as usual. ## Where you encounter the Question object - **REST API** — questions are nested in the `questions` array when [creating an exam](/developers/rest-api), managed individually through the exam questions endpoints, and stored as reusable items in the question bank. See the [REST API reference](/developers/rest-api) for the endpoints. - **Custom question type components** — the object is passed as the `question` prop, so you can read `settings`, `scoring`, `externalId` and `metadata` when rendering. The `assessment` component only gets this full shape in the question editor preview — during an actual exam session it instead receives a reduced object: `id`, `type`, `title`, `description`, `index` (the question's position in the array, zero-based), `number` (its display number, which skips `paragraph` questions), and `settings` (with `correctAnswer` removed) are included, plus `pointsToEarn` and `canProvideFeedback` when the exam is configured to show them. See [question type components](/developers/apps/question-types/components#question-object). - **Embed sessions** — flows such as [generate question](/developers/embed-sessions/flows/generate-question) and [grade answer](/developers/embed-sessions/flows/grade-answer) produce or consume questions in this same shape. --- // File: guides/importing/intent # Import intent URL To offer users an option to import a test from your application into Examplary, you can use the import intent URL. The import intent URL has the following format: ```http https://app.examplary.ai/intent/import?url={url}&name={name}&externalId={externalId} ``` Where: - `url`: The URL where the test file can be downloaded from - This file should be in a supported format (e.g., Moodle XML, QTI) - The file's content type isn't inspected for this flow, so a Moodle XML or bare QTI XML file is only recognized as such if `.xml` appears somewhere in the URL's path or filename (a query string like `?token=...` after it is fine) — otherwise it falls back to a slower, AI-based import. QTI packages (`.zip`) are unaffected by this. - The URL must be HTTPS with no custom port and no basic auth credentials, and it can't resolve to a private, loopback, or link-local address. It's fetched server-side with a plain request, so cookies or a browser session aren't forwarded; if the file needs authentication, put a token in the URL itself (e.g. `?token=...`). - `name`: Optional parameter to specify the name of the exam in Examplary. It's only used when the user creates a new test — an existing test keeps its own name. - `externalId`: Optional identifier of your own for this test (any string, e.g. your database ID). Examplary stores it on the test it creates and uses it to recognize repeat imports of the same test. ## Choosing where the questions go When a user clicks on this URL, they will be redirected to Examplary, where they are asked where the questions should go: | Option | When it's offered | What happens | | --- | --- | --- | | **Into a new test** | Always | A new test is created. If you passed an `externalId`, it's stored on that test. | | **Replace an existing test** | A test the user can edit carries the same `externalId` | That test's questions are replaced with the imported ones. It keeps its ID, share link and settings. | | **Add to an existing test** | No `externalId` match — the five most recently created tests the user can edit are offered | The questions are appended to that test, which keeps its settings. | When an `externalId` match is found, replacing that test is preselected, so a returning user only has to confirm. ## Things to know - **Matching is per user.** Only tests the user can edit (owner, manager or editor) are considered, so a colleague's test that hasn't been shared with them won't match — each user ends up with their own copy. - **Only new tests are tagged.** The `externalId` is stored when a test is created through this flow. If the user instead adds the questions to an existing test, that test isn't tagged, and a later import with the same `externalId` will offer a new test again. - **Replacing swaps out the questions only.** Imported questions get new IDs, so results from sessions that were already taken no longer line up with the test's questions. Use `externalId` for tests you may re-export before they're taken, rather than to patch a test that's already in use. - **You can read and write the same value through the API** as `metadata.externalId` on an exam, so your integration can look up what it previously imported without relying on the user's choice. - The underlying import endpoint is rate limited to 5 requests per minute per user — this is only a concern if you're triggering the import programmatically rather than through a single user click. --- // File: guides/default-question-types # Default question types Examplary ships with a set of built-in question types that are available to all organisations. This page provides an overview of each default question type, its capabilities, and configurable settings.This page is auto-generated from the [Examplary API](/developers/rest-api/question-types/get-question-types-public). ## Introduction Text shown to the student at the start of the test. **ID:** `exam-intro` **Capabilities**: AI generation ## Paragraph Some text to provide context or instructions to the student. **ID:** `paragraph` **Capabilities**: AI generation, QTI 3.0 export ## Outro Final text shown to the student after the test. **ID:** `exam-outro` **Capabilities**: AI generation ## Fill in the blanks Requires student to fill in one or more blanks with a short text answer. Also known as 'cloze' questions. **ID:** `examplary.expansion.fill-in-blank` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **The question text with blanks** | `text` | `string` | — | The text of the question (string), with blanks represented by ___ | | **Correct answer** | `correctAnswer` | `string-array` | — | The correct answer(s) to the question, that represent the blanks. There needs to be the same number of entries as there are blanks in the text. | | **Alternative answers per blank** | `alternativeAnswers` | `custom` | — | Optional. For each blank, other answers that are accepted besides its entry in `correctAnswer`, e.g. `[["Parijs"], []]`. An empty list (or no entry) accepts only the correct answer. | | **Choices per blank** | `choices` | `custom` | — | Optional. For each blank, the options the student picks from in a dropdown, e.g. `[["is", "are"], []]`. An empty list (or no entry) makes the blank a free text input. The correct answer for a dropdown blank must be one of its options. | | **Ignore spaces/capitals** | `exactValuesCaseInsensitive` | `boolean` | `true` | Leading/trailing whitespace is always ignored when comparing the student's answer to the correct answer. When this is enabled, letter casing is ignored too. | | **Exact order** | `exactOrder` | `boolean` | `true` | When enabled, every blank has to be filled in with the correct answer configured for that blank. When disabled, any of the correct answers is accepted in any blank, as long as each correct answer is used exactly once. | ## Matching Match the correct items with their pairs from two lists. **ID:** `examplary.expansion.matching` **Capabilities**: AI generation, Auto-scoring **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Left items** | `left` | `string-array` | — | Array containing the items shown in the left column (or top row). Example: `["Apple", "Banana"]`. | | **Right items** | `right` | `string-array` | — | Array containing the answer options the student can match with, shown in the right column (or bottom row). Example: `["Red", "Yellow"]`. | | **Correct answer** | `correctAnswer` | `string-array` | — | Array containing the correct pairs, where each pair is a string that contains ` = `. The text left of the ` = ` must exactly match an item from `left`, the text right of it an item from `right`. Example: `["Apple = Red", "Banana = Yellow"]`. | | **Layout** | `layout` | `vertical`, `horizontal` | `vertical` | The layout to use for displaying the matching question. `vertical` displays the items in two vertical columns, while `horizontal` displays them in two horizontal rows. Don't use horizontal if there are more than 3 items. | | **Shuffle options** | `shuffle` | `boolean` | `false` | Whether to show the options in a random order to the student during digital assessments. If disabled, the options in both columns are shown in alphabetical order. Printed sheets always show the items in the order of the settings. | ## Select point Students click the right spot on an image, like a place on a map. **ID:** `examplary.expansion.select-point` **Capabilities**: Auto-scoring **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Image** | `image` | `string` | — | URL of the image the student clicks on. | | **Width** | `width` | `number` | — | Optional width of the image's coordinate space, which points and areas are given in. Defaults to the image's own width. | | **Height** | `height` | `number` | — | Optional height of the image's coordinate space. Defaults to the image's own height. | | **Correct areas** | `areas` | `custom` | — | The areas the student has to click, e.g. `[{"shape": "circle", "coords": [191, 393, 10]}]`. A circle has coords [x, y, radius], a rect [left, top, right, bottom]. | | **Maximum number of points** | `maxChoices` | `number` | `1` | The number of points a student can place at most, 0 for no limit. | ## Select words Students select the correct words or phrases in a text. **ID:** `examplary.expansion.select-words` **Capabilities**: AI generation, Auto-scoring **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Text with selectable parts** | `text` | `string` | — | The text (HTML) with each part the student can select in square brackets, e.g. `<p>The [cat] [sat] on the [mat].</p>`. | | **Correct answer** | `correctAnswer` | `string-array` | — | The bracketed parts that should be selected, written exactly as between the brackets, e.g. `["sat"]`. | | **Show selectable words** | `showParts` | `boolean` | `true` | Whether the selectable parts are shown in boxes. When disabled, they read as plain text, so students have to find them themselves. | ## Sentence analysis Let students split a Dutch sentence into sentence parts, label each part, and mark the finite verb. **ID:** `examplary.expansion.sentence-analysis` **Capabilities**: AI generation, AI grading, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Sentence** | `sentence` | `string` | — | The single Dutch sentence the student should analyse. | | **Enabled labels** | `enabledLabels` | `string-array` | `OW,WG,LV,BWB` | Array of zinsdeel codes the student may choose from. Use only OW, WG, NG, LV, MV, VV, BWB, BVB, DB, VW. | | **Mark finite verb** | `requirePersoonsvorm` | `boolean` | `true` | Whether the student must underline the persoonsvorm. | | **Model answer** | `correctAnswer` | `string` | — | SentenceParse JSON containing tokens, ordered gapless segments, labels, and persoonsvorm. This field is hidden from the student-facing front-end. | ## Sequence Arrange items in the correct order. **ID:** `examplary.expansion.sequence` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Options** | `options` | `string-array` | — | The items that the student should rearrange, in the correct order. Can contain simple HTML markup. | ## Upload file Requires student to upload a file. **ID:** `examplary.expansion.upload-file` **Capabilities**: AI generation, AI grading, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Accepted file types** | `acceptFileTypes` | `*/*`, `application/pdf`, `.doc,.docx,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `image/*` | `*/*` | The types of files that students are allowed to upload. Should be one of the enum values specified below. | ## Voice recorder Ask the student to record a spoken answer. **ID:** `examplary.expansion.voice-recorder` **Capabilities**: AI generation, AI grading **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Maximum recording length** | `maxDurationSeconds` | `number` | `300` | Maximum recording length in seconds. | ## Javascript Ask the student to write a Javascript program to solve a problem. **ID:** `examplary.programming.javascript` **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Assertions** | `assertions` | `string` | `expect(result).toEqual([1, 2, 3]);` | The assertions to check the student's code against. | | **Initial value** | `initial-value` | `string` | `const result = "";` | The initial value to use for the code execution. | ## Persona chat Let the AI play a character - tutor, customer, debater - and hold a conversation with the student. **ID:** `persona-chat` **Capabilities**: AI generation, AI grading, AI-powered **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Persona** | `persona` | `knowledge-examiner`, `socratic-tutor`, `language-tutor`, `conversation-partner`, `math-tutor`, `debater`, `devils-advocate`, `curious-novice`, `quiz-master`, `job-interviewer`, `customer`, `client-briefing`, `patient`, `social-work-client`, `helpdesk-caller`, `historical-figure`, `journalist`, `lab-partner`, `code-reviewer`, `philosopher`, `case-examiner`, `investor`, `writing-coach`, `story-partner`, `municipal-official` | `knowledge-examiner` | The character the AI plays in the conversation. Each persona carries its own system prompt describing how it behaves. Must be one of the option values below. | | **Instructions** | `instructions` | `string` | — | Instructions for the AI character, as HTML. Must describe both the scenario (the situation, the topic and what the character should get the student to do) and the completion criteria (what the student has to have shown before the conversation may end, as a <ul> list). Never shown to the student. | | **Instructions written with AI** | `instructionsAiUsed` | `boolean` | `false` | Internal flag set when the teacher has used the AI button on the instructions field. Do not set this when generating a question. | | **AI starts conversation** | `aiStarts` | `boolean` | `false` | Whether the AI character sends the first message. Enable it when the scenario naturally opens with the character speaking (an interviewer welcoming the candidate, a patient describing a complaint); leave it off when the student is expected to open the conversation. | | **Maximum number of responses** | `maxTurns` | `number` | `10` | The maximum number of messages the AI character may send. The conversation always ends with the AI's closing message once this budget is used up. | ## Short answer A question that requires a short text response. **ID:** `single-line-text` **Capabilities**: AI generation, AI grading, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Maximum length** | `maxLength` | `number` | — | The maximum number of characters allowed in the answer - optional. Don't include unless relevant. | ## Long answer A question that requires a multi-line text response. **ID:** `multi-line-text` **Capabilities**: AI generation, AI grading, QTI 3.0 export ## Multiple choice A question where students select one correct answer from multiple options. **ID:** `multiple-choice-single-answer` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Multiple choice answer options** | `options` | `string-array` | — | An array of option strings that represent the choices to the student. Each value can contain HTML and <inline-math> tags. | | **Correct answer** | `correctAnswer` | `string` | — | The correct answer. Must be an exact copy of one of the strings in `options`, including punctuation, capitalisation and any HTML or <inline-math> tags, because scoring compares the strings directly. | | **Shuffle answer options** | `shuffleAnswers` | `boolean` | `false` | Whether to show the answer options in random order each time. | ## Checkboxes A question where students can select multiple correct answers from the available options. **ID:** `multiple-choice-multiple-answers` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Multiple choice answer options** | `options` | `string-array` | — | An array of option strings that represent the choices to the student. Each value can contain HTML and <inline-math> tags. | | **Correct answer(s)** | `correctAnswer` | `string-array` | — | The correct answers; there can be more than one. Each entry must be an exact copy of one of the strings in `options`, including punctuation, capitalisation and any HTML or <inline-math> tags, because scoring compares the strings directly. | | **Shuffle answer options** | `shuffleAnswers` | `boolean` | `false` | Whether to show the answer options in random order each time. | ## Picture choice Students select one of a set of images as the correct answer. **ID:** `picture-choice` **Capabilities**: Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Picture choice answer options** | `options` | `string-array` | — | An array of image URL strings that represent the choices to the student. | | **Correct answer** | `correctAnswer` | `string` | — | The correct answer. Must be an exact copy of one of the image URLs in `options`. | ## True/false A question that requires students to choose between true or false. **ID:** `true-false` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Correct answer** | `correctAnswer` | `true`, `false` | — | The correct answer to the question, either 'true' or 'false' (as a JSON string!). | ## Essay Prompt the student to write a long answer, often using headings and text formatting. **ID:** `essay` **Capabilities**: AI generation, AI grading, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Minimum word count** | `minWords` | `number` | — | — | | **Maximum word count** | `maxWords` | `number` | — | — | ## Formula A question that requires a mathematical expression as response. **ID:** `examplary.expansion.formula` **Capabilities**: AI generation, AI grading ## Math notebook A question where students show their work across multiple lines of math, with the final line as the answer. **ID:** `examplary.expansion.math-notebook` **Capabilities**: AI generation, AI grading **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Initial number of lines** | `initialLines` | `number` | `4` | The number of empty lines shown to the student at the start, including the final answer line. Students can add more lines, and printed sheets show exactly this many. Set it to roughly the number of steps the worked solution needs. | ## Date or year Ask the student to enter a year (e.g. 1925). **ID:** `date-year` **Capabilities**: AI generation, Auto-scoring, QTI 3.0 export **Settings**: | Setting | Key | Type | Default | Description | | --- | --- | --- | --- | --- | | **Date type** | `dateType` | `full-date`, `year` | — | The type of date to expect (e.g. year only, full date). | | **Correct answer** | `correctAnswer` | `string` | — | The correct answer to the question, which can be a year (e.g. 1925) or a full date (e.g. 1925-12-31), based on the dateType setting. | --- // File: guides/managing-permissions # Managing permissions Examplary uses a role-based and permission-based access control system to manage what users can do within an organization. Roles and permissions can be managed through the Examplary web application or via the API. ## Available roles The following roles can be assigned to actors (users, groups, or organizations) on a resource: | Role | Description | | ------------- | -------------------------------------------------------------------------------------------------------------- | | `owner` | Full control over the resource, including the ability to delete it. Can only be removed or downgraded by another owner. | | `manager` | Can edit the resource and manage its permissions (add/remove collaborators), but cannot grant the `owner` role, or remove or downgrade an existing owner's permission. | | `editor` | Can edit the resource, but cannot manage permissions. | | `viewer` | Read-only access to the resource. | | `participant` | For students: can take an exam or access a practice space, but cannot edit or view settings. | A resource can have multiple owners. To prevent it from ending up ownerless, an owner can never remove or downgrade their own owner permission — only another owner can do that for them. The same restriction applies when the `owner` role is granted to a group actor: only another owner can remove or downgrade that group's owner permission. ## Giving a user access to a content item You can assign a permission by actor ID: ```json title="POST /permissions/exam_1234" { "actor": "user_5678", "role": "manager" } ``` The `actor` field accepts a `user_`, `group_`, or `org_` prefixed ID — or the literal `org_this` as a shortcut for your own org's ID — plus a `public` option covered below. Two constraints are enforced by the API for these non-`public` actors: - An `org_` actor must be the requester's own org, except for library collections (`lib_coll_`), which can be explicitly shared with a different organization this way. - For a `user_` actor, `role` must be `participant` if and only if the target user is a student; assigning `participant` to a teacher/admin, or a higher role to a student, returns a `400`. This doesn't apply to `group_`/`org_` actors. `actor` also accepts the literal `public`, restricted to resources whose ID starts with `lib_coll_` (library collections) — assigning it on any other resource type returns a `400`. The `/library` endpoints themselves still require authentication regardless of this permission; granting `public` a role only controls whether the collection's items are indexed for `GET /search/tokens/public`, an unauthenticated endpoint that mints a search token scoped to publicly shared items. Alternatively, you can invite a user by email address instead of an actor ID. If the user does not yet exist in your workspace, they will be created automatically — as a student if `role` is `participant`, otherwise as a teacher. Set `sendInvite` to `true` to send them an invitation email. Students can't invite new users this way (`403`), and teachers can be blocked from inviting via the `sharingBlockTeachersInvitingUsers` org setting: ```json title="POST /permissions/exam_1234" { "email": "user@example.com", "role": "manager", "sendInvite": true } ``` ## Listing permissions for a content item ```json title="GET /permissions/exam_1234" [ { "actor": { "id": "user_5678", "name": "Jane Smith", "avatar": "https://cdn.examplary.ai/avatars/user_5678.jpg", "type": "user", "orgRole": "admin" }, "role": "manager", "createdAt": "2024-01-15T12:34:56Z", "updatedAt": "2024-01-20T09:21:43Z", "createdBy": "user_9012" }, { "actor": { "id": "group_9012", "name": "Teaching Staff", "type": "group" }, "role": "viewer", "createdAt": "2024-01-15T12:34:56Z", "updatedAt": "2024-01-20T09:21:43Z", "createdBy": "user_9012", "inheritedFrom": { "object": "folder_3456", "type": "folder", "name": "Shared Resources", "role": "viewer" } } ] ``` The `actor` object contains the following fields: | Field | Type | Description | | --------- | ------ | ---------------------------------------------------------------------------------------------- | | `id` | string | The actor's ID (user, group, or org prefixed, or the literal `public`). | | `name` | string | The actor's display name. Falls back to `"Unknown user"`, `"Unknown organization"`, or `"Unknown group"` if the actor could not be resolved. | | `avatar` | string | URL to the actor's avatar image. Only present for users and orgs with a logo. | | `type` | string | The type of actor: `"user"`, `"group"`, `"org"`, or `"public"` (name `"Public"`, for library collections shared publicly — see above). | | `orgRole` | string | The actor's role in the organization. Only present for `user` type actors. | When an item is inside a shared folder, the permissions list also includes actors who have access through that folder. These entries include an `inheritedFrom` field indicating the folder they inherited access from. Inherited permissions cannot be removed via `DELETE /permissions/:resource/:actor` — the call still returns `{ "success": true }`, but the actor keeps their access since there is no direct grant on the item to revoke. To revoke inherited access, update the permissions on the folder itself. ## Getting the role of a specific actor ```json title="GET /permissions/exam_1234/user_5678" { "actor": { "id": "user_5678", "name": "Jane Smith", "avatar": "https://cdn.examplary.ai/avatars/user_5678.jpg", "type": "user", "orgRole": "admin" }, "role": "manager", "createdAt": "2024-01-15T12:34:56Z", "updatedAt": "2024-01-20T09:21:43Z", "createdBy": "user_9012" } ``` Use `me` instead of an actor ID (`GET /permissions/exam_1234/me`) to get the authenticated user's own role on a resource. ## Autocompleting users and groups To populate a "share with" UI, search for users and groups by name or email: ```json title="GET /permissions/autocomplete?q=jane" [ { "id": "user_5678", "name": "Jane Smith", "email": "jane@example.com", "avatar": "https://cdn.examplary.ai/avatars/user_5678.jpg", "type": "user" }, { "id": "group_9012", "name": "Jane's Class", "type": "group" } ] ``` `email` and `avatar` are only present on `user` results. | Parameter | Required | Description | | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `q` | Yes | Search term, matched against name or email. Must be at least 3 characters. | | `type` | No | Restrict results to one kind of actor: `user` or `group`. | | `role` | No | Filter users by their organization role (the same role reported as `orgRole` on user actors above, not a resource permission role). | The authenticated user is never included in the results. If the organization has `restrictGroupVisibility` enabled, non-admin users only see users and groups they share a group with. ## Removing a permission ``` DELETE /permissions/exam_1234/user_5678 ``` Returns `{ "success": true }` on success. --- // File: guides/typescript-sdk # TypeScript SDK The [Examplary API SDK for TypeScript](https://www.npmjs.com/package/@examplary/sdk) provides a type-safe client for the Examplary API. It includes methods for all API endpoints, as well as type definitions for request and response data. ## Installation ```bash yarn add @examplary/sdk ``` ## Usage To use the SDK, create an instance of the client and provide your [personal API key](/developers/rest-api#authentication): ```typescript import { Examplary } from "@examplary/sdk"; const client = new Examplary({ apiKey: "my-api-key", }); const questionTypes = await client.questionTypes.listPublic(); ``` ## Calling conventions Every method takes its path, query, and body parameters merged into a single object — or, for operations with just one path parameter, that parameter as a plain string: ```typescript // Path + body merged into one object. await client.exams.update({ id: "exam_1234", name: "Updated name", }); // Just a string when the operation has a single path parameter. const questionType = await client.questionTypes.get("single-line-text"); ``` Nested resources (e.g. `client.exams.sessions.acceptSuggestion`) rename the parent `id` to `examId` (or `practiceSpaceId`, etc.) for readability: ```typescript await client.exams.sessions.acceptSuggestion({ examId: "exam_1234", sessionId: "ses_5678", questionId: "my_question_1", }); ``` Each method accepts an optional second argument that extends [axios's request config](https://axios-http.com/docs/req_config) (timeouts, an abort signal, extra headers, etc.) — `method`, `url`, `data`, `params`, and `baseURL` are excluded from this per-call config, since those are managed by the client itself. ## Errors A failed request rejects the returned promise with an `ExamplaryError` (an `AxiosError` subclass). The error message is taken from the API response body when available: ```typescript import { Examplary, ExamplaryError } from "@examplary/sdk"; const client = new Examplary({ apiKey: "my-api-key" }); try { await client.exams.get("exam_does_not_exist"); } catch (err) { if (err instanceof ExamplaryError) { console.error(err.message, err.response?.status); } } ``` ## Configuration `new Examplary(options)` accepts every [axios `CreateAxiosDefaults`](https://axios-http.com/docs/config_defaults) field plus: | Option | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------- | | `apiKey` | `string` | Required. API key or OAuth access token. Sent as `Authorization` header. | | `baseUrl` | `string` | Override the API host. Defaults to `https://api.examplary.ai`. | | `maxRetries` | `number` | Retries for failed requests. `0` disables retries. Defaults to `2`. | A `429` is retried for any method, waiting as long as the `Retry-After` header says. Network errors, timeouts, and `5xx` responses are only retried for idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`), with exponential backoff. `maxRetries` can also be set per call, alongside the other options described under [Calling conventions](#calling-conventions). --- // File: guides/uploading-files # Uploading files Get a file into Examplary when it isn't already available on a public URL. API endpoints that work with files, such as [creating a source material](/developers/grading/advanced/source-materials), take the file as a URL. Any public HTTPS URL works, and Examplary keeps its own copy of the file, so the original link doesn't have to stay online. If your file isn't online, upload it to Examplary first. That takes two requests: one to get an upload URL, and one to send the file to it. ## Step 1: Get an upload URL Ask for an upload URL, passing the file's name, its content type, and what the file is for: ```json title="GET /media/upload?filename=chapter-3.pdf&contentType=application/pdf&type=source-material" ``` | Parameter | Description | | ------------- | ---------------------------------------------------------------------------- | | `filename` | The file's name, such as `chapter-3.pdf`. | | `contentType` | The file's content type, such as `application/pdf`. | | `type` | What the file is for, such as `source-material`. Used to group your uploads. | This returns an `uploadUrl` to send the file to, and the `publicUrl` it will be available at: ```json { "uploadUrl": "https://…", "publicUrl": "https://examplarycontent.com/…/chapter-3.pdf" } ``` ## Step 2: Upload the file Send the file with a `PUT` request to the `uploadUrl`. Use the raw file as the body, not a form, and set the same `Content-Type` you asked for in step 1, or the upload is rejected. The upload URL is valid for an hour. ```bash curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: application/pdf" \ --data-binary @chapter-3.pdf ``` Once the upload has finished, use the `publicUrl` wherever the API asks for the file's URL.Anyone with the `publicUrl` can open the file, so don't share it beyond your own systems. --- // File: guides/webhooks # Webhooks Webhooks let Examplary tell your application when something has happened, like a test that finished generating or a session that finished grading, instead of you polling the API for it. You register a URL, pick the events you care about, and Examplary sends a signed `POST` request to that URL every time one of them happens. ## Creating a webhook Create a webhook with the [Create webhook](/developers/rest-api/webhooks/post-webhooks) endpoint. The URL must use HTTPS and be reachable from the internet, so `localhost` and private network addresses are rejected. To receive webhooks on your own machine during development, use a tunnelling tool such as [ngrok](https://ngrok.com).```json title="POST /webhooks" { "url": "https://example.com/webhooks/examplary", "events": [ "exam.generation.completed", "exam.session.completed" ] } ``` Use `resources` to only receive events for up to 100 tests, by their IDs: ```json title="POST /webhooks" { "url": "https://example.com/webhooks/examplary", "events": [ "exam.session.grading.completed" ], "resources": [ "{examId}" ] } ``` Org webhooks receive events for everyone in the workspace. Only admins and owners can create them: ```json title="POST /webhooks" { "url": "https://example.com/webhooks/examplary", "events": [ "exam.session.completed" ], "scope": "org" } ``` ``` Always check the signature before trusting a request. The easiest way is one of the Standard Webhooks libraries, which take the `whsec_` secret as is. Pass them the raw request body, before any JSON parsing: ```js import express from "express"; import { Webhook } from "standardwebhooks"; const app = express(); const webhook = new Webhook(process.env.EXAMPLARY_WEBHOOK_SECRET); app.post( "/webhooks/examplary", express.raw({ type: "application/json" }), (req, res) => { let event; try { event = webhook.verify(req.body.toString("utf8"), req.headers); } catch { return res.status(400).send("Invalid signature"); } // Handle event.type and event.data here res.sendStatus(204); }, ); ``` ```python import os from flask import Flask, request from standardwebhooks.webhooks import Webhook, WebhookVerificationError app = Flask(__name__) webhook = Webhook(os.environ["EXAMPLARY_WEBHOOK_SECRET"]) @app.post("/webhooks/examplary") def examplary_webhook(): try: event = webhook.verify(request.get_data(), dict(request.headers)) except WebhookVerificationError: return "Invalid signature", 400 # Handle event["type"] and event["data"] here return "", 204 ``` ` setting for the question (not on how many answers are marked correct) | | `truefalse` | `multiple-choice-single-answer` | | `essay` | `essay` | | `description` | `paragraph` | | anything else (e.g. `shortanswer`, `numerical`, `matching`, `cloze`) | `single-line-text`, using only the first answer marked correct as the reference for AI grading | Question types not in the first four rows still import, but degrade to a plain `single-line-text` question — review these after importing. Questions marked ` 1 ` in the Moodle XML are skipped entirely and won't appear in the imported quiz. ## Example XML ```xmlActinium The symbol for actinium is 1.0000000 0.1000000 0 0 Ac Calcium The symbol for calcium is 1.0000000 0.1000000 0 0 Ca H O Water is formed from which chemical elements?
Select all that apply: Hydrogen Oxygen Nitrogen Carbon