Moonraker's external API documentation has been significantly overhauled in an effort to improve clarity and readability. All parameters and responses are documented with specifications. Tables and other elements are used to make documentation more visible and less verbose. Spelling and other corrections have also been added. Signed-off-by: Eric Callahan <arksine.code@gmail.com>
1214 lines
45 KiB
Markdown
1214 lines
45 KiB
Markdown
# 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. |
|
|
{ #file-permissions-desc } Permissions
|
|
|
|
## 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](#get-directory-information) as opposed to listing
|
|
the entire root.
|
|
///
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/list?root=config
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.list",
|
|
"params": {
|
|
"root": "config"
|
|
},
|
|
"id": 4644
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
| 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.
|
|
////
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
[
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
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](#file-permissions-desc) of the file. |
|
|
{ #file-info-spec} File Info
|
|
|
|
///
|
|
|
|
## List registered roots
|
|
|
|
Reports information about "root" directories registered with Moonraker.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/roots
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.roots",
|
|
"id": 4644
|
|
}
|
|
```
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
[
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
The result is an array of `Root Info` objects:
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ------------------------------------------------------------ |
|
|
| `name` | string | The name of the registered root. |
|
|
| `path` | string | The absolute path on disk of the registered root. |
|
|
| `permissions` | string | [Permissions](#file-permissions-desc) available on the root. |
|
|
{ #root-info-spec } Root Info
|
|
|
|
///
|
|
|
|
## Get GCode Metadata
|
|
|
|
Get metadata for a specified gcode file.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/metadata?filename=tools/drill.gcode
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.metadata",
|
|
"params": {
|
|
"filename": "tools/drill.gcode"
|
|
},
|
|
"id": 3545
|
|
}
|
|
```
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ---------- | :--: | ------------ | ---------------------------------------------------------- |
|
|
| `filename` | str | **REQUIRED** | The path to the gcode file, relative to the `gcodes` root. |
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json #metadata-example-response .apiresponse title="Example Response"}
|
|
{
|
|
"size": 1629418,
|
|
"modified": 1706359465.4947228,
|
|
"uuid": "473a41d2-15f4-434b-aeb4-ab96eb122bbf",
|
|
"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"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| 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. |
|
|
| `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` | str | The name of the filament used. |
|
|
| `filament_type` | str | The type of filament used, ie: `PLA`. |
|
|
| `filament_total` | float | The total length filament used in mm. |
|
|
| `filament_weight_total` | float | The total weight of filament used in grams. |
|
|
| `thumbnails` | [object] | A list of `Thumbnail Info` objects. |
|
|
| | | #thumbnail-info-spec |+
|
|
| `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. |
|
|
{ #gcode-metadata-spec }
|
|
|
|
| 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. |
|
|
| `relative_path` | string | The path of the thumbnail, relative to the gcode file's parent. |
|
|
{ #thumbnail-info-spec } Thumbnail Info
|
|
|
|
//// 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.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /server/files/metascan?filename={filename}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.metascan",
|
|
"params": {
|
|
"filename": "{filename}"
|
|
},
|
|
"id": 3545
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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](#metadata-example-response).
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
The response spec is identical to the
|
|
[Metadata Request Specification](#gcode-metadata-spec)
|
|
///
|
|
|
|
|
|
## Get GCode Thumbnail Details
|
|
|
|
Returns thumbnail information for a supplied gcode file.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/thumbnails?filename=tools/drill.gcode
|
|
```
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.thumbnails",
|
|
"params": {
|
|
"filename": "{filename}"
|
|
},
|
|
"id": 3545
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ---------- | :--: | ------------ | ---------------------------------------------------------- |
|
|
| `filename` | str | **REQUIRED** | The path to the gcode file, relative to the `gcodes` root. |
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
[
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
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. |
|
|
{ #thumbnail-details-spec } Thumbnail Details
|
|
|
|
//// Note
|
|
The `Thumbnails Details` spec is nearly identical to the
|
|
[Thumbnail Info](#thumbnail-info-spec) spec reported in
|
|
a [metadata request](#get-gcode-metadata), 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.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/directory?path=gcodes/my_subdir&extended=true
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.get_directory",
|
|
"params": {
|
|
"path": "gcodes/my_subdir",
|
|
"extended": true
|
|
},
|
|
"id": 5644
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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. |^
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------------ | :------: | ------------------------------------------------------- |
|
|
| `dirs` | [object] | An array of `Directory Info` objects. Will be empty if |
|
|
| | | no sub-directories are found. |^
|
|
| | | #directory-info-spec |+
|
|
| `files` | [object] | An array of `File Info` objects. Will be empty if no |
|
|
| | | files are found. |^
|
|
| | | #dir-req-file-info-spec |+
|
|
| `disk_usage` | object | A `Disk Usage` object. This provides disk usage details |
|
|
| | | about the underlying storage media containing the |^
|
|
| | | requested directory. |^
|
|
| | | #disk-usage-spec |+
|
|
| `root_info` | object | A `Root Info` object. Provides details about the |
|
|
| | | directory's root parent. |^
|
|
| | | #root-info-spec |+
|
|
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | --------------------------------------------------------------------- |
|
|
| `modified` | float | The last modified date in Unix Time (seconds). |
|
|
| `size` | int | The size of the file in bytes. |
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the directory. |
|
|
| `dirname` | string | The name of the directory. |
|
|
{ #directory-info-spec } Directory Info
|
|
|
|
|
|
| Field | Type | Description |
|
|
| ----------------- | :----: | ---------------------------------------------------------------------- |
|
|
| `modified` | float | The last modified date in Unix Time (seconds). |
|
|
| `size` | int | The size of the file in bytes. |
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the directory. |
|
|
| `filename` | string | The name of the file. |
|
|
| _metadata-fields_ | _any_ | When the `extended` parameter is set to true all available metadata |
|
|
| | | fields are included in the object. See the |^
|
|
| | | [metadata response spec](#gcode-metadata-spec) for details. Note that |^
|
|
| | | the `filename` in the metadata spec, which is a relative path, will |
|
|
| | | not overwrite the `filename` above, which is not a path. |
|
|
{ #dir-req-file-info-spec } File Info
|
|
|
|
| Field | Type | Description |
|
|
| ------- | :--: | ---------------------------------------- |
|
|
| `free` | int | The amount of free space in bytes. |
|
|
| `used` | int | The amount of used data in bytes. |
|
|
| `total` | int | The total capacity of the disk in bytes. |
|
|
{ #disk-usage-spec } Disk Usage
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ---------------------------------------------------------- |
|
|
| `name` | string | The name of the root node for the requested directory. |
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the |
|
|
| | | root node. |^
|
|
{ #root-info-spec } Root Info
|
|
|
|
///
|
|
|
|
## Create directory
|
|
|
|
Creates a directory at the specified path.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /server/files/directory
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"path": "gcodes/my_new_dir"
|
|
}
|
|
```
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.post_directory",
|
|
"params": {
|
|
"path": "gcodes/my_new_dir"
|
|
},
|
|
"id": 6548
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| Name | Type | Default | Description |
|
|
| ------ | :----: | ------------ | ---------------------------------------------------------- |
|
|
| `path` | string | **REQUIRED** | The path to the directory to create, including its `root`. |
|
|
| | | | Note that the parent directory must exist. |^
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"item": {
|
|
"path": "my_new_dir",
|
|
"root": "gcodes",
|
|
"modified": 1676983427.3732708,
|
|
"size": 4096,
|
|
"permissions": "rw"
|
|
|
|
},
|
|
"action": "create_dir"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| -------- | :----: | ----------------------------------------------------------- |
|
|
| `item` | object | An `Item Details` object describing the directory created. |
|
|
| | | #create-dir-item-details-spec |+
|
|
| `action` | string | A description of the action taken by the host. Will always |
|
|
| | | be `create_dir` for this request. |^
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ---------------------------------------------------- |
|
|
| `path` | string | The path of the new directory, relative to the root. |
|
|
| `root` | string | The root node the directory was created under. |
|
|
| `modified` | float | The last modified date in Unix Time (seconds). |
|
|
| `size` | int | The size of the directory. Will generally be 4096. |
|
|
| `permissions` | string | Permissions available on the new directory. |
|
|
{ #create-dir-item-details-spec } Item Details
|
|
|
|
///
|
|
|
|
## Delete directory
|
|
Deletes a directory at the specified path.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
DELETE /server/files/directory?path=gcodes/my_subdir&force=false
|
|
```
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.delete_directory",
|
|
"params": {
|
|
"path": "gcodes/my_subdir",
|
|
"force": false
|
|
},
|
|
"id": 6545
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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. |^
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"item": {
|
|
"path": "my_subdir",
|
|
"root": "gcodes",
|
|
"modified": 0,
|
|
"size": 0,
|
|
"permissions": ""
|
|
|
|
},
|
|
"action": "delete_dir"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| -------- | :----: | ----------------------------------------------------------- |
|
|
| `item` | object | An `Item Details` object describing the directory deleted. |
|
|
| | | #delete-dir-item-details-spec |+
|
|
| `action` | string | A description of the action taken by the host. Will always |
|
|
| | | be `delete_dir` for this request. |^
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ------------------------------------------------------------- |
|
|
| `path` | string | The path of the deleted directory, relative to the root. |
|
|
| `root` | string | The root node the directory existed under prior to removal. |
|
|
| `modified` | float | The last modified date in Unix Time (seconds). Should be |
|
|
| | | 0 if the delete was successful. |^
|
|
| `size` | int | The size of the removed directory. Should be 0 if the delete |
|
|
| | | was successful. |^
|
|
| `permissions` | string | Permissions available on the removed directory. Should be |
|
|
| | | an empty string if the delete was successful. |^
|
|
{ #delete-dir-item-details-spec } Item Details
|
|
|
|
///
|
|
|
|
## 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 the
|
|
`virtual_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.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /server/files/move
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"source": "gcodes/orig_dir/my_file.gcode",
|
|
"dest": "gcodes/new_dir/my_file.gcode"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.move",
|
|
"params": {
|
|
"source": "gcodes/orig_dir/my_file.gcode",
|
|
"dest": "gcodes/new_dir/my_file.gcode"
|
|
},
|
|
"id": 5664
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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. |^
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ------------------------------------------------------- |
|
|
| `item` | object | A `Destination Item` object. |
|
|
| | | #move-dest-item-spec |+
|
|
| `source_item` | object | A `Source Item` object. |
|
|
| | | #move-source-item-spec |+
|
|
| `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. |^
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | --------------------------------------------------------- |
|
|
| `root` | string | The root node of the destination file or directory. |
|
|
| `path` | string | The path, relative to the root node, of the destination |
|
|
| | | file or directory. |^
|
|
| `modified` | float | The last modified time of the destination file or |
|
|
| | | directory. This is expressed in Unix Time (seconds). |^
|
|
| `size` | int | The size, in bytes, of the destination file or directory. |
|
|
| `permissions` | string | The permissions available on the destination file or |
|
|
| | | directory. |^
|
|
{ #move-dest-item-spec } Destination Item
|
|
|
|
| Field | Type | Description |
|
|
| ------ | :----: | ------------------------------------------------------------- |
|
|
| `root` | string | The root node of the source file or directory that was moved. |
|
|
| `path` | string | The path, relative to the root node, of the source file or |
|
|
| | | directory that was moved. |^
|
|
{ #move-source-item-spec } Source Item
|
|
|
|
///
|
|
|
|
|
|
## 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`.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /server/files/copy
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"source": "gcodes/my_file.gcode",
|
|
"dest": "gcodes/new_dir/my_file.gcode"
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.copy",
|
|
"params": {
|
|
"source": "gcodes/my_file.gcode",
|
|
"dest": "gcodes/new_dir/my_file.gcode"
|
|
},
|
|
"id": 5623
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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. |^
|
|
|
|
///
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"item": {
|
|
"root": "gcodes",
|
|
"path": "subdir/my_file.gcode",
|
|
"modified": 1676940082.8595376,
|
|
"size": 384096,
|
|
"permissions": "rw"
|
|
},
|
|
"action": "create_file"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| -------- | :----: | ------------------------------------------------------- |
|
|
| `item` | object | A `Destination Item` object. |
|
|
| | | #copy-dest-item-spec |+
|
|
| `action` | string | A description of the action taken. Expand for details. |
|
|
| | | #copy-action-desc |+
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | --------------------------------------------------------- |
|
|
| `root` | string | The root node of the destination file or directory. |
|
|
| `path` | string | The path, relative to the root node, of the destination |
|
|
| | | file or directory. |^
|
|
| `modified` | float | The last modified time of the destination file or |
|
|
| | | directory. This is expressed in Unix Time (seconds). |^
|
|
| `size` | int | The size, in bytes, of the destination file or directory. |
|
|
| `permissions` | string | The permissions available on the destination file or |
|
|
| | | directory. |^
|
|
{ #copy-dest-item-spec } Destination Item
|
|
|
|
| Name | Description |
|
|
| ------------- | ------------------------------------------------------- |
|
|
| `create_file` | A new file was created by the copy operation. |
|
|
| `modify_file` | An existing file was modified (overwritten) by the copy |
|
|
| | operation. |^
|
|
| `create_dir` | A new directory was created by the copy operation. In |
|
|
| | addition, children files and directories may have been |^
|
|
| | created. |^
|
|
{ #copy-action-desc }
|
|
///
|
|
|
|
## Create a ZIP archive
|
|
|
|
Creates a `zip` file consisting of one or more files.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
POST /server/files/zip
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"dest": "config/error_logs.zip",
|
|
"items": [
|
|
"config/printer.cfg",
|
|
"logs",
|
|
"gcodes/subfolder"
|
|
],
|
|
"store_only": false
|
|
}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"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
|
|
}
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
| 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. |^
|
|
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"destination": {
|
|
"root": "config",
|
|
"path": "error_logs.zip",
|
|
"modified": 1676984423.8892415,
|
|
"size": 420,
|
|
"permissions": "rw"
|
|
},
|
|
"action": "zip_files"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ---------------------------------------------------------- |
|
|
| `destination` | object | A `Zip Destination` object containing details about the |
|
|
| | | archived file. |^
|
|
| | | #zip-destination-spec |+
|
|
| `action` | string | The action taken be the file manager. Will be `zip_files`. |
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ------------------------------------------------------------------- |
|
|
| `root` | string | The root node of the destination file or directory. |
|
|
| `path` | string | The path of the zip archive, relative to the `root`. |
|
|
| `modified` | float | The last modified time in unix time. |
|
|
| `size` | int | The size of the file in bytes. |
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the archive. |
|
|
{ #zip-destination-spec } Zip Destination
|
|
|
|
///
|
|
|
|
## File download
|
|
Retrieves file `filename` at root `root`. The `filename` must include
|
|
the relative path if it is not in the root folder.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/{root}/{filename}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
Not Available
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
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.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
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--
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
Not Available
|
|
```
|
|
|
|
/// api-parameters
|
|
open: True
|
|
|
|
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. |^
|
|
|
|
///
|
|
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| --------------- | :----: | --------------------------------------------------------------------- |
|
|
| `item` | object | An `Uploaded Item` object. |
|
|
| | | #uploaded-item-spec |+
|
|
| `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". |
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | ------------------------------------------------------------------- |
|
|
| `path` | string | The path of the uploaded file, relative to the `root`. |
|
|
| `root` | string | The root node of the destination file or directory. |
|
|
| `modified` | float | The last modified time in unix time. |
|
|
| `size` | int | The size of the file in bytes. |
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the archive. |
|
|
{ #uploaded-item-spec } Uploaded Item
|
|
|
|
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.
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
DELETE /server/files/{root}/{filename}
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "server.files.delete_file",
|
|
"params": {
|
|
"path": "{root}/{filename}"
|
|
},
|
|
"id": 1323
|
|
}
|
|
```
|
|
|
|
/// collapse-code
|
|
```{.json .apiresponse title="Example Response"}
|
|
{
|
|
"item": {
|
|
"path": "Lock Body Shim 1mm_0.2mm_FLEX_MK3S_2h30m.gcode",
|
|
"root": "gcodes",
|
|
"size": 0,
|
|
"modified": 0,
|
|
"permissions": ""
|
|
},
|
|
"action": "delete_file"
|
|
}
|
|
```
|
|
///
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
| Field | Type | Description |
|
|
| -------- | :----: | --------------------------------------------------------------- |
|
|
| `item` | object | A `Deleted Item` object. |
|
|
| | | #deleted-item-spec |+
|
|
| `action` | string | Action taken by the file manager. Will always be "delete_file". |
|
|
|
|
| Field | Type | Description |
|
|
| ------------- | :----: | -------------------------------------------------------------------- |
|
|
| `path` | string | The path of the deleted file, relative to the `root`. |
|
|
| `root` | string | The root node of the deleted file or directory. |
|
|
| `modified` | float | The last modified time in unix time. Should always be 0 as the file |
|
|
| | | no longer exists. |^
|
|
| `size` | int | The size of the file in bytes. Should always be 0 as the file no |
|
|
| | | longer exits. |^
|
|
| `permissions` | string | The available [permissions](#file-permissions-desc) of the archive. |
|
|
| | | should always be an empty string as the file no longer exists. |^
|
|
{ #deleted-item-spec } Deleted Item
|
|
|
|
///
|
|
|
|
## 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.
|
|
///
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/klippy.log
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
Not Available
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
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.
|
|
///
|
|
|
|
```{.http .apirequest title="HTTP Request"}
|
|
GET /server/files/moonraker.log
|
|
```
|
|
|
|
```{.json .apirequest title="JSON-RPC Request"}
|
|
Not Available
|
|
```
|
|
|
|
/// api-response-spec
|
|
open: True
|
|
|
|
The body of the response contains the contents of `moonraker.log`.
|
|
|
|
/// |