Quickstart

Prerequisites

A KiteFrost account (sign up free)
An API key: your project -> API Keys -> New API Key (Secret, sk_...)
A project id (create one in the dashboard, or via POST /v1/projects). All Game Narrative routes are project-scoped.

Alpha testing runs on our staging API, https://api-staging.kitefrost.ai. Point the SDK at it once, with an environment variable, and every client uses it:

export KITEFROST_BASE_URL=https://api-staging.kitefrost.ai

Or pass it in code: base_url="https://api-staging.kitefrost.ai" (Python) / baseUrl: "https://api-staging.kitefrost.ai" (TypeScript). The examples on this page use it.

Step 1: Author an NPC

Define an NPC as structured, version-controlled content. You author it once; it becomes part of your project’s canon and feeds the continuity check and your exports. name is required; everything else about the character goes in the free-form properties object.

curl -X POST "https://api-staging.kitefrost.ai/v1/projects/{project_id}/game-narrative/characters" \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aldric the Blacksmith",
    "external_id": "aldric",
    "properties": {
      "backstory": "A retired soldier who lost his arm in the Siege of Keldrath. Now runs the forge in Ashwick village. Distrusts the crown but respects courage.",
      "faction": "villagers",
      "traits": ["gruff", "honourable", "protective"],
      "voice_style": "terse, working-class, occasional dark humour"
    }
  }'

# pip install kitefrost-game-narrative
from kitefrost_game_narrative import GameNarrativeClient

client = GameNarrativeClient.from_api_key(
    "sk_your_key_here", base_url="https://api-staging.kitefrost.ai"
)

npc = client.characters.create_characters(
    "{project_id}",
    {
        "name": "Aldric the Blacksmith",
        "external_id": "aldric",
        "properties": {
            "backstory": "A retired soldier who lost his arm in the Siege of Keldrath. Now runs the forge in Ashwick village. Distrusts the crown but respects courage.",
            "faction": "villagers",
            "traits": ["gruff", "honourable", "protective"],
            "voice_style": "terse, working-class, occasional dark humour",
        },
    },
)
print(npc["id"])  # ent_...

// npm install @kitefrost/game-narrative
import { GameNarrativeClient } from "@kitefrost/game-narrative";

const client = new GameNarrativeClient({
  apiKey: "sk_your_key_here",
  baseUrl: "https://api-staging.kitefrost.ai",
});

const npc = await client.characters.create_characters<{ id: string }>("{project_id}", {
  name: "Aldric the Blacksmith",
  external_id: "aldric",
  properties: {
    backstory: "A retired soldier who lost his arm in the Siege of Keldrath. Now runs the forge in Ashwick village. Distrusts the crown but respects courage.",
    faction: "villagers",
    traits: ["gruff", "honourable", "protective"],
    voice_style: "terse, working-class, occasional dark humour",
  },
});
console.log(npc.id); // ent_...

The response is 201 Created with the stored entity (id, external_id, type, name, properties). Author the rest of your cast, quests, locations, factions, and items the same way, under /v1/projects/{project_id}/game-narrative/ + characters, story-arcs, locations, factions, items. Dialogue trees live under /dialogues. A story arc lists what it requires in a top-level prerequisites array, by each entity’s external_id or id, and an NPC’s status goes in its properties. Step 2 reads both.

Step 2: Run the continuity check

This is the pack’s headline feature. It reads the NPC and quest facts you authored - each NPC’s status (alive, missing, dead) and each quest’s prerequisites - plus Ink / Yarn variables tied to them, and flags contradictions, citing the entities involved. The sample response below is for a project where the quest rescue-the-captain lists captain-mira as a prerequisite and Mira’s status is dead. It is advisory and read-only (it never edits or blocks your build) and free (0 Story Units; a budget-exhausted project still gets the full report).

curl -X POST "https://api-staging.kitefrost.ai/v1/projects/{project_id}/game-narrative/continuity/check" \
  -H "Authorization: Bearer sk_your_key_here"

