Run the same engine headlessly
POST a reference-case key or a complete 8,760-hour project to the simulation endpoint. The response returns provenance, an input fingerprint, technical results, lifecycle economics, and any requested outage or component-disturbance resilience analysis. Use is subject to the API terms.
POST /api/v1/simulate
JSON in, JSON out. CORS is enabled for public read-and-run integrations.
Aggregate, not hourly
Technical, economic, and requested resilience results are returned by default. Set includeHourly to true when the complete dispatch trace is required.
20 per minute · 3 MB · 50 years
20 requests per minute per client (HTTP 429 with Retry-After). Payloads are capped at 3 MB, project life at 50 years, and resilience studies by a published compute budget. Custom projects need exactly 8,760 non-negative load values.
Fastest first call
Run one of the published reference projects without constructing a full project payload.
curl -X POST https://www.microgridmodeler.com/api/v1/simulate \
-H "Content-Type: application/json" \
-d '{"benchmarkKey":"clinic-small","includeHourly":false}'Request contract
Provide exactly one source: benchmarkKey or project.
| Status | Code | Meaning |
|---|---|---|
| 415 | UNSUPPORTED_MEDIA_TYPE | Send the body as application/json. |
| 422 | VALIDATION_ERROR | The request does not match the OpenAPI schema; errors[] lists a JSON pointer, keyword and message for each problem. Unknown properties are rejected. |
| 422 | COMPUTE_BUDGET_EXCEEDED | The requested resilience study is too large; the response gives the budget and a suggested start-hour stride. |
| 429 | RATE_LIMITED | More than 20 requests a minute; retry after the given seconds. |
| 500 | NON_FINITE_RESULT, SIMULATION_ERROR, INTERNAL_ERROR | A server-side fault; the result is withheld rather than returned with invalid numbers. |
schemaVersion, project payload, and returned fingerprint with any automated study.Published benchmark keys
Stable inputs to the endpoint: the same synthetic reference cases shown on the reference-case page.
Response shape
The exact component and result schemas are published in the OpenAPI document.
{
"schemaVersion": "2026-09-25",
"engine": "MicrogridModeler 3.0.0 chronological techno-economic, resilience, and Pareto-sizing engine",
"engineVersion": "3.0.0",
"fingerprint": {
"value": "…",
"method": "cyrb53 over the serialized project payload",
"cryptographic": false
},
"project": { "id": "clinic-small", "name": "Remote clinic (small)" },
"provenance": { "solar": { "source": "synthetic", "badge": { "label": "Offline estimate" } }, "wind": null },
"resource": { "annualGhiKwhM2": 0, "annualPoaKwhM2": 0, "specificYieldKwhPerKw": 0 },
"result": {
"feasible": true,
"violations": [],
"technical": { "annualLoadKwh": 0, "fuelLitres": 0 },
"economics": { "npc": 0, "lcoe": 0 }
}
}