API Reference

{
  "characterIds": ["cmrkiw4f100017k7sfnicq08e"],  // Required, 1 to 5 characters
  "message": "Hey there!",                        // The player's line. Omit for an ambient turn
  "playerId": "player-001",                       // Optional, enables per player usage and limits
  "sessionId": "",                                // Optional, continue an existing conversation
  "speakerCharacterId": "",                       // Optional, force who answers this turn
  "playAs": null,                                 // Optional, a character the player role plays
  "maxTurns": 5,                                  // Optional, cap on speakers per turn (max 5)
  "metadata": [],                                 // Optional, what the character can perceive
  "events": []                                    // Optional, recent world events
}

{
  "sessionId": "cmdruuvyr0000jr04lteh35te",
  "messages": [
    {
      "characterId": "cmrkiw4f100017k7sfnicq08e",
      "name": "Aria",
      "lines": [
        { "text": "Good evening.", "emotion": "HAPPY" },
        { "text": "What can I get you tonight?", "emotion": "CURIOUS" }
      ],
      "actions": [{ "name": "POUR_DRINK", "targetId": "tankard-1" }],
      "flowState": ""
    }
  ],
  "metadata": []
}

{
  "sessionId": "cmdruuvyr0000jr04lteh35te",  // Required
  "limit": 20,                               // Optional, 1 to 100, default 20
  "before": ""                               // Optional, a previous nextCursor
}

{
  "sessionId": "cmdruuvyr0000jr04lteh35te",
  "messages": [
    {
      "content": "Hey there!",
      "sender": "USER",
      "speakerCharacterId": null,
      "name": null,
      "addressedTo": null,
      "emotion": null,
      "actions": [],
      "createdAt": "2026-07-18T10:00:00.000Z"
    },
    {
      "content": "Good evening. What can I get you tonight?",
      "sender": "ASSISTANT",
      "speakerCharacterId": "cmrkiw4f100017k7sfnicq08e",
      "name": "Aria",
      "addressedTo": "Player",
      "emotion": "HAPPY",
      "actions": ["POUR_DRINK"],
      "createdAt": "2026-07-18T10:00:02.000Z"
    }
  ],
  "nextCursor": "cmdruv1c40002jr04a1b2c3d4"
}

{
  "characterId": "cmrkiw4f100017k7sfnicq08e",  // Required
  "message": "Good evening, traveller.",       // Required
  "emotion": "HAPPY",                          // Optional, colours the delivery
  "format": "wav"                              // Optional, audio format
}

Raw audio bytes.

This endpoint does not return JSON on success. Write the body straight to a
file or feed it to your audio player.

{
  "characterId": "cmrkiw4f100017k7sfnicq08e",  // Required
  "message": "Good evening, traveller.",       // Required
  "emotion": "HAPPY"                           // Optional, colours the delivery
}

Raw audio bytes, sent in pieces as they are produced.

A WAV header arrives first, followed by 16-bit mono audio at 24 kHz. The
header declares an unknown length, because the length is not known when it
is sent, so play the audio as it arrives rather than waiting for the end.

X-Sample-Rate and X-Channels repeat the format as response headers.

{
  "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 with 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
  "questionCount": 5,        // Optional, first call only. Questions in this run
  "selectionMode": "random"  // Optional, first call only. "sequential" or "random"
}

{
  "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
}