FarmLoop Processing API

The Processing API lets your own software do what the FarmLoop web app does: send a sliced file plus tuning parameters to our server and receive the FarmLoop-modified file back — ready to print, with the detachment sequences injected.

Enterprise access

The Processing API is available to accounts that FarmLoop support has enabled for API access. Limits are conservative by default and can be raised for enterprise workloads — contact us.

What you need

1. A FarmLoop account with an active subscription — the same account you use on app.3d-farmers.com.
2. API access enabled — done by FarmLoop support for your account.
3. Your API key (fl_…) — provided during onboarding. Treat it like a password: it authenticates as your account. If it leaks, contact support and we revoke it immediately.

The endpoint

POST https://api.3d-farmers.com/api/v1/process

Authentication is a single header on every request:

X-API-Key: fl_your_key_here

A quick way to check your key works before sending files:

curl -sS https://api.3d-farmers.com/api/v1/process \
  -H "X-API-Key: fl_your_key_here"

GET on the same URL returns a machine-readable description of the API. If you get JSON back (not a 401/403), you’re in.

Sending a file

One sliced file per request as the multipart field file:

• Accepted: .gcode.3mf, .3mf (must be sliced, i.e. contain gcode), .gcode
• Not accepted: binary G-code (.bgcode), project files without gcode
• Max size: 200 MB
• No multi-file merge yet — send files individually

All tuning parameters are optional multipart fields:

Field	Values	Default
detachmentMode	push / lift	push
stage	1 / 2	1
cooldownType	temperature / time	temperature
cooldownTemperature	°C, 20–100	30
cooldownTime	seconds, 0–86400	300
heatedBedTemperature	°C, 0–120	taken from your slicer file
zOffset	mm, −5 to 5	taken from your slicer file
pushHeight	mm, 0–300	5
useFanUpgrade	true / false	false
copies	1–10	1

copies repeats the whole print inside one gcode file with the ejection sequence between loops — the printer runs all copies unattended in a single job. Output size grows with each copy; requests whose expanded output would exceed 400 MB are rejected with 413.

curl

curl -sS https://api.3d-farmers.com/api/v1/process \
  -H "X-API-Key: fl_your_key_here" \
  -F "file=@benchy.gcode.3mf" \
  -F "stage=2" \
  -F "detachmentMode=push" \
  -F "cooldownTemperature=28" \
  -OJ

-OJ saves the response using the server-suggested filename.

Python

import requests

resp = requests.post(
    "https://api.3d-farmers.com/api/v1/process",
    headers={"X-API-Key": "fl_your_key_here"},
    files={"file": open("benchy.gcode.3mf", "rb")},
    data={"stage": "2", "detachmentMode": "push"},
    timeout=300,
)
resp.raise_for_status()

if resp.headers.get("X-FarmLoop-Warning"):
    print("Warning:", resp.headers["X-FarmLoop-Warning"])

from urllib.parse import unquote
out_name = unquote(resp.headers["X-FarmLoop-Output-Name"])
with open(out_name, "wb") as f:
    f.write(resp.content)
print("Saved", out_name, "| printer:", resp.headers["X-FarmLoop-Printer"])

Node.js

const fs = require("node:fs");

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("benchy.gcode.3mf")]), "benchy.gcode.3mf");
form.append("stage", "2");

const resp = await fetch("https://api.3d-farmers.com/api/v1/process", {
  method: "POST",
  headers: { "X-API-Key": "fl_your_key_here" },
  body: form,
});
if (!resp.ok) throw new Error(await resp.text());

const outName = decodeURIComponent(resp.headers.get("x-farmloop-output-name"));
fs.writeFileSync(outName, Buffer.from(await resp.arrayBuffer()));

The response

On success (200) the body is the modified file, plus these headers:

Header	Meaning
X-FarmLoop-Printer	Detected printer model (e.g. P1S, X1E, H2D)
X-FarmLoop-Stage	Stage that was processed (1 or 2)
X-FarmLoop-Output-Name	Suggested filename, URL-encoded
X-FarmLoop-Warning	Only present when the input has compatibility issues — see below

Keep the FL_S2_ filename prefix

Stage 2 output filenames start with FL_S2_. Do not rename this away — FarmLoop kits running Digital Mode (Full MQTT) arm themselves off that prefix. If your software renames files before sending them to the printer, preserve the prefix.

Warnings

Processing still succeeds, but X-FarmLoop-Warning is set when:

• the file was sliced with OrcaSlicer (not supported — re-slice with Bambu Studio v02.04+),
• the file carries an outdated Bambu Studio printer profile (pre-v02.04 — update Bambu Studio and re-slice with the stock profile), or
• the filename suggests the file was already processed by FarmLoop (re-processing duplicates the injected sequences).

Surface these warnings to your users — a warned file may print without the detachment sequence working.

Errors and limits

Status	Meaning
400	Invalid parameters or unsupported file type — message says which
401	Missing/invalid API key
403	API access not enabled for the account, or no active subscription
413	File over 200 MB, or expanded output (file × copies) over 400 MB
422	Unreadable 3MF, no gcode inside, or unknown printer type
429	Rate limit: max 10 requests per 5 minutes per key. Retry-After header tells you when to retry
503	Server at capacity (max 2 concurrent jobs). Retry after a few seconds

Recommended client behavior: honor Retry-After on 429/503, and treat 4xx responses as permanent for that file/request (don’t blind-retry).

Building with an AI agent?

If you’re writing your integration with an AI coding assistant (Claude, Cursor, Copilot, ChatGPT, …), we maintain a machine-readable spec written specifically for agents — the complete API contract, validation ranges, required retry behavior, and reference implementations, with no marketing prose to wade through:

processing-api-for-ai-agents.md

How to use it:

• Claude Code / CLI agents — save it into your project (e.g. docs/farmloop-api.md) and reference it, or paste the URL into the chat:

  curl -sSo docs/farmloop-api.md \
    https://help.3d-farmers.com/integrations/processing-api-for-ai-agents.md

• Chat assistants — paste the URL (or the file’s contents) into the conversation and ask the assistant to build against it.

The file instructs the agent to read your API key from the FARMLOOP_API_KEY environment variable — set that before running generated code, and never let the key be committed or logged.

Support

API questions, key rotation, or limit increases: contact FarmLoop support and mention “Processing API”.