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

# Update encounter

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



## OpenAPI

````yaml /openapi.json patch /v1/projects/{project_id}/ttrpg-gm/encounters/{encounter_id}
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/{encounter_id}:
    patch:
      tags:
        - ttrpg
      summary: Update encounter
      description: >-
        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.
      operationId: >-
        update_encounter_v1_projects__project_id__ttrpg_gm_encounters__encounter_id__patch
      parameters:
        - name: encounter_id
          in: path
          required: true
          schema:
            type: string
            title: Encounter Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEncounterRequest'
      responses:
        '200':
          description: Encounter updated
          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: Encounter not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Too Many Requests - rate limit exceeded. Retry after the
            'Retry-After' header interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                error: Rate limit exceeded
                code: rate_limited
                request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                message: You have exceeded the rate limit for your plan.
                doc_url: https://docs.kitefrost.ai/errors/rate_limited
        '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:
    UpdateEncounterRequest:
      properties:
        description:
          anyOf:
            - type: string
              maxLength: 500
              minLength: 1
            - type: 'null'
          title: Description
        difficulty:
          anyOf:
            - type: string
              pattern: ^(easy|medium|hard|deadly)$
            - type: 'null'
          title: Difficulty
        party_level:
          anyOf:
            - type: integer
              maximum: 20
              minimum: 1
            - type: 'null'
          title: Party Level
        party_size:
          anyOf:
            - type: integer
              maximum: 10
              minimum: 1
            - type: 'null'
          title: Party Size
        game_system:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Game System
        project_context:
          anyOf:
            - type: string
              maxLength: 50000
            - type: 'null'
          title: Project Context
        environment:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Environment
      type: object
      title: UpdateEncounterRequest
      description: |-
        PATCH /v1/projects/{project_id}/encounters/{encounter_id}.

        Every field is optional - caller sends only the keys they intend to
        change. Generated `data` JSONB is preserved across the update; to
        refresh content, re-issue ``POST /encounters/{id}/generate``.
      example:
        description: Ambush by bandits, now with a goblin lieutenant
        difficulty: deadly
    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

````