# KiteFrost - Game Narrative API

## Docs

- [Authentication](https://game-narrative.docs.kitefrost.ai/_shared/core-concepts/auth.md): Authenticate API requests using API keys with scoped access control.
- [Billing](https://game-narrative.docs.kitefrost.ai/_shared/core-concepts/billing.md): Understand pricing tiers, Story Units, and how billing works.
- [Bring Your Own Key (BYOK)](https://game-narrative.docs.kitefrost.ai/_shared/core-concepts/byok.md): Route AI generation through your own LLM API keys to control costs and access frontier models.
- [Webhooks](https://game-narrative.docs.kitefrost.ai/_shared/core-concepts/webhooks.md): Receive real-time event notifications via HMAC-SHA256 signed HTTP POST deliveries.
- [API Reference](https://game-narrative.docs.kitefrost.ai/api-reference.md): Complete reference for all KiteFrost Game Narrative API endpoints.
- [Create account](https://game-narrative.docs.kitefrost.ai/api-reference/auth/create-account.md): Register a new tenant with email and password. Creates a default project and returns a secret API key. The full key is shown only once - store it securely.
- [Current identity (pack + billing plan)](https://game-narrative.docs.kitefrost.ai/api-reference/auth/current-identity-pack-+-billing-plan.md): Returns the authenticated tenant's identity - tenant_id, user_id (when available), and the effective pack_slug / billing_plan_slug (override_* columns supersede the underlying ones, matching ``effective_identity`` semantics). The dashboard frontend calls this on SSR hydration via ``useAuthContext``…
- [Login](https://game-narrative.docs.kitefrost.ai/api-reference/auth/login.md): Authenticate with email and password. Returns the tenant ID and a list of API key prefixes. Use the API key from signup to authenticate API calls.
- [Create checkout session](https://game-narrative.docs.kitefrost.ai/api-reference/billing/create-checkout-session.md): Create a Stripe Checkout Session for upgrading the tenant to a paid plan. Returns a ``checkout_url`` that the client should redirect to. When Stripe is not configured (dev mode), returns a placeholder URL.
- [Create portal session](https://game-narrative.docs.kitefrost.ai/api-reference/billing/create-portal-session.md): Create a Stripe Customer Portal session so the tenant can manage their subscription, update payment methods, or cancel. Requires an existing Stripe customer ID (i.e. the tenant must have completed checkout at least once).
- [Get current tier](https://game-narrative.docs.kitefrost.ai/api-reference/billing/get-current-tier.md): Return the current subscription tier, feature limits, and Stripe metadata for the authenticated tenant.
- [Get Story Unit usage](https://game-narrative.docs.kitefrost.ai/api-reference/billing/get-story-unit-usage.md): Return Story Unit (SU) usage for the current billing period: units consumed, monthly limit, and units remaining. Enterprise tenants have no limit (``story_units_limit`` and ``story_units_remaining`` are null).
- [Get usage stats](https://game-narrative.docs.kitefrost.ai/api-reference/billing/get-usage-stats.md): Return usage statistics for the current billing period: API calls, LLM tokens consumed, and NPCs created.
- [Stripe webhook receiver](https://game-narrative.docs.kitefrost.ai/api-reference/billing/stripe-webhook-receiver.md): Receives Stripe webhook events. This endpoint does NOT require API key authentication -- it verifies the ``Stripe-Signature`` header instead. Handles: ``checkout.session.completed``, ``customer.subscription.updated``, ``customer.subscription.deleted``, ``invoice.payment_succeeded``, ``invoice.paymen…
- [Get BYOK status](https://game-narrative.docs.kitefrost.ai/api-reference/byok/get-byok-status.md): Check whether the project has a BYOK key configured and which source (`byok`, `shared`, `none`) is active. The actual key is never returned.
- [Revoke BYOK key](https://game-narrative.docs.kitefrost.ai/api-reference/byok/revoke-byok-key.md): Remove the tenant-supplied BYOK key for the project. Subsequent LLM calls will fall back to the shared platform key.
- [Set BYOK key](https://game-narrative.docs.kitefrost.ai/api-reference/byok/set-byok-key.md): Store a tenant-supplied LLM provider API key (BYOK) for the project. The key is stored in memory and used instead of the shared platform key for all LLM calls in this project. **Paid plans only** (Pro and above) - see web/public/llms.txt § 'All paid plans include BYOK'. Free-tier tenants in the trea…
- [Update BYOK preferences](https://game-narrative.docs.kitefrost.ai/api-reference/byok/update-byok-preferences.md): Update routing preferences for an existing tenant-supplied BYOK key without requiring the raw API key to be submitted again. **Paid plans only** (Pro and above). Free-tier treatment tenants who have already attached a key via PUT may also update preferences.
- [Batch create NPCs](https://game-narrative.docs.kitefrost.ai/api-reference/characters/batch-create-npcs.md): Create multiple NPCs in one call (max 50).
- [Batch generate NPC dialogue](https://game-narrative.docs.kitefrost.ai/api-reference/characters/batch-generate-npc-dialogue.md): Trigger dialogue generation for multiple NPCs with shared context.
- [Cast distinctiveness audit (advisory)](https://game-narrative.docs.kitefrost.ai/api-reference/characters/cast-distinctiveness-audit-advisory.md): Advisory whole-cast distinctiveness + uniqueness review (Character-Shadow CSH-6). Never blocks; returns notes only.
- [Export NPC](https://game-narrative.docs.kitefrost.ai/api-reference/characters/export-npc.md): Export the NPC in the requested format. Supported formats: 'json' (Unity-compatible, default), 'csv' (dialogue nodes as rows), 'markdown' (readable dialogue graph). Returns 404 if the NPC does not exist.
- [Generate NPC dialogue](https://game-narrative.docs.kitefrost.ai/api-reference/characters/generate-npc-dialogue.md): Start async dialogue-graph generation for the NPC via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Refine NPC](https://game-narrative.docs.kitefrost.ai/api-reference/characters/refine-npc.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Synthesize dialogue audio](https://game-narrative.docs.kitefrost.ai/api-reference/characters/synthesize-dialogue-audio.md): Run NPC dialogue text through the configured TTS pipeline and return a short-lived URL pointing to the rendered MP3. Audio is cached in memory for 5 minutes. When speech synthesis is unavailable the response still returns 200 with `audio_url=null` so callers can degrade gracefully.
- [Run the dev-time consistency check (advisory)](https://game-narrative.docs.kitefrost.ai/api-reference/continuity/run-the-dev-time-consistency-check-advisory.md): On-demand, project-scoped, advisory consistency check over the project's current authored quests and NPCs. Returns a flat, located ConsistencyReport (errors / warnings / info). Read-only - never writes, never blocks generation or export. Free (0 SU): a budget-exhausted tenant still receives the repo…
- [Create dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/create-dialogue-graph.md)
- [Create dialogue node](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/create-dialogue-node.md)
- [Create narrative variable](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/create-narrative-variable.md)
- [Delete dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/delete-dialogue-graph.md)
- [Delete dialogue node](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/delete-dialogue-node.md)
- [Delete narrative variable](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/delete-narrative-variable.md)
- [Export a dialogue graph (JSON, Ink, or Yarn Spinner)](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/export-a-dialogue-graph-json-ink-or-yarn-spinner.md): Synchronous export. The request body `format` selects the serialization:
- [Generate dialogue graph nodes via AI](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/generate-dialogue-graph-nodes-via-ai.md): Start async AI generation for a dialogue graph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. On success, all existing nodes in the graph are replaced with the newly-generated set.
- [Get dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/get-dialogue-graph.md)
- [Get dialogue node](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/get-dialogue-node.md)
- [Get narrative variable](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/get-narrative-variable.md)
- [Import dialogue_graph JSON into a dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/import-dialogue_graph-json-into-a-dialogue-graph.md): Synchronous import. Replaces all existing nodes in the graph with the supplied tree. Node ids in the payload are preserved if they parse as UUIDs; otherwise new UUIDs are minted. Edges are remapped to the new node ids automatically. No LLM call; no Story Units consumed.
- [List dialogue graphs](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/list-dialogue-graphs.md)
- [List dialogue nodes for a graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/list-dialogue-nodes-for-a-graph.md)
- [List narrative variables](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/list-narrative-variables.md)
- [Refine dialogue graph nodes via AI](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/refine-dialogue-graph-nodes-via-ai.md): Refine an existing dialogue graph: the LLM receives the current nodes as context plus a free-text instruction. On completion, all existing nodes are replaced with the refined set.
- [Simulate a walk through the dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/simulate-a-walk-through-the-dialogue-graph.md): Synchronous walker. Starts at the graph's start_node_id (or the first node), follows branches, and applies the supplied variables + choices. Returns a linear transcript and final variable state. Cyclic graphs terminate via max_steps.
- [Update dialogue graph](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/update-dialogue-graph.md)
- [Update dialogue node](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/update-dialogue-node.md)
- [Update narrative variable](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/update-narrative-variable.md)
- [Validate dialogue graph structure](https://game-narrative.docs.kitefrost.ai/api-reference/dialogue/validate-dialogue-graph-structure.md): Synchronous structural check - returns dead-ends (non-'end' nodes with no branches), unreachable nodes (not reachable from the graph's start_node_id), and invalid branch targets (branches pointing at node ids not present in this graph). Empty lists mean a clean graph.
- [Export faction](https://game-narrative.docs.kitefrost.ai/api-reference/factions/export-faction.md): Export the faction in the requested format. Supported formats: 'json' (default) or 'markdown'. Returns 404 if the faction does not exist.
- [Generate faction details](https://game-narrative.docs.kitefrost.ai/api-reference/factions/generate-faction-details.md): Start async AI generation for a Faction entity via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Refine faction details](https://game-narrative.docs.kitefrost.ai/api-reference/factions/refine-faction-details.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Admin: list attachments on a feedback row with short-lived URLs](https://game-narrative.docs.kitefrost.ai/api-reference/feedback/admin:-list-attachments-on-a-feedback-row-with-short-lived-urls.md): Returns the attachments declared on a single ``feedback_raw`` row, each annotated with its current verify state and a 5-minute signed READ URL when (and only when) the post-upload verify worker has marked the attachment ``verified=true AND quarantined=false``. Quarantined or still-pending entries ar…
- [Feedback envelope JSON Schema (C-FB1)](https://game-narrative.docs.kitefrost.ai/api-reference/feedback/feedback-envelope-json-schema-c-fb1.md): Returns the JSON Schema of :class:`FeedbackSubmission` so that agent-card discovery flows can fetch the canonical feedback shape without scraping docs.
- [Look up feedback by feedback_id](https://game-narrative.docs.kitefrost.ai/api-reference/feedback/look-up-feedback-by-feedback_id.md): Look up a feedback signal by its short feedback_id token. Support agents can use this to quickly find feedback context.
- [Mint a signed PUT URL for a screenshot attachment (C-FBSA2)](https://game-narrative.docs.kitefrost.ai/api-reference/feedback/mint-a-signed-put-url-for-a-screenshot-attachment-c-fbsa2.md): Issues a Supabase Storage signed PUT URL for a single screenshot attachment. The customer's browser PUTs the bytes directly to object storage; this endpoint never sees the body. Server pre-validates MIME + size against C-FBSA1 caps so a wasted upload fails fast.
- [Submit feedback envelope (C-FB1)](https://game-narrative.docs.kitefrost.ai/api-reference/feedback/submit-feedback-envelope-c-fb1.md): Canonical feedback ingestion endpoint. Accepts any of the three C-FB1 signals (``error_telemetry``, ``bug_report``, ``quality_rating``) in a single stable envelope shape. ``error_telemetry`` allows anonymous submission; all other signals require a valid bearer token.
- [Handle Http Get](https://game-narrative.docs.kitefrost.ai/api-reference/handle-http-get.md)
- [Handle Http Post](https://game-narrative.docs.kitefrost.ai/api-reference/handle-http-post.md)
- [Liveness check](https://game-narrative.docs.kitefrost.ai/api-reference/health/liveness-check.md): Returns the overall liveness status of the API. `status` is `ok` when all backing services are reachable and `degraded` when at least one is not. Component-level detail is intentionally not exposed on the public endpoint - operators should call `GET /v1/admin/health` (ADMIN_SECRET-gated) for the per…
- [Readiness probe](https://game-narrative.docs.kitefrost.ai/api-reference/health/readiness-probe.md): Kubernetes-style readiness probe. Returns `200` once all core services are initialised, `503` until then. Use this to gate traffic during cold-start. The HTTP status code is the load-bearing signal; the body is intentionally minimal and does not name internal components.
- [Export item](https://game-narrative.docs.kitefrost.ai/api-reference/items/export-item.md): Export the item in the requested format. Supported formats: 'json' (default) or 'markdown'. Returns 404 if the item does not exist.
- [Generate item details](https://game-narrative.docs.kitefrost.ai/api-reference/items/generate-item-details.md): Start async AI generation for an Item entity via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Refine item details](https://game-narrative.docs.kitefrost.ai/api-reference/items/refine-item-details.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Bootstrap: create initial API key pair](https://game-narrative.docs.kitefrost.ai/api-reference/keys/bootstrap:-create-initial-api-key-pair.md): Create the first secret (`sk_...`) and publishable (`pk_...`) key pair for a tenant. Uses `SETUP_TOKEN` env-var authentication instead of an API key, so it can be called before any keys exist. Both full key values are returned **once** - store them securely. Disable or rotate the `SETUP_TOKEN` after…
- [Create API key](https://game-narrative.docs.kitefrost.ai/api-reference/keys/create-api-key.md): Create a new publishable (`pk`) or secret (`sk`) API key. The full key value is returned **once** in this response and cannot be retrieved again - store it securely. Requires scope: `api-keys:manage`.
- [List API keys](https://game-narrative.docs.kitefrost.ai/api-reference/keys/list-api-keys.md): List all API keys for the tenant. Key prefixes and metadata are returned - the full key value is never exposed after creation.
- [Per-key usage rollup](https://game-narrative.docs.kitefrost.ai/api-reference/keys/per-key-usage-rollup.md): Rolled-up request / token / error counts for a specific API key. Aggregated nightly from runtime_events into key_usage_daily (migration 043). A freshly minted key legitimately has no rollup rows yet - the endpoint returns zeros in that case rather than 404.
- [Revoke API key](https://game-narrative.docs.kitefrost.ai/api-reference/keys/revoke-api-key.md): Permanently revoke an API key identified by its prefix. Revoked keys are rejected immediately by the auth middleware. Requires scope: `api-keys:manage`.
- [Rotate API key](https://game-narrative.docs.kitefrost.ai/api-reference/keys/rotate-api-key.md): Revoke the existing key and issue a new one with identical settings (same tenant, project, type, and scopes). The new full key is returned once - store it immediately.
- [Export location](https://game-narrative.docs.kitefrost.ai/api-reference/locations/export-location.md): Export the location in the requested format. Supported formats: 'json' (default) or 'markdown'. Returns 404 if the location does not exist.
- [Generate location details](https://game-narrative.docs.kitefrost.ai/api-reference/locations/generate-location-details.md): Start async AI generation for a Location entity via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Refine location details](https://game-narrative.docs.kitefrost.ai/api-reference/locations/refine-location-details.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Generate the project's lore-bible (priced)](https://game-narrative.docs.kitefrost.ai/api-reference/lore-bible/generate-the-projects-lore-bible-priced.md): On-demand, project-scoped synthesis of the project's current authored quests and NPCs into a single, exportable LoreBible (a derived, regenerable projection - never the source of truth). Read-only: no Notes/entity writes occur during generation. Paid generation: charges `lore_bible_generate` (2.0 SU…
- [Create scene](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/create-scene.md): Create a Scene (session) with an optional title + synopsis, linking NPCs and encounters for a specific session number. Starts in `brainstorm` status. Use `/sessions/{session_id}/generate` to generate narrative content.
- [Delete scene](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/delete-scene.md): Permanently delete a Scene (session) - the game-narrative pack's label for the underlying ``sessions`` entity. Returns 404 if the scene does not exist or belongs to a different tenant/project.
- [Export scene](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/export-scene.md): Export the scene in the requested format. Supported formats: 'json' (default) or 'markdown'. Returns 404 if the scene does not exist.
- [Generate scene details](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/generate-scene-details.md): Start async AI generation for a Scene (session) via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Get scene detail](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/get-scene-detail.md): Fetch a Scene (session) by id. Returns the full SessionRepo row including the v0.6 `data` JSONB column (key_events / tone / tags / mentioned_location_ids). Returns 404 if the scene does not exist or belongs to a different tenant.
- [Refine scene details](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/refine-scene-details.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Update scene](https://game-narrative.docs.kitefrost.ai/api-reference/scenes/update-scene.md): Partial-update a Scene's mutable fields (title, synopsis, project_context, npc_ids, encounter_ids, data). Each field is independently optional; None means 'leave unchanged' (not 'set to NULL'). Returns 404 if the scene does not exist or belongs to a different tenant/project.
- [Bulk reject seeds (transition to REJECTED)](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/bulk-reject-seeds-transition-to-rejected.md): Bulk reject: for each supplied seed UUID, transition ``TRIAGED → REJECTED`` via ``SeedLifecycleStore.transition``. REJECTED is a terminal state that also writes the dead-seed registry (C-SSD §2.2) so the same premise will not regenerate. Per-item failures are isolated.
- [Bulk validate (promote) seeds to this project](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/bulk-validate-promote-seeds-to-this-project.md): Bulk version of ``POST /seeds/{seed_id}/promote``. For each supplied seed UUID: resolve tenant-scoped, then dispatch through ``IdeaPoolAPI.assign`` (canonical promote - R127-C6) to transition ``TRIAGED → PROMOTED`` and stamp ``promoted_project_id``. Per-item failures are isolated; the batch returns…
- [Get seed](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/get-seed.md): Fetch one seed by UUID or slug. Returns 404 if not found or cross-tenant.
- [List seeds](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/list-seeds.md): List story seeds for the project with optional lifecycle / provenance / search filters and cursor-style pagination.
- [Promote seed to the project](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/promote-seed-to-the-project.md): Transition the seed ``TRIAGED → PROMOTED`` and stamp the ``promoted_project_id`` (canonical promote per R4 R127-C6: ``promote = IdeaPoolAPI.assign()``). Idempotent for re-promote to the SAME project.
- [Soft-delete seed (transition to DEAD)](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/soft-delete-seed-transition-to-dead.md): Soft-delete the seed by transitioning to ``dead``. The row remains in ``story_seeds`` for audit; the lifecycle gate rejects re-use. Hard-delete is not exposed via REST.
- [Transition seed lifecycle state](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/transition-seed-lifecycle-state.md): Apply a lifecycle transition (e.g. ``raw → triaged``, ``triaged → rejected``). Legal edges enforced by the lifecycle store; illegal edges return 409.
- [Trigger on-demand seed discovery](https://game-narrative.docs.kitefrost.ai/api-reference/seeds/trigger-on-demand-seed-discovery.md): Enqueue an on-demand discovery run for this project via the scheduler. Returns immediately with a ``job_id``; the run executes async.
- [Create state snapshot](https://game-narrative.docs.kitefrost.ai/api-reference/sessions/create-state-snapshot.md): Manually checkpoint the current RuntimeState for a session. Snapshots can be used for rollback, replay, or debugging. Returns 404 if no active state is found for the session.
- [Poll session status](https://game-narrative.docs.kitefrost.ai/api-reference/sessions/poll-session-status.md): Poll the status of an async generation session. Possible statuses: `running`, `awaiting_human`, `completed`, `error`. When `awaiting_human`, the response includes `hitl_context` with proposals. When `completed` or `error`, the response includes the `result` payload.
- [Stream session events (SSE)](https://game-narrative.docs.kitefrost.ai/api-reference/sessions/stream-session-events-sse.md): Open a Server-Sent Events stream for a generation session. Emits typed events as session state changes:
- [Submit HITL response](https://game-narrative.docs.kitefrost.ai/api-reference/sessions/submit-hitl-response.md): Submit a human-in-the-loop (HITL) response to resume a paused generation session. Actions: `select` (pick a proposal by index), `refine` (provide a refinement dict), `skip`, or `abort`. Returns 404 if there is no pending HITL request for the given session.
- [Create story arc](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/create-story-arc.md): Create a Story Arc (quest) - the game-narrative pack's label for the underlying ``quests`` entity. Starts in ``offered`` status by default; non-D&D systems may use a different lifecycle.
- [Delete story arc](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/delete-story-arc.md): Permanently delete a Story Arc (quest) - the game-narrative pack's label for the underlying ``quests`` entity. Returns 404 if the story arc does not exist or belongs to a different tenant/project.
- [Export quest](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/export-quest.md): Export the quest in the requested format. Supported formats: 'json' (default) or 'markdown'. Returns 404 if the quest does not exist.
- [Generate quest details](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/generate-quest-details.md): Start async AI generation for a Quest via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Get quest detail](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/get-quest-detail.md): Fetch a Quest by id (Game Narrative pack). Returns the full QuestRepo row. Returns 404 if the quest does not exist or belongs to a different tenant.
- [Refine quest details](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/refine-quest-details.md): Re-trigger the DRAFT phase with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Requires the `runtime_generation` feature flag to be enabled for the tenant.
- [Update quest](https://game-narrative.docs.kitefrost.ai/api-reference/story-arcs/update-quest.md): Partial-update a Quest. Each field is independently optional; None means 'leave unchanged' (not 'set to NULL'). Returns 404 if the quest does not exist or belongs to a different tenant/project.
- [Delete webhook](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/delete-webhook.md): Permanently delete a webhook subscription. No further events will be delivered. Requires scope: `webhooks:manage`.
- [List delivery attempts](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/list-delivery-attempts.md): Return recent delivery attempts for a webhook (newest first).
- [List webhooks](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/list-webhooks.md): Return all webhook subscriptions for the project, with delivery-status fields.
- [Register webhook](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/register-webhook.md): Register an HTTPS endpoint to receive event notifications. Deliveries are signed with HMAC-SHA256 over `{timestamp}.{body}`; verify the `X-Webhook-Signature` header. The URL is validated against the SSRF blocklist before registration. Requires scope: `webhooks:manage`.
- [Rotate signing secret](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/rotate-signing-secret.md): Mint a new HMAC-SHA256 signing secret for this webhook. The new secret is returned ONCE and replaces the old one immediately. Requires scope: `webhooks:manage`.
- [Send test event](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/send-test-event.md): Fire a single `webhook.test` event through the regular delivery path so you can verify your receiver. The response reports the HTTP status the receiver returned (or null on a network error).
- [Update webhook](https://game-narrative.docs.kitefrost.ai/api-reference/webhooks/update-webhook.md): Partial-update a webhook subscription. Setting `active: true` re-enables an auto-disabled webhook. Requires scope: `webhooks:manage`.
- [Game Narrative API](https://game-narrative.docs.kitefrost.ai/index.md): Author your game's cast, quests, and lore - then run a pre-ship continuity audit and export it into your build.
- [Quickstart](https://game-narrative.docs.kitefrost.ai/quickstart.md): Author a cast, audit it for continuity, and export it into your build - in under 5 minutes.

## OpenAPI Specs

- [openapi](https://game-narrative.docs.kitefrost.ai/openapi.json)