# Flamenco Manager API Reference

Base URL: `<MANAGER_URL>` — replace with the user's Flamenco Manager root
(e.g. `https://flamenco.example.com` or `http://localhost:8080`).

API prefix: `/api/v3`

All request/response bodies are JSON unless noted otherwise. The API has no authentication
by default; if the user's deployment is behind an auth proxy, add the appropriate headers.

## Contents

- **Meta** — version, status, configuration, setup-assistant helpers
- **Jobs** — submit, query, cancel, set status / priority / tag, blocklist, last-rendered
- **Tasks** — fetch, set status, log info / tail
- **Worker management** — list/fetch/delete workers, status changes, tags, sleep schedules
- **Shaman** — content-addressed file storage (only relevant if Shaman is enabled)
- **Worker-side** — endpoints workers use to talk back to the Manager (rarely called by users)
- **Schemas** — `Job`, `Task`, `Worker`, status enums, etc.

---

## Meta

### Get Version

```
GET /api/v3/version
```

Returns the Flamenco Manager version.

**Response:** `200` - `FlamencoVersion`

```bash
curl <MANAGER_URL>/api/v3/version
```

---

### Get Farm Status

```
GET /api/v3/status
```

Returns the overall farm status (active, idle, waiting, asleep, etc.).

**Response:** `200` - `FarmStatusReport`

```bash
curl <MANAGER_URL>/api/v3/status
```

---

### Get Configuration

```
GET /api/v3/configuration
```

Returns Manager configuration (storage location, Shaman enabled, first run flag).

**Response:** `200` - `ManagerConfiguration`

```bash
curl <MANAGER_URL>/api/v3/configuration
```

---

### Get Configuration File

```
GET /api/v3/configuration/file
```

Retrieve the raw configuration file contents.

**Response:** `200` - JSON object or YAML string (via `Accept` header)

```bash
curl <MANAGER_URL>/api/v3/configuration/file
```

---

### Update Configuration File

```
PUT /api/v3/configuration/file
```

Overwrite the configuration file. Does not actively reload.

**Body:** JSON object (no schema validation)

**Responses:** `204` success | `default` error

```bash
curl -X PUT <MANAGER_URL>/api/v3/configuration/file \
  -H 'Content-Type: application/json' \
  -d '{"storage": "/render/storage"}'
```

---

### Get Shared Storage Location

```
GET /api/v3/configuration/shared-storage/{audience}/{platform}
```

Get the shared storage path adjusted for a specific audience and platform.

| Parameter  | In   | Type   | Description                              |
|------------|------|--------|------------------------------------------|
| `audience` | path | string | `workers` or `users`                     |
| `platform` | path | string | OS platform (`linux`, `windows`, `darwin`) |

**Response:** `200` - `SharedStorageLocation`

```bash
curl <MANAGER_URL>/api/v3/configuration/shared-storage/users/linux
```

---

### Get Variables

```
GET /api/v3/configuration/variables/{audience}/{platform}
```

Get Manager variables (used for two-way path replacement).

| Parameter  | In   | Type   | Description                              |
|------------|------|--------|------------------------------------------|
| `audience` | path | string | `workers` or `users`                     |
| `platform` | path | string | OS platform (`linux`, `windows`, `darwin`) |

**Response:** `200` - `ManagerVariables` (map of variable name to properties)

```bash
curl <MANAGER_URL>/api/v3/configuration/variables/workers/linux
```

---

### Find Blender Executable

```
GET /api/v3/configuration/check/blender
```

Auto-discover Blender executable paths on the Manager host.

**Response:** `200` - `BlenderPathFindResult` (array of `BlenderPathCheckResult`)

```bash
curl <MANAGER_URL>/api/v3/configuration/check/blender
```

---

### Check Blender Executable Path

```
POST /api/v3/configuration/check/blender
```

Validate a specific path or command as a Blender executable.

**Body:** `PathCheckInput` - `{"path": "/usr/bin/blender"}`

