claude-plugins/plugins/flamenco/skills/flamenco-api/SKILL.md

---
name: flamenco-api
description: Flamenco render farm Manager API reference (REST + Python SDK), configuration, and usage guide. Use when querying or controlling jobs, workers, tasks, or farm status; submitting renders; configuring the Manager or Workers; managing worker tags or sleep schedules; creating custom job types; or any mention of Flamenco, render farm, render workers, or job queue.
---

# Flamenco Render Farm

[Flamenco](https://flamenco.blender.org/) is the render farm manager developed by the Blender
Foundation. It consists of a **Manager** (HTTP server, web UI, REST API) and one or more
**Workers** that pull jobs from the Manager and execute them — usually Blender renders, but the
job-type system is generic enough for ffmpeg encodes, file copies, or anything else.

## Setup before answering

Flamenco is self-hosted, so the Manager URL is site-specific. Before constructing API calls:

1. Check the user's environment for a Manager URL (env var like `FLAMENCO_MANAGER_URL`,
   project config, or `CLAUDE.md`). The Manager web UI and the REST API share the same host;
   `/api/v3/` is the API prefix.
2. If you can't find one, ask the user. Don't invent a URL.

In examples below, `<MANAGER_URL>` is a placeholder for the user's Manager root
(e.g. `https://flamenco.example.com` or `http://localhost:8080`). The API base is
`<MANAGER_URL>/api/v3/`.

Useful endpoints on any Manager:

- Web UI: `<MANAGER_URL>/`
- Swagger UI: `<MANAGER_URL>/api/v3/swagger-ui/`
- OpenAPI spec: `<MANAGER_URL>/api/v3/openapi3.json`

The API has no authentication by default — Flamenco assumes a trusted LAN. If the user has
fronted it with a reverse proxy that adds auth, account for that.

## Quick API examples

```bash
# Farm status (one of: active, idle, waiting, asleep, inoperative, unknown, starting)
curl -s <MANAGER_URL>/api/v3/status

# Manager version
curl -s <MANAGER_URL>/api/v3/version

# List all workers
curl -s <MANAGER_URL>/api/v3/worker-mgt/workers

# List all jobs
curl -s <MANAGER_URL>/api/v3/jobs

# Get a specific job
curl -s <MANAGER_URL>/api/v3/jobs/{job_id}

# Get tasks for a job
curl -s <MANAGER_URL>/api/v3/jobs/{job_id}/tasks

# Get task details (commands, status, assigned worker)
curl -s <MANAGER_URL>/api/v3/tasks/{task_id}

# Tail a task's log as plain text
curl -s <MANAGER_URL>/api/v3/tasks/{task_id}/logtail

# Query jobs by status (note: jobs query is POST, not GET)
curl -s <MANAGER_URL>/api/v3/jobs \
  -X POST -H 'Content-Type: application/json' \
  -d '{"status_in": ["failed"], "order_by": ["updated_at"], "limit": 5}'

# Change worker status (awake, asleep, offline, restart) — is_lazy waits for current task
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/workers/{worker_id}/setstatus \
  -H 'Content-Type: application/json' -d '{"status": "awake", "is_lazy": false}'

# Cancel / pause / requeue a job
curl -X POST <MANAGER_URL>/api/v3/jobs/{job_id}/setstatus \
  -H 'Content-Type: application/json' -d '{"status": "canceled", "reason": "no longer needed"}'
```

## Key concepts

- **Job**: A render request, typically submitted from the Blender add-on. Carries settings
  (blend file, frame range, output path, format) and is compiled by the Manager into tasks.
- **Task**: An executable unit within a job (e.g. "render frames 1–10"). Assigned to one worker
  at a time. A task contains one or more **commands**.
- **Command**: The lowest-level operation a worker runs (e.g. `blender-render`, `move-directory`,
  `frames-to-video`). Defined by the worker code; referenced by job-type scripts.
- **Worker**: A machine that polls the Manager for tasks and executes them. Has a status
  (awake, asleep, offline, error, …) and a list of supported task types.
- **Tag**: A grouping label for workers. Jobs can be restricted to a tag so they only run on
  matching workers (e.g. a `gpu` tag for GPU-only nodes).
- **Job type**: A JavaScript file in the Manager's `scripts/` directory that defines settings
  and the compile function (turns a submitted job into a sequence of tasks). Built-in types
  like `simple-blender-render` cover the common cases; custom types add new behaviors.
- **Shaman**: Optional content-addressed file store. When enabled, files are uploaded by
  SHA256+size and symlinked into per-job checkout dirs. When disabled, files are referenced
  in place on shared storage.

## Status enums

- **Job**: `active`, `canceled`, `completed`, `failed`, `paused`, `pause-requested`, `queued`,
  `cancel-requested`, `requeueing`, `under-construction`
- **Task**: `active`, `canceled`, `completed`, `failed`, `queued`, `soft-failed`, `paused`
- **Worker**: `starting`, `awake`, `asleep`, `error`, `testing`, `offline`, `restart`
- **Farm**: `active`, `idle`, `waiting`, `asleep`, `inoperative`, `unknown`, `starting`

## Python SDK

Flamenco ships an auto-generated Python client (`flamenco-manager` on PyPI, importable as
`flamenco.manager`):

```python
from flamenco.manager import ApiClient, Configuration
from flamenco.manager.api import JobsApi, WorkerMgtApi, MetaApi

configuration = Configuration(host="<MANAGER_URL>")
api_client = ApiClient(configuration)

meta_api = MetaApi(api_client)
print(meta_api.get_version())  # FlamencoVersion

jobs_api = JobsApi(api_client)
jobs = jobs_api.fetch_jobs()
failed = [j for j in jobs.jobs if j.status == "failed"]

worker_api = WorkerMgtApi(api_client)
for w in worker_api.fetch_workers().workers:
    print(f"{w.name}: {w.status}")
```

For ad-hoc scripts, plain `requests` against the REST API is often simpler and avoids the SDK
dependency.

## Submitting a job

Two endpoints take the same body — `POST /api/v3/jobs/check` validates without inserting,
`POST /api/v3/jobs` actually submits. Always send `submitter_platform` (`linux`, `windows`,
`darwin`, or `manager`) so the Manager can apply path replacements.

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

The exact `settings` keys depend on the job type. List available types with
`GET /api/v3/jobs/types`, or fetch one with `GET /api/v3/jobs/type/{typeName}` to see its
declared settings.

## Reference files

- **`references/api-reference.md`** — every endpoint with parameters, request/response
  schemas, status codes, and curl examples. Load when constructing a specific API call or
  decoding a response shape.

If the reference is out of date, the canonical source is `<MANAGER_URL>/api/v3/swagger-ui/`
or `<MANAGER_URL>/api/v3/openapi3.json` — fetching the OpenAPI JSON is the fastest way to
verify a schema.

## Notes on the worker-side API

`/api/v3/worker/*` endpoints (`sign-on`, `sign-off`, `register-worker`, `state`,
`state-changed`, `task`, `task/{id}`, `task/{id}/may-i-run`, `task/{id}/output-produced`)
exist for the worker process to talk back to the Manager. They are not normally called by
end-user scripts; only touch them if you're implementing a custom worker or debugging the
worker protocol.