Chat
Send messages to NPCs and receive AI-generated responses within a session.
Overview
The Chat API handles real-time conversations with published personas. Initialize a session, send messages, and receive NPC responses along with state transition data and scoring metadata.
ℹNote
Chat endpoints do not require authentication. Players can interact with any published persona without signing in.
Initialize Session
POST /api/v1/chat/{persona_id}/init-session
Starts a new chat session with the specified persona. Returns the NPC's opening message and a session ID for subsequent requests.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
machine_id | string | No | Target a specific state machine. Defaults to the persona's primary machine. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | Unique identifier for the player's session |
player_name | string | Yes | The player's display name, used in NPC responses |
player_gender | string | Yes | One of female, male, or non-binary |
Response
| Field | Type | Description |
|---|---|---|
message | string | The NPC's opening message |
session_id | string | Server-assigned session identifier |
player_name | string | Echoed player name |
player_gender | string | Echoed player gender |
machine_id | string | The active state machine ID |
Send Message
POST /api/v1/chat/{persona_id}/message
Sends a player message to the NPC and returns the response along with state machine metadata including current state, score, and outcome information.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
machine_id | string | No | Target a specific state machine |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | The player's message text |
user_session_id | string | Yes | Session identifier from init |
Response
| Field | Type | Description |
|---|---|---|
message | string | The NPC's response text |
current_state | string | The current state machine state key |
score | number | Current cumulative score for the session |
outcome | string | null | Outcome label if a terminal state was reached |
decision | string | null | Transition decision made by the AI |
follow_up | boolean | Whether the NPC expects a follow-up message |
redirect_count | number | null | Number of redirects used in the current state |
session_id | string | The active session identifier |
scoring_mode | string | The scoring mode for this persona |
machine_completed | boolean | Whether the state machine has reached a terminal state |
unlocked_machines | array | List of newly unlocked machine IDs, if any |
Get Chat History
GET /api/v1/chat/{persona_id}/history
Retrieves the full message history for a session.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | The session to retrieve history for |
machine_id | string | No | Filter history to a specific state machine |
Reset Session
POST /api/v1/chat/{persona_id}/reset
Resets a chat session, clearing all history and returning the state machine to its initial state.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | The session to reset |
machine_id | string | No | Reset only a specific state machine |
Example: Full Conversation Flow
Here's a complete example of initializing a session and sending a message.
1. Initialize the session
curl -X POST /api/v1/chat/abc123/init-session \
-H "Content-Type: application/json" \
-d '{
"user_session_id": "player-session-001",
"player_name": "Alex",
"player_gender": "non-binary"
}'Response:
{
"message": "Well, well... another traveler. What brings you to the Hollow Market, Alex?",
"session_id": "sess_7f8a9b2c",
"player_name": "Alex",
"player_gender": "non-binary",
"machine_id": "machine_main"
}2. Send a message
curl -X POST /api/v1/chat/abc123/message \
-H "Content-Type: application/json" \
-d '{
"message": "I heard you have something rare for sale.",
"user_session_id": "player-session-001"
}'Response:
{
"message": "Rare? Everything here is rare, friend. But the real question is — can you afford it? Not everything costs gold.",
"current_state": "negotiation",
"score": 1,
"outcome": null,
"decision": "pass",
"follow_up": true,
"session_id": "sess_7f8a9b2c",
"scoring_mode": "scoring",
"machine_completed": false,
"unlocked_machines": []
}