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:

```json
{
  "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/snapshot`

Returns local status, all jobs, and a timestamp.

Known callers:

- `full_status()` internally.

Review note: no direct in-repo HTTP callers were found. It overlaps with
`/api/status` plus `/api/jobs`.

### `GET /api/full_status`

Returns a multi-server shaped status payload with the local server populated.

Known callers:

- `RenderServerProxy.get_full_status()`
- `dashboard.py`

Review note: this currently reports only the local server. The response shape
suggests an intended future aggregation point.

### `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

Likely redundant or overlapping routes:

- `/api/snapshot` overlaps with `/api/status` and `/api/jobs`. It is currently
  used internally by `/api/full_status`.
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.