You can now add an intelligence layer to your apps or games in minutes! Our cloud-based intelligence engine has memory to remember important events in your app or game's user sessions. You can create unique AI personalities that respond intelligently to guide, support, or manage your user experience.
Follow these steps to integrate companions into your application.
Download API doc as Claude Skill
All requests require these headers:
Authorization: Bearer <key> Content-Type: application/json
Two key types are used:
API_KEY — Simulation, NPC, and Player read/delete operations
DISTR_KEY — Player create and all stream event operations
A simulation represents your game world or app context. NPCs and players belong to a simulation.
There are tier based limits to how many simulations you can create for your account.
Create a new simulation.
| Field | Type | Description | |
|---|---|---|---|
| name | string | required | Display name for the simulation |
| lore | string | required | World-building text that NPCs use as context (max 2000 words). (Sample) |
{
"sim_id": "si8a3f...",
"name": "My Game",
"lore": "me8f2a...",
"creation_time": 1708646400
}
List all simulations for your account.
[
{ "sim_id": "si8a3f...", "name": "My Game", "lore": "...", "creation_time": 1708646400 },
...
]
Get a single simulation by ID.
Update the simulation's lore/world description. Max 2000 words. Connected NPCs will restart to pick up the new lore.
| Field | Type | Description | |
|---|---|---|---|
| lore | string | required | World-building text that NPCs use as context |
Delete a simulation. All NPCs must be deleted first.
| Field | Type | Description | |
|---|---|---|---|
| sim_id | string | required | ID of the simulation to delete |
NPC companions that live inside a simulation. Each has a personality, description, and interests that shape their responses.
There are tier based limits to how many NPCs you can create per simulation for your account.
Create an NPC in a simulation.
| Field | Type | Description | |
|---|---|---|---|
| sim_id | string | required | Parent simulation ID |
| npc_name | string | required | Display name |
| description | string | required | Character personality, role, behavior |
| interests | string[] | required | 5 sentences (up to 5-8 words each) to describe the NPC's events of interest. (Sample) |
{
"npc_id": "npc7b2e...",
"sim_id": "si8a3f...",
"creation_time": 1708646500,
"update_time": 1708646500
}
List all NPCs in a simulation.
Get a single NPC by ID.
{
"npc_id": "npc7b2e...",
"sim_id": "si8a3f...",
"description": "...",
"curr_interest_raw": ["phrase1", "phrase2", ...],
"creation_time": 1708646500,
"update_time": 1708646500
}
Update an NPC's description or interests.
| Field | Type | Description | |
|---|---|---|---|
| description | string | optional | Updated character personality/role |
| interests | string[] | optional | Updated interest phrases (5 phrases, 5-8 words each) |
Delete an NPC.
| Field | Type | Description | |
|---|---|---|---|
| npc_id | string | required | ID of the NPC to delete |
Players are user sessions within a simulation. Each player can send events and ask NPCs questions.
Create a player session. Uses DISTR_KEY.
| Field | Type | Description | |
|---|---|---|---|
| sim_id | string | required | Simulation to join |
| expire_min | int | optional | Session expiry in minutes |
{
"player_id": "pl4c91...",
"sim_id": "si8a3f...",
"created_on": 1708646600,
"connected_from": "...",
"expires_on": 1708646900
}
List all players in a simulation.
Get a single player by ID.
Delete a player session.
| Field | Type | Description | |
|---|---|---|---|
| player_id | string | required | Player to remove |
| sim_id | string | required | Simulation the player belongs to |
Send game state updates and player questions to NPCs. All event operations use DISTR_KEY.
Rate limits per player: 30/min (HTTP), 60/min (WebSocket).
Send a game state event. These are contextual updates that NPCs observe — things like "player entered dark forest zone" or "enemy defeated in arena".
| Field | Type | Description | |
|---|---|---|---|
| player_id | string | required | |
| sim_id | string | required | |
| event_kind | "state" | required | |
| event | string | required | Short natural-language event (5-8 words). (Sample) |
| event_id | string | optional | Your own event identifier for deduplication |
{
"player_id": "pl4c91...",
"sim_id": "si8a3f...",
"event_kind": "state",
"event": "player entered dark forest zone"
}
Ask a specific NPC a question. The NPC responds based on its personality, the simulation lore, and recent game state.
| Field | Type | Description | |
|---|---|---|---|
| player_id | string | required | |
| sim_id | string | required | |
| event_kind | "ask" | required | |
| npc_id | string | required | Which NPC to ask |
| ask_text | string | required | A question for the NPC |
| ask_id | string | optional | An optional identifier to correlate response |
{
"player_id": "pl4c91...",
"sim_id": "si8a3f...",
"event_kind": "ask",
"npc_id": "npc7b2e...",
"ask_text": "what should i do next?"
}
For high-frequency event streaming, connect via WebSocket instead of individual HTTP calls.
Open a persistent connection and send JSON messages. Auth headers go in the WebSocket handshake.
Authorization: Bearer <DISTR_KEY>
{ "event_kind": "state", "event": "player picked up legendary sword" }
{ "event_kind": "ask", "npc_id": "npc7b2e...", "ask_text": "where is the hidden temple?" }
{ "cmd": "close" }