Skip to content

HTTP REST API

Jump to bottom
GhostTypes edited this page Sep 1, 2026 · 9 revisions

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 Parameters is error A required field is missing, has the wrong type, or the body is not valid JSON
1 SN is different The serial number does not match the printer
1 Access code is different The check code does not match the printer
2 Printer is Busy. The printer is not idle (/printGcode only)
3 File does not exist. The named file is not on printer storage (/printGcode only)

/control always answers {code:0, message:"Success"} once authentication passes. The response confirms dispatch only. An unknown command name is ignored and still answers Success.

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": 0,
    "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.
measure string Build volume, e.g. 220X220X220. Fixed per model
nozzleCnt int Extruder count. Fixed at 1 on the 5M series
nozzleStyle int Nozzle style flag. Fixed at 0 on the 5M series
doorStatus string Fixed at close on the 5M series. The 5M has no door sensor
tvoc int TVOC sensor value. The field is present on all models. The base 5M and the Creator 5 series report the fixed value 0. Base-5M value not yet verified on hardware
cameraStreamUrl string MJPEG stream URL. The field is present on all models. It is empty when no camera is installed. It fills in when a camera accessory is active
chamberFanSpeed int Chamber fan speed, percent (0–100). 0 when no print is active
chamberTemp / chamberTargetTemp int Fixed at 0 on the 5M series. The 5M Pro has a chamber, but the firmware does not report a chamber temperature sensor
coolingFanSpeed int Part-cooling fan speed, percent (0–100). 0 when no print is active
autoShutdown string Auto-shutdown switch state ("open" or "close")
autoShutdownTime int Auto-shutdown delay in the unit shown on the printer screen

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

Model note (base 5M): on the Adventurer 5M the response never changes. The printer returns fixed values: nozzleTempCtrlState: 1, platformTempCtrlState: 1, and 0 for chamberTempCtrlState, lightCtrlState, internalFanCtrlState, and externalFanCtrlState. The values do not change when accessories are installed.

⚠️ 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": 100,
      "coolingFan": 100
    }
  }
}
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). The printer ignores values outside this range
chamberFan 0-100 Chamber fan speed, percent (0=off, 100=full). The printer clamps values above 100 to 100
coolingFan 0-100 Part-cooling fan speed, percent (0=off, 100=full). The printer clamps values above 100 to 100

Fan values are percent (0–100) on this endpoint. Do not send 0–255 here. The 0–255 scale applies only to the TCP M106 command, not to printerCtl_cmd.

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: The command is accepted on the 5M series and the AD5X. Only the 5M Pro has factory fan hardware. The base 5M returns Success but actuates nothing.

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: The command is accepted on all 5M-series models. It actuates only when a camera is installed. On the 5M Pro the camera is built in. On the base 5M the camera is an accessory.

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.

5M-series behavior: the printer applies platform and rightNozzle only. It accepts leftNozzle and chamber without error and ignores them. A missing field means "no change".

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 (5M / 5M Pro):

The 5M series reads two fields: fileName and levelingBeforePrint. Send this body on every 5M-series firmware version:

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

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

If either field is missing, the printer returns code -1. If the file is missing it returns code 3. If the printer is not idle it returns code 2.

Note: the material-station fields below (flowCalibration, useMatlStation, gcodeToolCnt, materialMappings) apply to the AD5X only. The 5M and 5M Pro firmware never reads them. The fields are harmless extras on a 5M, but they are not required on any 5M firmware version.

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. The table below lists the values of 5M-series firmware:

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
pausing In process of pausing
pause Job paused
canceling In process of canceling
cancel Job cancelled
completed Job finished successfully
downloading Receiving a file or job
cloud_slicing Cloud slicing in progress (firmware 5.x)
sending Sending data to the printer (firmware 5.x)
unzipping Extracting a received file (firmware 5.x)

The paused state is spelled pause. The values working, paused, and building do not exist on 5M-series firmware. Treat any unknown value as busy and keep polling.

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

Core Protocols

References

Printer Families

Advanced

Clone this wiki locally