DEVS-Fire API

Debugging API calls

How to interpret responses and troubleshoot DEVS-Fire API requests

View for LLMs

Quick checklist

  1. Call /connectToServer and save the userToken.
  2. (optional) Load environment data — /loadFuel, /loadAspect, /loadSlope, /loadWindFlow.
  3. Configure the simulation — setCellResolution, setWindCondition, setPointIgnition, setMultiParameters, etc.
  4. Run /runSimulation (single interval) or step with /continueSimulation (repeated intervals).
  5. Query results only after the simulation has run (some endpoints return 500 before that).

Reading responses

Each API reference endpoint lists Responses tabs (200, 400, 500).

StatusTypical meaning
200Success — plain text or JSON depending on endpoint
400Bad request — often empty body; invalid types or empty file upload
500Spring Boot error JSON — missing or invalid userToken, missing params, or wrong call order (not HTTP 401)

Missing or invalid userToken returns 500 with {"error":"Internal Server Error",...}, not 401. The server cannot locate a simulation instance for an unrecognized token.

Common pitfalls

  • getCellState, getPerimeterCells, computeBurnedArea — may return 500 before runSimulation or continueSimulation has been called.
  • runSimulation / continueSimulation — the time parameter must be greater than 0. An empty array response means the computed fire perimeter is empty, which usually indicates a backend error or a misconfigured API call.
  • continueSimulation — does not require runSimulation to be called first; use it on its own to run in steps.
  • Load endpoints — require a non-empty text/plain body and fileName header. loadFuel, loadSlope, and loadAspect also update cellResolution from the file's cellsize field. loadWindFlow uses the SIMS ncols / nrows file format.
  • setDynamicIgnition — passing an invalid mode value returns 400.

Authentication

How authentication works with the DEVS-Fire API

On this page

Quick checklistReading responsesCommon pitfalls