Quiz

One of your characters hosts a quiz. You send a character id and a question set id once, then forward whatever the player said for the rest of the run. Question order, retries, hints, scoring and when to stop are authored on the question set and decided on the server, so none of it lives in your game.

POST https://api.neocortex.link/v3/quiz
GET  https://api.neocortex.link/v3/quiz/session

The whole integration

curl -X POST https://api.neocortex.link/v3/quiz \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "YOUR_CHARACTER_ID",
    "questionSetId": "YOUR_QUESTION_SET_ID"
  }'

{
  "sessionId": "RETURNED_SESSION_ID",
  "say": "ummm I think it's a triangle"
}

Reading a turn

{
  "sessionId": "cmu9w20hi00527k9kpcoirzuw",
  "lines": [
    { "text": "Close! Think about the corners.", "emotion": "CURIOUS", "role": "reaction" },
    { "text": "What shape has three sides?", "emotion": "CURIOUS", "role": "question" }
  ],
  "expecting": "answer",
  "intent": "answer",
  "result": [{ "verdict": "INCORRECT", "score": 0, "participantId": "player-1" }],
  "leaderboard": [
    { "participantId": "player-1", "displayName": "Player", "totalScore": 0, "rank": 1 }
  ],
  "done": false
}

Anything absent means there is nothing to report. A field that is always present and usually null teaches a reader nothing, so only what a turn actually carries is sent.

Line roles

role says what each line is doing, so you can time the scene to it rather than to the turn.

Show the next thing on screen as the question line begins, not while the host is still reacting to the last answer.

spokenText appears on a line only when it respells that line for speech, for example "Alex +100" spoken as "Alex plus one hundred points". When it is absent, speak text.

Intents

Only answer can score. A request for a clue or a turn the host could not make out never spends an attempt.

The question on screen

{
  "question": {
    "questionId": "q_mfx2k1_a7c2",
    "keyword": "SHOW_RED_APPLE",
    "type": "multiple_choice",
    "questionText": "Which one is the apple?",
    "options": [
      { "id": "opt_a", "text": "Apple" },
      { "id": "opt_b", "text": "Pear" }
    ],
    "hasHint": true
  },
  "upcoming": { "questionId": "q_mfx2k4_b913", "keyword": "SHOW_GREEN_PEAR" },
  "progress": { "asked": 1, "total": 5 }
}

keyword is the author's own name for the scene a question needs, in the same shape as an action keyword. Question ids are generated and mean nothing to a game; key your scene on the keyword instead, and use the one on upcoming to preload the next.

hasHint is only present when the run will actually give a clue. A set with hints turned off never advertises one, even on a question whose author wrote hint text.

Answering

An authored welcome is its own beat

When the set has opening words written on it, the first call returns only the greeting: question is absent and expecting is nothing. The turn after that asks question one. This is so a game can greet the player, dress the scene, and only then put a question on screen.

Leave the opening blank and the run opens on the first question instead, in the same breath as the welcome.

The same applies to the closing words. With none written, the run ends on the host's last reaction.

Several players

{
  "characterId": "YOUR_CHARACTER_ID",
  "questionSetId": "YOUR_QUESTION_SET_ID",
  "participants": [
    { "id": "alex", "displayName": "Alex", "type": "human" },
    { "id": "maya", "displayName": "Maya", "type": "human" }
  ]
}

Up to ten participants, and their ids must be unique. Send participantId with every answer so the right person is credited. The round waits until everyone has answered before anything is judged, and pending tells you who is left.

Omit participants entirely for a single player.

Reading a run back

If a client loses its place, restarts, or you want a scoreboard, read the whole run.

curl "https://api.neocortex.link/v3/quiz/session?sessionId=SESSION_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "state": {
    "phase": "collecting",
    "roundNumber": 2,
    "totalQuestions": 5,
    "questionsRemaining": 3,
    "participants": [{ "id": "player-1", "displayName": "Player", "type": "human" }],
    "activeQuestion": { "questionId": "q_mfx2k4_b913", "type": "free_text", "questionText": "And this one?", "hasHint": false },
    "answeredParticipantIds": [],
    "pendingParticipantIds": ["player-1"],
    "leaderboard": [{ "participantId": "player-1", "displayName": "Player", "totalScore": 100, "rank": 1 }],
    "startedAt": "2026-09-20T09:14:02.881Z",
    "finishedAt": null,
    "nextAction": "evaluate",
    "expecting": "answer"
  },
  "leaderboard": [],
  "roundHistory": [],
  "questionSet": { "name": "Shape School", "evaluationProtocol": "educational" },
  "startedAt": "2026-09-20T09:14:02.881Z",
  "finishedAt": null
}

state.expecting is the same value a turn carries, so a client whose turn response was lost can reopen the microphone instead of guessing. roundHistory carries every round played, with the host's lines and the verdicts, and gains correctAnswer on each round once the run is finished.

Scores never come from the host

Every point is derived from the question's own scoring table. The host reads the player and reports a verdict for open answers; the engine works out the number. A host that proposes a retry the set forbids, or a verdict on a turn that was not an answer, changes nothing.

result[].score is what actually reached the standings. On a replay the set does not count it is 0, while the verdict still says whether they were right, so you can celebrate a correct answer without the leaderboard disagreeing with you.

Multiple choice and true or false questions are graded in code. When the words do not name an option outright, the host is asked which option they pointed at and the engine compares that pick to the answer key, so a player answering in their own language is not marked wrong by a string comparison.

Errors

Request reference

{
  "sessionId": "",           // Continue a run. Omit on the first call
  "characterId": "",         // Required on the first call, the host of the quiz
  "questionSetId": "",       // Required on the first call, the set to play
  "playerId": "",            // Optional, your own id for this player
  "participants": [],        // Optional, up to 10, unique ids. Omit for one player
  "participantId": "",       // Who spoke, once there is more than one player
  "say": "",                 // What the player said. "" is an explicit pass
  "optionId": ""             // The option they tapped
}