**Response:** `200` - `BlenderPathCheckResult`

```bash
curl -X POST <MANAGER_URL>/api/v3/configuration/check/blender \
  -H 'Content-Type: application/json' \
  -d '{"path": "/usr/bin/blender"}'
```

---

### Check Shared Storage Path

```
POST /api/v3/configuration/check/shared-storage
```

Validate a directory path for use as shared storage.

**Body:** `PathCheckInput` - `{"path": "/render/storage"}`

**Response:** `200` - `PathCheckResult`

```bash
curl -X POST <MANAGER_URL>/api/v3/configuration/check/shared-storage \
  -H 'Content-Type: application/json' \
  -d '{"path": "/render/storage"}'
```

---

### Save Setup Assistant Config

```
POST /api/v3/configuration/setup-assistant
```

Save initial configuration from the Setup Assistant and restart Manager.

**Body:** `SetupAssistantConfig` - `{"storageLocation": "...", "blenderExecutable": {...}}`

**Responses:** `204` success | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/configuration/setup-assistant \
  -H 'Content-Type: application/json' \
  -d '{"storageLocation": "/render/storage", "blenderExecutable": {"input": "blender", "path": "/usr/bin/blender", "source": "path_envvar", "is_usable": true, "cause": "Found on PATH"}}'
```

---

## Jobs

### List All Jobs

```
GET /api/v3/jobs
```

Fetch all jobs in the database.

**Response:** `200` - `JobsQueryResult` (`{"jobs": [Job, ...]}`)

```bash
curl <MANAGER_URL>/api/v3/jobs
```

---

### Submit a Job

```
POST /api/v3/jobs
```

Submit a new job for execution.

**Body:** `SubmittedJob`

| Field                | Type   | Required | Description                                        |
|----------------------|--------|----------|----------------------------------------------------|
| `name`               | string | yes      | Job name                                           |
| `type`               | string | yes      | Job type (e.g. `simple-blender-render`)            |
| `priority`           | int    | yes      | 0-100, default 50                                  |
| `submitter_platform` | string | yes      | `linux`, `windows`, `darwin`, or `manager`         |
| `settings`           | object | no       | Job-type-specific settings                         |
| `metadata`           | object | no       | Arbitrary key-value metadata                       |
| `type_etag`          | string | no       | Etag from `AvailableJobType` to prevent stale submissions |
| `initial_status`     | string | no       | Override initial status (default: `queued`)         |
| `worker_tag`         | string | no       | UUID of worker tag to restrict execution            |
| `storage`            | object | no       | Shaman checkout ID info                            |

**Responses:** `200` - `Job` | `412` etag mismatch | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Render",
    "type": "simple-blender-render",
    "priority": 50,
    "submitter_platform": "linux",
    "settings": {
      "blendfile": "/render/project/scene.blend",
      "frames": "1-100",
      "chunk_size": 5,
      "render_output_path": "/render/project/output/######",
      "format": "PNG"
    },
    "metadata": {
      "project": "MyProject",
      "user.name": "artist"
    }
  }'
```

---

### Check Job (Dry Run)

```
POST /api/v3/jobs/check
```

Validate a job definition without creating it. Same body as Submit.

**Responses:** `204` valid | `412` etag mismatch | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/jobs/check \
  -H 'Content-Type: application/json' \
  -d '{"name": "Test", "type": "simple-blender-render", "priority": 50, "submitter_platform": "linux", "settings": {"blendfile": "/render/scene.blend", "frames": "1-10"}}'
