> ## Documentation Index
> Fetch the complete documentation index at: https://ttrpg.docs.kitefrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create encounter

> 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.



## OpenAPI

````yaml /openapi.json post /v1/projects/{project_id}/ttrpg-gm/encounters
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
    <key>` 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}/ttrpg-gm/encounters:
    post:
      tags:
        - ttrpg
      summary: Create encounter
      description: >-
        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.
      operationId: create_encounter_v1_projects__project_id__ttrpg_gm_encounters_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEncounterRequest'
        required: true
      responses:
        '201':
          description: Encounter created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncounterResponse'
        '401':
          description: Invalid or missing API key
        '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:
    CreateEncounterRequest:
      properties:
        description:
          type: string
          maxLength: 500
          minLength: 1
          title: Description
          description: Brief description of the encounter scenario
        difficulty:
          type: string
          pattern: ^(easy|medium|hard|deadly)$
          title: Difficulty
          description: 'Encounter difficulty: easy | medium | hard | deadly'
          default: medium
        party_level:
          type: integer
          maximum: 20
          minimum: 1
          title: Party Level
          description: Average party level (1-20)
          default: 5
        party_size:
          type: integer
          maximum: 10
          minimum: 1
          title: Party Size
          description: Number of players in the party
          default: 4
        game_system:
          type: string
          maxLength: 50
          title: Game System
          description: Game system (e.g. dnd5e, pathfinder2e)
          default: dnd5e
        project_context:
          anyOf:
            - type: string
              maxLength: 50000
            - type: 'null'
          title: Project Context
          description: Project or setting description
        environment:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Environment
          description: Physical environment (e.g. dungeon, forest, city)
        generate_token:
          type: boolean
          title: Generate Token
          description: >-
            When true, generate a top-down battle-map / token image via the
            configured image provider. Returns the URL on the EncounterResponse.
            Silently degrades to no image if no provider is configured or the
            prompt is blocked by content safety.
          default: false
      type: object
      required:
        - description
      title: CreateEncounterRequest
      description: POST /v1/projects/{project_id}/encounters
      example:
        description: Ambush by bandits on the mountain pass
        difficulty: hard
        environment: mountain_pass
        game_system: dnd5e
        party_level: 5
        party_size: 4
        project_context: A treacherous mountain range in a dark fantasy project
    EncounterResponse:
      properties:
        encounter_id:
          type: string
          title: Encounter Id
          description: Unique encounter identifier
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: >-
            Human-readable slug for the URL
            (`/projects/<slug>/encounters/<external_id>`). Derived from
            `description` at create time and immutable. May be null on rows that
            pre-date migration 102 backfill - frontend falls back to `id`. See
            docs/conventions/dashboard-slug-urls.md.
        description:
          type: string
          title: Description
          description: Brief description of the encounter scenario
        project_id:
          type: string
          title: Project Id
          description: Project this encounter belongs to
        status:
          type: string
          title: Status
          description: 'Lifecycle status: brainstorm | draft | final'
          default: brainstorm
        difficulty:
          type: string
          title: Difficulty
          description: Encounter difficulty level
          default: medium
        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
        token_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Token Url
          description: >-
            URL of a generated battle-map / token image when
            `generate_token=true` was passed and image generation succeeded.
            Null otherwise.
      type: object
      required:
        - encounter_id
        - description
        - project_id
      title: EncounterResponse
      description: Encounter resource representation.
      example:
        created_at: '2026-01-01T12:00:00Z'
        description: Ambush by bandits on the mountain pass
        difficulty: hard
        encounter_id: enc_abc123
        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
    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

````