Quickstart

Prerequisites

An KiteFrost account (sign up free)
Your sk_live_... API key from Settings → API Keys

Step 1 - Create an encounter

Define the encounter context. The engine uses your campaign’s project state to generate balanced, flavourful output.

curl -X POST https://api.kitefrost.io/v1/encounters \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleset": "dnd5e",
    "party_size": 4,
    "party_level": 5,
    "difficulty": "hard",
    "environment": "abandoned dwarven mine",
    "narrative_context": "Players are chasing a thieves guild courier who fled into the mines",
    "monster_preferences": ["undead", "constructs"]
  }'

import requests

encounter = requests.post(
    "https://api.kitefrost.io/v1/encounters",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    json={
        "ruleset": "dnd5e",
        "party_size": 4,
        "party_level": 5,
        "difficulty": "hard",
        "environment": "abandoned dwarven mine",
        "narrative_context": "Players are chasing a thieves guild courier who fled into the mines",
        "monster_preferences": ["undead", "constructs"],
    },
).json()
print(encounter["id"])  # enc_01HZ...

const encounter = await fetch("https://api.kitefrost.io/v1/encounters", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ruleset: "dnd5e",
    party_size: 4,
    party_level: 5,
    difficulty: "hard",
    environment: "abandoned dwarven mine",
    narrative_context: "Players are chasing a thieves guild courier who fled into the mines",
    monster_preferences: ["undead", "constructs"],
  }),
}).then((r) => r.json());

Step 2 - Generate a session plan

Pass the encounter id (and any other hooks already in your campaign) to get a full session outline with pacing, contingencies, and boxed read-aloud text.

curl -X POST https://api.kitefrost.io/v1/sessions/plan \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "session_number": 7,
    "opening_hook": "The courier drops a coded letter before fleeing deeper into the mine",
    "encounter_ids": ["enc_01HZ..."],
    "desired_length_hours": 3,
    "tone": "tense, investigative"
  }'

{
  "id": "plan_01HZ...",
  "session_number": 7,
  "scenes": [
    {
      "order": 1,
      "title": "The Chase Begins",
      "description": "Players enter the mine entrance. Flickering torchlight. The sound of running feet ahead.",
      "read_aloud": "The mine yawns before you, the stench of old iron and damp stone filling your lungs...",
      "estimated_minutes": 20,
      "type": "exploration"
    },
    {
      "order": 2,
      "title": "Ambush at the Smelting Chamber",
      "description": "Encounter enc_01HZ... - four Animated Armours guard a barricaded door.",
      "estimated_minutes": 45,
      "type": "combat"
    }
  ],
  "contingencies": [
    "If players bypass the combat: courier is cornered in the treasure vault (scene 4)",
    "If a PC is knocked unconscious: a friendly duergar ghost offers a bargain"
  ],
  "generation_ms": 1240
}

Step 3 - Track items, quests, and notes

A campaign is more than encounters. Track the loot the players are hunting, the quests they have signed on for, and the lore they have uncovered. Every entity has its own dashboard page and its own REST endpoint.

Track your loot - create an item

Items are gear, treasures, set pieces, and macguffins. They live alongside NPCs and Places in the campaign and can be referenced from quest rewards, encounter loot, or location inventories.

curl -X POST https://api.kitefrost.io/v1/projects/{project_id}/ttrpg-gm/items \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunset Edge",
    "properties": {
      "description": "A curved blade that shimmers gold at dawn and dusk",
      "rarity": "rare",
      "item_type": "weapon"
    }
  }'

item = requests.post(
    f"https://api.kitefrost.io/v1/projects/{project_id}/ttrpg-gm/items",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    json={
        "name": "Sunset Edge",
        "properties": {
            "description": "A curved blade that shimmers gold at dawn and dusk",
            "rarity": "rare",
            "item_type": "weapon",
        },
    },
).json()

