HTTP REST API

HTTP REST API Reference

The HTTP REST API is the primary control interface for modern FlashForge printers (Adventurer 5M, 5M Pro, AD5X). It operates on port 8898 and provides a modern, JSON-based interface for printer control.

Overview

Property	Value
Port	8898
Protocol	HTTP/1.1
Content-Type	application/json (most endpoints)
Authentication	serialNumber + checkCode

Authentication

All HTTP API endpoints require authentication. See Authentication for complete details.

JSON Body Authentication (most endpoints):

{
  "serialNumber": "YOUR_SERIAL_NUMBER",
  "checkCode": "YOUR_CHECK_CODE"
}

Header Authentication (uploadGcode only):

serialNumber: YOUR_SERIAL_NUMBER
checkCode: YOUR_CHECK_CODE

Response Format

All responses use a standard JSON envelope:

Success:

{
  "code": 0,
  "message": "Success"
}

Error:

{
  "code": <non-zero>,
  "message": "Error description"
}

Code	Message	Description
0	Success	Operation completed successfully
1	Error	Generic error occurred
2	Invalid parameter	Request payload contains invalid parameters
3	Unauthorized	Authentication failed (invalid serial or check code)
4	Not found	Requested resource or file not found
5	Busy	Printer is busy with another operation

Endpoints

/detail - Get Printer Details

Retrieves comprehensive information about the printer's current status.

Method: POST

Request:

POST http://10.0.0.42:8898/detail
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345"
}

Response:

{
  "code": 0,
  "message": "Success",
  "detail": {
    "autoShutdown": "open",
    "autoShutdownTime": 30,
    "cameraStreamUrl": "http://10.0.0.43:8080/?action=stream",
    "chamberFanSpeed": 100,
    "chamberTargetTemp": 0,
    "chamberTemp": 45,
    "coolingFanSpeed": 100,
    "cumulativeFilament": 120.5,
    "cumulativePrintTime": 1234,
    "currentPrintSpeed": 100,
    "doorStatus": "close",
    "errorCode": "",
    "estimatedLeftLen": 0,
    "estimatedLeftWeight": 0,
    "estimatedRightLen": 12500,
    "estimatedRightWeight": 35.5,
    "estimatedTime": 3600,  // REMAINING print time, seconds (countdown). 0.0 when idle. See "Print Time Fields" below.
    "externalFanStatus": "open",
    "fillAmount": 20,
    "firmwareVersion": "v3.1.3",
    "flashRegisterCode": "ABCDEFGH",
    "internalFanStatus": "open",
    "ipAddr": "10.0.0.43",
    "leftFilamentType": "",
    "leftTargetTemp": 0,
    "leftTemp": 0,
    "lightStatus": "open",
    "location": "Office",
    "macAddr": "00:11:22:33:44:55",
    "name": "CustomPrinterName",
    "nozzleCnt": 1,
    "nozzleModel": "0.4mm",
    "nozzleStyle": 1,
    "pid": 36,
    "platTargetTemp": 60,
    "platTemp": 58,
    "polarRegisterCode": "IJKLMNOP",
    "printDuration": 1800,  // ELAPSED print time for this job, seconds. 0 when idle. See "Print Time Fields" below.
    "printFileName": "Benchy.gcode",
    "printFileThumbUrl": "http://10.0.0.43:8898/thumb/Benchy.gcode",
    "printLayer": 50,
    "printProgress": 0.45,
    "printSpeedAdjust": 100,
    "remainingDiskSpace": 1024,
    "rightFilamentType": "PLA",
    "rightTargetTemp": 210,
    "rightTemp": 209,
    "status": "printing",
    "targetPrintLayer": 100,
    "tvoc": 0,
    "zAxisCompensation": 0
  }
}

Key Fields:

Field	Type	Description
status	string	Current printer state (see Machine States below)
printProgress	float	Print progress ratio (0.0 - 1.0). Note: This value is a ratio (0.0–1.0), not a percentage. Multiply by 100 to get a percentage.
printLayer	int	Current print layer
targetPrintLayer	int	Total layers in print
estimatedTime	float	Print time remaining, in seconds (countdown; firmware-derived from progress). `0.0` when idle. See Print Time Fields.
printDuration	int	Elapsed print time for the current job, in seconds. `0` when idle. See Print Time Fields.
platTemp	float	Current bed temperature (C)
platTargetTemp	float	Target bed temperature (C)
leftTemp / rightTemp	float	Current extruder temperature(s) (C)
leftTargetTemp / rightTargetTemp	float	Target extruder temperature(s) (C)
lightStatus	string	LED status ("open" or "close")
firmwareVersion	string	Firmware version string
name	string	Printer name
pid	int	Product ID — canonical model identifier. Firmware reports it as a hex string (parse base-16). 35 = 5M, 36 = 5M Pro, 38 = AD5X. Most reliable model detector; see Printer PIDs.
tvoc	int	TVOC level (5M Pro only)

