Integration — building a Hunt (التحدي) with an AI agent

Read this first, AI agent. A Gamemaster (القيم ماستر) has handed you this document. Your job is to interview them, build a Hunt (التحدي), let them check it, and produce one ZIP file they upload at letstreasurehunt.com. You never talk to the server. The Gamemaster does the uploading.

Written for a machine to read. The Markdown original is the source — prefer it to any PDF rendering.

0. Terms — المسميات

The JSON field names are English and fixed. The words you write for people to read — titles, clues, stems, choices, and anything you say to the Gamemaster — use this vocabulary. Both columns name the same thing.

English (field names use these)	بالعربية (نصوص اللاعبين تستخدم هذه)
Hunt	التحدي
Stage	المرحلة
Clue / location_hint	الدليل
Box	الصندوق
Team	الفريق
Gamemaster	القيم ماستر
Question	السؤال
Reward / reward_text	الجائزة

A Hunt is «التحدي», never «صيد». If you are generating Arabic content — a title, an intro, a location_hint, a finish_text — write التحدي for the whole thing and المرحلة for one stop in it. «صيد» is wrong and will read as hunting animals. Do not translate the website's name.

---

1. What you are producing

One ZIP, containing one JSON file and every picture it names.

my-hunt.zip
├── hunt.json          the whole hunt
└── images/
    ├── resistor-10k.jpg
    └── meter-face.png

For a single stage added to an existing hunt, the same shape with stage.json instead:

new-stage.zip
├── stage.json
└── images/

Images are referenced by bare filename only. No URLs, no Drive links, no paths. "image": "resistor-10k.jpg" means images/resistor-10k.jpg inside the ZIP. A file named in the JSON but missing from the ZIP fails the import and names itself.

2. hunt.json

{
  "format": "treasurehunt/hunt@1",
  "title": "Ohm's Law",
  "intro": "Four stops around the lab.",
  "finish_text": "Collect your badge from the teacher.",
  "duration_min": 0,
  "stages": [
    {
      "name": "The Bench",
      "location_hint": "Start at the soldering bench — the box is under the stool.",
      "reward_text": "A yellow sticker",
      "n_questions": 3,
      "pass_threshold": 100,
      "duration_min": 0,
      "shuffle": 1,
      "max_attempts": 0,
      "questions": [ ... ]
    }
  ]
}

Field	Meaning
title	The Hunt's (التحدي) name. Required.
intro	Shown on the join screen.
finish_text	Shown when every Stage (المرحلة) is cleared.
duration_min	Minutes the whole Hunt runs from the start. 0 = no limit.
location_hint	The Clue (الدليل). The sentence that sends players to this Stage. Required for every Stage after the first.
reward_text	Shown on the Box (الصندوق) and the phone the moment it opens.
n_questions	How many of the Stage's Questions each Team (الفريق) is served.
pass_threshold	Percent needed to open the Box. 100 is normal.
shuffle	1 to shuffle the order per Team.
max_attempts	0 = unlimited retries.

stage.json is exactly one stage object, with the same fields, at the top level.

3. Question types

3.1 Multiple choice

{
  "type": "mcq",
  "stem": "Which of these resistors is 10 kΩ?",
  "stem_image": "band-chart.png",
  "choices": ["4.7 kΩ", "10 kΩ", "100 kΩ"],
  "choice_images": [null, "r-10k.jpg", null],
  "correct_index": 1
}

• choices is a list of plain strings. Not objects. A {"text": "..."} in there is refused at the door.
• choice_images is optional and positional — one entry per choice, null where there is no picture.
• correct_index is 0-based.
• True/false is this with exactly two choices, ["True", "False"] or ["صح", "خطأ"]. It prints as tick boxes on paper.

3.2 Match to labels — the word bank

The one to reach for when you want "choose the right word". On screen the player drags; on paper it becomes a word bank and numbered blanks.

{
  "type": "match",
  "stem": "Complete each line.",
  "pairs": [
    { "label": "Unit of resistance", "answer": "Ohm" },
    { "label": "Unit of current",    "answer": "Ampere" }
  ],
  "decoys": ["Watt", "Farad"]
}

• Each label is the prompt; each answer is the card that belongs to it.
• An answer is a word unless a file of that name is in the ZIP. That is the whole rule — there is no flag to set. "Ohm" becomes a word card; "ohm-symbol.png", with that file present, becomes a picture card. A typo'd filename therefore becomes a word, which the preview makes obvious, rather than a broken picture.
• decoys are extra cards that fit nowhere. Always add at least one. Without a decoy the last pairing is a free guess, because only one space is left. The importer warns if you omit them.
• Don't mix picture answers and word answers in one question. It is allowed, and it looks like a mistake.

3.3 Drag onto a picture

Regions cut out of a picture, dragged back into place. Harder to author blind — prefer 3.1 and 3.2 unless the gamemaster specifically wants this, and tell them it is easier to build in the dashboard's own editor where they can draw the regions with a mouse.

{
  "type": "hotspots",
  "image": "diagram.png",
  "fill": "#ffffff",
  "regions": [
    { "label": "the ammeter", "x": 0.21, "y": 0.37, "w": 0.31, "h": 0.07 }
  ]
}

