preview-scorecard

Create a RooQuiz Preview Scorecard

POST a scorecard as JSON to RooQuiz's open preview endpoint and instantly get a short-lived (~1 hour), browser-openable preview link. The creation endpoint is public (access.create => true), so this needs no account, login, API key, or credentials — anything that can make an HTTP request can use it.

A scorecard (scene: "scored_quiz") is a scored questionnaire: there's no "correct" answer — instead each option carries a point value, the report.formula totals them, and report.levels buckets the total into a result band (e.g. "Needs Work" → "Healthy"). It produces a temporary preview, not a permanently published form — the link expires automatically (recreate it in RooQuiz if you need to keep it).

Two sibling skills cover the other assessment types — pick the one that matches:

• preview-quiz — a right/wrong assessment where correct answers earn points and the taker gets a graded score.
• preview-outcome — a personality / type test where options vote for result types and the most-voted type wins (no scores).

Three steps

1. Build the scorecard JSON (structure below).
2. Create it: POST {PREVIEW_BASE}/api/preview-forms with the JSON as the body and header Content-Type: application/json. Returns { doc: { publicToken, expiresAt }, message }.
3. Hand back the link: {QUIZ_BASE}/b/{publicToken} — that is the whole link, nothing to append.

Endpoints

Override the env vars only when targeting a self-hosted RooQuiz deployment; otherwise the defaults work as-is.

Create it

Send one HTTP request. There is no auth — Content-Type: application/json is the only required header. Use whatever HTTP client your environment has (an agent's built-in fetch/HTTP tool, curl, requests, fetch, Postman, …):

POST https://preview.rooquiz.com/api/preview-forms
Content-Type: application/json

For example, with curl (write the JSON to a file first, or inline it with --data):

curl -sS -X POST https://preview.rooquiz.com/api/preview-forms \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/preview-form.json

The response is JSON shaped like:

{ "doc": { "publicToken": "7k3m9q2p", "expiresAt": "2026-06-16T09:12:00.000Z" }, "message": "..." }

Read doc.publicToken and build the preview link to hand the user:

https://quizster.app/b/

That is the complete link — nothing to append. For a self-hosted RooQuiz, swap the two hosts for your deployment's preview-API and quiz hosts (see the endpoints table above).

Scorecard JSON — top level

{
  "scene": "scored_quiz",            // required & fixed for this skill. Sets allowed question types and scoring. Cannot change after creation.
  "title": "My Scorecard",         // required
  "description": "Optional intro",
  "language": "en_US",             // form language; default zh_CN. See "language values" in Notes.
  "personalized": {                // appearance; omit to use defaults (light theme)
    "key": "default",
    "theme": { "name": "light" }
  },
  "indexDisplayMode": "number",    // question numbering: none (default) | number | uppercase | roman
  "fields": [ /* questions — see "Question types" and "Scoring" */ ],
  "report": { /* results page — see "Report configuration" */ },
  "rules": []                      // conditional-display rules (scorecard-only feature); usually []
}

Key points:

• Every question needs a unique code (string); option codes must be unique within their question. A code must be a valid identifier — start with a letter or _, then only letters/digits/_ (no -, spaces, or leading digit), max 64 chars, and not a reserved math word (e, E, pi, PI, tau, phi, i, Infinity, NaN, true, false, null, undefined). The server rejects violations with HTTP 400. Codes are also what the formula references.
• name is the question text; description is optional helper text.
• Unknown top-level fields are silently ignored by the server (no error).

Themes

personalized.theme.name sets the visual theme. Omit theme to default to light. Set it as "personalized": { "key": "default", "theme": { "name": "synthwave" } }. There is no personalized.layout — card is the only answering layout. (The per-field layout (list/grid) is a different thing and still valid.)

Pick a theme that fits the questionnaire's topic/mood. To use a random theme — when the user asks for one, wants variety, or has no preference — just choose a random name from this list when building the JSON (there's no server-side "random" option). Recommended palette:

The full daisyUI theme set also renders (e.g. emerald, dracula, retro, nord, sunset, winter, lofi, garden, aqua, business, lemonade, dim, bumblebee, acid, fantasy, wireframe, black, cmyk) — the table above is just the recommended palette. The server doesn't validate the name, so a typo silently falls back to default styling rather than erroring.

Question types

Each field is { type, code, name, ... }. In a scorecard you can use:

• Choice (carry choices: [{ code, value }], where value is the option label): SingleCheck (single), MultiCheck (multiple; optional min/max), DropDown, Cascade, TrueFalse (no choices)
• Input: NumberField, DateField (needs precision), TimeField, Rate (needs steps)
• Display only (never scored): Statement (content), Breaker (page break / divider), Swiper (image carousel, items)

