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

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.