CreatBot/CreatBotMoonraker
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
CreatBotMoonraker/docs/external_api/file_manager.md
Eric Callahan 9c550a8f9a docs: complete API documentation rework 
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>
2025-02-06 19:15:38 -05:00

1214 lines
45 KiB
Markdown
Raw Blame History

# 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`.
///
Reference in New Issue View Git Blame Copy Permalink