Print Time Fields: `estimatedTime` and `printDuration`

The /detail response carries two print-time fields. Each field has one meaning. Do not mix them.

Field	Type	Unit	Direction	Meaning	When idle
`estimatedTime`	float / double	seconds	counts down	Print time remaining. The firmware computes it from progress data.	`0.0`
`printDuration`	int	seconds	counts up	Elapsed print time for the current job.	`0`

Recommended derivations (correct formulas)

Remaining time: use estimatedTime directly. Do not subtract printDuration. estimatedTime is already the remaining value.
Absolute completion time: now() + estimatedTime. This value is valid only while the print is advancing. Gate it on status = printing (see State Machines).
Best practice: consume the API library's pre-computed, already-gated completion_time / CompletionTime field. Do not recompute it locally.

When the printer is paused, heating, or in an error state, the firmware freezes estimatedTime. If you recompute now() + estimatedTime on every poll, the completion time recedes minute by minute while the print stays paused.

Common pitfalls (anti-patterns)

❌ remaining = estimatedTime - printDuration — double-counts. estimatedTime is already the remaining value. (This exact bug existed in two frontends.)
❌ Recompute completion_time = now() + estimatedTime on every poll without a printing-state gate. The result recedes while the print is paused.
❌ Treat printDuration as a total or as a remaining value. It is neither. It is the elapsed counter.
✅ Gate every ETA computation on status = printing, or use the library completion_time / CompletionTime field directly.

Do not confuse these fields with static per-file estimates

Three different fields carry a time value. They are not interchangeable.

Field	Where it appears	What it means
`estimatedTime`	live `/detail`	Remaining print time (countdown). Live value.
`printingTime`	`GcodeFileEntry` in `/gcodeList` (AD5X)	Static slicer estimate for one file. Not live.
`estimateTime`	per-file cloud-sync field (note: no `d`)	Static total estimate for one file. Not live.

printProgress (progress ratio, 0.0-1.0), cumulativePrintTime (lifetime total), and printLayer / targetPrintLayer (layer progress) are separate fields. They do not depend on estimatedTime or printDuration.

/product - Get Feature Availability

Returns the availability status of the controllable printer features.

Method: POST

Request:

POST http://10.0.0.42:8898/product
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345"
}

Response:

{
  "code": 0,
  "message": "Success",
  "product": {
    "chamberTempCtrlState": 0,
    "externalFanCtrlState": 1,
    "internalFanCtrlState": 1,
    "lightCtrlState": 1,
    "nozzleTempCtrlState": 1,
    "platformTempCtrlState": 1
  }
}

Field	Value	Description
0	Not available/controllable	Feature not present
1	Available/controllable	Feature is present

⚠️ Note: The /product *CtrlState flags are NOT a reliable indicator of hardware capabilities. Across models and firmware versions, FlashForge firmware may report 1 for absent hardware. It may also report 0 for present hardware. Do not use these flags as the source of truth. Instead, identify the model via /detail pid (see Printer PIDs) and consult the Capability Matrix.

Note: Even if lightCtrlState returns 0, the lightControl_cmd often still functions. This is common with aftermarket LED installations.

/control - Send Control Commands

Sends control commands to the printer. This endpoint uses a command/args structure.

Method: POST

Request Format:

POST http://10.0.0.42:8898/control
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "COMMAND_NAME",
    "args": {
      // Command-specific arguments
    }
  }
}

Success Response:

{
  "code": 0,
  "message": "Success"
}

lightControl_cmd - LED Control

Controls the printer's internal LED lighting.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "lightControl_cmd",
    "args": {
      "status": "open"
    }
  }
}

Argument	Values	Description
status	"open", "close"	Turn LEDs on or off

jobCtl_cmd - Job Control

Manages the current print job (pause, resume, cancel).

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "jobCtl_cmd",
    "args": {
      "jobID": "",
      "action": "pause"
    }
  }
}

Argument	Values	Description
jobID	string	Typically empty
action	"pause", "continue", "cancel"	Job action to perform

printerCtl_cmd - Printer Control

Adjusts printer settings during an active print.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "printerCtl_cmd",
    "args": {
      "speed": 100,
      "zAxisCompensation": 0.1,
      "chamberFan": 255,
      "coolingFan": 255
    }
  }
}

