> ## 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. # Batch create NPCs > Create multiple NPCs in one call (max 50). ## OpenAPI ````yaml /openapi.json post /v1/projects/{project_id}/game-narrative/characters/batch 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}/game-narrative/characters/batch: post: tags: - characters summary: Batch create NPCs description: Create multiple NPCs in one call (max 50). operationId: >- batch_create_npcs_v1_projects__project_id__game_narrative_characters_batch_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchCreateNPCsRequest' required: true responses: '201': description: NPCs created successfully content: application/json: schema: items: $ref: '#/components/schemas/NPCResponse' type: array title: >- Response Batch Create Npcs V1 Projects Project Id Game Narrative Characters Batch Post '401': description: Invalid or missing API key '403': description: Insufficient scope - requires `npcs:write` '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 (e.g. too many NPCs) '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: BatchCreateNPCsRequest: properties: npcs: items: $ref: '#/components/schemas/CreateNPCRequest' type: array maxItems: 50 minItems: 1 title: Npcs description: List of NPC definitions to create (max 50) type: object required: - npcs title: BatchCreateNPCsRequest description: POST /v1/projects/{project_id}/characters/batch NPCResponse: properties: npc_id: type: string title: Npc Id description: Unique NPC identifier (UUID) name: type: string title: Name description: Display name of the NPC project_id: type: string title: Project Id description: Project this NPC belongs to status: type: string title: Status description: 'Lifecycle status: brainstorm | draft | final' default: brainstorm session_id: anyOf: - type: string - type: 'null' title: Session Id description: Active generation session ID, if any created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: ISO 8601 creation timestamp portrait_url: anyOf: - type: string - type: 'null' title: Portrait Url description: >- URL of the generated character portrait when `generate_portrait=true` was passed and image generation succeeded. Null otherwise. type: object required: - npc_id - name - project_id title: NPCResponse description: NPC resource representation. example: created_at: '2026-01-01T12:00:00Z' name: Aria Shadowstep npc_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 project_id: proj_abc123 session_id: sess_xyz789 status: brainstorm 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 CreateNPCRequest: properties: npc_name: type: string maxLength: 100 minLength: 1 title: Npc Name description: Display name of the NPC npc_role: anyOf: - type: string - type: 'null' title: Npc Role description: Role in the story project (e.g. 'merchant', 'villain') project_context: anyOf: - type: string - type: 'null' title: Project Context description: Brief description of the project/setting personality_hints: items: type: string type: array title: Personality Hints description: Trait keywords that shape the NPC's personality player_actions: items: type: string type: array title: Player Actions description: Actions the player can take with this NPC generate_portrait: type: boolean title: Generate Portrait description: >- When true, generate a fantasy character portrait via the configured image provider. Returns the portrait URL on the NPCResponse. Silently degrades to no image if image generation is unavailable or the prompt is blocked by content safety. default: false type: object required: - npc_name title: CreateNPCRequest description: POST /v1/projects/{project_id}/characters example: npc_name: Aria Shadowstep npc_role: merchant personality_hints: - cunning - secretive - charming player_actions: - talk - trade - persuade project_context: A bustling port city in a high-fantasy setting ````