Personas
Programmatically create, update, and manage NPC personas.
Overview
The Personas API lets you list, retrieve, create, publish, and delete NPC personas. Public personas can be browsed without authentication, but creating and managing personas requires a valid JWT token.
List Personas
GET /api/v1/personas
Returns a list of personas. By default, only public personas are returned. Pass my_personas=true with a valid auth token to list your own personas.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
public_only | boolean | true | Only return published personas |
my_personas | boolean | false | Return only the authenticated user's personas. Requires auth. |
limit | integer | 20 | Maximum number of results. Max 100. |
Get Persona
GET /api/v1/personas/{persona_id}
Returns basic information for a single persona, including name, description, and publish status.
Get Full Persona
GET /api/v1/personas/{persona_id}/full
Returns the complete persona definition including all machines, states, transitions, variables, and machine links. Use this endpoint when you need the full structure for rendering or editing.
Response includes
| Field | Type | Description |
|---|---|---|
persona | object | Core persona fields (name, description, identity prompt) |
machines | array | State machines with their states and transitions |
variables | array | Persona-level variables |
machine_links | array | Links between machines (unlock conditions) |
Delete Persona
DELETE /api/v1/personas/{persona_id}
Permanently deletes a persona and all associated data (machines, states, transitions, chat history). Requires authentication. Only the owner can delete their persona.
Save / Update Persona
POST /api/v1/creator/save
Creates a new persona or updates an existing one. Pass persona_id as a query parameter to update. Requires authentication.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
persona_id | string | No | If provided, updates the existing persona. Otherwise creates a new one. |
Request Body
The request body follows the PersonaCreate schema:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Persona display name |
description | string | Yes | Short description of the persona |
persona_identity_prompt | string | Yes | System prompt defining the NPC's personality and behavior |
machines | array | Yes | Array of state machines, each containing states and transitions |
Publish Persona
POST /api/v1/creator/publish
Publishes a persona, making it publicly playable. Returns a shareable play link. Requires authentication.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
persona_id | string | Yes | The persona to publish |
Response
| Field | Type | Description |
|---|---|---|
play_link | string | Shareable URL for playing the persona |
persona_id | string | The published persona's ID |
Get Player Progress
GET /api/v1/personas/{persona_id}/progress
Returns a player's progress across all machines within a persona, including completed machines, available machines, route history, and cross-machine variables. No authentication required.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | The player's session ID |
Response
| Field | Type | Description |
|---|---|---|
persona_id | string | The persona ID |
current_machine_id | string | null | The machine the player is currently engaged with |
relationship_level | number | Overall relationship level with the persona |
total_score | number | Cumulative score across all completed machines |
completed_machines | array | List of completed machines with outcome, score, and completion time |
available_machines | array | Machines the player can currently access |
route_path | array | Chronological list of machines the player has entered |
cross_machine_vars | object | Variables extracted and carried across machines |
has_links | boolean | Whether this persona has machine links configured |
Reset Player Progress
DELETE /api/v1/personas/{persona_id}/progress
Resets all player progress and chat sessions for a persona. This clears completed machines, route history, cross-machine variables, and all active sessions.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | The player's session ID |
Get Available Machines
GET /api/v1/personas/{persona_id}/available-machines
Returns the list of machines currently available to a player for a given persona, based on their progress and unlock conditions.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_session_id | string | Yes | The player's session ID |
Examples
List public personas
curl /api/v1/personas?public_only=true&limit=10Response:
[
{
"id": "abc123",
"name": "Merchant Kael",
"description": "A shrewd trader in the Hollow Market",
"is_public": true,
"created_at": "2026-02-15T10:30:00Z"
},
{
"id": "def456",
"name": "Guard Captain Sera",
"description": "Gate commander who decides who enters the city",
"is_public": true,
"created_at": "2026-02-14T08:15:00Z"
}
]Get a specific persona
curl /api/v1/personas/abc123Response:
{
"id": "abc123",
"name": "Merchant Kael",
"description": "A shrewd trader in the Hollow Market",
"persona_identity_prompt": "You are Kael, a merchant who has seen...",
"is_public": true,
"user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created_at": "2026-02-15T10:30:00Z",
"updated_at": "2026-03-01T14:20:00Z"
}Publish a persona
curl -X POST /api/v1/creator/publish?persona_id=abc123 \
-H "Authorization: Bearer <your_jwt_token>"Response:
{
"play_link": "https://foilengine.io/play/abc123",
"persona_id": "abc123"
}