Flamenco-Management/.specstory/history/2026-03-17_19-18-15Z-flamenco-api-exploration.md

2026-03-17 19:18:15Z

User

Explore this codebase to find information about Flamenco's API. Look for:

1. API documentation files (API.md, api/, docs/api/, etc.)
2. API endpoints and routes in the code
3. Any OpenAPI/Swagger specifications
4. Main server files that define API routes
5. Any README or documentation that explains the API

Return a summary of:

• What Flamenco is (what does this software do?)
• What API capabilities exist
• Key API endpoints or features found
• How to access/interact with the API

---

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

The user wants me to explore a codebase called "Flamenco" to find information about its API. I need to:

1. Look for API documentation files
2. Find API endpoints and routes in the code
3. Look for OpenAPI/Swagger specs
4. Find main server files with API routes
5. Find README or documentation about the API

Let me start by exploring the project structure to understand what Flamenco is and then dive into API-related files.

Agent (accounts/fireworks/models/kimi-k2p5)

I'll explore the Flamenco codebase to find information about its API. Let me start by understanding the project structure and then look for API-related files.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **run_terminal_command_v2** • Run command: ls -la

ls -la

Tool use: **run_terminal_command_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

It seems the directory might be empty or the files aren't matching my patterns. Let me try different approaches to explore the workspace.

Agent (accounts/fireworks/models/kimi-k2p5)

Let me try a different approach to explore the workspace.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **run_terminal_command_v2** • Run command: dir

dir

Tool use: **run_terminal_command_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **68** results in **1** directory

Directory: **** (68 files)

File
scripts/TalkingHeads cycles_optix_gpu.js
sqlite/2025.04.22.09.37.45_flamenco-manager.sqlite
unified_flamenco_launcher.ps1
.specstory/history/2025-07-15_18-30Z-configure-launch-standard-worker-for-flamenco-3-7.md
.gitignore
.specstory/history/2025-05-06_21-34Z-identifying-mistakes-and-seeking-guidance.md
.specstory/history/2025-08-13_18-59Z-remove-seq-from-jobname-format.md
.specstory/history/2025-11-21_01-14Z-workers-failing-and-ssh-connection-issues.md
sqlite/2025.06.06.09.50.20_flamenco-manager.sqlite
sqlite/2025.05.09.09.38.44_flamenco-manager.sqlite
.specstory/history/2025-05-05_16-17Z-flamenco-job-status-troubleshooting.md
.specstory/history/2025-04-04_17-25Z-creating-worker2-scripts-for-flamenco.md
.specstory/history/2025-11-06_17-28Z-update-path-structure-for-renders.md
sqlite/2025.05.05.16.15.03_flamenco-manager.sqlite
.specstory/history/2025-11-19_17-03Z-why-is-git-frozen.md
sqlite/2025.05.05.10.09.33_flamenco-manager.sqlite
sqlite/2025.07.22.09.37.20_flamenco-manager.sqlite
.specstory/history/2025-04-23_20-48Z-network-drive-mapping-and-file-copying-script.md
.specstory/history/2025-11-21_16-43Z-fixing-sheepit-worker-incompatibility.md
.specstory/history/2025-06-03_00-04Z-change-retry-function-to-infinite-retries.md
.specstory/history/2026-01-08_23-42Z-windows-symlinking-error.md
sqlite/2026.01.08.10.06.50_flamenco-manager.sqlite
.specstory/history/2026-03-06_22-52Z-sequence-determination-in-custom-javascripts.md
sqlite/2025.11.19.11.05.13_flamenco-manager.sqlite
TODO.md
sqlite/2025.06.17.13.57.17_flamenco-manager.sqlite
.specstory/history/2025-05-06_20-07Z-switching-to-optix-gpu-rendering.md
.specstory/history/2026-01-09_18-22Z-nexus-manager-access-issue.md
sqlite/2025.07.15.10.16.07_flamenco-manager.sqlite
sqlite/2025.04.17.09.50.29_flamenco-manager.sqlite
unified_sheepit_launcher.bat
sqlite/2025.07.10.10.00.59_flamenco-manager.sqlite
.specstory/history/2026-03-04_02-01Z-testing-discussion.md
.specstory/history/2026-03-16_20-23Z-blocklisting-in-flamenco-codebase.md
.specstory/history/2026-03-16_20-23Z-disabling-blocklisting-in-flamenco.md
sqlite/2025.05.12.10.52.00_flamenco-manager.sqlite
unified_sheepit_launcher.ps1
.specstory/.project.json
linux_flamenco_manager.bat
.specstory\.what-is-this.md
sqlite/2025.05.28.17.21.15_flamenco-manager.sqlite
.specstory/history/2025-05-23_23-12Z-replace-remotecmd-with-remotesimplified.md
sqlite/2025.07.15.14.04.28_flamenco-manager.sqlite
unified_flamenco_launcher.bat
.specstory/history/2026-02-10_22-00Z-error-in-blender-file-cleanup-command.md
sqlite/2025.04.24.09.43.08_flamenco-manager.sqlite
.specstory/history/2025-05-07_22-05Z-script-modification-for-masterbox.md
.specstory/history/2026-01-09_20-34Z-flamenco-project-file-path-consistency.md
.specstory/.gitignore
.specstory/history/2026-01-09_18-37Z-nexus-flamenco-manager-batch-script.md
.specstory/history/2025-05-14_15-49Z-cmd-worker-error-handling-and-retry-logic.md
sqlite/2025.04.21.09.53.46_flamenco-manager.sqlite
sqlite/2025.09.11.11.39.47_flamenco-manager.sqlite
sqlite/2026.02.10.10.22.19_flamenco-manager.sqlite
.specstory/history/2026-01-08_17-28Z-shaman-symlinking-for-windows-samba.md
.specstory/history/2025-05-13_23-13Z-bypassing-password-prompts-in-script.md
.gitattributes
sqlite/2025.10.27.12.46.53_flamenco-manager.sqlite
scripts/outline.txt
sqlite/2025.04.25.09.55.50_flamenco-manager.sqlite
.specstory/history/2025-05-12_16-04Z-technical-scripting-and-troubleshooting-discussion.md
.specstory/history/2025-11-03_19-27Z-create-sister-script-for-sheepit.md
sqlite/2025.07.28.09.34.53_flamenco-manager.sqlite
sqlite/2025.07.01.11.02.08_flamenco-manager.sqlite
.cursorindexingignore
.specstory/history/2025-04-25_19-30Z-i9-13ks-setup-troubleshooting.md
scripts/TalkingHeads Custom Render.js
sqlite/2026.03.02.11.11.48_flamenco-manager.sqlite

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