Argument	Range	Description
speed	50–500	Print speed percentage (50–150 for 5M/Pro, up to 500 for AD5X)
zAxisCompensation	-5.0 to +5.0	Z-axis offset (mm)
chamberFan	0-255	Chamber fan speed (0=off)
coolingFan	0-255	Cooling fan speed (0=off)

Important - Partial Updates: Do not send default values (like 0) for fields you do not intend to change. Fields omitted from the payload are ignored (internally set to sentinel values like -200). Explicit values overwrite current settings.

circulateCtl_cmd - Air Filtration Control

Controls the printer's internal and external air circulation/filtration fans.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "circulateCtl_cmd",
    "args": {
      "internal": "open",
      "external": "close"
    }
  }
}

Argument	Values	Description
internal	"open", "close"	Internal circulation fan
external	"open", "close"	External exhaust fan

Availability: 5M Pro only (internal/external fan hardware required).

streamCtrl_cmd - Camera Stream Control

Controls the printer's integrated camera stream.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "streamCtrl_cmd",
    "args": {
      "action": "open"
    }
  }
}

Argument	Values	Description
action	"open", "close"	Start or stop the camera stream

Availability: 5M Pro only (built-in camera required).

stateCtrl_cmd - State Control

Clears printer state dialogs that block further operations. Use this to dismiss on-screen dialogs after:

Print completes (build plate needs clearing)
Print is stopped/cancelled (via TCP M26 or HTTP jobCtl_cmd stop)

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "stateCtrl_cmd",
    "args": {
      "action": "setClearPlatform"
    }
  }
}

Argument	Value	Description
action	"setClearPlatform"	Dismiss dialog and reset to ready state

Availability: 5M Series, AD5X

temperatureCtl_cmd - Temperature Control

Sets target temperatures for nozzle, bed, and chamber.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "temperatureCtl_cmd",
    "args": {
      "rightNozzle": 210,
      "platform": 60
    }
  }
}

Argument	Range	Description
rightNozzle	0-265, -100=off, -200=no change	Main/right nozzle temperature (C)
leftNozzle	0-265, -100=off, -200=no change	Left nozzle temperature (C, dual-extruder)
platform	0-100, -100=off, -200=no change	Bed temperature (C)
chamber	0-60, -100=off, -200=no change	Chamber temperature (C, if supported)

Note: Use -200 to leave a temperature unchanged (partial update). Use -100 or 0 to turn off a heater.

reName_cmd - Rename Printer

Changes the printer's display name.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "reName_cmd",
    "args": {
      "name": "My Printer"
    }
  }
}

delayClose_cmd - Auto Shutdown Timer

Configures automatic shutdown timing.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "delayClose_cmd",
    "args": {
      "automaticShutdown": "open",
      "shutdownAfterTime": 30
    }
  }
}

Argument	Values	Description
automaticShutdown	"open", "close"	Enable or disable auto-shutdown
shutdownAfterTime	int	Minutes before shutdown after print completes

calibration_cmd - Calibration Control

Triggers a pre-print calibration sequence (automatic bed leveling and/or input-shaper vibration compensation). Each option is an independent toggle.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "calibration_cmd",
    "args": {
      "levelingDetection": "open",
      "vibrationCompensation": "open"
    }
  }
}

Argument	Values	Description
levelingDetection	"open", "close"	Enable automatic bed-leveling detection before the print
vibrationCompensation	"open", "close"	Enable input-shaper vibration compensation calibration

Note: Only the exact string "open" enables a step; the firmware treats any other value (e.g. "close") as disabled. Both fields are required. The command is silently ignored while a print is in progress.

Availability: 5M, 5M Pro, AD5X.

userProfile_cmd - User Profile

Sets the local user profile displayed on the printer (profile name and avatar). The firmware forwards both values as raw strings.

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "payload": {
    "cmd": "userProfile_cmd",
    "args": {
      "name": "Workshop",
      "avatar": "avatar_03"
    }
  }
}

Argument	Type	Description
name	string	Display/profile name
avatar	string	Avatar identifier (raw string; the exact catalog of valid IDs is not yet confirmed)

Availability: 5M, 5M Pro, AD5X (present in the firmware control dispatch and the OpenAPI specs).

/gcodeList - Get Recent Files

Retrieves a list of the 10 most recently used files stored on the printer.

Method: POST

Request:

POST http://10.0.0.42:8898/gcodeList
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345"
}

Response (5M/5M Pro):