```

---

### Fetch a Job

```
GET /api/v3/jobs/{job_id}
```

Get full info about a specific job.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Response:** `200` - `Job`

```bash
curl <MANAGER_URL>/api/v3/jobs/abc123-uuid
```

---

### Delete a Job

```
DELETE /api/v3/jobs/{job_id}
```

Request deletion of a job, its tasks, and log files. Actual deletion happens in background.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Responses:** `204` accepted | `default` error

```bash
curl -X DELETE <MANAGER_URL>/api/v3/jobs/abc123-uuid
```

---

### What Would Delete Do

```
GET /api/v3/jobs/{job_id}/what-would-delete-do
```

Preview what will be deleted (e.g. whether Shaman checkout dir is removed).

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Response:** `200` - `JobDeletionInfo`

```bash
curl <MANAGER_URL>/api/v3/jobs/abc123-uuid/what-would-delete-do
```

---

### Mass Delete Jobs

```
DELETE /api/v3/jobs/mass-delete
```

Mark jobs for deletion based on criteria. Deletion happens in background.

**Body:** `JobMassDeletionSelection`

| Field              | Type     | Description                                  |
|--------------------|----------|----------------------------------------------|
| `last_updated_max` | datetime | Delete jobs last updated before this timestamp |

**Responses:** `204` accepted | `416` no matching jobs | `default` error

```bash
curl -X DELETE <MANAGER_URL>/api/v3/jobs/mass-delete \
  -H 'Content-Type: application/json' \
  -d '{"last_updated_max": "2025-01-01T00:00:00Z"}'
```

---

### Set Job Status

```
POST /api/v3/jobs/{job_id}/setstatus
```

Change a job's status (e.g. pause, cancel, requeue).

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Body:** `JobStatusChange`

| Field    | Type   | Required | Description                |
|----------|--------|----------|----------------------------|
| `status` | string | yes      | New `JobStatus` value      |
| `reason` | string | yes      | Reason for the change      |

**Responses:** `204` accepted | `422` invalid transition | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/jobs/abc123-uuid/setstatus \
  -H 'Content-Type: application/json' \
  -d '{"status": "canceled", "reason": "No longer needed"}'
```

---

### Set Job Priority

```
POST /api/v3/jobs/{job_id}/setpriority
```

Change a job's priority.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Body:** `JobPriorityChange` - `{"priority": 75}`  (0-100)

**Responses:** `204` accepted | `422` invalid priority | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/jobs/abc123-uuid/setpriority \
  -H 'Content-Type: application/json' \
  -d '{"priority": 75}'
```

---

### Set Job Tag

```
POST /api/v3/jobs/{job_id}/settag
```

Assign or remove a worker tag from a job. Send empty body to remove tag.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Body:** `JobTagChange` - `{"id": "tag-uuid"}` or `{"name": "TagName"}`

**Responses:** `204` accepted | `422` invalid tag | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/jobs/abc123-uuid/settag \
  -H 'Content-Type: application/json' \
  -d '{"name": "GPU-EEVEE"}'
```

---

### Fetch Job Tasks

```
GET /api/v3/jobs/{job_id}/tasks
```

Get a summary list of all tasks belonging to a job.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Response:** `200` - `JobTasksSummary` (`{"tasks": [TaskSummary, ...]}`)

```bash
curl <MANAGER_URL>/api/v3/jobs/abc123-uuid/tasks
```

---

### Fetch Job Blocklist

```
GET /api/v3/jobs/{job_id}/blocklist
```

Get the list of worker/task-type pairs blocked on this job.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Response:** `200` - `JobBlocklist` (array of `JobBlocklistEntry`)

```bash
curl <MANAGER_URL>/api/v3/jobs/abc123-uuid/blocklist
```

---

### Remove Job Blocklist Entries

```
DELETE /api/v3/jobs/{job_id}/blocklist
```

Remove specific worker/task-type pairs from the blocklist.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Body:** `JobBlocklist` (array of `{"worker_id": "...", "task_type": "..."}`)

**Responses:** `204` accepted | `default` error

```bash
curl -X DELETE <MANAGER_URL>/api/v3/jobs/abc123-uuid/blocklist \
  -H 'Content-Type: application/json' \
  -d '[{"worker_id": "worker-uuid", "task_type": "blender"}]'
```

