Developer Platform
Emergentic API Documentation
Use the API to create worlds, build agents and action surfaces, run live simulations, ask questions over world state, and read generated state back into your tools.
Step 1
Authenticate
Create a service API key from Settings, then send it as a Bearer token on REST and Socket.IO requests.
Step 2
Create a world
A world is the ownership boundary and parent container for agents, locations, actions, plots, and simulations.
Step 3
Add entities
Create locations, actions, and agents. Link actions to agents so the runtime has a strict action surface.
Step 4
Run a simulation
Create or load a simulation, start it through the realtime API, then read logs and live state.
Quickstart
Authenticate and create your first resources
Service API keys authenticate as the owning user. Send the key with every REST request as Authorization: Bearer. For browser sessions, the app continues to use its normal session credentials.
curl -X POST "https://emergentic.ai/api/public/v1/worlds" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Harbor District",
"description": "A compact city district with competing studios, public spaces, and production offices.",
"width": 1600,
"height": 1200,
"generate_visemes": false
}'Resource Model
How the platform is organized
Worlds own the content graph. Agents, locations, actions, plots, and simulations are scoped through a world id, and mutation payloads use explicit create/update shapes across REST and TypeScript examples.
World
A project space and access boundary for all authoring resources.
Agent
A persistent character, worker, or participant with behavior, memory, voice, and media references.
Location
A named place in the world graph, optionally connected to other locations.
Action
A strict tool or behavior surface that can be assigned to agents and chained through transitions.
Plot And Schedule
A narrative plan for a world. Linear plots provide ordered story context; schedule plots use schedule_state to place agents, locations, and events across time.
Simulation
A saved runtime configuration. Live execution is controlled through Socket.IO events.
Question
A scoped read model that turns world, agent, location, simulation, and log context into a grounded answer.
Log
The auditable output stream from simulation turns, actions, and messages.
REST API
Common endpoints
These are the endpoints most integrations need first. Use them to create resources, update world content, connect actions, save simulations, and ask questions over authored state. Numeric ids in isolated endpoint examples are placeholders; any referenced agent, location, plot, action, or simulation id must come from the same owned world.
Note: Public REST requests are limited to 120 requests per minute per API key or client IP. Question submission endpoints have an additional 30 requests per minute limit because they enqueue LLM-backed jobs. Polling question jobs counts against the general REST limit. A limited request returns 429 with a Retry-After header.
Worlds
Worlds are the top-level container for owned content and runtime state.
Request
void
No body.
Path Parameters
No path parameters.
Query Parameters
No query parameters.
Request Body
No request body.
Headers
Authorization
Service API key sent as Authorization: Bearer <key>.
Response
Returns World objects with ids, names, dimensions, image URLs, and current simulation/default plot references.
Response Fields
id
Unique resource id.
name
Display name.
description
Human-readable description.
background_image_url
Primary background image URL.
image_urls
Image URLs associated with the resource.
width
World canvas width.
height
World canvas height.
current_simulation_id
Current simulation id for the world.
default_plot_id
Default plot id for the world.
created_at
Creation timestamp.
updated_at
Update timestamp.
Example
curl "https://emergentic.ai/api/public/v1/worlds" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY"Agents
Agents hold character, worker, or participant behavior, media, dynamic properties, and action access.
Locations
Locations define places in a world and the graph agents can move through.
Actions
Actions define what agents can do and which actions can validly follow one another.
Plots
Plots can be linear story structures or schedule-driven plans. Use narrative_mode to choose the behavior and schedule_state to create or replace scheduled entries.
Simulations
REST endpoints save and inspect simulation records. Socket.IO controls live execution.
Recommendations
Recommendations rank similar agents from conversation history and profile data. Reads return the latest prepared result.
Questions
Question endpoints answer from structured world, agent, location, simulation, and log context.
Realtime API
Run live simulations over Socket.IO
REST creates and inspects public simulation records. Live runtime control uses Socket.IO with the same Bearer token contract. Use the TypeScript client for the high-level public flow, or emit raw Socket.IO events when you need direct runtime control. The public lifecycle does not expose backend database sessions; raw chat clients create a runtime chat session with new_session. Load or create a simulation with load_simulation, then start it with start_simulation. The default client flow is to create or choose a world, list agents in that world, then attach a live chat with createAndAttachChat. Use createSimulationRecord when you specifically need a REST-created simulation record before the live Socket.IO step.
load_simulation
Payload
LoadSimulationPayload
Emit this event with an ack callback for request/response workflows.
Payload Fields
world_id
Unique world id.
simulation_id
Unique simulation id.
simulation_name
Simulation display name.
mode
Simulation mode: play, record, or chat.
agent_ids
Selected agent ids.
plot_id
Unique plot id.
simulation_time
Simulation start time.
simulated_seconds_per_real_second
Simulation clock speed.
Ack Response
Response Fields
error
Error payload when loading fails.
data
Loaded or created simulation.
Related Server Events
Example Flow
End-to-end agent chat
Create a chat simulation, attach a live session, send a conversation message, stop the run, and read the resulting logs.
- The TypeScript client uses createAndAttachChat for the recommended live-chat path.
- Python shows the raw Socket.IO lifecycle: load_simulation, start_simulation, simulation_heartbeat, new_session, chat_with_agents, and stop_simulation.
- curl can prepare the REST simulation record and read logs, but the live chat step requires Socket.IO.
- Read the transcript and action output through paginated REST logs after the live step.
AGENT_IDS=$(curl -s "https://emergentic.ai/api/public/v1/worlds/42/agents" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY" | jq '[.[].id][0:2]')
SIMULATION_ID=$(curl -s -X POST "https://emergentic.ai/api/public/v1/worlds/42/simulations" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Harbor District chat",
"mode": "chat"
}' | jq -r '.id')
curl -X PUT "https://emergentic.ai/api/public/v1/simulations/$SIMULATION_ID/agents" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY" \
-H "Content-Type: application/json" \
-d "{"agent_ids": $AGENT_IDS}"
# The conversation step is Socket.IO, not plain HTTP.
# Use Python or TypeScript for load/start/heartbeat/new_session/chat/stop.
curl "https://emergentic.ai/api/public/v1/simulations/$SIMULATION_ID/logs?limit=20" \
-H "Authorization: Bearer $EMERGENTIC_API_KEY"Note: Send simulation_heartbeat with the simulation id while a client owns a running simulation. Read historical output through GET /api/public/v1/simulations/{simulation_id}/logs with a bounded limit, then request subsequent pages with after_id.