Create Resource

Create Resource Skill

This skill helps you create educational resources for the Beau platform. Resources are the building blocks of your curriculum - each is a self-contained learning unit delivered to students as a voice conversation, a narrated presentation, or a no-bot worksheet (self-paced screens / printable handout written for the student). Resources are grouped into courses.

Reference guides

This skill folder ships two markdown guides. They have different audiences (see each file's audience frontmatter):

• resource-creation-guide.md (audience: assistant) — your authoring reference. Follow it when designing and writing resources.
• teacher-guide.md (audience: human-ui) — end-user documentation for the Beau dashboard UI, written for human teachers. Useful background for terminology and workflow, but it is not authoring rules — don't treat its UI walkthroughs as instructions to you. (The repo's top-level guides/ folder holds the human-facing admin and student guides; those are not part of this skill.)

Instructions for Claude

When this skill is invoked, follow these steps:

0. Preflight Check: Verify the beaubot MCP server is connected by calling list_tags(pageSize: 1). If this fails with a tool error, tell the user: "The Beau MCP server is not connected. Please check your MCP connection and authenticate if prompted." Then stop.

1. Tag Governance (before creating anything): a. Call list_tags(pageSize: 50) to fetch the full tag catalog b. Reuse existing tags where possible — do not create near-duplicates (e.g. "maths" vs "math") c. For genuinely new tags: ask the user to confirm, then call create_tag(name) to add them d. Only use tags that exist in the catalog when calling create_resource

2. Gather Requirements: Ask the user about:

   • Topic/subject for the resource
   • Target audience (age, skill level)
   • Delivery mode preference: conversation (two-way voice), presentation (one-way narration), or worksheet (no bot — self-paced screens / printable, written FOR THE STUDENT). This changes who the content is written for: conversation/presentation are written for the bot; a worksheet is written directly to the student.
   • Desired length (default: 5-10 minutes)
   • Any specific learning objectives
   • Whether they want AI-generated images or have URLs to images/PDFs

3. Design the Resource: Based on the guides, create a structure with:

   • Clear learning objectives
   • Logical sections with headings
   • A quiz after every major concept or section — aim for at least 2-3 quizzes per resource. Quizzes are the primary way students actively engage with the material, and lessons without them feel passive and text-heavy.
   • At least 1-2 images per resource — visuals break up text, illustrate concepts, and give the bot something concrete to discuss with the student. A resource with no images is almost always too text-heavy.
   • Mix quiz types for variety (single choice, multiple choice, open answer, fraction, ordered list, matching)

4. Create Content: Draft the markdown content following best practices:

   • Write instructions for the bot, not a script
   • Use "the student" with they/them pronouns
   • Keep sections digestible
   • IMPORTANT: Avoid text-heavy resources. Every section should either have a quiz, an image, or both. If a section is just text with no interactivity, consider adding a quick quiz to check understanding or an image to illustrate the concept. Students learn best when they actively participate, not passively listen.
   • If a quiz refers to a figure, attach that figure to the quiz (its image field), don't just place it inline before ::quiz{#id}. Then the diagram and the question are on screen together while the student answers. See Quiz Illustrations.

5. Source Media: Find or create visuals for the resource. Every resource should have images — they are essential for engagement, not optional decoration.

   • Do NOT generate images via Python/code — this is too slow and produces poor results
   • Use the text visual (create_visual with kind: "text") for vocabulary cards, sight words, labels and key terms, and the math visual for equations — these are instant, vector (crisp at any size), and teacher-editable. create_text_image is deprecated — never use it.
   • Use generate_image only for custom educational illustrations / photoreal scenes — server-side AI generation; slower, so reserve it for when a real raster picture is genuinely needed
   • Use upload_image_from_url for existing public images (Wikimedia, educational sites)
   • Use create_image (base64) only as a last resort for user-provided local files
   • Verify every image: After generation/upload, view the image to confirm it matches intent
   • Write description/question/answer/hint based on what the image ACTUALLY shows, not what you intended
   • For PDFs: description is critical since the bot cannot read PDF content