{
  "code": 0,
  "message": "Success",
  "gcodeList": [
    "Benchy.3mf",
    "CalibrationCube.gcode",
    "Vase.gcode"
  ]
}

Response (AD5X):

{
  "code": 0,
  "message": "Success",
  "gcodeListDetail": [
    {
      "gcodeFileName": "Model.gcode",
      "printingTime": 3600,
      "totalFilamentWeight": 150.5,
      "useMatlStation": true,
      "gcodeToolCnt": 4,
      "gcodeToolDatas": [
        {
          "toolId": 0,
          "materialName": "PLA",
          "materialColor": "#FF0000",
          "filamentWeight": 50.2,
          "slotId": 0
        }
      ]
    }
  ]
}

Response (Creator 5 / 5 Pro): identical in shape to the 5M — file names only.

{
  "code": 0,
  "message": "Success",
  "gcodeList": [
    "anchor knauf 3.3mf",
    "dark angels heraldry.3mf"
  ]
}

The AD5X is the only model that returns gcodeListDetail. The Creator 5 series is newer hardware than the AD5X, but it reports less here. It reports no print time, no filament weight, and no gcodeToolDatas. Live-confirmed on a Creator 5 Pro (2026-08-05).

A client cannot offer material matching for a file already on a Creator 5: /detail says what each slot holds, but nothing says what the file needs. If a client reconstructs the missing half from the slot report or the file name, it sends the printer a mapping the printer never described. Material matching on this model is possible only at upload. When the client uploads the file, it parses the .3mf itself and supplies materialMappings at print-start. See Creator 5 Series.

/gcodeThumb - Get File Thumbnail

Retrieves a thumbnail image for a file stored on the printer.

Method: POST

Request:

POST http://10.0.0.42:8898/gcodeThumb
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "fileName": "Benchy.gcode"
}

Response:

{
  "code": 0,
  "message": "Success",
  "imageData": "BASE64_ENCODED_IMAGE_DATA"
}

Note: /gcodeThumb is how thumbnails are fetched on every model, one file at a time — no listing response embeds image data. On the AD5X, /gcodeList additionally returns per-file metadata (gcodeListDetail), but no thumbnails.

/printGcode - Print Local File

Initiates a print job for a file already on the printer's storage.

Method: POST

Request body — firmware 3.1.3+ (modern, current), single-color / standard:

Firmware 3.1.3 and newer (including 3.2.7) requires the extended body. For single-color / non-material-station prints the material-station fields are sent disabled (empty):

POST http://10.0.0.42:8898/printGcode
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "fileName": "Benchy.gcode",
  "levelingBeforePrint": true,
  "flowCalibration": false,
  "useMatlStation": false,
  "gcodeToolCnt": 0,
  "materialMappings": []
}

Pre-3.1.3 (legacy) — minimal body:

Older firmware accepted only the four core fields. On 3.1.3+, this minimal body is rejected or misbehaves. Use this body only when you target pre-3.1.3 firmware:

POST http://10.0.0.42:8898/printGcode
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "fileName": "Benchy.gcode",
  "levelingBeforePrint": true
}

Request (AD5X multi-material):

AD5X multi-color/multi-material prints must carry the tool→slot mapping in the request body. Set useMatlStation: true, put one entry per gcode tool in materialMappings, and make gcodeToolCnt equal the array length.

POST http://10.0.0.42:8898/printGcode
Content-Type: application/json

{
  "serialNumber": "SNADVA5MXXXXX",
  "checkCode": "12345",
  "fileName": "Multicolor.gcode",
  "levelingBeforePrint": true,
  "firstLayerInspection": false,
  "flowCalibration": false,
  "timeLapseVideo": false,
  "useMatlStation": true,
  "gcodeToolCnt": 2,
  "materialMappings": [
    {
      "toolId": 0,
      "slotId": 1,
      "materialName": "PLA",
      "toolMaterialColor": "#FFFFFF",
      "slotMaterialColor": "#FFFFFF"
    },
    {
      "toolId": 1,
      "slotId": 2,
      "materialName": "PLA",
      "toolMaterialColor": "#FF0000",
      "slotMaterialColor": "#FF0000"
    }
  ]
}

Parameter	Type	Description
serialNumber	string	Printer serial number
checkCode	string	Printer check code
fileName	string	Name of file to print (must already be on printer storage)
levelingBeforePrint	boolean	Perform auto-leveling before print
firstLayerInspection	boolean	AD5X only — run first-layer inspection
flowCalibration	boolean	AD5X only — perform flow calibration
timeLapseVideo	boolean	AD5X only — capture time-lapse video
useMatlStation	boolean	AD5X only — drive the material station (set `true` for multi-material)
gcodeToolCnt	integer	AD5X only — number of tool channels in the gcode (1-4); equals `materialMappings` length
materialMappings	array	AD5X only — tool→slot mapping objects (see below)