---

### Get Last Rendered Image Info (Job)

```
GET /api/v3/jobs/{job_id}/last-rendered
```

Get URL info for the last-rendered image of a specific job.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `job_id`  | path | string | yes      |

**Responses:** `200` - `JobLastRenderedImageInfo` | `204` no image

```bash
curl <MANAGER_URL>/api/v3/jobs/abc123-uuid/last-rendered
```

---

### Get Last Rendered Image Info (Global)

```
GET /api/v3/jobs/last-rendered
```

Get URL info for the global last-rendered image (across all jobs).

**Responses:** `200` - `JobLastRenderedImageInfo` | `204` no image

```bash
curl <MANAGER_URL>/api/v3/jobs/last-rendered
```

---

### Get Job Types

```
GET /api/v3/jobs/types
```

List all available job types and their settings.

**Response:** `200` - `AvailableJobTypes` (`{"job_types": [AvailableJobType, ...]}`)

```bash
curl <MANAGER_URL>/api/v3/jobs/types
```

---

### Get Single Job Type

```
GET /api/v3/jobs/type/{typeName}
```

Get a specific job type and its parameters.

| Parameter  | In   | Type   | Required |
|------------|------|--------|----------|
| `typeName` | path | string | yes      |

**Response:** `200` - `AvailableJobType`

```bash
curl <MANAGER_URL>/api/v3/jobs/type/simple-blender-render
```

---

### Fetch a Task

```
GET /api/v3/tasks/{task_id}
```

Get full details of a single task.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `task_id` | path | string | yes      |

**Response:** `200` - `Task`

```bash
curl <MANAGER_URL>/api/v3/tasks/task-uuid
```

---

### Set Task Status

```
POST /api/v3/tasks/{task_id}/setstatus
```

Change a task's status. May affect the parent job status.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `task_id` | path | string | yes      |

**Body:** `TaskStatusChange`

| Field    | Type   | Required | Description                |
|----------|--------|----------|----------------------------|
| `status` | string | yes      | New `TaskStatus` value     |
| `reason` | string | yes      | Reason for the change      |

**Responses:** `204` accepted | `422` invalid transition | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/tasks/task-uuid/setstatus \
  -H 'Content-Type: application/json' \
  -d '{"status": "queued", "reason": "Retry after fix"}'
```

---

### Get Task Log Info

```
GET /api/v3/tasks/{task_id}/log
```

Get metadata about the task log (URL, size).

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `task_id` | path | string | yes      |

**Responses:** `200` - `TaskLogInfo` | `204` no log yet

```bash
curl <MANAGER_URL>/api/v3/tasks/task-uuid/log
```

---

### Get Task Log Tail

```
GET /api/v3/tasks/{task_id}/logtail
```

Fetch the last few lines of the task's log as plain text.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `task_id` | path | string | yes      |

**Responses:** `200` - `text/plain` | `204` no log yet

```bash
curl <MANAGER_URL>/api/v3/tasks/task-uuid/logtail
```

---

## Worker Management (worker-mgt)

### List Workers

```
GET /api/v3/worker-mgt/workers
```

Get all known workers.

**Response:** `200` - `WorkerList` (`{"workers": [WorkerSummary, ...]}`)

```bash
curl <MANAGER_URL>/api/v3/worker-mgt/workers
```

---

### Fetch a Worker

```
GET /api/v3/worker-mgt/workers/{worker_id}
```

Get detailed info about a specific worker.

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Response:** `200` - `Worker`

```bash
curl <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid
```

---

### Delete a Worker

```
DELETE /api/v3/worker-mgt/workers/{worker_id}
```

Remove a worker. Best used when worker is offline. Assigned tasks will be requeued.

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Responses:** `204` deleted | `default` error

```bash
curl -X DELETE <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid
```

---

### Request Worker Status Change

```
POST /api/v3/worker-mgt/workers/{worker_id}/setstatus
```

Ask a worker to change state (e.g. send to sleep, wake up, restart).

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Body:** `WorkerStatusChangeRequest`

| Field    | Type    | Required | Description                                      |
|----------|---------|----------|--------------------------------------------------|
| `status` | string  | yes      | Target `WorkerStatus` value                      |
| `is_lazy`| boolean | yes      | If true, wait for current task to finish first    |

**Responses:** `204` accepted | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid/setstatus \
  -H 'Content-Type: application/json' \
  -d '{"status": "asleep", "is_lazy": true}'
```