FillBlank and Ordering are not allowed in a scorecard (they're quiz types). Optional shared props on any field: required, description, explain, hidden, activeColor (primary/secondary/accent/neutral), layout (list/grid).

Scoring

Give each option a point value with partialScoring (a field-level array, sitting next to choices). Do not set correctAnswer or exactScoring — there are no "correct" answers in a scorecard.

"partialScoring": [
  { "value": "never", "score": 0 },
  { "value": "some",  "score": 5 },
  { "value": "daily", "score": 10 }
]

Each value must be one of that question's choices[].codes. A Rate question contributes its selected step value to the total. Display-only fields (Statement/Breaker/Swiper) are never scored. The per-question scores are combined by the report.formula (below).

Report configuration

report.overallAnalysis is required. A scorecard needs a formula to total the questions, plus levels to bucket the total.

"report": {
  "overallAnalysis": {
    "title": "Your Score",
    "formula": "q1 + q2",          // total from question codes via + - * / ( )
    "summaryTemplate": " pts · ",
    "levels": [                    // map total score → level (see strict rules below)
      { "minScore": null, "maxScore": 10, "label": "Needs Work" },
      { "minScore": 10, "maxScore": 20, "label": "On Track" },
      { "minScore": 20, "maxScore": null, "label": "Excellent", "description": "Top tier!" }
    ]
  }
}

Strict levels rules (violations return HTTP 400): the first level's minScore must be null (−∞); the last level's maxScore must be null (+∞); middle levels have finite numbers on both ends; for adjacent levels current.minScore === previous.maxScore; maxScore strictly increases down the array. A single level has null on both ends.

Levels may carry a color (hex) and a cta (results-page button): { enabled, type: "link", text, url, newWindow }. When the cta is enabled, text and url are required, and url must be an http/https link. summaryTemplate defaults to a built-in template if omitted.

Common mistakes

These wrong patterns get reached for out of habit; the server rejects them with HTTP 400. The formats above are correct — match them exactly.

• Option lists are choices, never options. Every choice question uses "choices": [{ "code": "a", "value": "Label" }]. There is no options key.
• Codes must be valid identifiers, not arbitrary text — no hyphens (type-a), spaces, or leading digits (1q), and not reserved math words. Watch out for 5+ options coded a,b,c,d,e: e (Euler's number) is reserved and rejected — use o1, o2, … or another non-reserved identifier.
• Scoring is a field-level partialScoring array, not a value nested inside each choice. Correct: "partialScoring": [{ "value": "a", "score": 5 }] next to choices. Wrong: { "code": "a", "value": "…", "score": 5 } on the option itself.
• Don't set correctAnswer/exactScoring — those are for the right/wrong knowledge_quiz scene and are rejected here.
• Provide a formula that references your question codes — without it the total won't add up. And report.overallAnalysis is required.

Complete example

The personalized.theme.name is matched to the topic (see Themes above) — swap in any other name, or pick one at random.

{
  "scene": "scored_quiz",
  "title": "Healthy Habits Score",
  "language": "en_US",
  "personalized": { "key": "default", "theme": { "name": "forest" } },
  "fields": [
    {
      "type": "SingleCheck", "code": "q1", "name": "How often do you exercise?",
      "choices": [
        { "code": "never", "value": "Never" },
        { "code": "some", "value": "Sometimes" },
        { "code": "daily", "value": "Daily" }
      ],
      "partialScoring": [
        { "value": "never", "score": 0 },
        { "value": "some", "score": 5 },
        { "value": "daily", "score": 10 }
      ]
    },
    {
      "type": "SingleCheck", "code": "q2", "name": "Hours of sleep per night?",
      "choices": [
        { "code": "low", "value": "Under 6" },
        { "code": "ok", "value": "6-8" },
        { "code": "great", "value": "8+" }
      ],
      "partialScoring": [
        { "value": "low", "score": 0 },
        { "value": "ok", "score": 5 },
        { "value": "great", "score": 10 }
      ]
    }
  ],
  "report": {
    "overallAnalysis": {
      "title": "Your Wellness Score",
      "formula": "q1 + q2",
      "levels": [
        { "minScore": null, "maxScore": 10, "label": "Needs Work", "color": "#e57373" },
        { "minScore": 10, "maxScore": null, "label": "Healthy", "color": "#4caf50" }
      ]
    }
  }
}

Notes & limits

• Expiry: previews self-destruct after about 1 hour (expiresAt); the link 404s afterward. Recreate it in RooQuiz to keep it permanently.
• Rate limit: anonymous creation is capped at about 10 previews per hour per IP.
• Validation errors: a 400 response includes errors[].path and message — fix the JSON and retry. Most common: a question type or scoring style that doesn't match scene: "scored_quiz", non-contiguous levels, or a formula referencing a code that isn't a question.
• Results page looks empty? This is a preview (no submission backend); results are computed in the browser from the returned questions + report. Make sure report.overallAnalysis exists with a formula, and scored questions carry partialScoring.
• language values: en_US de_DE es pt_BR fr zh_CN (default) zh_TW ja_JP ko_KR.