Simulation API

Add AI-powered NPC companions to your app or game. Your players talk to characters that understand context, remember state, and respond intelligently.

Flow Auth Simulations NPCs Players Events WebSocket

Integration Flow

Follow these steps to integrate companions into your application.

Create Simulation

Set up your game world with a name and optional lore

Add NPCs

Create AI characters with descriptions and interests

Create player sessions with optional expiry

Stream Events

Send game state & player questions via HTTP or WebSocket

Authentication

All requests require these headers:

Authorization: Bearer <key>
Content-Type: application/json
Product: <your_product_id>

Two key types are used:
API_KEY — Simulation, NPC, and Player read/delete operations
DISTR_KEY — Player create and all stream event operations

Contact support@niopub.com to get your keys and product ID.

Simulations

A simulation represents your game world or app context. NPCs and players belong to a simulation.

POST /simulation

Create a new simulation.

Request body

Field	Type		Description
name	string	required	Display name for the simulation

Response

{
  "sim_id": "si8a3f...",
  "name": "My Game",
  "creation_time": 1708646400
}

GET /simulation

List all simulations for your account.

Response

[
  { "sim_id": "si8a3f...", "name": "My Game", "lore": "...", "creation_time": 1708646400 },
  ...
]

GET /simulation/{sim_id}

Get a single simulation by ID.

PUT /simulation/{sim_id}

Set or update the simulation's lore/world description. Max 2000 words.

Field	Type		Description
lore	string	required	World-building text that NPCs use as context

DELETE /simulation

Delete a simulation and all its NPCs.

Field	Type		Description
sim_id	string	required	ID of the simulation to delete

NPCs

NPC companions that live inside a simulation. Each has a personality, description, and interests that shape their responses.

POST /npc

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 interest phrases (5-8 words each) that define what triggers this NPC

Response

{
  "npc_id": "npc7b2e...",
  "sim_id": "si8a3f...",
  "creation_time": 1708646500,
  "update_time": 1708646500
}

GET /simulation/{sim_id}/npcs

List all NPCs in a simulation.

GET /npc/{npc_id}

Get a single NPC by ID.

Response

{
  "npc_id": "npc7b2e...",
  "sim_id": "si8a3f...",
  "description": "...",
  "curr_interest_raw": ["phrase1", "phrase2", ...],
  "creation_time": 1708646500,
  "update_time": 1708646500
}

PUT /npc/{npc_id}

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 /npc

Delete an NPC.

Field	Type		Description
npc_id	string	required	ID of the NPC to delete

Players

Players are user sessions within a simulation. Each player can send events and ask NPCs questions.

POST /user/player

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

Response

{
  "player_id": "pl4c91...",
  "sim_id": "si8a3f...",
  "created_on": 1708646600,
  "connected_from": "...",
  "expires_on": 1708646900
}

GET /user/players?sim_id={sim_id}

List all players in a simulation.

GET /user/player/{player_id}?sim_id={sim_id}

Get a single player by ID.

DELETE /user/player

Delete a player session.

Field	Type		Description
player_id	string	required	Player to remove
sim_id	string	required	Simulation the player belongs to

Stream Events

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).

POST /stream/event

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)
event_id	string	optional	Your own event identifier for deduplication

Example

{
  "player_id": "pl4c91...",
  "sim_id": "si8a3f...",
  "event_kind": "state",
  "event": "player entered dark forest zone"
}

POST /stream/event

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	The player's question
ask_id	string	optional	Your identifier to correlate response

Example

{
  "player_id": "pl4c91...",
  "sim_id": "si8a3f...",
  "event_kind": "ask",
  "npc_id": "npc7b2e...",
  "ask_text": "what should i do next?"
}

WebSocket WS

For high-frequency event streaming, connect via WebSocket instead of individual HTTP calls.

WSS /stream/event/ws/{sim_id}/{player_id}

Open a persistent connection and send JSON messages. Auth headers go in the WebSocket handshake.

Connection headers

Authorization: Bearer <DISTR_KEY>
Product: <your_product_id>

Send state events

{ "event_kind": "state", "event": "player picked up legendary sword" }

Send ask events

{ "event_kind": "ask", "npc_id": "npc7b2e...", "ask_text": "where is the hidden temple?" }

Close connection

{ "cmd": "close" }