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

name, description

name

description

flamenco-api

Flamenco render farm manager API reference, configuration, and usage guide. Use this skill whenever working with Flamenco — querying jobs, workers, tasks, or farm status via the REST API, writing curl commands or Python scripts that talk to the Flamenco Manager, configuring the manager or workers, troubleshooting render farm issues, managing worker tags or sleep schedules, creating custom job types, or understanding how Flamenco integrates with Blender. Also use when the user mentions render farm, farm status, render workers, job submission, or Flamenco in any context. Trigger on mentions of flamenco, render farm, render worker, farm status, job queue, render job, or worker management in the context of rendering.

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

For complete details, read these as needed — they're verbose and only worth loading when you're actually constructing API calls or troubleshooting:

• references/api-reference.md: Every endpoint with parameters, request/response schemas, status codes, and curl examples. Read this when constructing a specific API call or understanding a response shape.
• references/usage-docs.md (optional, may not be present): General Flamenco usage — shared storage, manager/worker configuration, two-way variable replacement, custom job types, failure handling, troubleshooting. Read this for setup or non-API questions.

If a reference file is missing or out of date, the canonical source is <MANAGER_URL>/api/v3/swagger-ui/ and <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.