Zordon/docs/API.md

Zordon API Reference

Zordon exposes a Flask API from src/api/api_server.py. The server is started by start_api_server() and listens on Config.port_number with all application routes mounted under /api.

The in-repo client wrapper is src/api/server_proxy.py. Most UI and distributed rendering code should prefer RenderServerProxy instead of constructing request URLs directly.

Versioning

• Current API version: 0.1
• RenderServerProxy.request() sends X-API-Version with the current API_VERSION, but the server does not currently validate this header.

Response Conventions

• JSON endpoints return Flask-serialized dictionaries or lists.
• File endpoints return send_file() responses.
• Most error responses are plain text with HTTP 400, 404, 500, or 503.
• JobNotFoundError is mapped to HTTP 400.
• Unhandled exceptions are mapped to HTTP 500 with a plain-text message.

Jobs

GET /api/jobs

Returns all render jobs and a cache token.

Response:

{
  "jobs": [
    {
      "id": "job-id",
      "name": "job name",
      "status": "running"
    }
  ],
  "token": "cache-token"
}

Known callers:

• RenderServerProxy.get_jobs()
• src/ui/main_window.py

GET /api/jobs/long_poll

Long-polls the job list until the supplied cache token changes or 30 seconds elapse.

Query parameters:

Name	Required	Description
token	No	Cache token returned by /api/jobs.

Responses:

• 200 with the same shape as /api/jobs when jobs changed.
• 204 with an empty body when no changes arrive before timeout.

Known callers:

• RenderServerProxy.get_jobs() through the background cache updater.

GET /api/jobs/status/<status_val>

Returns jobs matching a render status.

Path parameters:

Name	Description
status_val	Status string converted by string_to_status().

Responses:

• 200 with a list of job JSON objects when matches exist.
• 400 when no jobs match the requested status.

Review note: this route is not currently wrapped by RenderServerProxy and no in-repo callers were found.

GET /api/jobs/<job_id>

Returns one job as JSON.

Known callers:

• RenderServerProxy.get_job()
• add_job.py
• src/ui/main_window.py
• src/distributed_job_manager.py
• tests/job_creation_tests.py

GET /api/jobs/<job_id>/logs

Returns the job log file as text/plain.

Known callers:

• src/ui/main_window.py opens this URL directly.

GET /api/jobs/<job_id>/files

Returns a list of output filenames for the job.

Known callers:

• RenderServerProxy.get_job_files()
• src/utilities/server_helper.py

GET /api/jobs/<job_id>/download

Downloads one output file.

Query parameters:

Name	Required	Description
filename	Yes	Case-insensitive filename from the job file list.

Responses:

• 200 with the requested file as an attachment.
• 400 when filename is missing.
• 404 when the file is not found.

Known callers:

• RenderServerProxy.download_job_file()
• src/utilities/server_helper.py

GET /api/jobs/<job_id>/download_all

Creates a temporary zip of the job output directory and downloads it.

Known callers:

• RenderServerProxy.download_all_job_files()
• src/ui/main_window.py
• src/utilities/server_helper.py

GET /api/jobs/<job_id>/thumbnail

Returns a generated preview image or video for a job.

Query parameters:

Name	Required	Description
size	No	big selects the larger preview path. Currently parsed but not applied.
video_ok	No	If truthy and a video preview exists, video can be returned.

Responses:

• 200 with image/jpeg or video/mp4.
• 404 when no thumbnail is available.
• 500 on preview generation errors.

Known callers:

• src/ui/main_window.py

Review note: size=big is parsed into big_thumb but not used.

Job Lifecycle

POST /api/add_job

Adds one or more render jobs.

Request formats:

• JSON request body.
• Multipart form with a json field and optional file upload.

Common job fields include:

Name	Description
name	Display name for the render job.
renderer	Render engine name such as blender or ffmpeg.
start_frame	First frame to render.
end_frame	Last frame to render.
args	Engine-specific render arguments.
enable_split_jobs	Whether distributed subjobs may be created.
child_jobs	Optional subjob definitions.
local_path	Local file path used when posting to localhost.

Responses:

• 200 with created job data.
• 400 for invalid or missing job data.
• 500 for unexpected processing or creation errors.

Known callers:

• RenderServerProxy.create_job()
• add_job.py
• src/ui/add_job_window.py
• src/distributed_job_manager.py
• tests/job_creation_tests.py

POST /api/jobs/<job_id>/cancel

Cancels a job.

Query parameters:

Name	Required	Description
confirm	Yes	Must be truthy or the request is rejected.
redirect	No	If truthy, redirects to index.

Known callers:

• RenderServerProxy.cancel_job()
• src/ui/main_window.py
• src/distributed_job_manager.py

POST /api/jobs/<job_id>/delete

Deletes a job, stops it first, deletes previews, and removes owned upload/output directories when safe.

Query parameters:

Name	Required	Description
confirm	Yes	Must be truthy or the request is rejected.

Known callers:

• RenderServerProxy.delete_job()
• src/ui/main_window.py

POST /api/jobs/<job_id>/subjob_update

Notifies a parent job that a child/subjob changed state.

Request body:

• JSON representation of a subjob.

Known callers:

• RenderServerProxy.send_subjob_update_notification()
• src/distributed_job_manager.py

Status and Environment

GET /api/heartbeat

Returns the current timestamp as plain text. Used for fast connectivity checks.

Known callers:

• RenderServerProxy.check_connection()

GET /api/status

Returns local system and queue status.

Response includes:

• timestamp
• operating system and version
• CPU brand, count, and current utilization
• memory totals and current utilization
• job counts
• hostname and port
• app and API versions

Known callers:

• RenderServerProxy.get_status()

GET /api/presets

Returns config/presets.yaml.

Review note: no in-repo callers were found.

GET /api/cpu_benchmark

Runs a CPU benchmark for 10 seconds and returns the score as plain text.

Known callers:

• src/utilities/server_helper.py

GET /api/disk_benchmark

Runs a disk I/O benchmark and returns write/read speeds.

Review note: no in-repo callers were found.

Engines

GET /api/engines/for_filename

Returns the engine name suitable for a project filename.

Query parameters:

Name	Required	Description
filename	Yes	Project filename or path. The client currently sends only the basename.

Known callers:

• RenderServerProxy.get_engine_for_filename()
• src/ui/add_job_window.py

GET /api/engines

Returns installed engine data keyed by engine name.

Query parameters:

Name	Required	Description
response_type	No	standard or full; defaults to standard.

full responses also include supported extensions, supported export formats, system info, and UI options.

Known callers:

• RenderServerProxy.get_engines()
• src/ui/settings_window.py
• src/ui/engine_browser.py

GET /api/engines/names

Returns installed engine names as a list without instantiating engine classes. Use this for lightweight selection UIs that only need engine names.

Known callers:

• RenderServerProxy.get_engine_names()
• src/ui/add_job_window.py

GET /api/engines/<engine_name>

Returns installed version data for a single engine.

Query parameters:

Name	Required	Description
response_type	No	standard or full; defaults to standard.

full responses also include supported extensions, supported export formats, system info, and UI options.

Known callers:

• RenderServerProxy.get_engine()
• src/ui/add_job_window.py

GET /api/engines/<engine_name>/availability

Returns whether an engine can accept jobs on this server, plus CPU count, installed versions, and hostname.

Known callers:

• RenderServerProxy.get_engine_availability()
• src/distributed_job_manager.py

GET /api/engines/<engine_name>/args

Returns engine arguments.

Review note: no in-repo callers were found.

GET /api/engines/<engine_name>/help

Returns engine help text.

Known callers:

• src/ui/add_job_window.py opens this URL directly.

GET /api/engines/download_available

Checks whether a managed engine version is available to download.

Query parameters:

Name	Required	Description
engine	Yes	Engine name.
version	Yes	Engine version.
system_os	No	Target OS.
cpu	No	Target CPU architecture.

Review note: no in-repo callers were found.

GET /api/engines/most_recent_version

Finds the most recent downloadable version for an engine.

Query parameters:

Name	Required	Description
engine	Yes	Engine name.
system_os	No	Target OS.
cpu	No	Target CPU architecture.

Review note: no in-repo callers were found.

POST /api/engines/download

Downloads a managed engine version.

Query parameters:

Name	Required	Description
engine	Yes	Engine name.
version	Yes	Engine version.
system_os	No	Target OS.
cpu	No	Target CPU architecture.

Review note: no in-repo callers were found. Settings currently calls EngineManager.download_engine() directly instead of this API route.

POST /api/engines/delete

Deletes a managed engine download.

JSON body:

Name	Required	Description
engine	Yes	Engine name.
version	Yes	Engine version.
system_os	No	Target OS.
cpu	No	Target CPU architecture.

Known callers:

• RenderServerProxy.delete_engine_download()
• src/ui/engine_browser.py

Debug

GET /api/_debug/detected_clients

Returns hostnames detected by Zeroconf.

Review note: development/debug only, with an inline comment saying it probably should not ship.

POST /api/_debug/clear_history

Clears render queue history and returns success.

Review note: development/debug only.

Redundancy and Cleanup Review

Routes with no in-repo callers found:

• GET /api/jobs/status/<status_val>
• GET /api/presets
• GET /api/disk_benchmark
• GET /api/engines/<engine_name>/args
• GET /api/engines/download_available
• GET /api/engines/most_recent_version
• POST /api/engines/download
• GET /api/_debug/detected_clients
• POST /api/_debug/clear_history

Routes or methods with cleanup risks:

• job_thumbnail() parses size=big but never uses the resulting big_thumb value.