.. _sec-api-fileops: *************** File operations *************** .. toctree:: :maxdepth: 5 .. _sec-api-fileops-retrieveall: Retrieve all files ================== .. http:get:: /api/files Retrieve information regarding all files currently available and regarding the disk space still available locally in the system. Returns a :ref:`Retrieve response `. **Example request**: .. sourcecode:: http GET /api/files HTTP/1.1 Host: example.com X-Api-Key: abcdef... **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "files": [ { "name": "whistle_v2.gcode", "bytes": 1468987, "size": "1.4MB" "date": "2013-05-21 23:15", "origin": "local", "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" }, "print": { "failure": 4, "success": 23, "last": { "date": "2013-11-18 18:00", "success": true } } }, { "name": "whistle_.gco", "bytes": 0, "size": "n/a", "date": "n/a", "origin": "sdcard" } ], "free": "3.2GB" } :statuscode 200: No error .. _sec-api-fileops-retrievetarget: Retrieve files from specific origin =================================== .. http:get:: /api/files/(string:origin) Retrieve information regarding the files currently available on the selected `origin` and regarding the disk space still available locally in the system. Returns a :ref:`Retrieve response `. **Example request**: .. sourcecode:: http GET /api/files/local HTTP/1.1 Host: example.com X-Api-Key: abcdef... **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "files": [ { "name": "whistle_v2.gcode", "bytes": 1468987, "size": "1.4MB" "date": "2013-05-21 23:15", "origin": "local", "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" }, "print": { "failure": 4, "success": 23, "last": { "date": "2013-11-18 18:00", "success": true } } } ], "free": "3.2GB" } :param origin: The origin location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are supported, with ``local`` referring to files stored in OctoPrint's ``uploads`` folder and ``sdcard`` referring to files stored on the printer's SD card (if available). :statuscode 200: No error :statuscode 400: If `origin` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid. .. _sec-api-fileops-uploadfile: Upload file =========== .. http:post:: /api/files/(string:target) Upload a file to the selected `target`. Other than most of the other requests on OctoPrint's API which are expected as JSON, this request is expected as ``Content-Type: multipart/form-data`` due to the included file upload. Returns an :ref:`Upload Response ` upon successful completion. **Example request** .. sourcecode:: http POST /api/files/local HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDeC2E3iWbTv1PwMC ------WebKitFormBoundaryDeC2E3iWbTv1PwMC Content-Disposition: form-data; name="file"; filename="whistle_v2.gcode" Content-Type: application/octet-stream ;Generated with Cura_SteamEngine 13.11.2 M109 T0 S220.000000 T0 ;Sliced at: Wed 11-12-2013 16:53:12 ;Basic settings: Layer height: 0.2 Walls: 0.8 Fill: 20 ;Print time: #P_TIME# ;Filament used: #F_AMNT#m #F_WGHT#g ;Filament cost: #F_COST# ;M190 S70 ;Uncomment to add your own bed temperature line ;M109 S220 ;Uncomment to add your own temperature line G21 ;metric values G90 ;absolute positioning ... ------WebKitFormBoundaryDeC2E3iWbTv1PwMC Content-Disposition: form-data; name="select" true ------WebKitFormBoundaryDeC2E3iWbTv1PwMC Content-Disposition: form-data; name="print" true ------WebKitFormBoundaryDeC2E3iWbTv1PwMC-- **Example response** .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "files": [ ... { "name": "whistle_v2.gcode", "bytes": 1468987, "size": "1.4MB" "date": "2013-05-21 23:15", "origin": "local" }, ... ], "done": true, "filename": "whistle_v2.gcode" } :param target: The target location to which to upload the file. Currently only ``local`` and ``sdcard`` are supported here, with ``local`` referring to OctoPrint's ``uploads`` folder and ``sdcard`` referring to the printer's SD card. If an upload targets the SD card, it will also be stored locally first. :form file: The file to upload, including a valid ``filename``. :form select: Whether to select the file directly after upload (``true``) or not (``false``). Optional, defaults to ``false``. :form print: Whether to start printing the file directly after upload (``true``) or not (``false``). If set, `select` is implicitely ``true`` as well. Optional, defaults to ``false``. :statuscode 200: No error :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, no `file` is included in the request, the file is neither a ``gcode`` nor an ``stl`` file (or it is an ``stl`` file but slicing support is disabled) or the request is otherwise invalid. :statuscode 403: If the upload of the file would override the file that is currently being printed :statuscode 500: If the upload failed internally .. _sec-api-fileops-retrievefile: Retrieve a file's contents ========================== .. http:get:: /api/files/local/(path:filename) Downloads the selected file's contents. Only available for locally stored files, hence no `target` parameter. Will actually redirect to serve the download via a static context directly from the filesystem. **Example Request** .. sourcecode:: http GET /api/files/local/whistle_v2.gcode HTTP/1.1 Host: example.com **Example Response** .. sourcecode:: http HTTP/1.1 302 Found Location: /downloads/files/whistle_v2.gcode **Redirect Request** .. sourcecode:: http GET /downloads/files/whistle_v2.gcode HTTP/1.1 Host: example.com **Redirect Response** .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/octet-stream ;Generated with Cura_SteamEngine 13.11.2 M109 T0 S220.000000 T0 ;Sliced at: Wed 11-12-2013 16:53:12 ;Basic settings: Layer height: 0.2 Walls: 0.8 Fill: 20 ;Print time: #P_TIME# ;Filament used: #F_AMNT#m #F_WGHT#g ;Filament cost: #F_COST# ;M190 S70 ;Uncomment to add your own bed temperature line ;M109 S220 ;Uncomment to add your own temperature line G21 ;metric values G90 ;absolute positioning ... :param filename: The filename of the file for which to retrieve the contents :resheader Location: The statically served download location for the file of the format ``/downloads/files/`` :statuscode 302: No error, regular redirect to statically served download location .. _sec-api-fileops-filecommand: Issue a file command ==================== .. http:post:: /api/files/(string:target)/(path:filename) Issue a file command to an existing file. Currently supported commands are: load Selects a file for printing. Additional parameters are: * ``print``: Optional, if set to ``true`` the file will start printing directly after selection. **Example Request** .. sourcecode:: http POST /api/files/local/whistle_v2.gcode HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { "command": "load", "print": true } **Example Response** .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json {} :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` folder) or ``sdcard`` for the printer's SD card (if available) :param filename: The filename of the file for which to issue the command :json string command: The command to issue for the file, currently only ``load`` is supported :json boolean print: ``load`` command: Optional, whether to start printing the file directly after selection, defaults to ``false``. :statuscode 200: No error :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, the `command` is unknown or the request is otherwise invalid .. _sec-api-fileops-delete: Delete file =========== .. http:delete:: /api/files/(string:target)/(path:filename) Delete the selected `filename` on the selected `target`. Returns a :ref:`Retrieve Response ` corresponding to the updated file list after successful deletion. **Example Request** .. sourcecode:: http DELETE /api/files/local/whistle_v2.gcode HTTP/1.1 Host: example.com X-Api-Key: abcdef... **Example Response** .. sourcecode:: http HTTP/1.1 200 Ok Content-Type: application/json { "files": [ ... ], "free": "3.2GB" } :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` folder) or ``sdcard`` for the printer's SD card (if available) :param filename: The filename of the file to delete :statuscode 200: No error :statuscode 400: If `target` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid :statuscode 403: If the file to be deleted is currently being printed .. _sec-api-fileops-datamodel: Datamodel ========= .. _sec-api-fileops-datamodel-retrieveresponse: Retrieve response ----------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``files`` - 0..* - Array of :ref:`File information items ` - The list of requested files. Might be an empty list if no files are available * - ``free`` - 1 - String - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder) .. _sec-api-fileops-datamodel-uploadresponse: Upload response --------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``files`` - 0..* - Array of :ref:`File information items ` - The list of files available in the system. Might be an empty list if no files are available * - ``done`` - 1 - Boolean - Whether the file is directly available for printing after receiving the response (``true``) or not, e.g. due to first needing to be sliced into GCODE (``false``) * - ``filename`` - 1 - String - The name of the file that was just uploaded .. _sec-api-fileops-datamodel-fileinfo: File information ---------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``name`` - 1 - String - The name of the file * - ``bytes`` - 1 - Number - The size of the file in bytes. Only available for ``local`` files, always ``0`` for files stored on ``sdcard``. * - ``size`` - 1 - String - The size of the file in a human readable format. Only available for ``local`` files, set to ``n/a`` for files stored on ``sdcard``. * - ``date`` - 1 - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` - The date and time this files was uploaded. Only available for ``local`` files, set to ``n/a`` for files stored on ``sdcard``. * - ``origin`` - 0..1 - String, either ``local`` or ``sdcard`` - The origin of the file, ``local`` when stored in OctoPrint's ``uploads`` folder, ``sdcard`` when stored on the printer's SD card (if available) * - ``gcodeAnalysis`` - 0..1 - :ref:`GCODE analysis information ` - Information from the analysis of the GCODE file, if available. * - ``prints`` - 0..1 - :ref:`Print information ` - Information regarding prints of this file, if available. .. todo:: Make fields which are not available for ``sdcard`` (``bytes``, ``size``, ``date``) optional and don't include them in the output if not available. Clients should be able to decide on their own what to display in such a case. .. _sec-api-fileops-datamodel-gcodeanalysis: GCODE analysis information -------------------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``estimatedPrintTime`` - 1 - String representing a duration in the format ``HH:mm:ss`` - The estimated print time of the file * - ``filament`` - 1 - String - The estimated usage of filament (length in meters and volume in cubic centimeters) in a human readable format. Example: ``1.89m / 11.90cm³`` .. _sec-api-fileops-datamodel-prints: Print information ----------------- .. list-table:: :widths: 15 5 10 30 :header-rows: 1 * - Name - Multiplicity - Type - Description * - ``failure`` - 1 - Number - The number of failed prints on record for the file * - ``success`` - 1 - Number - The number of successful prints on record for the file * - ``last`` - 0..1 - Object - Information regarding the last print on record for the file * - ``last.date`` - 1 - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` - Date and time when the file was printed last * - ``last.success`` - 1 - Boolean - Whether the last print on record was a success (``true``) or not (``false``)