---

### Set Worker Tags

```
POST /api/v3/worker-mgt/workers/{worker_id}/settags
```

Update which tags a worker belongs to.

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Body:** `WorkerTagChangeRequest` - `{"tag_ids": ["tag-uuid-1", "tag-uuid-2"]}`

**Responses:** `204` accepted | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid/settags \
  -H 'Content-Type: application/json' \
  -d '{"tag_ids": ["tag-uuid-1"]}'
```

---

### Get Worker Sleep Schedule

```
GET /api/v3/worker-mgt/workers/{worker_id}/sleep-schedule
```

Fetch the sleep schedule for a worker.

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Responses:** `200` - `WorkerSleepSchedule` | `204` no schedule | `default` error

```bash
curl <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid/sleep-schedule
```

---

### Set Worker Sleep Schedule

```
POST /api/v3/worker-mgt/workers/{worker_id}/sleep-schedule
```

Create or update a worker's sleep schedule.

| Parameter   | In   | Type   | Required |
|-------------|------|--------|----------|
| `worker_id` | path | string | yes      |

**Body:** `WorkerSleepSchedule`

| Field          | Type    | Required | Description                                          |
|----------------|---------|----------|------------------------------------------------------|
| `is_active`    | boolean | yes      | Whether the schedule is enabled                      |
| `start_time`   | string  | yes      | Start time in `HH:MM` format                        |
| `end_time`     | string  | yes      | End time in `HH:MM` format                          |
| `days_of_week` | string  | yes      | Space-separated day codes (`mo tu we th fr sa su`) or empty for every day |

**Responses:** `204` stored | `default` error

```bash
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/workers/worker-uuid/sleep-schedule \
  -H 'Content-Type: application/json' \
  -d '{"is_active": true, "start_time": "09:00", "end_time": "18:00", "days_of_week": "mo tu we th fr"}'
```

---

### List Worker Tags

```
GET /api/v3/worker-mgt/tags
```

Get all worker tags.

**Response:** `200` - `WorkerTagList` (`{"tags": [WorkerTag, ...]}`)

```bash
curl <MANAGER_URL>/api/v3/worker-mgt/tags
```

---

### Create Worker Tag

```
POST /api/v3/worker-mgt/tags
```

Create a new worker tag.

**Body:** `WorkerTag`

| Field         | Type   | Required | Description                      |
|---------------|--------|----------|----------------------------------|
| `name`        | string | yes      | Tag name                        |
| `description` | string | no       | Tag description                 |
| `id`          | string | no       | UUID (auto-generated if omitted) |

**Response:** `200` - `WorkerTag` (with assigned UUID)

```bash
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/tags \
  -H 'Content-Type: application/json' \
  -d '{"name": "GPU-EEVEE", "description": "Workers with GPU for EEVEE rendering"}'
```

---

### Fetch Worker Tag

```
GET /api/v3/worker-mgt/tag/{tag_id}
```

Get a single worker tag.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `tag_id`  | path | string | yes      |

**Response:** `200` - `WorkerTag`

```bash
curl <MANAGER_URL>/api/v3/worker-mgt/tag/tag-uuid
```

---

### Update Worker Tag

```
PUT /api/v3/worker-mgt/tag/{tag_id}
```

Update an existing worker tag.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `tag_id`  | path | string | yes      |

**Body:** `WorkerTag` - `{"name": "NewName", "description": "Updated desc"}`

**Responses:** `204` stored | `default` error

```bash
curl -X PUT <MANAGER_URL>/api/v3/worker-mgt/tag/tag-uuid \
  -H 'Content-Type: application/json' \
  -d '{"name": "GPU-Cycles", "description": "GPU workers for Cycles"}'
