Plugin Files APIs¶

OctoEverywhere's Plugin Files API is a 3D printer platform agnostic API that allows file access such as list, upload, download, and delete.

Tip

These APIs work with every 3D printer OctoEverywhere supports, including OctoPrint, Moonraker, Klipper, Bambu Lab, Prusa, Elegoo, Creality, and more.

Get Started With Plugin APIs

Virtual File Paths¶

All of the File APIs use a common virtual root folder for different file types. For example, gcode, logs, config, etc. When using any file paths for the File APIs, you must include these virtual root folders.

Common Error Codes¶

All Plugin APIs share a set of common error codes that can be returned for issues like the OctoEverywhere plugin is offline, auth issues, etc.

List Files¶

Returns a recursive list of files on the 3D printer.

HTTP Request

GET https://<unique_id>.octoeverywhere.com/octoeverywhere-command-api/files/list

Example Response

{
    "Status": 200,
    "Result:": {
        "Root": [
            {
                "Type": "folder",
                "Name": "gcode",
                "VirtualPath": "gcode",
                "Children": [
                    {
                        "Type": "file",
                        "Name": "test.gcode",
                        "Path": "gcode/test.gcode",
                        "PlatformPath": "test.gcode",
                        "SizeBytes": 180576306,
                        "ModifiedTimeSec": 1780783212.2935026,
                        "Permissions": "rw",
                        "Metadata": {
                            ...
                        }
                    },
                ]
            }
        ]
    }
}

Name	Type	Description
`Type`	string	`folder` or `file`
`Name`	string	The file or folder name
`VirtualPath`	string	The path generated by the OctoEverywhere plugin, us this path for upload, download, or delete commands.
`PlatformPath`	string	The file path used by the 3D printer software. Use this path to reference the file when interacting with the 3D printer's software.
`SizeBytes`	int	The file size in bytes.
`ModifiedTimeSec`	int	The last modified time in seconds.
`Permissions`	string	The file permission.
`Metadata`	object	Optional platform specific metadata for the file.
`Children`	list	Folders can optionally have more files or folders objects.

Upload File¶

Upload a file to the 3D printer's file system.

HTTP Request

PUT https://<unique_id>.octoeverywhere.com/octoeverywhere-command-api/files/upload?path=<VirtualPath>

Request GET Parameters¶

Name	Type	Default	Description
`path`	string	None	A `VirtualPath` file path to put the file.

Request Body¶

The request body must be the file contents to be uploaded.

Response¶

Example Response

{
    "Status": 200,
    "Result": {
        "VirtualPath": "gcode/test.gcode",
        "PlatformPath": "test.gcode",
        "SizeBytes": 1360548,
        "PrinterResponse": {
            ...
        }
    }
}

Name	Type	Description
`VirtualPath`	string	The OctoEverywhere virtual file path.
`PlatformPath`	string	The file path used by the 3D printer software. Use this path to reference the file when interacting with the 3D printer's software.
`SizeBytes`	int	The file size in bytes.
`PrinterResponse`	object	Optional platform specific response for the upload command.

Download File¶

Download a file from the 3D printer's file system.

HTTP Request

GET https://<unique_id>.octoeverywhere.com/octoeverywhere-command-api/files/download?path=<VirtualPath>

Request GET Parameters¶

Name	Type	Default	Description
`path`	string	None	A `VirtualPath` file path of the file to be downloaded.

Response¶

A common error json result or the file's contents as the HTTP response body.

Delete File¶

Delete a file from the 3D printer's file system.

HTTP Request

POST https://<unique_id>.octoeverywhere.com/octoeverywhere-command-api/files/delete?path=<VirtualPath>

Request GET Parameters¶

Name	Type	Default	Description
`path`	string	None	A `VirtualPath` file path of the file to be deleted.

Response¶

Example Response

{
    "Status": 200,
    "Result": {
        "VirtualPath": "gcode/test.gcode",
        "PlatformPath": "/server/files/gcodes/test.gcode",
        "PrinterResponse": {
            ...
        }
    }
}

Name	Type	Description
`VirtualPath`	string	The OctoEverywhere virtual file path.
`PlatformPath`	string	The file path used by the 3D printer software. Use this path to reference the file when interacting with the 3D printer's software.
`PrinterResponse`	object	Optional platform specific response for the delete command.