File Management¶
Most file operations are available over both HTTP and JSON-RPC APIs, however file transfers (upload and download) are exclusive to the HTTP API.
Moonraker organizes local directories into "roots". For example,
gcodes are located at http://host/server/files/gcodes/*, otherwise known
as the "gcodes" root. The following default roots are generally available:
- gcodes
- config
- logs (read-only)
- config_examples (Klipper Configuration Examples, read-only)
- docs (Klipper Documentation, read-only)
Write operations (upload, delete, make directory, remove directory) are
only available on the gcodes and config roots, however it is possible
for users to configure the config root to be read-only.
Many endpoints return permission information on files and/or folders. Permissions are represented as a string value in the following format:
| Value | Description |
|---|---|
"r" |
Item is read-only. |
"rw" |
Item has read and write permissions. |
"" |
Item is not accessible. |
List available files¶
Walks through a directory and fetches all detected files.
File names include a path relative to the specified root.
Tip
In most scenarios it will likely be preferable to request files by directory as opposed to listing the entire root.
GET /server/files/list?root=config
{
"jsonrpc": "2.0",
"method": "server.files.list",
"params": {
"root": "config"
},
"id": 4644
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
root |
string | gcodes |
The name of the root from which a file list should be returned. |
Note
The gcodes root will only return files with valid gcode file extensions.
[
{
"path": "3DBenchy_0.15mm_PLA_MK3S_2h6m.gcode",
"modified": 1615077020.2025201,
"size": 4926481,
"permissions": "rw"
},
{
"path": "Shape-Box_0.2mm_PLA_Ender2_20m.gcode",
"modified": 1614910966.946807,
"size": 324236,
"permissions": "rw"
},
{
"path": "test_dir/A-Wing.gcode",
"modified": 1605202259,
"size": 1687387,
"permissions": "rw"
},
{
"path": "test_dir/CE2_CubeTest.gcode",
"modified": 1614644445.4025,
"size": 1467339,
"permissions": "rw"
},
{
"path": "test_dir/V350_Engine_Block_-_2_-_Scaled.gcode",
"modified": 1615768477.5133543,
"size": 189713016,
"permissions": "rw"
}
]
Response Specification
The result is an array of File Info objects:
| Field | Type | Description |
|---|---|---|
path |
string | The path of the file, relative to the requested root. |
modified |
float | The last modified date in Unix Time (seconds). |
size |
int | The size of the file in bytes. |
permissions |
string | The available permissions of the file. |
List registered roots¶
Reports information about "root" directories registered with Moonraker.
GET /server/files/roots
{
"jsonrpc": "2.0",
"method": "server.files.roots",
"id": 4644
}
[
{
"name": "config",
"path": "/home/pi/printer_data/config",
"permissions": "rw"
},
{
"name": "logs",
"path": "/home/pi/printer_data/logs",
"permissions": "r"
},
{
"name": "gcodes",
"path": "/home/pi/printer_data/gcodes",
"permissions": "rw"
},
{
"name": "config_examples",
"path": "/home/pi/klipper/config",
"permissions": "r"
},
{
"name": "docs",
"path": "/home/pi/klipper/docs",
"permissions": "r"
}
]
Response Specification
The result is an array of Root Info objects:
Get GCode Metadata¶
Get metadata for a specified gcode file.
GET /server/files/metadata?filename=tools/drill.gcode
{
"jsonrpc": "2.0",
"method": "server.files.metadata",
"params": {
"filename": "tools/drill.gcode"
},
"id": 3545
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
filename |
str | REQUIRED | The path to the gcode file, relative to the gcodes root. |
{
"size": 1629418,
"modified": 1706359465.4947228,
"uuid": "473a41d2-15f4-434b-aeb4-ab96eb122bbf",
"file_processors": [],
"slicer": "PrusaSlicer",
"slicer_version": "2.7.1+win64",
"gcode_start_byte": 87410,
"gcode_end_byte": 1618468,
"object_height": 8,
"estimated_time": 5947,
"nozzle_diameter": 0.4,
"layer_height": 0.2,
"first_layer_height": 0.2,
"first_layer_extr_temp": 215,
"first_layer_bed_temp": 60,
"chamber_temp": 50,
"filament_name": "Generic PLA Brown",
"filament_type": "PLA",
"filament_total": 9159.55,
"filament_weight_total": 27.32,
"thumbnails": [
{
"width": 32,
"height": 32,
"size": 1078,
"relative_path": ".thumbs/hook_x4_0.2mm_PLA_MK3S_1h39m-32x32.png"
},
{
"width": 400,
"height": 300,
"size": 61576,
"relative_path": ".thumbs/hook_x4_0.2mm_PLA_MK3S_1h39m-400x300.png"
}
],
"print_start_time": 1706359466.722097,
"job_id": "0000BF",
"filename": "hook_x4_0.2mm_PLA_MK3S_1h39m.gcode"
}
Response Specification
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
size |
int | The gcode file size in bytes. | |||||||||||||||
modified |
float | The last modified time in Unix Time (seconds). | |||||||||||||||
uuid |
string | A unique identifier for the metadata object. | |||||||||||||||
file_processors |
[string] | An array of File Processors that have processed and modified the file. |
|||||||||||||||
|
|||||||||||||||||
slicer |
string | The name of the slicer software used to slice the file. | |||||||||||||||
slicer_version |
string | The version of the slicer software. | |||||||||||||||
gcode_start_byte |
int | The byte offset in the file where the first gcode command is detected. | |||||||||||||||
gcode_int_byte |
int | The byte offset in the file where the last gcode command is detected. | |||||||||||||||
object_height |
float | The height (in mm) of the tallest object in the file. | |||||||||||||||
estimated_time |
float | The estimated time to complete the print, in seconds. | |||||||||||||||
nozzle_diameter |
float | The configured nozzle diameter, in mm. | |||||||||||||||
layer_height |
float | The configured layer height, in mm. | |||||||||||||||
first_layer_height |
float | The configured first layer height in mm. | |||||||||||||||
first_layer_extr_temp |
float | The configured first layer extruder temperature, in Celsius. | |||||||||||||||
first_layer_bed_temp |
float | The configured first layer bed temperature, in Celsius. | |||||||||||||||
chamber_temp |
float | The configured chamber temperature, in Celsius. | |||||||||||||||
filament_name |
string | The name(s) of the filaments contained in print. | |||||||||||||||
filament_colors |
[string] | List of filament colors used in #RRGGBB format. | |||||||||||||||
extruder_colors |
[string] | List of slicer defined extruder colors for the print. | |||||||||||||||
filament_temps |
[int] | List of base temperatures for filaments, in Celsius. | |||||||||||||||
filament_type |
string | The type(s) of filament used, ie: PLA. |
|||||||||||||||
filament_total |
float | The total length filament used in mm. | |||||||||||||||
filament_change_count |
int | The number of filament changes in the print. | |||||||||||||||
filament_weight_total |
float | The total weight of filament used in grams. | |||||||||||||||
filament_weights |
[float] | List of weights in grams used by each tool in the print. | |||||||||||||||
printer_vendor |
string | The vendor name of the associated printer. | |||||||||||||||
printer_model |
string | The model of the associated printer. | |||||||||||||||
printer_variant |
string | The variant of the associated printer. | |||||||||||||||
profile_version |
string | The version of the profile configured in the slicer. | |||||||||||||||
mmu_print |
int | Identifies a multimaterial print with single extruder. | |||||||||||||||
referenced_tools |
[int] | List of tool numbers used in the print. | |||||||||||||||
thumbnails |
[object] | A list of Thumbnail Info objects. |
|||||||||||||||
|
|||||||||||||||||
job_id |
string? | The last history job ID associated with the gcode. Will be null if no job has been associated with the file. |
|||||||||||||||
print_start_time |
float | The most recent start time the gcode file was printed. Will be null if the file has yet to be printed. |
|||||||||||||||
filename |
string | Path to the gcode file, relative to the gcodes root. |
|||||||||||||||
Note
Metadata field availability depends on the Slicer application and its configuration. If a field cannot be parsed from the slicer it will be omitted.
Scan GCode Metadata¶
Initiate a metadata scan for a selected file. If the file has already been scanned the endpoint will force a re-scan.
POST /server/files/metascan?filename={filename}
{
"jsonrpc": "2.0",
"method": "server.files.metascan",
"params": {
"filename": "{filename}"
},
"id": 3545
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
filename |
str | REQUIRED | The path to the gcode file, relative to the gcodes root. |
For an example response refer to the Metadata Example Response.
Response Specification
The response spec is identical to the Metadata Request Specification
Get GCode Thumbnail Details¶
Returns thumbnail information for a supplied gcode file.
GET /server/files/thumbnails?filename=tools/drill.gcode
{
"jsonrpc": "2.0",
"method": "server.files.thumbnails",
"params": {
"filename": "{filename}"
},
"id": 3545
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
filename |
str | REQUIRED | The path to the gcode file, relative to the gcodes root. |
[
{
"width": 32,
"height": 32,
"size": 1551,
"thumbnail_path": "test/.thumbs/CE2_FanCover-120mm-Mesh-32x32.png"
},
{
"width": 300,
"height": 300,
"size": 31819,
"thumbnail_path": "test/.thumbs/CE2_FanCover-120mm-Mesh.png"
}
]
Response Specification
The result is an array of Thumbnail Details objects.
| Field | Type | Description |
|---|---|---|
width |
int | The width of the thumbnail in pixels. |
height |
int | The height of the thumbnail in pixels. |
size |
int | The size of the thumbnail in bytes. |
thumbnail_path |
string | The path of the thumbnail, relative to the gcodes root. |
Note
The Thumbnails Details spec is nearly identical to the
Thumbnail Info spec reported in
a metadata request, with one exception.
The thumbnail_path field in the result above contains a
path relative to the gcodes root, whereas the relative_path
field reported in the Thumbnail Info is relative to the gcode
file's parent folder.
Get directory information¶
Returns a list of files and subdirectories given a supplied path.
Unlike /server/files/list, this command does not walk through
subdirectories. This request will return all files in a directory,
including files in the gcodes root that do not have a valid gcode
extension.
GET /server/files/directory?path=gcodes/my_subdir&extended=true
{
"jsonrpc": "2.0",
"method": "server.files.get_directory",
"params": {
"path": "gcodes/my_subdir",
"extended": true
},
"id": 5644
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path |
string | gcodes |
Path to the directory. The first part must be a registered root. |
extended |
bool | false |
When set to true metadata will be included in the response for gcode file. |
{
"dirs": [
{
"modified": 1615768162.0412788,
"size": 4096,
"permissions": "rw",
"dirname": "test"
},
{
"modified": 1613569827.489749,
"size": 4096,
"permissions": "rw",
"dirname": "Cura"
},
{
"modified": 1615767459.6265886,
"size": 4096,
"permissions": "rw",
"dirname": "thumbs"
}
],
"files": [
{
"modified": 1615578004.9639666,
"size": 7300692,
"permissions": "rw",
"filename": "Funnel_0.2mm_PLA_Ender2_2h4m.gcode"
},
{
"modified": 1589156863.9726968,
"size": 4214831,
"permissions": "rw",
"filename": "CE2_Pi3_A+_CaseLID.gcode"
},
{
"modified": 1615030592.7722695,
"size": 2388774,
"permissions": "rw",
"filename": "CE2_calicat.gcode"
}
],
"disk_usage": {
"total": 7522213888,
"used": 4280369152,
"free": 2903625728
},
"root_info": {
"name": "gcodes",
"permissions": "rw"
}
}
Response Specification
| Field | Type | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
dirs |
[object] | An array of Directory Info objects. Will be empty if no sub-directories are found. |
||||||||||||||||||||||||
|
||||||||||||||||||||||||||
files |
[object] | An array of File Info objects. Will be empty if no files are found. |
||||||||||||||||||||||||
|
||||||||||||||||||||||||||
disk_usage |
object | A Disk Usage object. This provides disk usage details about the underlying storage media containing the requested directory. |
||||||||||||||||||||||||
|
||||||||||||||||||||||||||
root_info |
object | A Root Info object. Provides details about the directory's root parent. |
||||||||||||||||||||||||
|
||||||||||||||||||||||||||
| Field | Type | Description |
|---|---|---|
name |
string | The name of the root node for the requested directory. |
permissions |
string | The available permissions of the root node. |
Create directory¶
Creates a directory at the specified path.
POST /server/files/directory
Content-Type: application/json
{
"path": "gcodes/my_new_dir"
}
{
"jsonrpc": "2.0",
"method": "server.files.post_directory",
"params": {
"path": "gcodes/my_new_dir"
},
"id": 6548
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path |
string | REQUIRED | The path to the directory to create, including its root. Note that the parent directory must exist. |
{
"item": {
"path": "my_new_dir",
"root": "gcodes",
"modified": 1676983427.3732708,
"size": 4096,
"permissions": "rw"
},
"action": "create_dir"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | An Item Details object describing the directory created. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | A description of the action taken by the host. Will always be create_dir for this request. |
||||||||||||||||||
Delete directory¶
Deletes a directory at the specified path.
DELETE /server/files/directory?path=gcodes/my_subdir&force=false
{
"jsonrpc": "2.0",
"method": "server.files.delete_directory",
"params": {
"path": "gcodes/my_subdir",
"force": false
},
"id": 6545
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path |
string | REQUIRED | The path to the directory to delete, including its root. Note that the directory must be empty if force is false |
force |
bool | false |
When set to true the directory and all of its contents will be deleted. |
{
"item": {
"path": "my_subdir",
"root": "gcodes",
"modified": 0,
"size": 0,
"permissions": ""
},
"action": "delete_dir"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | An Item Details object describing the directory deleted. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | A description of the action taken by the host. Will always be delete_dir for this request. |
||||||||||||||||||
Move a file or directory¶
Moves a file or directory from one location to another. The following conditions must be met for a move successful move:
- The source item must exist.
- The user that owns the Moonraker process must have the appropriate file permissions.
- Neither the source nor destination can be loaded by Klipper's
virtual_sdcard. If the source is a directory, it must not contain a file loaded by thevirtual_sdcard.
When specifying the source and dest, the root directory should be
prefixed. Currently the only supported roots for dest are gcodes"
and config".
This endpoint may also be used to rename a file or directory. Be aware that an attempt to rename a directory to a directory that exists with the same name will move the source directory into the destination directory. Also be aware that renaming a file to a file that already exists will overwrite the existing file.
POST /server/files/move
Content-Type: application/json
{
"source": "gcodes/orig_dir/my_file.gcode",
"dest": "gcodes/new_dir/my_file.gcode"
}
{
"jsonrpc": "2.0",
"method": "server.files.move",
"params": {
"source": "gcodes/orig_dir/my_file.gcode",
"dest": "gcodes/new_dir/my_file.gcode"
},
"id": 5664
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
source |
string | REQUIRED | The source file or directory to move. This is a path that must start with the root node. |
dest |
string | REQUIRED | The destination path. The path must start with the root node. |
{
"item": {
"root": "gcodes",
"path": "subdir/my_file.gcode",
"modified": 1676940082.8595376,
"size": 384096,
"permissions": "rw"
},
"source_item": {
"path": "testdir/my_file.gcode",
"root": "gcodes"
},
"action": "move_file"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | A Destination Item object. |
||||||||||||||||||
|
||||||||||||||||||||
source_item |
object | A Source Item object. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | A description of the action taken. Will be move_file if a file was moved or move_dir if a directory was moved. |
||||||||||||||||||
Copy a file or directory¶
Copies a file or directory from one location to another. A successful copy has
the same prerequisites as a move with one exception, a copy may complete if the
source file or directory is loaded by the virtual_sdcard.
POST /server/files/copy
Content-Type: application/json
{
"source": "gcodes/my_file.gcode",
"dest": "gcodes/new_dir/my_file.gcode"
}
{
"jsonrpc": "2.0",
"method": "server.files.copy",
"params": {
"source": "gcodes/my_file.gcode",
"dest": "gcodes/new_dir/my_file.gcode"
},
"id": 5623
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
source |
string | REQUIRED | The source file or directory to copy. This is a path that must start with the root node. |
dest |
string | REQUIRED | The destination path. The path must start with the root node. |
{
"item": {
"root": "gcodes",
"path": "subdir/my_file.gcode",
"modified": 1676940082.8595376,
"size": 384096,
"permissions": "rw"
},
"action": "create_file"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | A Destination Item object. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | A description of the action taken. Expand for details. | ||||||||||||||||||
|
||||||||||||||||||||
Create a ZIP archive¶
Creates a zip file consisting of one or more files.
POST /server/files/zip
Content-Type: application/json
{
"dest": "config/error_logs.zip",
"items": [
"config/printer.cfg",
"logs",
"gcodes/subfolder"
],
"store_only": false
}
{
"jsonrpc": "2.0",
"method": "server.files.zip",
"params": {
"dest": "config/error_logs.zip",
"items": [
"config/printer.cfg",
"logs",
"gcodes/subfolder"
],
"store_only": false
},
"id": 5623
}
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
dest |
string | config/collection-{timestamp}.zip |
Path to the destination archive file. The path must begin with a valid "root" that has write permission. |
items |
[string] | REQUIRED | An array of paths indicating the items to be included in the archive. Each path must start with a valid root. An item may be a file or directory. |
store_only |
bool | false |
When set to true the contents of the zip archive are not compressed. Otherwise the deflation algorithm will be used to compress the contents. |
{
"destination": {
"root": "config",
"path": "error_logs.zip",
"modified": 1676984423.8892415,
"size": 420,
"permissions": "rw"
},
"action": "zip_files"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
destination |
object | A Zip Destination object containing details about the archived file. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | The action taken be the file manager. Will be zip_files. |
||||||||||||||||||
File download¶
Retrieves file filename at root root. The filename must include
the relative path if it is not in the root folder.
GET /server/files/{root}/{filename}
Not Available
Response Specification
The body of the response contains the contents of the requested file.
File upload¶
Upload a file. Currently files may be uploaded to the gcodes or config
roots, with gcodes being the default. If one wishes to upload
to a subdirectory, the path may be added to the upload's file name
(relative to the root). If the directory does not exist an error will be
returned. Alternatively, the path form argument may be set, as explained
below.
POST /server/files/upload`
Content-Type: multipart/form-data
------FormBoundaryemap3PkuvKX0B3HH
Content-Disposition: form-data; name="file"; filename="myfile.gcode"
Content-Type: application/octet-stream
<binary data>
------FormBoundaryemap3PkuvKX0B3HH--
Not Available
Parameters
The file data must be included in the request's body as multipart/form-data
(ie: <input type="file">). The following optional arguments may also be
added to the form-data:
| Name | Type | Default | Description |
|---|---|---|---|
root |
string | gcodes |
The root location in which to upload the file. Currently this may only be gcodes or config. |
path |
string | An optional path, relative to the root, indicating a subfolder in which to save the file. If the subfolder does not exist it will be created. |
|
checksum |
string | An optional SHA256 hex digest calculated by the client for the uploaded file. If this argument is supplied the server will compare it to its own checksum calculation after the upload has completed. A checksum mismatch will result in a 422 error. | |
print |
string | false |
Available only for files uploaded to the gcodes root. When set to true Moonraker will command Klippy to start the print after the upload has successfully completed. |
{
"item": {
"path": "Lock Body Shim 1mm_0.2mm_FLEX_MK3S_2h30m.gcode",
"root": "gcodes",
"modified": 1676984527.636818,
"size": 71973,
"permissions": "rw"
},
"print_started": false,
"print_queued": false,
"action": "create_file"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | An Uploaded Item object. |
||||||||||||||||||
|
||||||||||||||||||||
print_started |
bool | Set to true if the uploaded file has successfully started printing. |
||||||||||||||||||
print_queued |
bool | Set to true if the uploaded file has been queued for printing at a later time. |
||||||||||||||||||
action |
string | Action taken by the file manager. Will always be "create_file". | ||||||||||||||||||
In addition to the above returned object, all successful uploads will respond with
a 201 response code and set the Location response header to the full path of
the uploaded file.
File delete¶
Delete a file in the requested root. If the file exists in a subdirectory,
its relative path must be part of the {filename} argument.
DELETE /server/files/{root}/{filename}
{
"jsonrpc": "2.0",
"method": "server.files.delete_file",
"params": {
"path": "{root}/{filename}"
},
"id": 1323
}
{
"item": {
"path": "Lock Body Shim 1mm_0.2mm_FLEX_MK3S_2h30m.gcode",
"root": "gcodes",
"size": 0,
"modified": 0,
"permissions": ""
},
"action": "delete_file"
}
Response Specification
| Field | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
item |
object | A Deleted Item object. |
||||||||||||||||||
|
||||||||||||||||||||
action |
string | Action taken by the file manager. Will always be "delete_file". | ||||||||||||||||||
Download klippy.log¶
Note
Logs are now available in the logs root. Front ends should consider
presenting all available logs using "file manager" type of UI. That said,
If Klipper has not been configured to write logs in the logs root then
this endpoint is available as a fallback.
GET /server/files/klippy.log
Not Available
Response Specification
The body of the response contains contents of klippy.log.
Download moonraker.log¶
Note
Logs are now available in the logs root. Front ends should consider
presenting all available logs using "file manager" type of UI. That said,
If Moonraker has not been configured to write logs in the logs root then
this endpoint is available as a fallback.
GET /server/files/moonraker.log
Not Available
Response Specification
The body of the response contains the contents of moonraker.log.