```

---

### Delete Worker Tag

```
DELETE /api/v3/worker-mgt/tag/{tag_id}
```

Remove a worker tag. Unassigns all workers from it.

| Parameter | In   | Type   | Required |
|-----------|------|--------|----------|
| `tag_id`  | path | string | yes      |

**Responses:** `204` removed | `default` error

```bash
curl -X DELETE <MANAGER_URL>/api/v3/worker-mgt/tag/tag-uuid
```

---

## Shaman (File Transfer)

Shaman is Flamenco's content-addressed file storage system. Files are uploaded by SHA256+size, then symlinked into job checkout directories.

### Check File Status

```
GET /api/v3/shaman/files/{checksum}/{filesize}
```

Check whether a file exists in the Shaman store.

| Parameter  | In   | Type    | Required |
|------------|------|---------|----------|
| `checksum` | path | string  | yes      | SHA256 hex digest |
| `filesize` | path | integer | yes      | File size in bytes |

**Response:** `200` - `ShamanSingleFileStatus` (`{"status": "stored"|"uploading"|"unknown"}`)

```bash
curl <MANAGER_URL>/api/v3/shaman/files/35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0/1424
```

---

### Upload File

```
POST /api/v3/shaman/files/{checksum}/{filesize}
```

Upload a file to the Shaman store. Body is raw binary.

| Parameter  | In     | Type    | Required | Description                    |
|------------|--------|---------|----------|--------------------------------|
| `checksum` | path   | string  | yes      | SHA256 hex digest              |
| `filesize` | path   | integer | yes      | File size in bytes             |
| `X-Shaman-Can-Defer-Upload` | header | boolean | no | Allow deferring if someone else is uploading |
| `X-Shaman-Original-Filename` | header | string | no | Original filename for logging |

**Body:** `application/octet-stream` - raw file contents

**Responses:** `204` accepted | `208` already known | `417` checksum/size mismatch | `425` defer upload

```bash
curl -X POST <MANAGER_URL>/api/v3/shaman/files/35b0491c27b0333d1fb45fc0789a12ca06b1d640d2569780b807de504d7029e0/1424 \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-Shaman-Original-Filename: scene.blend' \
  --data-binary @scene.blend
```

---

### Check Requirements

```
POST /api/v3/shaman/checkout/requirements
```

Check which files from a list are missing from the Shaman store.

**Body:** `ShamanRequirementsRequest`

```json
{
  "files": [
    {"sha": "35b049...", "size": 1424, "path": "scene.blend"},
    {"sha": "63b72c...", "size": 127, "path": "config.py"}
  ]
}
```

**Response:** `200` - `ShamanRequirementsResponse` (only unknown/uploading files returned; known files are omitted)

```bash
curl -X POST <MANAGER_URL>/api/v3/shaman/checkout/requirements \
  -H 'Content-Type: application/json' \
  -d '{"files": [{"sha": "35b0491c...", "size": 1424, "path": "scene.blend"}]}'
```

---

### Create Checkout

```
POST /api/v3/shaman/checkout/create
```

Create a directory with symlinks to the specified files. All files must already be uploaded.

**Body:** `ShamanCheckout`

| Field          | Type   | Required | Description                                             |
|----------------|--------|----------|---------------------------------------------------------|
| `checkoutPath` | string | yes      | Relative path for the checkout (e.g. `project/scene/id`) |
| `files`        | array  | yes      | Array of `ShamanFileSpec` (`{sha, size, path}`)         |

**Responses:** `200` - `ShamanCheckoutResult` | `409` already exists | `424` missing files

```bash
curl -X POST <MANAGER_URL>/api/v3/shaman/checkout/create \
  -H 'Content-Type: application/json' \
  -d '{
    "checkoutPath": "my-project/scene-01/unique-id",
    "files": [
      {"sha": "35b0491c...", "size": 1424, "path": "scene.blend"},
      {"sha": "63b72c63...", "size": 127, "path": "config.py"}
    ]
  }'
