Lifecycle Actions

GET|POST /runtime/stop

Stops the currently running project, transitioning to Idle state. All infrastructure services (HTTP API, WebSocket, Prometheus) remain active.

Parameters: None

Preconditions:

• Runtime state must be Running (returns 409 if already Idle, or in Loading/Stopping state)

Response (success): 200 OK

{
  "success": true,
  "message": "Project stopped. Runtime is idle.",
  "state": "Idle"
}

Response (already idle): 200 OK

{
  "success": true,
  "message": "Already idle — no project to stop.",
  "state": "Idle"
}

Response (wrong state): 409 Conflict

{
  "error": "Cannot stop: runtime is in Loading state.",
  "currentState": "Loading"
}

GET|POST /runtime/start

Starts the last loaded project from Idle state. The project file must have been previously loaded (via initial CLI startup or /runtime/load).

Parameters (optional, POST body):

{
  "decryptKey": "optional-key-for-encrypted-projects"
}

Preconditions:

• Runtime state must be Idle (returns 409 otherwise)
• A project file must have been previously loaded (returns 400 if no project file is known)

Response (success): 200 OK

{
  "success": true,
  "message": "Project started: MyProject.prj",
  "state": "Running"
}

Response (wrong state): 409 Conflict

{
  "error": "Cannot start: runtime is not in Idle state",
  "currentState": "Running"
}

Response (no project): 400 Bad Request

{
  "error": "Cannot start: no project file has been loaded. Use /runtime/load instead."
}

GET|POST /runtime/reload

Stops the current project, reloads it from disk, and starts it again. Useful for picking up project file changes without a full restart.

Parameters (optional, POST body):

{
  "decryptKey": "optional-key-for-encrypted-projects"
}

Preconditions:

• Runtime state must be Running (returns 409 otherwise)

Response (success): 200 OK

{
  "success": true,
  "message": "Project reloaded: MyProject.prj",
  "state": "Running"
}

Response (wrong state): 409 Conflict

{
  "error": "Cannot reload: runtime is not in Running state",
  "currentState": "Idle"
}

GET|POST /runtime/load

Loads a different project file and starts it. Works from any stable state — if a project is currently running, it is stopped first.

GET parameters:

Also accepts filename, projectName, and projectname as case-insensitive aliases for fileName.

POST body:

{
  "fileName": "path/to/project.prj",
  "decryptKey": "optional"
}

File resolution:

• Relative paths are resolved against the configured ProjectsDirectory setting
• If the file extension is omitted, .prj is appended automatically

Examples:

GET /runtime/load?fileName=MyProject.prj
GET /runtime/load?fileName=C:\Projects\MyProject.prj
GET /runtime/load?fileName=subfolder/MyProject
POST /runtime/load  {"fileName": "MyProject.prj"}

Response (success): 200 OK

{
  "success": true,
  "message": "Project loaded and started: MyProject.prj",
  "state": "Running"
}

Response (file not found): 404 Not Found

{
  "error": "Project file not found",
  "fileName": "C:\\Projects\\Missing.prj"
}

Response (missing parameter): 400 Bad Request

{
  "error": "fileName is required",
  "examples": {
    "GET": "/runtime/load?fileName=project.prj",
    "POST": { "fileName": "path/to/project.prj", "decryptKey": "(optional)" }
  }
}

GET|POST /runtime/exit

Requests a graceful application shutdown. Responds immediately, then the runtime process exits.

Parameters: None

Response: 200 OK

{
  "message": "Exit requested. Application will shut down.",
  "state": "Running"
}