6. Execute Creation: Use MCP tools to:

   • Create the resource via create_resource
   • Upload any media files via upload_image_from_url or create_image
   • Create quizzes via create_quiz
   • CRITICAL: Update resource content via update_resource to embed image and quiz references using the correct markdown syntax (see below)
   • Set a cover image: pick the most representative image for the resource and set it via update_resource(id, coverImage: imageId). Cover images are shown to students when the lesson starts and make the catalog feel less like a wall of text. Do this in the same update_resource call as the content update.
   • Optionally create a course and add the resource to it

7. Provide Testing Instructions: Tell the user how to test their resource using the Test Resource button in the admin UI

MCP Tools

Use the beaubot MCP server tools:

Available Tools

Choosing how to show something visual

When a lesson needs a picture or diagram, pick the most specific option — in this order. Going higher up the list gives crisper, more responsive, more editable results, so don't drop to a raster image out of habit.

1. A dedicated visual tool — create_visual (best). If the concept maps to a built-in kind, use it: number line, fraction, grid, timeline, math (KaTeX), word/text, counters, clock, ten frame, bar chart, base-ten blocks, money, phoneme frame, place value, Chart.js chart, function graph, geometry, coordinate grid, box plot, probability tree, atom (Bohr), pH scale, syllable split, onset/rime. These are purpose-built, teacher-editable, and render responsively. For arbitrary data charts the chart kind (Chart.js) covers bar/line/pie/scatter/etc.
2. A hand-drawn SVG — create_svg (good fallback). If no visual kind fits but the thing can be expressed with shapes, lines and text — a labelled diagram, a custom illustration, a flowchart, a simple map, a process diagram — write an SVG. It stays sharp at any size and is lightweight. Prefer this over a raster image.
3. A raster image (last resort). Only when you truly need a photograph or a richly detailed picture that can't be vector-drawn: generate_image (AI) or prepare_image_upload / create_image (an existing file). Supported raster uploads: PNG and JPEG. (SVG uploads are supported too, but use create_svg rather than uploading SVG by hand.)