```

---

## Worker-Side Endpoints

These endpoints under `/api/v3/worker/` are used by the Flamenco Worker process to talk back
to the Manager. Normal user scripts and pipeline tools do **not** call them — only touch them
when implementing a custom worker, or when debugging the worker protocol. They typically
require the worker's bearer token (set during `register-worker`) for authentication.

| Method | Path                                           | Operation              | Purpose                                                              |
|--------|------------------------------------------------|------------------------|----------------------------------------------------------------------|
| POST   | `/api/v3/worker/register-worker`               | `RegisterWorker`       | First-time registration; returns a worker ID and secret              |
| POST   | `/api/v3/worker/sign-on`                       | `SignOn`               | Worker comes online and reports metadata (hostname, task types, OS)  |
| POST   | `/api/v3/worker/sign-off`                      | `SignOff`              | Worker is going offline                                              |
| GET    | `/api/v3/worker/state`                         | `WorkerState`          | Poll for a pending state-change request from the Manager             |
| POST   | `/api/v3/worker/state-changed`                 | `WorkerStateChanged`   | Acknowledge a state change (or report a worker-local one)            |
| POST   | `/api/v3/worker/task`                          | `ScheduleTask`         | Ask the Manager for the next task to execute                         |
| POST   | `/api/v3/worker/task/{task_id}`                | `TaskUpdate`           | Report progress, completion, or failure                              |
| GET    | `/api/v3/worker/task/{task_id}/may-i-run`      | `MayWorkerRun`         | Check whether the worker is still allowed to run this task           |
| POST   | `/api/v3/worker/task/{task_id}/output-produced`| `TaskOutputProduced`   | Upload the latest rendered frame thumbnail (PNG/JPEG)                |

For the exact request/response schemas, consult `<MANAGER_URL>/api/v3/swagger-ui/` — these
endpoints evolve with the worker protocol and are best read from the live OpenAPI spec.

---

## Schemas

### Job

Extends `SubmittedJob` with server-assigned fields.

| Property              | Type     | Description                              |
|-----------------------|----------|------------------------------------------|
| `id`                  | string   | UUID                                     |
| `name`                | string   | Job name                                 |
| `type`                | string   | Job type identifier                      |
| `priority`            | integer  | 0-100                                    |
| `status`              | JobStatus | Current status                          |
| `activity`            | string   | Last activity description                |
| `created`             | datetime | Creation timestamp                       |
| `updated`             | datetime | Last update timestamp                    |
| `settings`            | object   | Job-type-specific settings               |
| `metadata`            | object   | Arbitrary key-value pairs                |
| `submitter_platform`  | string   | OS of the submitter                      |
| `worker_tag`          | string   | Worker tag UUID (optional)               |
| `storage`             | object   | Shaman checkout info (optional)          |
| `steps_completed`     | integer  | Progress numerator                       |
| `steps_total`         | integer  | Progress denominator                     |
| `delete_requested_at` | datetime | When deletion was requested (optional)   |

### SubmittedJob

The job definition as sent by the client (see Submit a Job above for fields).

### Task

| Property          | Type         | Description                           |
|-------------------|--------------|---------------------------------------|
| `id`              | string       | UUID                                  |
| `name`            | string       | Task name                             |
| `job_id`          | string       | Parent job UUID                       |
| `index_in_job`    | integer      | Task index within the job             |
| `status`          | TaskStatus   | Current status                        |
| `priority`        | integer      | Task priority                         |
| `task_type`       | string       | Type of task (e.g. `blender`, `ffmpeg`) |
| `activity`        | string       | Current activity description          |
| `created`         | datetime     | Creation timestamp                    |
| `updated`         | datetime     | Last update timestamp                 |
| `last_touched`    | datetime     | When a worker last worked on this     |
| `commands`        | [Command]    | List of commands to execute           |
| `worker`          | TaskWorker   | Currently assigned worker (optional)  |
| `failed_by_workers` | [TaskWorker] | Workers that failed this task       |
| `steps_completed` | integer      | Progress numerator                    |
| `steps_total`     | integer      | Progress denominator                  |

### Worker

Extends `WorkerSummary` with full details.

| Property               | Type           | Description                         |
|------------------------|----------------|-------------------------------------|
| `id`                   | string         | UUID                                |
| `name`                 | string         | Worker name                         |
| `status`               | WorkerStatus   | Current status                      |
| `version`              | string         | Flamenco version running            |
| `ip_address`           | string         | IP address                          |
| `platform`             | string         | OS (linux, windows, darwin)         |
| `supported_task_types` | [string]       | Task types this worker can handle   |
| `gpus`                 | [string]       | GPU descriptions                    |
| `last_seen`            | datetime       | Last contact time                   |
| `can_restart`          | boolean        | Whether worker can auto-restart     |
| `status_change`        | object         | Pending status change request       |
| `tags`                 | [WorkerTag]    | Assigned tags                       |
| `task`                 | WorkerTask     | Currently assigned task (optional)  |

### JobStatus

Enum: `active` | `canceled` | `completed` | `failed` | `paused` | `pause-requested` | `queued` | `cancel-requested` | `requeueing` | `under-construction`

### TaskStatus

Enum: `active` | `canceled` | `completed` | `failed` | `queued` | `soft-failed` | `paused`

### WorkerStatus

Enum: `starting` | `awake` | `asleep` | `error` | `testing` | `offline` | `restart`

### WorkerTag

| Property      | Type   | Description                          |
|---------------|--------|--------------------------------------|
| `id`          | string | UUID (optional on create)            |
| `name`        | string | Tag name (required)                  |
| `description` | string | Tag description (optional)           |

### WorkerSleepSchedule

| Property       | Type    | Description                                                |
|----------------|---------|------------------------------------------------------------|
| `is_active`    | boolean | Whether the schedule is enabled                            |
| `start_time`   | string  | Start time `HH:MM`                                        |
| `end_time`     | string  | End time `HH:MM`                                          |
| `days_of_week` | string  | Space-separated day codes (`mo tu we th fr sa su`) or empty |

### AvailableJobType

| Property      | Type                   | Description                           |
|---------------|------------------------|---------------------------------------|
| `name`        | string                 | Internal identifier                   |
| `label`       | string                 | Display name                          |
| `description` | string                 | Tooltip/description (optional)        |
| `etag`        | string                 | Hash (changes when settings change)   |
| `settings`    | [AvailableJobSetting]  | List of configurable settings         |

Each `AvailableJobSetting` has: `key` (string), `type` (`string|int32|float|bool`), `subtype` (optional: `file_path|dir_path|file_name|hashed_file_path`), `default`, `choices` (array), `required` (bool), `editable` (bool), `visible` (`visible|hidden|submission|web`).

### Command

| Property           | Type    | Description                    |
|--------------------|---------|--------------------------------|
| `name`             | string  | Command name                   |
| `parameters`       | object  | Command parameters             |
| `total_step_count` | integer | Expected number of steps       |

### FarmStatus

Enum: `active` | `idle` | `waiting` | `asleep` | `inoperative` | `unknown` | `starting`

### FlamencoVersion

| Property       | Type   | Description                         |
|----------------|--------|-------------------------------------|
| `version`      | string | Full version string for display     |
| `shortversion` | string | Short version (e.g. `3.3-alpha0`)   |
| `name`         | string | Manager instance name               |
| `git`          | string | Git version tag                     |