This is interesting. I can see:

1. SQLite databases named "flamenco-manager.sqlite" - suggesting Flamenco is a render farm manager
2. Scripts for "TalkingHeads" which seem to be custom JavaScript files
3. Some .specstory/history files which contain conversations about Flamenco
4. Scripts for launching workers and managing Flamenco

Let me look at the TODO.md file and some of these specstory files to understand what Flamenco is. Also let me check the scripts folder.

Agent (accounts/fireworks/models/kimi-k2p5)

I can see this is related to Flamenco render farm manager. Let me explore the key files to understand the API.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\TODO.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\.specstory\.what-is-this.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **0** results in **1** directory

Directory: **** (0 files)

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **glob_file_search** • Searched codebase "" • **2** results in **1** directory

Directory: **** (2 files)

File
scripts/TalkingHeads cycles_optix_gpu.js
scripts/TalkingHeads Custom Render.js

Tool use: **glob_file_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

So there are no Go or Python source files in this directory - this seems to be a workspace with scripts and databases for using Flamenco, not the actual Flamenco source code. The Flamenco source code must be elsewhere. Let me look at the specstory history files to learn more about what Flamenco is and its API.

Agent (accounts/fireworks/models/kimi-k2p5)

This workspace contains scripts for using Flamenco but not the source code. Let me examine the specstory history files to find API information.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\.specstory\history\2025-05-05_16-17Z-flamenco-job-status-troubleshooting.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\.specstory\history\2026-03-16_20-23Z-blocklisting-in-flamenco-codebase.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\.specstory\history\2026-03-16_20-23Z-disabling-blocklisting-in-flamenco.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\scripts\TalkingHeads Custom Render.js

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

Now I have comprehensive information about Flamenco's API from the specstory history files. Let me read a few more files to get a complete picture and also check for any additional API documentation.

Agent (accounts/fireworks/models/kimi-k2p5)

Excellent! I've found extensive API information. Let me read a few more specstory files and scripts to get a complete picture.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\.specstory\history\2025-07-15_18-30Z-configure-launch-standard-worker-for-flamenco-3-7.md

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\scripts\outline.txt

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **read_file_v2** • Read file: C:\Users\Nathan\Desktop\flamenco\unified_flamenco_launcher.ps1

Tool use: **read_file_v2**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

I now have extensive information about Flamenco's API. Let me also search for more information about the API endpoints and how to interact with them.

Agent (accounts/fireworks/models/kimi-k2p5)

Let me search for a few more references to complete the API picture.

Agent (accounts/fireworks/models/kimi-k2p5)

Tool use: **ripgrep_raw_search**

Parameters:

{
  "caseInsensitive": false,
  "context": 2,
  "outputMode": "content",
  "path": "C:\\Users\\Nathan\\Desktop\\flamenco\\.specstory",
  "pattern": "api/v3|GET|POST|PATCH|DELETE"
}

Additional data:

{
  "isPruned": true,
  "outputMode": "content",
  "path": "C:\\Users\\Nathan\\Desktop\\flamenco\\.specstory",
  "pattern": "api/v3|GET|POST|PATCH|DELETE",
  "topFiles": [
    {
      "matchCount": 500,
      "uri": ".specstory/history/2025-08-13_18-59Z-remove-seq-from-jobname-format.md"
    }
  ],
  "totalFiles": 1,
  "totalMatches": 203
}