All of these embed the same way in the content — ![ID](/api/v1/images/ID/data) for images and SVGs, ::visual{#ID} for visual tools.

Workflow

0. list_tags(pageSize: 50) → Fetch org's tag catalog
   create_tag(name) → Create new tags (after user confirmation)

1. create_resource(name, content, tags, deliveryMode)
   → Returns resource with ID (tags must come from the catalog)

2. create_visual(resourceId, kind, config)
   → Vector visual — use kind "text" for words/labels/vocabulary, "math" for equations,
     or any other kind for diagrams. Instant, editable. PREFERRED for words. Embed with ::visual{#id}.
   OR
   generate_image(resourceId, prompt, description, question, answer, hint, botVisible)
   → AI-generated image — only for photoreal illustrations/scenes
   OR
   upload_image_from_url(resourceId, url, description, question, answer, hint, botVisible)
   → Downloads and attaches image from URL
   OR (for a file on local disk)
   prepare_image_upload(resourceId) → { uploadUrl }; then `curl -F file=@/path "$uploadUrl"`
   → Single-use multipart upload, no base64 round-trip
   OR (last resort)
   create_image(resourceId, name, mimeType, data, description, question, answer, hint, botVisible)
   → Uploads base64-encoded image

2b. create_visual(resourceId, kind, config, ...)
   → Authored visual tool (number line, fraction, grid, timeline, math, text, counters)
   → Renders as crisp SVG; embed in content with ::visual{#id}. Prefer this over an image
     whenever the content is structured data the platform can draw.

3. create_quiz(resourceId, question, questionType, answers, image?, ...)
   → Returns quiz with ID
   → Pass image: <imageId> to attach an illustration (image must be on the same resource)
   OR
   update_quiz(resourceId, id, image?, ...)
   → Update an existing quiz — fix typos or attach an illustration after generating it

4. update_resource(id, content, coverImage?)
   → CRITICAL: Update content to include image and quiz references
   → Optionally set coverImage to an image ID to give the resource a cover

5. (Optional) create_course(name, description, tags, progressionType)
   → Returns course with ID

6. (Optional) list_course_resources(courseId)
   → View existing resources in a course before adding

7. (Optional) add_resource_to_course(courseId, resourceId, order)
   → Adds resource to the course

8. (Optional) export_resource(resourceId)
   → Returns base64-encoded ZIP for backup or sharing

9. (Optional) import_resource(zipData)
   → Creates a new resource from a previously exported ZIP

Tool Parameters

get_image:

• imageId (required): The image ID to download
• Returns: For images (image/png, image/jpeg), returns the image visually plus a text label. For PDFs/videos, returns metadata only:

  {
    "id": 42,
    "name": "dog-breeds.png",
    "mimeType": "image/png",
    "description": "Common dog breeds",
    "question": "Can you identify these breeds?",
    "answer": "Labrador, Poodle, German Shepherd",
    "hint": "Look at the ear shapes",
    "botVisible": true,
    "resource": 15,
    "organization": 3,
    "createdAt": "2026-03-15T10:30:00.000Z",
    "updatedAt": "2026-03-15T10:30:00.000Z"
  }
  

create_resource:

• name (required): Display name for the resource
• content (required): Markdown content
• tags (optional): Array of tags — must come from the tag catalog (call list_tags first, use create_tag for new ones)
• deliveryMode (optional): "conversation", "presentation", or "worksheet"

update_resource:

• id (required): The resource ID to update
• name (optional): New name
• content (optional): New markdown content
• tags (optional): New tags (replaces existing — must come from the catalog)
• deliveryMode (optional): "conversation", "presentation", or "worksheet"
• coverImage (optional): Image ID to use as the resource cover (shown to students when the lesson starts). The image must already be attached to the resource (use create_visual, generate_image, upload_image_from_url, prepare_image_upload + curl, or create_image first, then pass the returned ID here). Pass null to remove the cover.

generate_image (preferred for custom illustrations):

• resourceId (required): Resource to attach the image to
• prompt (required): Text prompt describing the educational image to generate (max 4000 chars)
• description (optional): What the image shows (important for bot)
• question (optional): Question to ask about the image
• answer (optional): Expected answer
• hint (optional): Help for students
• botVisible (optional): If true, bot can see the image

create_text_image — DEPRECATED. Do not use. To render a word, phrase, label or key term, use the text visual instead: create_visual(resourceId, "text", { text: "...", … }). It renders the same inline formatting (_underline_, *italic*, **bold**, [highlight], {red:colored}), is vector instead of a raster PNG, is teacher-editable, and supports the org logo.

upload_image_from_url (preferred for remote use):

• resourceId (required): Resource to attach image to
• url (required): Public URL of the image to download
• name (required): Image filename
• description (optional): What the image shows (important for bot)
• question (optional): Question to ask about the image
• answer (optional): Expected answer
• hint (optional): Help for students
• botVisible (optional): If true, bot can see the image

create_image:

• resourceId (required): Resource to attach image to
• name (required): Image filename
• mimeType (required): "image/png", "image/jpeg", "image/svg+xml", or "application/pdf". For SVG, prefer the dedicated create_svg tool (it takes raw markup, no base64).
• data (required): Base64-encoded image data
• description (optional): What the image shows (important for bot)
• question (optional): Question to ask about the image
• answer (optional): Expected answer
• hint (optional): Help for students
• botVisible (optional): If true, bot can see the image

create_visual (authored visual tool — renders as crisp SVG, no AI):

• resourceId (required): Resource to attach the visual to
• kind (required): One of "number_line", "fraction", "grid", "timeline", "math", "text", "counters", "clock", "ten_frame", "bar_chart", "base_ten", "money", "phoneme_frame", "place_value", "chart", "function_graph", "geometry", "coordinate_grid", "box_plot", "probability_tree", "atom", "ph_scale", "syllable_split", "onset_rime", "writing_area"
• config (required): Kind-specific JSON object (shapes below). Add "logo": true to render the org logo above the visual.
• question, answer, hint (optional): let the bot quiz the student on the visual, exactly like an image. Do not set a description — the bot is given one regenerated from the config every lesson, so it always matches what's drawn; and there is no botVisible (a vector/text visual is always legible).
• Returns an image ID — embed it in the content with ::visual{#id} (mirrors ::quiz{#id}). A visual ID can also be passed as a create_quiz image or a update_resource coverImage.

Per-kind config shapes:

// number_line — marks may be numbers or strings; highlights = up to 4 points, auto-coloured red/blue/green/pink in order (legacy single "highlight" still works)
{ "from": 0, "to": 10, "marks": [0, 2, 4, 6, 8, 10], "highlights": [3, 7] }
// fraction — style: "bar" | "circle"; showValue:false hides the n/d label (name-the-fraction quiz)
{ "num": 3, "den": 4, "style": "bar", "showValue": true }
// grid — rows of cells; optional header per row; optional highlighted cells
{ "cols": ["1", "2", "3"], "rows": [{ "header": "x2", "cells": [2, 4, 6] }], "highlight": [{ "row": 0, "col": 1 }] }
// timeline
{ "events": [{ "date": "1969", "label": "Moon landing" }, { "date": "1989", "label": "Web invented" }] }
// math — KaTeX / LaTeX
{ "tex": "\\frac{1}{2} + \\frac{1}{3}" }
// text — font: "beginner" | "comic" | "standard"; inline _u_ *i* **both** [hl] {red:color}. ONE word/phrase/label only — NO newlines or multi-line lists; a literal \n will NOT break the line (use separate text visuals or a grid for several lines)
{ "text": "cat", "color": "#333333", "font": "beginner" }
// counters — a single emoji, count 1-99
{ "emoji": "🍎", "count": 5 }
// clock — 12-hour face; hours 0-23, minutes 0-59; showMinuteTicks optional (default true)
{ "hours": 3, "minutes": 15, "showMinuteTicks": true }
// ten_frame — 0-20 counters in a 2x5 frame (two frames above 10); color optional
{ "count": 7, "color": "#E53935" }
// bar_chart — unit + color optional; showValues:false hides value labels (read heights off the axis) for a quiz
{ "bars": [{ "label": "Cats", "value": 4 }, { "label": "Dogs", "value": 6 }], "unit": "children", "showValues": true }
// base_ten — Dienes blocks for place value, 0-999
{ "value": 124 }
// money — coins/notes in MINOR units (pence/cents); currency GBP|USD|EUR (default GBP); showTotal:false hides the total (adding-up quiz)
{ "coins": [200, 200, 20, 20, 5], "currency": "GBP", "showTotal": true }
// phoneme_frame — one grapheme per sound (phonics sound buttons)
{ "graphemes": ["sh", "i", "p"] }
// place_value — digits in place columns; columns optional (derived if omitted)
{ "value": 3406, "columns": ["Th", "H", "T", "O"] }
// chart — a full Chart.js spec (the most flexible kind). type one of
//   bar|line|pie|doughnut|radar|polarArea|scatter|bubble. Pure data only: no URLs, max 50KB.
{ "spec": { "type": "bar", "data": { "labels": ["Jan", "Feb"], "datasets": [{ "label": "Rain", "data": [42, 35] }] }, "options": {} } }
// function_graph — plot y=f(x); explicit * (2*x); funcs sin cos tan sqrt abs exp ln log; consts pi e
{ "functions": ["x^2", "2*x+1"], "xMin": -5, "xMax": 5 }
// geometry — labelled polygon; coords auto-scale; rightAngles = vertex indices
{ "vertices": [{ "x": 0, "y": 0, "label": "A" }, { "x": 4, "y": 0, "label": "B" }, { "x": 0, "y": 3, "label": "C" }], "sideLabels": ["4 cm", "5 cm", "3 cm"], "rightAngles": [0] }
// coordinate_grid — plot points/segments; xMin/xMax/yMin/yMax optional
{ "points": [{ "x": 2, "y": 3, "label": "A" }], "segments": [{ "from": [0, 0], "to": [2, 3] }] }
// box_plot — five-number summary
{ "min": 2, "q1": 5, "median": 7, "q3": 10, "max": 14, "label": "Scores" }
// probability_tree — recursive branches with probabilities
{ "branches": [{ "label": "Red", "prob": "1/2", "branches": [{ "label": "Red", "prob": "1/2" }, { "label": "Blue", "prob": "1/2" }] }] }
// atom — Bohr model; electrons per shell
{ "protons": 11, "neutrons": 12, "electrons": [2, 8, 1] }
// ph_scale — 0-14
{ "value": 7 }
// syllable_split — phonics: one chunk per syllable
{ "syllables": ["but", "ter", "fly"] }
// onset_rime — phonics: onset may be empty (e.g. "at")
{ "onset": "str", "rime": "ing" }
// writing_area — WORKSHEET blank answer space (size: "sentence" | "paragraph" | "multi_paragraph"; label optional). Print-first.
{ "size": "paragraph", "label": "Your answer" }

update_visual:

• resourceId (required), imageId (required)
• config (optional): replaces the whole config; must match the visual's existing kind (kind is immutable — delete and recreate to change it)
• name, question, answer, hint (optional). No description/botVisible — see create_visual.

create_quiz:

• resourceId (required): Resource to attach quiz to
• question (required): Question text
• questionType (required): "single", "multiple", "freetext", "ordered_list", "matching", or "fill_in_blank"
• answers (for single/multiple/ordered_list): Array of {id, text, isCorrect}. For matching: {id, text, isCorrect, matchText}
• expectedAnswer (for freetext): Correct answer
• inputRestriction (for freetext): "text", "integer", "decimal", or "fraction"
• numericMin (optional): Minimum allowed value for numeric inputs (integer, decimal, fraction)
• numericMax (optional): Maximum allowed value for numeric inputs (integer, decimal, fraction)
• allowNegative (optional): Whether negative values are accepted (default: true)
• evaluationCriteria (optional): AI grading guidelines
• retryLimit (optional): Max attempts
• hint (optional): Guidance for wrong answers
• description (optional): When the bot should present this quiz
• exactMatch (freetext only): grade the answer EXACTLY against expectedAnswer (case + punctuation count) with deterministic feedback, instead of lenient AI grading. This is the flag that turns a freetext quiz into a spelling/dictation quiz — see the recipe below.
• image (optional): Illustration image ID — see Quiz Illustrations below. The image must already be attached to the same resource.

Recipe: a spelling or dictation quiz (end-to-end)

A spelling/dictation quiz = the student hears a word or sentence and types it; grading is exact. Build it in three steps:

1. Make the audio prompt — generate_audio({ resourceId, text: "<the word or sentence>", name: "..." }). Returns an image id. The text is the answer spoken aloud; it is never shown to the student and never sent to the bot, so it can't leak.
2. Create the quiz — create_quiz({ resourceId, questionType: "freetext", inputRestriction: "text", exactMatch: true, expectedAnswer: "<the word or sentence>", question: "Listen and type what you hear.", image: <audio id from step 1>, retryLimit: <null for unlimited, or a number> }). expectedAnswer MUST match the audio text exactly (the capitalisation + punctuation you want graded). Leave evaluationCriteria off — exactMatch ignores it.
3. Embed it — put ::quiz{#<quiz id>} in the markdown where the dictation should happen.

Notes:

• Words vs sentences both work — for a sentence, include the exact capital letter + full stop in both text and expectedAnswer; the deterministic feedback calls out "Check your capital letters" / "You forgot the full stop" / "You got N letters wrong".
• exactMatch only applies to inputRestriction: "text" (not numeric inputs).
• Use retryLimit: null (unlimited) for practice; a number to cap attempts.
• To make a whole dictation lesson, repeat steps 1–3 per phrase (one audio + one quiz each), under headings like ## Phrase 1, and the bot reads the instruction, plays each clip, and checks the typed answer.

update_quiz:

• resourceId (required): The resource the quiz belongs to
• id (required): The quiz ID to update
• All other fields from create_quiz are optional — omitted fields are left unchanged
• Use this to fix typos, change answers, or attach an illustration image after the image has been generated
• Pass image: null to remove an existing illustration image

create_course:

• name (required): Course name
• description (optional): Course description
• tags (optional): Array of tags
• progressionType (optional): "flexible", "sequential", or "random"
• openEnrollment (optional): If true, students can self-enroll from the course catalog
• defaultTeacher (optional): User ID of the teacher assigned to self-enrolled students (required when openEnrollment is true)
• maxEnrollments (optional): Maximum number of students who can enroll (null = unlimited)
• priceCents (optional): Price in cents for paid courses (requires Stripe Connect)
• currency (optional): Currency code for paid courses (e.g., "GBP", "USD", "EUR")
• teacherOnly (optional): If true, course is only visible to teachers in the catalog (preview mode)

export_resource:

• resourceId (required): The resource ID to export
• Returns: Base64-encoded ZIP containing manifest, content, media, and quizzes

import_resource:

• zipData (required): Base64-encoded ZIP file data matching the format below
• fileName (optional): Filename for the ZIP (default: "import.zip")
• Returns: The newly created resource (with ID and name)

Resource Archive Format (for import/export)

The ZIP file must have all files at the root level (no subdirectory wrapper) with this structure:

manifest.json        # Required: metadata and file references
content.md           # Required: markdown content with portable tokens
media/               # Media files (images, videos, PDFs)
  media-001.png
  media-002.jpeg
quizzes/             # Quiz definitions
  quiz-001.json
  quiz-002.json

CRITICAL: Files must be at the ZIP root — NOT inside a subdirectory. A ZIP containing my-resource/manifest.json will fail; it must be just manifest.json.

manifest.json format

{
  "version": 1,
  "exportedAt": "2026-01-01T00:00:00.000Z",
  "resource": {
    "name": "Subtraction on a Number Line",
    "tags": ["maths", "subtraction"],
    "deliveryMode": "conversation"
  },
  "media": [
    {
      "ref": "media-001",
      "filename": "media/media-001.png",
      "name": "Number Line Diagram",
      "mimeType": "image/png",
      "description": "A number line showing 15 - 3 = 12",
      "question": "Where do we land after 3 hops back from 15?",
      "answer": "We land on 12",
      "hint": "Count the arrows backwards",
      "order": null,
      "botVisible": true
    }
  ],
  "quizzes": [
    {
      "ref": "quiz-001",
      "filename": "quizzes/quiz-001.json"
    }
  ]
}

Key rules:

• version must be 1
• media and quizzes are arrays (not objects)
• Each media entry must have a ref field (e.g. "media-001") matching its portable token in content.md
• Each quiz entry must have a ref field (e.g. "quiz-001") matching its portable token in content.md
• Media filenames must match their mimeType extension (e.g. media-001.png for image/png)
• Only image/png, image/jpeg, and application/pdf are supported for images

content.md portable tokens

Content must use portable media:// and quiz tokens (NOT database IDs):

![media-001](media://media-001)

::quiz{#quiz-001}

The importer replaces these tokens with real database IDs after creating the records.

Quiz JSON format

Each quiz file (e.g. quizzes/quiz-001.json) contains:

{
  "question": "What is 15 - 3?",
  "questionType": "freetext",
  "inputRestriction": "integer",
  "expectedAnswer": "12",
  "numericMin": 0,
  "numericMax": 20,
  "allowNegative": false,
  "evaluationCriteria": "Accept only the number 12.",
  "retryLimit": 3,
  "hint": "Start at 15 and count back 3 hops.",
  "description": "Quiz after the number line example."
}

create_tag:

• name (required): Tag name to create (max 128 chars, lowercase recommended)

list_course_resources:

• courseId (required): The course ID to list resources for
• Returns: Ordered list of resources with name, tags, order, and bot details (content stripped to save tokens)

add_resource_to_course:

• courseId (required): Course ID
• resourceId (required): Resource ID to add
• order (optional): Position in the course (important for sequential courses)
• bot (optional): Override the course's default bot for this specific resource
• deliveryMode (optional): Override the resource's default delivery mode within this course

Organizing Resources into Courses

Courses group related resources together for students to complete. When creating a course, consider:

Progression Types

Course Design Tips

• Use sequential progression when earlier resources teach concepts needed for later ones
• Use flexible progression when resources cover independent topics within a theme
• Set resource order carefully for sequential courses - use the order parameter in add_resource_to_course
• Override the bot for specific resources if a different AI persona or expertise is needed
• Override delivery mode per resource if some topics work better as conversation, presentation, or worksheet
• Keep courses focused - 3-8 resources per course is a good range
• Use consistent tags across resources and courses for easy organization

Open Enrollment

Enable open enrollment to let students self-enroll from the course catalog:

• Requires a defaultTeacher to be assigned for managing self-enrolled students
• Optionally set maxEnrollments to cap capacity
• Set teacherOnly: true to preview the course before releasing to students

Paid Courses

If the organization has Stripe Connect configured:

• Set priceCents and currency to create a paid course
• Open enrollment must be enabled for paid courses
• Students go through Stripe checkout and are automatically enrolled after payment

CRITICAL: Embedding Media and Quizzes in Resource Content

After creating images and quizzes, you MUST update the resource content to include references to them. Without these references, the bot will NOT display the media or quizzes during delivery.

Image Reference Syntax

![IMAGE_ID](/api/v1/images/IMAGE_ID/data)

Example: If create_image returns { id: 156 }, insert:

![156](/api/v1/images/156/data)

Quiz Reference Syntax

::quiz{#QUIZ_ID}

Example: If create_quiz returns { id: 28 }, insert:

::quiz{#28}

Visual Reference Syntax

::visual{#VISUAL_ID}

Example: If create_visual returns { id: 91 }, insert:

::visual{#91}

The bot displays the visual via display_media when it reaches this point in the prose — exactly like images and quizzes.

Complete Example

# Step 1: Create resource
create_resource(
  name: "Introduction to Photosynthesis",
  content: "# Learning Objectives\n\nPlaceholder content...",
  tags: ["science", "biology"],
  deliveryMode: "conversation"
)
# Response: { id: 42, ... }

# Step 2: Upload image from URL
upload_image_from_url(
  resourceId: 42,
  url: "https://example.com/plant-cell.png",
  name: "Plant Cell Diagram",
  description: "Diagram of a plant cell showing chloroplasts",
  question: "Where does photosynthesis occur?",
  answer: "In the chloroplasts",
  hint: "Look for the green organelles",
  botVisible: true
)
# Response: { id: 156, ... }

# Step 3: Create quiz
create_quiz(
  resourceId: 42,
  description: "Test understanding of photosynthesis location",
  question: "In which organelle does photosynthesis take place?",
  questionType: "single",
  answers: [
    { id: "a", text: "Mitochondria", isCorrect: false },
    { id: "b", text: "Chloroplast", isCorrect: true },
    { id: "c", text: "Nucleus", isCorrect: false }
  ],
  retryLimit: 2,
  hint: "It contains chlorophyll, which is green"
)
# Response: { id: 28, ... }

# Step 4: CRITICAL - Update resource with image and quiz references
update_resource(
  id: 42,
  content: "# Learning Objectives\n\nBy the end of this resource, the student should understand photosynthesis.\n\n## What is Photosynthesis?\n\nExplain that plants convert sunlight into energy. Show the diagram:\n\n![156](/api/v1/images/156/data)\n\nDiscuss the diagram with the student.\n\n## Check Understanding\n\nNow test the student's knowledge:\n\n::quiz{#28}\n\n## Summary\n\nReview the key points."
)

Quiz Types

Single Choice

{
  "question": "What gas do plants absorb?",
  "questionType": "single",
  "answers": [
    { "id": "a", "text": "Oxygen", "isCorrect": false },
    { "id": "b", "text": "Carbon dioxide", "isCorrect": true }
  ],
  "hint": "Think about what humans breathe out"
}

Multiple Choice

{
  "question": "Select ALL ingredients for photosynthesis",
  "questionType": "multiple",
  "answers": [
    { "id": "a", "text": "Sunlight", "isCorrect": true },
    { "id": "b", "text": "Water", "isCorrect": true },
    { "id": "c", "text": "Oxygen", "isCorrect": false }
  ]
}

Open Answer

{
  "question": "Calculate 15% of 80",
  "questionType": "freetext",
  "inputRestriction": "decimal",
  "expectedAnswer": "12",
  "evaluationCriteria": "Accept 12, 12.0, or 12.00"
}

Fraction

{
  "question": "What is 1/2 + 1/6?",
  "questionType": "freetext",
  "inputRestriction": "fraction",
  "expectedAnswer": "2/3",
  "numericMin": 0,
  "numericMax": 1,
  "allowNegative": false,
  "evaluationCriteria": "Accept equivalent fractions (e.g. 4/6, 8/12)"
}

Ordered List

Students drag and drop items into the correct sequence. The answers array order defines the correct sequence — students see items shuffled.

{
  "question": "Put these in order from smallest to largest",
  "questionType": "ordered_list",
  "answers": [
    { "id": "a", "text": "1/2", "isCorrect": false },
    { "id": "b", "text": "0.55", "isCorrect": false },
    { "id": "c", "text": "3/5", "isCorrect": false },
    { "id": "d", "text": "62%", "isCorrect": false }
  ],
  "hint": "Convert everything to decimals to compare"
}

Note: isCorrect is ignored for ordered_list — the array order IS the correct answer. Minimum 2 items, maximum 10.

Matching

Students match items from two columns. The left column shows fixed terms, the right column shows shuffled matches that students drag to align correctly.

{
  "question": "Match each part of speech to its example",
  "questionType": "matching",
  "answers": [
    { "id": "a", "text": "verb", "isCorrect": false, "matchText": "jump" },
    { "id": "b", "text": "noun", "isCorrect": false, "matchText": "book" },
    { "id": "c", "text": "adverb", "isCorrect": false, "matchText": "quickly" }
  ],
  "hint": "Think about what each word does in a sentence"
}

Note: isCorrect is ignored for matching — correct state is when each answer's matchText is aligned next to its text. Each answer needs both text (term) and matchText (match). Minimum 2 pairs, maximum 10.

Fill in the Blank

Students fill in missing words within a sentence. Supports free text input or word bank (dropdown) mode.

{
  "question": "Water freezes at [] degrees Celsius and boils at [] degrees Celsius",
  "questionType": "fill_in_blank",
  "answers": [
    { "id": "a", "text": "0", "isCorrect": true },
    { "id": "b", "text": "100", "isCorrect": true }
  ],
  "hint": "Think about the states of water"
}

For word bank mode (dropdown with distractors), set inputRestriction to "word_bank" and add distractor answers with isCorrect: false:

{
  "question": "The [] sat on the []",
  "questionType": "fill_in_blank",
  "inputRestriction": "word_bank",
  "answers": [
    { "id": "a", "text": "cat", "isCorrect": true },
    { "id": "b", "text": "mat", "isCorrect": true },
    { "id": "c", "text": "dog", "isCorrect": false },
    { "id": "d", "text": "hat", "isCorrect": false }
  ]
}

Note: Use [] in the question to mark blank positions. Correct answers (isCorrect: true) map in order to blanks. Distractors (isCorrect: false) appear as extra options in word bank mode. Minimum 1 blank.

Quiz Illustrations

A quiz can have an illustration image attached to it (separate from the resource's inline images and cover image). The illustration appears alongside the question, on the same screen, when the quiz is shown to the student.

This is the preferred way to give a quiz a supporting figure. If a question refers to a diagram — "find the missing side of this triangle", "label the parts of this cell", "which angle is x?" — attach that figure to the quiz via its image field. Because the picture and the question render together and stay together, the student can read the diagram while they answer. Do not instead drop the figure inline in the content just before ::quiz{#id}: the bot shows an inline image earlier, as it narrates that part of the lesson, so by the time the student is answering the quiz the picture may no longer be on screen. A quiz that depends on a figure should own that figure.

A quiz illustration can be any image kind — an uploaded/AI image, a create_svg drawing, or a create_visual visual tool (pass the visual's id as the quiz image). For maths/science diagrams, prefer a create_visual (e.g. geometry, coordinate_grid, function_graph) or a create_svg so it stays crisp.

Quiz images are not embedded in the resource markdown — they are linked directly to the quiz record via the image field. The resource content does NOT need a ![ID](/api/v1/images/ID/data) reference for quiz illustrations.

Attaching an illustration

The image must already be attached to the same resource as the quiz. The normal flow is:

# Step 1: Generate or upload the illustration, attached to the resource
generate_image(resourceId: 42, prompt: "A cross-section of a leaf showing chloroplasts")
# → { id: 177, ... }

# Step 2a: Create the quiz with the image attached
create_quiz(
  resourceId: 42,
  question: "Which labelled part contains the chloroplasts?",
  questionType: "freetext",
  expectedAnswer: "The palisade mesophyll",
  image: 177
)

# OR Step 2b: Create the quiz first, then attach the image later
create_quiz(resourceId: 42, question: "...", questionType: "single", answers: [...])
# → { id: 99, ... }
update_quiz(resourceId: 42, id: 99, image: 177)

When to use a quiz illustration vs. an inline image

• **Quiz illu

…(truncated)