# KiteFrost - TTRPG GM API ## Docs - [Authentication](https://ttrpg.docs.kitefrost.ai/_shared/core-concepts/auth.md): Authenticate API requests using API keys with scoped access control. - [Billing](https://ttrpg.docs.kitefrost.ai/_shared/core-concepts/billing.md): Understand pricing tiers, Story Units, and how billing works. - [Bring Your Own Key (BYOK)](https://ttrpg.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://ttrpg.docs.kitefrost.ai/_shared/core-concepts/webhooks.md): Receive real-time event notifications via HMAC-SHA256 signed HTTP POST deliveries. - [API Reference](https://ttrpg.docs.kitefrost.ai/api-reference.md): Complete reference for all KiteFrost TTRPG GM API endpoints. - [Create account](https://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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. - [Admin: list attachments on a feedback row with short-lived URLs](https://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.docs.kitefrost.ai/api-reference/handle-http-get.md) - [Handle Http Post](https://ttrpg.docs.kitefrost.ai/api-reference/handle-http-post.md) - [Liveness check](https://ttrpg.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://ttrpg.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. - [Bootstrap: create initial API key pair](https://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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. - [Bulk reject seeds (transition to REJECTED)](https://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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 encounter](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/create-encounter.md): Create a TTRPG encounter record with difficulty, party info, and optional world context. The encounter starts in `brainstorm` status. Use `/encounters/{encounter_id}/generate` to generate content. - [Create note](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/create-note.md): Create a free-form Markdown note. `note_type` is an optional free-text discriminator (suggested snake_case values: `lore`, `rumour`, `house_rule`, `recap`, `secret`). - [Create quest](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/create-quest.md): Create a TTRPG quest record. Starts in `offered` status by default; non-D&D systems may use a different lifecycle. - [Create session](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/create-session.md): Create a TTRPG 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 encounter](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/delete-encounter.md): Permanently delete an encounter. Session plans that referenced the encounter via `encounter_ids` retain the dangling reference; the dashboard surfaces deleted encounters as such at read time. - [Delete note](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/delete-note.md): Permanently delete a note record. - [Delete quest](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/delete-quest.md): Permanently delete a quest record. - [Delete session](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/delete-session.md): Permanently delete a session record. - [Generate encounter content](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/generate-encounter-content.md): Async generation of encounter content (monsters, tactics, rewards) via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. - [Generate quest content](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/generate-quest-content.md): Async AI generation of quest content (summary, objectives, hooks, rewards) via CoreRuntimeGraph. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. Reuses the shared QuestRepo + quest-generation engine (a quest is pack-agnostic). - [Generate quick NPC dialogue](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/generate-quick-npc-dialogue.md): Synchronous NPC dialogue generation for real-time use (e.g. Foundry VTT). Makes a single LLM call (economy tier, quick-dialogue pack) and returns within 1-3 seconds. No session creation or polling required. Requires a valid Bearer token. - [Generate session content](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/generate-session-content.md): Async generation of full session narrative (hooks, scenes, NPC motivations) via CoreRuntimeGraph. Returns a `runtime_session_id` (HTTP 202). Poll `GET /v1/sessions/{runtime_session_id}/status` for completion. - [Get encounter](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/get-encounter.md): Fetch a single encounter by ID. Returns 404 if not found or owned by a different project. - [Get note](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/get-note.md): Fetch a single note by ID. Returns 404 if not found or owned by a different project. - [Get quest](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/get-quest.md): Fetch a single quest by ID. Returns 404 if not found or owned by a different project. - [Get session](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/get-session.md): Fetch a single session by ID. Returns 404 if not found or owned by a different project. - [Import a Foundry/Roll20 export into the project (persist)](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/import-a-foundryroll20-export-into-the-project-persist.md): Re-parse a Foundry VTT module or Roll20 export SERVER-SIDE and create the NPCs, scenes, and journal notes as project entities in one transaction. Idempotent (skip-existing) on re-import. Pro tier; counts against the entity cap, no Story Units. - [List encounters](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/list-encounters.md): Return all encounters for the specified project. - [List notes](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/list-notes.md): Return all notes for the specified project, sorted with pinned notes first then by most-recent update. - [List quests](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/list-quests.md): Return all quests for the specified project. - [List sessions](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/list-sessions.md): Return all sessions for the specified project. - [Parse a Foundry/Roll20 VTT export back into KiteFrost content](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/parse-a-foundryroll20-vtt-export-back-into-kitefrost-content.md): Reverse of the VTT export. Accepts a previously-exported Foundry module or Roll20 JSON and returns a neutral KiteFrost structure (adventure metadata, NPCs, scenes, journal). Parse-only: nothing is persisted - the caller decides what to create. Pro tier and above. - [Refine quest content](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/refine-quest-content.md): Re-generate a quest with a refinement instruction injected as a constraint. Returns a `session_id` immediately (HTTP 202). Poll `GET /v1/sessions/{session_id}/status` for completion. - [Update encounter](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/update-encounter.md): Partial update of encounter fields. Accepts description, difficulty, party_level, party_size, game_system, project_context, environment. Generated `data` JSONB is preserved - re-generate the encounter if you want fresh content. - [Update note](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/update-note.md): Partial update of note fields. Accepts title, body, note_type, pinned, tags. - [Update quest](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/update-quest.md): Partial update of quest fields. Accepts title, summary, status, quest_giver_npc_id, location_id, reward_item_ids, objectives, notes, completed_session_id, tags. - [Update session](https://ttrpg.docs.kitefrost.ai/api-reference/ttrpg/update-session.md): Partial update of mutable session fields. Accepts title, synopsis, project_context, npc_ids, encounter_ids. Each field is independently optional; an omitted field is left unchanged. `session_number` is set once at create and is not patchable. - [Delete webhook](https://ttrpg.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://ttrpg.docs.kitefrost.ai/api-reference/webhooks/list-delivery-attempts.md): Return recent delivery attempts for a webhook (newest first). - [List webhooks](https://ttrpg.docs.kitefrost.ai/api-reference/webhooks/list-webhooks.md): Return all webhook subscriptions for the project, with delivery-status fields. - [Register webhook](https://ttrpg.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://ttrpg.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://ttrpg.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://ttrpg.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`. - [TTRPG GM API](https://ttrpg.docs.kitefrost.ai/index.md): AI-powered encounter generation, session planning, and living project management for tabletop RPG game masters. - [Quickstart](https://ttrpg.docs.kitefrost.ai/quickstart.md): Create your first encounter and generate a full session plan in under 5 minutes. ## OpenAPI Specs - [openapi](https://ttrpg.docs.kitefrost.ai/openapi.json)