> ## Documentation Index > Fetch the complete documentation index at: https://game-narrative.docs.kitefrost.ai/llms.txt > Use this file to discover all available pages before exploring further. # Set BYOK key > 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 treatment cohort of the BYOK experiment may also set a key after a successful live probe (KF_FREE_BYOK_COHORT). ## OpenAPI ````yaml /openapi.json put /v1/projects/{project_id}/byok openapi: 3.1.0 info: title: KiteFrost description: > ## KiteFrost API Persistent memory and queryable context for AI-powered products. Create projects, track entities and relationships, record events, and query context - stateful AI you can audit, with durable state across sessions, agents, and tools. ### What you get - **Persistent projects** - entities, relationships, and events live across sessions - **Context queries** - ask "what does this entity know right now?" and get a consistent answer - **Event sourcing** - every state transition is recorded and replayable - **BYOK** - bring your own LLM provider key per project ### Authentication All routes (except `/health` and `/ready`) require an `Authorization: Bearer ` header. Use publishable keys (`pk_...`) for read-only client calls and secret keys (`sk_...`) for write / generation / admin operations. ### Async generation pattern 1. Call a `POST .../generate` endpoint → receive `{"session_id": "...", "status": "accepted"}` 2. Poll `GET /v1/sessions/{session_id}/status` until `status` is `completed` or `error` 3. If `status == "awaiting_human"`, submit a response via `POST /v1/sessions/{session_id}/respond` version: 1.0.0 servers: - url: https://api.kitefrost.ai description: Production security: [] tags: - name: projects description: >- Project, entity, and event management: create projects, upsert entities, record events, query context, and generate content with project context. - name: npcs description: >- NPC (non-player character) CRUD, dialogue generation, and export. Supports the brainstorm → draft lifecycle. - name: sessions description: >- Poll generation session status, submit HITL responses, and create manual state snapshots for rollback/replay. - name: events description: >- Lightweight player-event ingestion path. Accepts player choices, quest triggers, and custom events without spinning up a full session. - name: players description: >- Player data management: GDPR erasure (right to be forgotten), data export (right of access), player context, facts, quests, and preferences. - name: keys description: >- API key lifecycle management: create publishable / secret keys, list, revoke, and rotate keys with scoped permissions. - name: byok description: >- Bring Your Own Key (BYOK) management. Store, revoke, and check the status of a tenant-supplied LLM provider API key per project. - name: ttrpg description: >- TTRPG GM pack endpoints: encounter CRUD and generation, session CRUD and async generation. - name: chapters description: >- Book Author pack endpoints: chapter CRUD, async generation, and markdown export. - name: ideas description: >- Idea Generation Engine: generate novel story ideas, list, fetch, mutate, blend, assign, and archive ideas. - name: seeds description: >- Story-seed discovery operations: list, detail, on-demand generate, promote (canonical assign per R127-C6), lifecycle transition, and soft-delete. - name: feedback description: >- Collect explicit feedback signals (thumbs, rating, A/B choice) and retrieve aggregated insights for model improvement. - name: webhooks description: >- Webhook subscription management: register HTTPS endpoints for async event delivery, list, delete, and test HMAC signatures. - name: audio description: >- Audio Story pack endpoints: async audio-story generation, list, fetch, and export (SSML / manifest / audio). - name: billing description: >- Billing integration: checkout, portal, subscription management, tier info, and usage stats. - name: demo description: >- Public demo endpoint - try the KiteFrost from the landing page without signing up. Limited to 5 messages per session and 20 requests per IP per hour. No authentication required. - name: health description: >- Health and readiness probes for load-balancer and orchestrator liveness checks. - name: score description: >- Content scoring: run craft-layer quality metrics (C10-C15) and humanness scoring (H2) on arbitrary text to get a per-dimension quality breakdown. - name: resilience description: >- Resilience Score: aggregate compliance, training, and education pack results into an overall project resilience score (0-100) with per-dimension breakdown and trend. - name: compliance-exercises description: >- Compliance Tabletop pack endpoints: create exercises, generate scenarios, evaluate participant responses, and produce after-action reviews. - name: training description: >- Training Simulation pack endpoints: create scenarios, generate branching scenario trees, and assess learner competency. - name: support description: >- Support Orchestration pack endpoints: create ticket contexts, generate response drafts, and escalate tickets. - name: story_bible description: >- Story Bible: assemble the Knowledge Graph into a structured canonical reference of characters, locations, events, factions, and items with their relationships. Supports point-in-time snapshots via at_seq. - name: gamification description: >- Gamification endpoints: player points, earned achievements, leaderboards with configurable visibility and weekly reset, and activity streaks. - name: conversations description: >- Multi-player conversation lifecycle: create, join, submit input, stream events (SSE), leave, and get conversation state. - name: images description: >- Image generation: create AI-generated images from text prompts with pack-configurable presets, safety controls, and audit logging. paths: /v1/projects/{project_id}/byok: put: tags: - byok summary: Set BYOK key description: >- 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 treatment cohort of the BYOK experiment may also set a key after a successful live probe (KF_FREE_BYOK_COHORT). operationId: set_byok_key_v1_projects__project_id__byok_put requestBody: content: application/json: schema: $ref: '#/components/schemas/SetBYOKRequest' required: true responses: '200': description: BYOK key stored content: application/json: schema: $ref: '#/components/schemas/BYOKStatusResponse' '401': description: Invalid or missing API key '402': description: BYOK requires a paid plan - upgrade to Pro or higher '403': description: Forbidden - API key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/APIError' example: error: Forbidden code: forbidden request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 message: Your API key does not have the required scope. doc_url: https://docs.kitefrost.ai/errors/forbidden '404': description: Not Found - resource does not exist or is not accessible. content: application/json: schema: $ref: '#/components/schemas/APIError' example: error: Not found code: not_found request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 message: The requested resource does not exist. doc_url: https://docs.kitefrost.ai/errors/not_found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded '500': description: >- Internal Server Error - unexpected server-side failure. Retry with exponential back-off. content: application/json: schema: $ref: '#/components/schemas/APIError' example: error: Internal server error code: internal_error request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 message: An unexpected error occurred. doc_url: https://docs.kitefrost.ai/errors/internal_error components: schemas: SetBYOKRequest: properties: api_key: type: string minLength: 1 title: Api Key description: LLM provider API key provider: type: string title: Provider description: LLM provider name (e.g. openai, anthropic) default: openai provider_url: anyOf: - type: string - type: 'null' title: Provider Url description: >- Optional custom LLM provider base URL (e.g. for self-hosted OpenAI-compatible endpoints). Must be an HTTPS URL that passes SSRF validation - internal network addresses, cloud metadata endpoints, and non-HTTPS schemes are rejected. model_preference: anyOf: - type: string - type: 'null' title: Model Preference description: >- Optional specific model the tenant prefers from their provider (a provider model id). Used as a hint when routing - if the model cannot satisfy the request's capability requirements, normal model selection is applied. allow_platform_fallback: type: boolean title: Allow Platform Fallback description: >- When ``False``, requests that cannot be satisfied by the tenant's BYOK key fail with an explicit error instead of silently falling back to the platform's shared key. Defaults to ``True`` (permissive) to preserve current behavior. default: true type: object required: - api_key title: SetBYOKRequest description: PUT /v1/projects/{project_id}/byok BYOKStatusResponse: properties: project_id: type: string title: Project Id has_key: type: boolean title: Has Key source: type: string title: Source provider: anyOf: - type: string - type: 'null' title: Provider key_preview: anyOf: - type: string - type: 'null' title: Key Preview model_preference: anyOf: - type: string - type: 'null' title: Model Preference allow_platform_fallback: type: boolean title: Allow Platform Fallback default: true probe_status: anyOf: - type: string - type: 'null' title: Probe Status model_warning: anyOf: - type: string - type: 'null' title: Model Warning type: object required: - project_id - has_key - source title: BYOKStatusResponse description: BYOK key status (never exposes the actual key). APIError: properties: error: type: string title: Error code: type: string title: Code request_id: anyOf: - type: string - type: 'null' title: Request Id detail: anyOf: - additionalProperties: true type: object - type: 'null' title: Detail message: anyOf: - type: string - type: 'null' title: Message doc_url: anyOf: - type: string - type: 'null' title: Doc Url feedback_id: anyOf: - type: string - type: 'null' title: Feedback Id type: object required: - error - code title: APIError example: code: not_found doc_url: https://docs.kitefrost.ai/errors/not_found error: Not found message: >- The requested resource does not exist or you do not have permission to access it. Verify the resource ID and your API key scopes. request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````