Zordon API Reference

Overview

Versioning

Current API version: 0.1
RenderServerProxy.request() sends X-API-Version.
The server does not currently validate that header.

Response Conventions

JSON endpoints return Flask-serialized dictionaries or lists.
File endpoints return send_file() responses.
Most errors are plain text with 400, 404, 500, or 503.
JobNotFoundError maps to HTTP 400.

Jobs

GET/api/jobs

Returns all render jobs and a cache token.

{
  "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 Parameter	Required	Description
`token`	No	Cache token returned by `/api/jobs`.

Returns 200 with job data when changed, or 204 when no change arrives before timeout.

GET/api/jobs/status/<status_val>

Returns jobs matching a render status converted by string_to_status().

No RenderServerProxy wrapper or in-repo caller was found.

GET/api/jobs/<job_id>

Returns one job as JSON.

Known callers include RenderServerProxy.get_job(), add_job.py, src/ui/main_window.py, src/distributed_job_manager.py, and tests/job_creation_tests.py.

GET/api/jobs/<job_id>/logs

Returns the job log file as text/plain. The main window 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() and src/utilities/server_helper.py.

GET/api/jobs/<job_id>/download

Downloads one output file.

Query Parameter	Required	Description
`filename`	Yes	Case-insensitive filename from the job file list.

Returns 200 with an attachment, 400 when filename is missing, or 404 when the file is not found.

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, and src/utilities/server_helper.py.

GET/api/jobs/<job_id>/thumbnail

Returns a generated preview image or video for a job.

Query Parameter	Required	Description
`size`	No	`big` is parsed but not currently applied.
`video_ok`	No	If truthy and a video preview exists, video can be returned.

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

Job Lifecycle

POST/api/add_job

Adds one or more render jobs. Accepts either a JSON request body or multipart form data with a json field and optional file upload.

Common Field	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.

Known callers include RenderServerProxy.create_job(), add_job.py, src/ui/add_job_window.py, src/distributed_job_manager.py, and integration tests.

POST/api/jobs/<job_id>/cancel

Cancels a job. Requires a truthy confirm query parameter.

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

POST/api/jobs/<job_id>/delete

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

Query Parameter	Required	Description
`confirm`	Yes	Must be truthy or the request is rejected.

POST/api/jobs/<job_id>/subjob_update

Notifies a parent job that a child/subjob changed state. The request body is the JSON representation of the subjob.

Status and Environment

GET/api/heartbeat

Returns the current timestamp as plain text. Used by RenderServerProxy.check_connection().

GET/api/status

Returns local system and queue status, including operating system, CPU, memory, job counts, hostname, port, app version, and API version.

GET/api/presets

Returns config/presets.yaml.

No in-repo callers were found.

GET/api/cpu_benchmark

Runs a CPU benchmark for 10 seconds and returns the score as plain text. Used by src/utilities/server_helper.py.

GET/api/disk_benchmark

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

No in-repo callers were found.

Engines

GET/api/engines/for_filename

Returns the engine name suitable for a project filename.

Query Parameter	Required	Description
`filename`	Yes	Project filename or path. The client currently sends only the basename.

GET/api/engines

Returns installed engine data keyed by engine name.

Query Parameter	Required	Description
`response_type`	No	`standard` or `full`; defaults to `standard`.

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

Known callers: RenderServerProxy.get_engines(), src/ui/settings_window.py, and 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() and src/ui/add_job_window.py.

GET/api/engines/<engine_name>

Returns installed version data for a single engine.

Query Parameter	Required	Description
`response_type`	No	`standard` or `full`; defaults to `standard`.

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

Known caller: RenderServerProxy.get_engine() in the add-job window.

GET/api/engines/<engine_name>/availability

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

GET/api/engines/<engine_name>/args

Returns engine arguments.

No in-repo callers were found.

GET/api/engines/<engine_name>/help

Returns engine help text. The add-job window opens this URL directly.

GET/api/engines/download_available

Checks whether a managed engine version is available to download.

Query Parameter	Required	Description
`engine`	Yes	Engine name.
`version`	Yes	Engine version.
`system_os`	No	Target OS.
`cpu`	No	Target CPU architecture.

No in-repo callers were found.

GET/api/engines/most_recent_version

Finds the most recent downloadable version for an engine.

Query Parameter	Required	Description
`engine`	Yes	Engine name.
`system_os`	No	Target OS.
`cpu`	No	Target CPU architecture.

No in-repo callers were found.

POST/api/engines/download

Downloads a managed engine version.

Query Parameter	Required	Description
`engine`	Yes	Engine name.
`version`	Yes	Engine version.
`system_os`	No	Target OS.
`cpu`	No	Target CPU architecture.

Settings currently calls EngineManager.download_engine() directly instead of this API route.

POST/api/engines/delete

Deletes a managed engine download.

JSON Field	Required	Description
`engine`	Yes	Engine name.
`version`	Yes	Engine version.
`system_os`	No	Target OS.
`cpu`	No	Target CPU architecture.

Debug

GET/api/_debug/detected_clients

Returns hostnames detected by Zeroconf.

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.

Development/debug only.

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

Cleanup Risks

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