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

name, description

name	description
flamenco-api	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 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

# 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):

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.

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.