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

# Update a character

> Patch metadata + brain fields (persona, greeting, lore, voiceId, stances, intro, free). Graph/stance-node edits go through the /v1/worlds/{id}/* endpoints.



## OpenAPI

````yaml /alakazam-v1.yaml patch /v1/characters/{id}
openapi: 3.1.0
info:
  title: Alakazam — Programmable Worlds API
  version: '1.0'
  description: >
    **Alakazam is the programmable worlds API.** Generate playable, AI-rendered
    worlds from a prompt or an image, program their logic, and embed them in
    your own products and games.


    A world is *programmable*: a live graph of states and events you generate,
    then read, edit, fork, drive, and react to through the API. Two surfaces: a
    **Creation API** (generate, read, manage, fork worlds) and a **Runtime/Embed
    API** (mint short-lived session tokens your end-users' browsers use to boot
    an embedded world).


    **Authentication.** Two schemes. Management endpoints (`/v1/apps*`) use your
    Supabase user session. Data endpoints use an **API key** issued per app:
    `pk_…` (publishable, browser-safe, read + embed) and `sk_…` (secret,
    server-only, create worlds + mint sessions). Never ship a secret key to a
    browser.


    **Usage & quota.** Generations and session mints are metered per app and
    reserved before any GPU spend; exceeding the daily quota returns `402`.
servers:
  - url: https://api.alakazam.gg
    description: Production (placeholder — set to your conjure-service host)
security: []
tags:
  - name: Apps & Keys
    description: >-
      Create apps (tenants) and manage API keys. Authenticated with your user
      session.
  - name: Worlds
    description: >-
      Create, read, manage, and fork SMWorld games. Authenticated with an API
      key.
  - name: Graph editing
    description: >
      Read and program a world's graph — states (nodes), events (edges), and the
      entrance — with deterministic CRUD, a batch op vocabulary, a
      natural-language kernel-agent edit, and the kernel validate/lint gate.
      Every write is validated fail-closed before it persists. Authenticated
      with an API key.
  - name: Versions
    description: >
      Snapshot, branch, check out, and diff a world's graph. Versions form a
      branching tree of full snapshots; a HEAD pointer tracks the working graph.
      Authenticated with an API key.
  - name: Characters
    description: >
      Create, manage, and talk to characters — a SMWorld subtype that pairs a
      stance-graph with a "brain" (persona, lore, voice). CRUD is authenticated
      with an API key; the live talk turn (/say) and voice (/tts) are called
      from the browser with a short-lived session token.
  - name: Sessions
    description: Mint short-lived runtime tokens for embedding a world.
  - name: Usage
    description: Per-app usage and quota.
  - name: Webhooks
    description: >-
      Register HTTPS endpoints to receive signed server-side event
      notifications. Managed with your user session.
paths:
  /v1/characters/{id}:
    patch:
      tags:
        - Characters
      summary: Update a character
      description: >-
        Patch metadata + brain fields (persona, greeting, lore, voiceId,
        stances, intro, free). Graph/stance-node edits go through the
        /v1/worlds/{id}/* endpoints.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                cover:
                  type: string
                visibility:
                  type: string
                  enum:
                    - private
                    - unlisted
                    - public
                persona:
                  type: string
                scene:
                  type: string
                greeting:
                  type: string
                lore:
                  type: string
                examples:
                  type: string
                voiceId:
                  type: string
                modelId:
                  type: string
                free:
                  type: boolean
      responses:
        '200':
          description: Updated character
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Character:
      type: object
      description: >-
        A character (owner view). The brain (persona/lore) is included for the
        owning app, but NEVER leaves the server on the embed path.
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
          nullable: true
        name:
          type: string
        description:
          type: string
        cover:
          type: string
          nullable: true
        visibility:
          type: string
          enum:
            - private
            - unlisted
            - public
        voiceId:
          type: string
          nullable: true
        modelId:
          type: string
          nullable: true
        free:
          type: boolean
        greeting:
          type: string
          nullable: true
        intro:
          type: object
          nullable: true
        stances:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              mood:
                type: string
                nullable: true
        persona:
          type: string
        scene:
          type: string
          nullable: true
        lore:
          type: string
          nullable: true
        examples:
          type: string
          nullable: true
        schemaVersion:
          type: string
          example: '1.0'
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          items:
            type: string
          description: Field-level validation errors (e.g. on 422 from POST /v1/worlds).
        schemaVersion:
          type: string
      required:
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        An app API key, e.g. `Authorization: Bearer sk_live_…`. Secret (`sk_`)
        for writes/sessions; publishable (`pk_`) for read/embed.

````