Plugin Files APIs¶

OctoEverywhere's Plugin Files API is a platform-agnostic API for listing, inspecting, uploading, downloading, and deleting files. It also exposes the installed OctoEverywhere plugin's log for diagnostics.

Tip

File-system support depends on what the printer platform exposes. Unsupported commands return plugin status 788. The plugin-log command is available independently of printer file-system support.

Get Started With Plugin APIs

Virtual File Paths¶

All File APIs use a common virtual root for each file type. A path must include its root, such as gcode/models/benchy.gcode, config/printer.cfg, or logs/klippy.log. Always pass the returned VirtualPath to another File API; PlatformPath is for native platform APIs.

Platform	List roots	Upload roots	Download roots	Delete roots	File details
OctoPrint	`gcode`, `logs`	`gcode`	`gcode`, `logs`	`gcode`, `logs`	`gcode`
Moonraker / Klipper	`gcode`, `config`, `logs`	`gcode`, `config`	`gcode`, `config`, `logs`	`gcode`, `config`	`gcode`
Bambu Lab	`gcode`	`gcode`	`gcode`	`gcode`	`gcode` basic details
PrusaLink, Elegoo, Elegoo CC2	Not supported	Not supported	Not supported	Not supported	Not supported

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

By default, the command returns every virtual root supported by the platform. Use root to request one root. A full path is also accepted and selects its first path segment as the root; listing remains recursive from that root.

Name	Type	Default	Description
`root`	string	All supported roots	Optional virtual root such as `gcode`, `config`, or `logs`.
`path`	string	None	Optional virtual path whose first segment selects the root. Ignored when `root` is supplied.

Example Response

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

Name	Type	Description
`Type`	string	`folder` or `file`
`Name`	string	The file or folder name
`VirtualPath`	string	Path generated by the OctoEverywhere plugin. Use it for details, upload, download, start, 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.
Additional fields	any	Optional platform-specific metadata is flattened onto the file object. Field names vary by platform.
`Children`	list	Folders can optionally have more files or folders objects.

Get File Details¶

Returns normalized metadata about one printable file. The amount of metadata varies by platform and file type; unsupported or unknown fields are omitted rather than returned as null.

HTTP Request

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

Name	Type	Required	Description
`path`	string	Yes	The `VirtualPath` of the file to inspect. File metadata is currently limited to the `gcode` root.

Example Response

{
    "Status": 200,
    "Result": {
        "VirtualPath": "gcode/models/benchy.gcode",
        "PlatformPath": "models/benchy.gcode",
        "FileName": "benchy.gcode",
        "SizeBytes": 1360548,
        "ModifiedTimeSec": 1780783212,
        "EstPrintTimeSec": 4620,
        "EstFilamentUsedMm": 5234,
        "EstFilamentWeightMg": 15632,
        "LayerCount": 240,
        "LayerHeightMm": 0.2,
        "FirstLayerHeightMm": 0.24,
        "ObjectHeightMm": 48.0,
        "NozzleDiameterMm": 0.4,
        "FilamentType": "PLA",
        "FilamentName": "Generic PLA",
        "BedTempC": 60.0,
        "HotendTempC": 220.0,
        "ChamberTempC": 35.0,
        "Slicer": "PrusaSlicer",
        "SlicerVersion": "2.9.2",
        "ThumbnailCount": 3,
        "PlatformDetails": {
            "platform_native_field": "value"
        }
    }
}

VirtualPath, PlatformPath, and FileName are always present on success. The remaining normalized fields are optional:

Name	Type	Description
`SizeBytes`	int	File size in bytes.
`ModifiedTimeSec`	int	Unix time in seconds when the file was last modified.
`EstPrintTimeSec`	int	Slicer's estimated print duration in seconds.
`EstFilamentUsedMm`	int	Estimated filament length in millimeters.
`EstFilamentWeightMg`	int	Estimated filament weight in milligrams.
`LayerCount`	int	Total sliced layer count.
`LayerHeightMm`	float	Nominal layer height in millimeters.
`FirstLayerHeightMm`	float	First-layer height in millimeters.
`ObjectHeightMm`	float	Sliced object height in millimeters.
`NozzleDiameterMm`	float	Nozzle diameter used by the slicer profile.
`FilamentType`	string	Generic material family, such as `PLA` or `PETG`.
`FilamentName`	string	Slicer filament-profile name.
`BedTempC`	float	Sliced bed target in Celsius.
`HotendTempC`	float	Sliced hotend target in Celsius.
`ChamberTempC`	float	Sliced chamber target in Celsius.
`PrintStartTimeSec`	int	Unix time when this file was most recently started, when tracked.
`Slicer`	string	Slicer name.
`SlicerVersion`	string	Slicer version.
`ThumbnailCount`	int	Number of embedded thumbnails found.
`PlatformDetails`	any	Native metadata returned by the platform. Its structure is platform-specific.

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": {
            "result": "ok"
        }
    }
}

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`	any	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": "test.gcode",
        "PrinterResponse": {
            "result": "ok"
        }
    }
}

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`	any	Optional platform-specific response for the delete command.