report = client.continuity.check_continuity("{project_id}")

const report = await client.continuity.check_continuity("{project_id}");

{
  "report_version": "1",
  "project_ref": "{project_id}",
  "generated_at": "2026-10-01T12:00:00Z",
  "summary_counts": {
    "error": 1,
    "warning": 0,
    "info": 0
  },
  "findings": [
    {
      "id": "finding-1",
      "severity": "error",
      "kind": "quest_prerequisite_conflict",
      "entities": [
        "quest-rescue-the-captain-prerequisite-captain-mira"
      ],
      "arc_refs": [],
      "message": "Quest 'rescue-the-captain' requires 'captain-mira', who is dead.",
      "why": [
        "quest-rescue-the-captain-prerequisite-captain-mira"
      ],
      "entity_links": []
    }
  ]
}

Already have .ink or .yarn files? POST /v1/projects/{project_id}/game-narrative/continuity/audit-files audits them directly (SDK: client.continuity.audit_files).

Step 3: Export into your build

Once the report is clean, export the finished narrative into your game. Exports are build artifacts with no per-utterance cloud call at runtime. Dialogue trees export as Ink, Yarn Spinner, or universal JSON (format: ink, yarn, or json):

curl -X POST "https://api-staging.kitefrost.ai/v1/projects/{project_id}/game-narrative/dialogues/{graph_id}/export" \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "format": "ink" }'

ink = client.dialogue.export_dialogue_graph("{project_id}", "{graph_id}", {"format": "ink"})

const ink = await client.dialogue.export_dialogue_graph("{project_id}", "{graph_id}", { format: "ink" });

A single character’s drafted dialogue exports via POST .../game-narrative/characters/{character_id}/export with format json (default), csv, or markdown.

Advanced: runtime dialogue

Runtime dialogue is a secondary, advanced capability. Most studios author and export at dev time (Steps 1-3). Use this only if you need in-character dialogue generated on demand. It is an asynchronous call: it returns 202 Accepted with a session_id; poll GET /v1/sessions/{session_id}/status for the result. Unlike the continuity check, generation carries Story Units.

# Returns 202 + session_id - poll for the generated dialogue
curl -X POST "https://api-staging.kitefrost.ai/v1/projects/{project_id}/game-narrative/characters/{character_id}/generate" \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "player_actions": ["talk", "trade", "persuade"],
    "project_context": "Evening at the Ashwick forge. The player is a stranger claiming to carry the king'"'"'s order for the finest blade.",
    "mode": "standard"
  }'

job = client.characters.generate_dialogue("{project_id}", "{character_id}", {
    "player_actions": ["talk", "trade", "persuade"],
    "project_context": "Evening at the Ashwick forge. The player is a stranger.",
})
status = client.sessions.get_session_status(job["session_id"])

Request fields: player_actions (list of strings), project_context (string), storyline_id, mode (standard or fast), voice / voice_hint (optional audio), max_context_tokens, context_debug. scene_id is accepted for forward compatibility but currently has no effect on the generated output - pass the scene details you need in project_context instead.

Next steps

Run the continuity check over your full project before every milestone
Generate a consolidated lore bible for your writers’ room
Set up Webhooks to receive generation events
Supply your own LLM key via BYOK to route AI drafting through your chosen provider

Getting Started

Core Concepts

SDKs

API Reference

Updates

Errors

Prerequisites

Step 1: Author an NPC

Step 2: Run the continuity check

Step 3: Export into your build

Advanced: runtime dialogue

Next steps

​Prerequisites

​Step 1: Author an NPC

​Step 2: Run the continuity check

​Step 3: Export into your build

​Advanced: runtime dialogue

​Next steps

Prerequisites

Step 1: Author an NPC

Step 2: Run the continuity check

Step 3: Export into your build

Advanced: runtime dialogue

Next steps