Material mapping object:

Field	Type	Description
toolId	integer	G-code tool index, 0-based (0-3)
slotId	integer	Material station slot, 1-based (1-4)
materialName	string	Material type, e.g. `PLA`
toolMaterialColor	string	Color declared in the gcode, `#RRGGBB`
slotMaterialColor	string	Color of the physical slot filament, `#RRGGBB`

Response:

{
  "code": 0,
  "message": "Success"
}

Note: toolId is 0-based (0-3) while slotId is 1-based (1-4) — do not confuse the two. To set the mapping at upload time, use /uploadGcode. Pass materialMappings as a Base64-encoded header. You can also start a print immediately on upload with the same endpoint. See Multi-Material Printing Workflow for the end-to-end sequence.

/uploadGcode - Upload File

Uploads a file to the printer and optionally starts printing immediately.

Method: POST

Content-Type: multipart/form-data

Headers:

Header	Description
serialNumber	Printer serial number
checkCode	Printer check code
fileSize	File size in bytes
printNow	"true" or "false" (string boolean)
levelingBeforePrint	"true" or "false" (string boolean)
flowCalibration	"true" or "false" (AD5X only)
useMatlStation	"true" or "false" (AD5X only)
gcodeToolCnt	Number of tools (AD5X only, integer as string)
materialMappings	Base64-encoded JSON array (AD5X only)
firstLayerInspection	"true" or "false" (AD5X only, firmware dependent)
timeLapseVideo	"true" or "false" (AD5X only, firmware dependent)

Note: Boolean headers use lowercase string values ("true"/"false").

Request (5M/5M Pro):

POST http://10.0.0.42:8898/uploadGcode
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
serialNumber: SNADVA5MXXXXX
checkCode: 12345
fileSize: 1234567
printNow: "true"
levelingBeforePrint: "true"
flowCalibration: "false"
useMatlStation: "false"
gcodeToolCnt: 0
materialMappings: []

------WebKitFormBoundary
Content-Disposition: form-data; name="gcodeFile"; filename="Benchy.gcode"
Content-Type: application/octet-stream

[binary file content]
------WebKitFormBoundary--

Response:

{
  "code": 0,
  "message": "Success"
}

Machine States

The status field in /detail responses indicates the printer's operational state:

Status	Description
ready	Idle and ready to accept commands
busy	Performing non-printing operation (e.g., homing)
calibrate_doing	Performing calibration sequence
error	Error has occurred
heating	Heating nozzle or platform
printing	Actively printing
working	Alternative printing state (same as printing)
pausing	In process of pausing
paused	Job paused
canceling	In process of canceling
cancel	Job cancelled
completed	Job finished successfully

AD5X Extended Commands

AD5X printers support additional commands for the material station (IFS). See AD5X Documentation for details.

Command	Description
msConfig_cmd	Configure slot material metadata
ms_cmd	Load/unload/cancel by slot
moveCtrl_cmd	Manual axis movement
extrudeCtrl_cmd	Manual extrusion control
homingCtrl_cmd	Manual homing control
errorCodeCtrl_cmd	Error code management

Uh oh!

HTTP REST API

HTTP REST API Reference

Overview

Authentication

Response Format

Endpoints

/detail - Get Printer Details

Print Time Fields: estimatedTime and printDuration

Recommended derivations (correct formulas)

Common pitfalls (anti-patterns)

Do not confuse these fields with static per-file estimates

/product - Get Feature Availability

/control - Send Control Commands

lightControl_cmd - LED Control

jobCtl_cmd - Job Control

printerCtl_cmd - Printer Control

circulateCtl_cmd - Air Filtration Control

streamCtrl_cmd - Camera Stream Control

stateCtrl_cmd - State Control

temperatureCtl_cmd - Temperature Control

reName_cmd - Rename Printer

delayClose_cmd - Auto Shutdown Timer

calibration_cmd - Calibration Control

userProfile_cmd - User Profile

/gcodeList - Get Recent Files

/gcodeThumb - Get File Thumbnail

/printGcode - Print Local File

/uploadGcode - Upload File

Machine States

AD5X Extended Commands

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Core Protocols

References

Printer Families

Advanced

Clone this wiki locally

Print Time Fields: `estimatedTime` and `printDuration`