Chat Endpoints

List Personas

GET /api/v1/sdk/personas

Returns all published personas owned by your API key. Use this to discover persona IDs for chat endpoints.

Response

Returns an array of persona objects:

curl /api/v1/sdk/personas \
  -H "X-API-Key: pk_live_..."

Response:

[
  {
    "id": "a1b2c3d4-...",
    "name": "Grumpy Barista",
    "description": "A coffee shop NPC with a bad attitude",
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:00:00Z"
  }
]

Initialize Session

POST /api/v1/sdk/chat/{persona_id}/init-session

Starts a new chat session. Returns the NPC's opening greeting, session ID, and persona metadata.

Query Parameters

Request Body

Response

Send Message

POST /api/v1/sdk/chat/{persona_id}/message

Sends a player message and returns the NPC response with state machine metadata.

Request Body

Response

Check Session

GET /api/v1/sdk/chat/{persona_id}/session

Check if a player already has an active session with a persona. Returns session status or 404 if no session exists. Useful for resuming conversations on reconnect instead of re-initializing.

Query Parameters

Response

List Available Machines

GET /api/v1/sdk/chat/{persona_id}/machines

Lists all machines (scenarios) available to a player for a persona. Includes entry machines, unlocked machines, and unlinked standalone machines. Use this to discover which machines a player can interact with.

Query Parameters

Response

Returns an array of available machine objects:

curl "/api/v1/sdk/chat/{persona_id}/machines?user_session_id=player-001" \
  -H "X-API-Key: pk_live_..."

Response:

[
  {
    "machine_id": "a1b2c3d4-...",
    "machine_key": "opening_scene",
    "name": "Opening Scene",
    "description": "The first encounter with the barista",
    "has_session": true,
    "session_outcome": null,
    "is_linked": true
  },
  {
    "machine_id": "e5f6a7b8-...",
    "machine_key": "side_quest",
    "name": "Side Quest",
    "description": "An optional standalone scenario",
    "has_session": false,
    "session_outcome": null,
    "is_linked": false
  }
]

Get Chat History

GET /api/v1/sdk/chat/{persona_id}/history

Retrieves the full message history for a session.

Query Parameters

Reset Session

POST /api/v1/sdk/chat/{persona_id}/reset

Resets a chat session, clearing all history and returning the state machine to its initial state.

Query Parameters

Error Responses

All errors return a consistent JSON format:

{
  "error": {
    "message": "Description of what went wrong"
  }
}

Example: Full Conversation Flow

1. Discover your personas

curl /api/v1/sdk/personas \
  -H "X-API-Key: pk_live_..."

2. Check for existing session

curl "/api/v1/sdk/chat/{persona_id}/session?user_session_id=player-001" \
  -H "X-API-Key: pk_live_..."
# Returns 404 if no session — proceed to init

3. Initialize

curl -X POST /api/v1/sdk/chat/{persona_id}/init-session \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_session_id": "player-001",
    "player_name": "Alex",
    "player_gender": "non-binary"
  }'

Response:

{
  "session_id": "f7a8b9c0-...",
  "user_session_id": "player-001",
  "persona_name": "Grumpy Barista",
  "persona_description": "A coffee shop NPC with a bad attitude",
  "player_name": "Alex",
  "player_gender": "non-binary",
  "message": "Well, well... another traveler. What brings you here, Alex?",
  "machine_id": "d4e5f6a7-..."
}

4. Send a message

curl -X POST /api/v1/sdk/chat/{persona_id}/message \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I heard you have something rare for sale.",
    "user_session_id": "player-001"
  }'

Response:

{
  "message": "Rare? Everything here is rare, friend. But the real question is — can you afford it?",
  "current_state": "negotiation",
  "score": 15,
  "outcome": null,
  "decision": "pass",
  "follow_up": true,
  "session_id": "f7a8b9c0-...",
  "scoring_mode": "scoring",
  "machine_completed": false,
  "unlocked_machines": []
}

5. Reset when done

curl -X POST "/api/v1/sdk/chat/{persona_id}/reset?user_session_id=player-001" \
  -H "X-API-Key: pk_live_..."