Lifecycle Actions

These are not the only start/stop endpoints, and the two pairs differ. The Runtime also serves the legacy Composer HTTP API, whose /api/stop and /api/start stop and resume playback while keeping the loaded project in memory — so in-memory changes, including an /api/project/load, survive the cycle. The /runtime pair below additionally tears the project graph down on stop and rebuilds it from the retained project file on start, which is what an orchestrator reclaiming a channel's resources wants but does discard in-memory changes. Both routes drive this same state machine, so /runtime/status stays accurate whichever you use, and mixing them in one sequence is supported: a legacy /api/start after a /runtime/stop finds no graph in memory and reloads the retained file.

GET|POST /runtime/stop

Requires: control (operator+)

Stops the currently running project, transitioning to Idle state, and clears the project graph — releasing its inputs, decoders and sockets. All infrastructure services (HTTP API, WebSocket, Prometheus) remain active. Use the legacy /api/stop instead to stop playback while keeping the project loaded.

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

Requires: control (operator+)

Starts the last loaded project from Idle state, re-reading it from disk. The project file must have been previously loaded (via initial CLI startup or /runtime/load). Use the legacy /api/start instead to start whatever is currently in memory without re-reading it.

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

Requires: control (operator+)

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

Requires: control (operator+)

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

Requires: control (operator+)

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"
}