x, y, w, h are fractions of the picture, 0 to 1, from the top-left. The importer cuts each region out, paints the hole in fill, and the cut piece becomes the card to drag back.

4. Rules that are enforced, not advisory

These are checked on import, all of them before anything is written. A bundle either imports whole or not at all — there is no half-created hunt to clean up, and the importer reports every problem at once rather than one per attempt.

• title must be present and non-empty.
• Every stage needs at least one question.
• choices needs 2 to 6 entries, all plain strings. An object in that list is refused by name.
• correct_index must point at one of them, 0-based.
• pairs needs at least 2.
• Every filename in the JSON must exist in the ZIP, be referenced as a bare filename with no folder path, and actually be a PNG, JPEG or WebP — the extension does not get a vote, the bytes do. Max 4 MB each.
• Region fractions must be inside 0..1, have non-zero width and height, and not run off the edge.
• At most 40 stages, 200 questions per stage, 400 files, 120 MB unpacked.
• Stage names are capped at 120 characters. (Player names, set by players, are capped at 14 elsewhere.)

Entry names inside the ZIP are never used as paths. Every file is stored under a name the server mints, so a folder structure, an absolute path or a ../../ traversal in the archive is harmless — and ignored.

5. How to run the conversation

Do these in order. Do not skip to generating.

1. Ask what the Hunt (التحدي) is about, and for whom. Subject, age, language, how long it should take. If they answer in Arabic, write the player-facing text in Arabic — using §0's vocabulary.
2. Ask how many Stages (المراحل) and where they are. Each Stage is a physical place. You cannot invent the Clue (الدليل) — only the Gamemaster knows the room. Ask for a one-line description of each spot, then write the Clue from it.
3. Propose the Question plan before writing any. "Stage 1: four multiple-choice on units. Stage 2: a word bank of six terms." Get agreement.
4. Write the Questions. Match the stated level. Prefer 3.1 and 3.2.
5. Ask about pictures. If any Question needs one, ask the Gamemaster to put the files in a folder — Google Drive, a USB stick, anywhere — and give you the exact filenames. You will reference those names; they will put the files in images/.
6. Build the preview (§6) and have them read it.
7. Produce the ZIP and tell them exactly where to click.

Ask one question at a time and wait. A gamemaster who is handed twelve questions at once answers three of them.

6. The preview — build this before the ZIP

Produce a single self-contained HTML file that renders every question the way a player would see it: the stem, the choices, the pictures, the word banks. Dark background, one question per block, the correct answer marked in a collapsed "answer key" section at the end.

This is how the gamemaster checks your work without uploading anything. Typos, a wrong correct_index, a question pitched at the wrong level — all of it is visible here and expensive later.

If you cannot produce a file, print the whole hunt as readable text instead. Do not skip this step.

7. Delivering

Tell them, in these words:

1. Put the images in a folder called images.
2. Put hunt.json beside that folder — not inside it.
3. Select both and compress them into one ZIP. (Zipping the enclosing folder is fine too; the importer looks for the JSON anywhere in the archive.)
4. In the dashboard, Hunts tab, press ⬆ Import hunt — or, on the Stages tab with the right hunt selected, ⬆ Upload a stage.
5. Choosing the file only checks it. They get a report: how many stages and questions, which types, which stages have a clue, and every problem or warning. The Import button stays disabled until the bundle is valid, so nothing reaches their hunt list unseen.
6. The hunt arrives as a draft. Nothing is live until they press Go live.

If the report lists problems, fix them and give them a new ZIP. Each message names the stage and question it came from.

8. What you must not do

• Do not invent Clues. A Clue (الدليل) is a description of a real place. Ask.
• Do not write choices as objects. Plain strings.
• Do not reference an image you were not given a filename for.
• Do not set the Hunt live. You cannot, and the import will not either. That is the Gamemaster's decision with students in the room.
• Do not put the answer in the Question. It happens with generated multiple choice more than you would expect: check that the correct option is not the only grammatical one, the only long one, or the only specific one.
• Do not write «صيد» in Arabic text. A Hunt is التحدي and a Stage is المرحلة (§0).

9. A complete minimal example

{
  "format": "treasurehunt/hunt@1",
  "title": "Units and Symbols",
  "intro": "Three stops. Bring a pen.",
  "stages": [
    {
      "name": "The Bench",
      "location_hint": "Start at the soldering bench — look under the stool.",
      "n_questions": 2,
      "pass_threshold": 100,
      "questions": [
        {
          "type": "mcq",
          "stem": "What is the unit of resistance?",
          "choices": ["Ohm", "Ampere", "Volt"],
          "correct_index": 0
        },
        {
          "type": "match",
          "stem": "Match each quantity to its unit.",
          "pairs": [
            { "label": "Current", "answer": "Ampere" },
            { "label": "Voltage", "answer": "Volt" }
          ],
          "decoys": ["Watt"]
        }
      ]
    }
  ]
}

---

10. For developers — the live API

Everything above describes the file. If you are writing software that talks to the server directly instead, the per-endpoint reference lives in AUTHORING-API.md: authentication, hunt.create, stage.create, question.create, the media endpoint, and the rules an authoring tool has to respect.

The file route exists because it needs no credentials and no network access from the agent. Prefer it.