Skip to content

HTTP REST API

Jump to bottom
GhostTypes edited this page Jun 26, 2026 · 6 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 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,
    "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,
    "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
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)

/product - Get Feature Availability

Retrieves the availability status of various 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. FlashForge firmware may report 1 for absent hardware or 0 for present hardware across models and firmware versions — do not use them 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 various 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 various 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). Sending explicit values will 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
        }
      ]
    }
  ]
}

/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: On AD5X printers, use /gcodeList which returns extended file details including thumbnail information.

/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, so it should only be used when targeting 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 (or to start printing immediately on upload), use /uploadGcode and pass materialMappings as a Base64-encoded header. 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

Core Protocols

References

Printer Families

Advanced

Clone this wiki locally