The dashboard’s Items page lists every item in the campaign and lets you create more from a simple form. Vocabulary follows your campaign - in the TTRPG GM pack these objects are called “Items”.

Plan a quest - create a quest with objectives

Quests track multi-step adventure threads. Each quest has a status (offered → active → completed), a list of objectives, and optional links to a quest-giver NPC and reward items.

curl -X POST https://api.kitefrost.io/v1/projects/{project_id}/quests \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Courier'\''s Letter",
    "summary": "Recover the coded letter the courier dropped in the mines",
    "status": "active",
    "objectives": [
      { "text": "Catch the courier before they reach the lower vault", "order": 1 },
      { "text": "Recover the letter intact", "order": 2 },
      { "text": "Decipher the cipher with help from the duergar ghost", "order": 3 }
    ]
  }'

quest = requests.post(
    f"https://api.kitefrost.io/v1/projects/{project_id}/quests",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    json={
        "title": "The Courier's Letter",
        "summary": "Recover the coded letter the courier dropped in the mines",
        "status": "active",
        "objectives": [
            {"text": "Catch the courier before they reach the lower vault", "order": 1},
            {"text": "Recover the letter intact", "order": 2},
            {"text": "Decipher the cipher with help from the duergar ghost", "order": 3},
        ],
    },
).json()

Toggle each objective complete from the dashboard or by patching the quest. When every objective is done, set status: "completed" and link the session that resolved it via completed_session_id.

Capture lore - create a note

Notes are free-form Markdown text - use them for lore, rumours, house rules, and post-session recaps. Pin the ones you reach for every session so they sort to the top.

curl -X POST https://api.kitefrost.io/v1/projects/{project_id}/notes \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "House rule: Critical hits explode",
    "body": "On a natural 20, the player rolls the damage die again and adds it. Stacks recursively on another 20.",
    "note_type": "house_rule",
    "pinned": true,
    "tags": ["combat", "rules"]
  }'

note = requests.post(
    f"https://api.kitefrost.io/v1/projects/{project_id}/notes",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    json={
        "title": "House rule: Critical hits explode",
        "body": "On a natural 20, the player rolls the damage die again and adds it. Stacks recursively on another 20.",
        "note_type": "house_rule",
        "pinned": True,
        "tags": ["combat", "rules"],
    },
).json()

Pick a note_type to file the note in a category - lore, rumour, house_rule, recap, secret are common values; the field is free text so use whatever taxonomy fits your table. Pinned notes sort first; the rest sort by most recently updated.

Step 4 - Record session outcomes

After the session, record what actually happened so the project state updates for next time.

curl -X POST https://api.kitefrost.io/v1/sessions/plan_01HZ.../outcomes \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "completed_scenes": [1, 2],
    "skipped_scenes": [],
    "notable_events": [
      "Players captured the courier",
      "One PC made an alliance with the duergar ghost"
    ]
  }'

Next steps

Browse Encounter endpoints for stat block export and CR adjustment
Use BYOK to route generation through your own LLM provider key
Subscribe to generation.completed webhooks to stream results to your VTT

Getting Started

Core Concepts

API Reference

Prerequisites

Step 1 - Create an encounter

Step 2 - Generate a session plan

Step 3 - Track items, quests, and notes

Track your loot - create an item

Plan a quest - create a quest with objectives

Capture lore - create a note

Step 4 - Record session outcomes

Next steps

​Prerequisites

​Step 1 - Create an encounter

​Step 2 - Generate a session plan

​Step 3 - Track items, quests, and notes

​Track your loot - create an item

​Plan a quest - create a quest with objectives

​Capture lore - create a note

​Step 4 - Record session outcomes

​Next steps

Prerequisites

Step 1 - Create an encounter

Step 2 - Generate a session plan

Step 3 - Track items, quests, and notes

Track your loot - create an item

Plan a quest - create a quest with objectives

Capture lore - create a note

Step 4 - Record session outcomes

Next steps