Developer / API Reference

API Documentation

Integrate the multi-agent alternate-history simulator into custom applications and pipelines.

POST/api/scenarios

Submit a raw query string to initiate a new multi-agent simulation run background task.

// Request Body
{
"raw_input": "What if the Roman Empire never fell?"
}
// Response Body
{
"scenario_id": "a542fe56-0c14-4113-95dc-ace0dd0e4b4e"
}
GET/api/scenarios/{id}/status

Check the simulation processing status and active completed agent lists.

// Response Body
{
"status": "running",
"completed_agents": ["historian", "climate"],
"error_message": null
}
GET/api/scenarios/{id}/report

Retrieve the synthesized final alternate history report, indices, timeline, and critic logs. Returns HTTP 409 if not finished.

POST/api/scenarios/{id}/branch

Fork a new simulation from a specific timeline event. Pre-divergence events are locked in as historical context.

// Request Body
{
"divergent_event_id": "ev-2",
"alternative_event": "A different outcome at that point"
}
POST/api/scenarios/{id}/ask

Ask a follow-up question about a completed report. Answers are grounded in the report context and include citations.

// Response Body
{
"answer": "...",
"citations": ["..."]
}
POST/api/scenarios/{id}/debate

Run a structured two-round debate between any two domain agents, concluded by a Critic synthesis.

// Request Body
{
"topic": "the speed of reforestation",
"agent_a": "historian",
"agent_b": "economist"
}
POST/api/scenarios/{id}/adjust

Re-simulate a scenario with adjusted parameters. Only the affected agents re-run; the final report is recomposed.

// Request Body (each value 0-100)
{
"adjustments": { "resource_abundance": 80, "transition_speed": 40 }
}
WS/api/scenarios/{id}/ws

WebSocket channel that streams live agent progress logs while a simulation is running.

GET/

Health check endpoint returning service status and database connectivity.