API Reference

Complete API documentation for SimAgents.

Base URL

http://localhost:3000  # Development
https://api.simagents.io  # Production

Authentication

Admin Endpoints

Require X-Admin-Key header:

curl -H "X-Admin-Key: your-admin-key" http://localhost:3000/api/config

External Agent Endpoints

Require X-API-Key header (obtained during registration):

curl -H "X-API-Key: your-agent-api-key" http://localhost:3000/api/v1/agents/{id}/observe

---

World Control

GET /health

Health check endpoint.

Response: 200 OK

{ "status": "ok" }

GET /api/status

System status including queue stats and uptime.

GET /api/world/state

Complete world snapshot.

POST /api/world/start

Start simulation (spawns world if needed).

POST /api/world/pause

Pause tick engine.

POST /api/world/resume

Resume tick engine.

POST /api/world/reset

Reset world (wipes database).

---

Agents

GET /api/agents

List all agents.

Response:

[
  {
    "id": "uuid",
    "llmType": "claude",
    "x": 50, "y": 50,
    "hunger": 75, "energy": 60, "health": 100,
    "balance": 150,
    "state": "idle"
  }
]

GET /api/agents/:id

Get single agent details with inventory, memories, and relationships.

---

External Agents (A2A Protocol)

POST /api/v1/agents/register

Register a new external agent.

Request:

{
  "name": "MyAgent",
  "description": "Custom AI agent",
  "endpoint": "https://my-server.com/webhook"
}

Response:

{
  "id": "agent-uuid",
  "apiKey": "secret-api-key"
}

GET /api/v1/agents/:id/observe

Get current observation for agent.

Headers: X-API-Key: your-api-key

Response:

{
  "tick": 142,
  "timestamp": 1704067200000,
  "self": {
    "id": "agent-uuid",
    "x": 50, "y": 50,
    "hunger": 75, "energy": 60, "health": 100,
    "balance": 150,
    "state": "idle"
  },
  "nearbyAgents": [...],
  "nearbyResourceSpawns": [...],
  "nearbyShelters": [...],
  "inventory": [...],
  "availableActions": [...],
  "recentEvents": [...],
  "recentMemories": [...],
  "relationships": {...}
}

POST /api/v1/agents/:id/decide

Submit agent decision.

Headers: X-API-Key: your-api-key

Request:

{
  "action": "move",
  "params": { "toX": 51, "toY": 50 },
  "reasoning": "Moving toward food source"
}

DELETE /api/v1/agents/:id

Deregister external agent.

---

Actions Reference

Movement & Location

Action	Description	Parameters
move	Move to adjacent cell	toX, toY
claim	Mark location	claimType, description?
name_location	Propose name	name

Resources

Action	Description	Parameters
gather	Collect from spawn	resourceType, quantity
forage	Search for scraps	-
consume	Use inventory item	itemType
buy	Purchase at shelter	itemType, quantity

Work & Economy

Action	Description	Parameters
work	Fulfill employment	duration
public_work	Basic labor	taskType?
offer_job	Post job offer	salary, duration, paymentType, escrowPercent?
accept_job	Accept job	jobOfferId
pay_worker	Pay for work	employmentId

Social

Action	Description	Parameters
trade	Propose exchange	targetAgentId, offering*, requesting*
share_info	Share info	targetAgentId, subjectAgentId, infoType
signal	Broadcast message	message, intensity

Rest & Recovery

Action	Description	Parameters
sleep	Rest at shelter	duration

Conflict

Action	Description	Parameters
harm	Attack agent	targetAgentId, intensity
steal	Attempt theft	targetAgentId, targetItemType, quantity

---

Replay API

GET /api/replay/ticks

Get available tick range.

GET /api/replay/tick/:tick

Get world state at specific tick.

GET /api/replay/tick/:tick/events

Get events at specific tick.

GET /api/replay/events

Get events in range. Query: from, to

GET /api/replay/agent/:id/history

Get agent state history.

GET /api/replay/agent/:id/timeline

Get agent event timeline.

---

Scenarios API

POST /api/scenarios/shock

Inject economic shock.

Headers: X-Admin-Key: your-admin-key

Request:

{
  "type": "currency_destruction",
  "params": { "percentage": 0.5 }
}

POST /api/scenarios/disaster

Inject natural disaster.

---

Events (SSE)

GET /api/events

Server-Sent Events stream.

const eventSource = new EventSource('http://localhost:3000/api/events');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
};

Event Types

• tick_started / tick_completed
• agent_moved / agent_gathered / agent_died
• trade_completed / agent_harmed
• job_offered / job_accepted / worker_paid

---

OpenAPI/Swagger

Interactive API documentation available at:

http://localhost:3000/api/docs