Skip to main content
POST
Generate quick NPC dialogue

Body

application/json

POST /v1/projects/{project_id}/quick-dialogue

Synchronous NPC dialogue generation - single LLM call, 1-3 sec response. Bypasses CoreRuntimeGraph; no session creation, no event sourcing.

Design reference: docs/discovery/foundry-vtt-module/4-decide/concepts-extracted.md

npc_name
string
required

Display name of the NPC

Required string length: 1 - 100
player_message
string
required

What the player just said or did.

Required string length: 1 - 500
npc_context
default:""

Free-text or structured description of the NPC (race, alignment, traits, biography). Accepts either a plain string or a JSON object from Actor Context Extraction.

situation
string
default:""

GM-provided situational context (location, stakes, mood of scene).

Maximum string length: 500
tone
string
default:neutral

Desired emotional tone: neutral, friendly, hostile, cautious, suspicious, etc.

Maximum string length: 50
game_system
string
default:dnd5e

Game system identifier (dnd5e, pf2e, generic).

Maximum string length: 20
max_tokens
integer
default:200

Maximum tokens for the LLM response (50-500).

Required range: 50 <= x <= 500

Response

NPC dialogue generated successfully

200 response for POST /v1/projects/{project_id}/quick-dialogue.

dialogue
string
required

The NPC's spoken words (inline stage directions stripped out).

mood
string
default:neutral

NPC's current emotional state, e.g. 'worried'.

stage_direction
string
default:""

Behavioral/visual description for the GM, e.g. 'leans in close, lowers voice'.

suggested_actions
string[]

GM hints for follow-up player actions.