Status: completed

Tool use: **ripgrep_raw_search**

Agent (accounts/fireworks/models/kimi-k2p5)

Thought Process

I have gathered comprehensive information about Flamenco's API from the specstory history files. Let me compile this into a comprehensive summary for the user.

Agent (accounts/fireworks/models/kimi-k2p5)

Based on my exploration of the codebase and specstory history files, I can now provide you with a comprehensive summary of Flamenco's API.

---

Flamenco API Summary

What Flamenco Is

Flamenco is a production render farm manager developed by the Blender Studio. It's designed to distribute Blender rendering jobs across multiple worker machines in a network. The system consists of:

• Flamenco Manager: The central server that coordinates jobs, manages the queue, and communicates with workers
• Flamenco Workers: Machines that execute rendering tasks
• Web Interface: A browser-based UI for managing jobs and monitoring the farm
• API: A RESTful API for programmatic access to all Flamenco functionality

The default port is 8888, and the API is accessible at http://<manager-host>:8888/api/v3/.

---

API Capabilities

Based on the specstory history, Flamenco provides a comprehensive REST API (v3) with the following capabilities:

1. Job Management

• List all jobs: GET /api/v3/jobs
• Get job details: GET /api/v3/jobs/{job_id}
• Get job tasks: GET /api/v3/jobs/{job_id}/tasks
• Delete a job: DELETE /api/v3/jobs/{job_id}

2. Task Management

• List tasks for a job: GET /api/v3/jobs/{job_id}/tasks
• Get specific task: GET /api/v3/jobs/{job_id}/tasks/{task_id}

3. Worker Management

• Worker sign-on: POST /api/v3/worker/sign-on
• Workers can connect to the manager to receive tasks and report status

4. Swagger/OpenAPI Documentation

• Swagger UI: http://<manager>:8888/api/v3/swagger-ui/#/
• This provides interactive API documentation and testing interface

---

Key API Endpoints Found

From the troubleshooting sessions in the specstory history, these endpoints were discovered:

Endpoint	Method	Description
/api/v3/jobs	GET	List all jobs
/api/v3/jobs/{id}	GET	Get job details
/api/v3/jobs/{id}/tasks	GET	List tasks for a job
/api/v3/jobs/{id}	DELETE	Delete a specific job
/api/v3/worker/sign-on	POST	Worker registration endpoint
/api/v3/swagger-ui/	GET	Swagger UI documentation

Note: The specstory history reveals that many intuitive endpoints for updating job/task status (like PATCH /api/v3/jobs/{id}/status) returned 404 errors, suggesting that either:

1. The API documentation in Swagger UI should be consulted for the correct endpoints
2. Some operations may only be available through the web interface
3. The API may have limited write operations exposed

---

How to Access/Interact with the API

Using curl (Command Line)

# List all jobs
curl "http://localhost:8888/api/v3/jobs"

# Get specific job details
curl "http://localhost:8888/api/v3/jobs/{job_id}"

# List tasks for a job
curl "http://localhost:8888/api/v3/jobs/{job_id}/tasks"

# Delete a job
curl -X DELETE "http://localhost:8888/api/v3/jobs/{job_id}" \
  -H "Content-Type: application/json"

Using PowerShell

# List all jobs
Invoke-RestMethod -Method GET -Uri "http://localhost:8888/api/v3/jobs"

# Delete a job
Invoke-RestMethod -Method DELETE -Uri "http://localhost:8888/api/v3/jobs/{job_id}" \
  -ContentType "application/json"

Using Swagger UI

The easiest way to explore and test the API is through the built-in Swagger UI:

1. Navigate to: http://<manager-ip>:8888/api/v3/swagger-ui/#/
2. This provides an interactive interface to:
   • View all available endpoints
   • Test API calls directly from the browser
   • See request/response formats

---

Configuration and Database

Manager Configuration: flamenco-manager.yaml

• Location: Next to the flamenco-manager executable
• Contains API port settings, database path, timeouts, and blocklist thresholds

Database: SQLite database

• Default: flamenco-manager.sqlite
• Contains all job, task, and worker information
• Can be queried directly as a fallback when API operations are limited

---

Summary of API Limitations Found

The specstory history revealed that programmatic job/task status updates were problematic:

• PATCH /api/v3/jobs/{id}/status returned 404
• PATCH /api/v3/tasks/{id}/status returned 404
• POST /api/v3/jobs/{id}/pause returned 404

This suggests that the Flamenco API may be primarily read-only for external clients, with job state changes intended to be done through:

1. The web interface
2. Direct database manipulation (for advanced users)
3. The Blender Flamenco addon

For the most accurate and up-to-date API documentation, always check the Swagger UI at /api/v3/swagger-ui/ on your Flamenco Manager instance.