MrDraw/docs/api/fileops.rst

.. _sec-api-fileops:

***************
File operations
***************

.. contents::

.. _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 <sec-api-fileops-datamodel-retrieveresponse>`.

   **Example request**:

   .. sourcecode:: http

      GET /api/files HTTP/1.1
      Host: example.com

   **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",
            "refs": {
              "resource": "http://example.com/api/files/local/whistle_v2.gcode",
              "download": "http://example.com/downloads/files/local/whistle_v2.gcode"
            },
            "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",
            "origin": "sdcard",
            "refs": {
              "resource": "http://example.com/api/files/sdcard/whistle_.gco"
            }
          }
        ],
        "free": "3.2GB"
      }

   :statuscode 200: No error

.. _sec-api-fileops-retrievespecific:

Retrieve files from specific location
=====================================

.. http:get:: /api/files/(string:location)

   Retrieve information regarding the files currently available on the selected `location` and -- if targeting
   the ``local`` location -- regarding the disk space still available locally in the system.

   Returns a :ref:`Retrieve response <sec-api-fileops-datamodel-retrieveresponse>`.

   **Example request**:

   .. sourcecode:: http

      GET /api/files/local HTTP/1.1
      Host: example.com

   **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",
            "refs": {
              "resource": "http://example.com/api/files/local/whistle_v2.gcode",
              "download": "http://example.com/downloads/files/local/whistle_v2.gcode"
            },
            "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 location: 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 404: If `location` is neither ``local`` nor ``sdcard``

.. _sec-api-fileops-uploadfile:

Upload file
===========

.. http:post:: /api/files/(string:location)

   Upload a file to the selected `location`.

   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 a :http:statuscode:`201` response with a ``Location`` header set to the management URL of the uploaded
   file and an :ref:`Upload Response <sec-api-fileops-datamodel-uploadresponse>` as the body upon successful completion.

   **Example request**

   .. sourcecode:: http

      POST /api/files/sdcard 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
      Location:

      {
        "files": {
          "local": {
            "name": "whistle_v2.gcode",
            "origin": "local",
            "refs": {
              "resource": "http://example.com/api/files/local/whistle_v2.gcode",
              "download": "http://example.com/downloads/files/local/whistle_v2.gcode"
            }
          },
          "sdcard": {
            "name": "whistle_.gco",
            "origin": "sdcard",
            "refs": {
              "resource": "http://example.com/api/files/sdcard/whistle_.gco"
            }
          }
        },
        "done": true
      }

   :param location: 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 201: No error
   :statuscode 400: If no `file` is included in the request, or the request is otherwise invalid.
   :statuscode 404: If `location` is neither ``local`` nor ``sdcard`` or trying to upload to SD card and SD card support
                    is disabled
   :statuscode 409: If the upload of the file would override the file that is currently being printed or if an upload
                    to SD card was requested and the printer is either not operational or currently busy with a print job.
   :statuscode 415: If the file is neither a ``gcode`` nor an ``stl`` file (or it is an ``stl`` file but slicing support
                    is disabled)
   :statuscode 500: If the upload failed internally

.. _sec-api-fileops-retrievefileinfo:

Retrieve a specific file's information
======================================

.. http:get:: /api/files/(string:location)/(path:filename)

   Retrieves the selected file's information.

   If the file is unknown, a :http:statuscode:`404` is returned.

   On success, a :http:statuscode:`200` is returned, with a :ref:`file information item <sec-api-fileops-datamodel-fileinfo>`
   as the response body.

   **Example Request**

   .. sourcecode:: http

      GET /api/files/local/whistle_v2.gcode HTTP/1.1
      Host: example.com

   **Example Response**

   .. sourcecode:: http

      HTTP/1.1 200 Ok
      Content-Type: application/json

      {
        "name": "whistle_v2.gcode",
        "bytes": 1468987,
        "size": "1.4MB"
        "date": "2013-05-21 23:15",
        "origin": "local",
        "refs": {
          "resource": "http://example.com/api/files/local/whistle_v2.gcode",
          "download": "http://example.com/downloads/files/local/whistle_v2.gcode"
        },
        "gcodeAnalysis": {
          "estimatedPrintTime": "00:31:40",
          "filament": "0.79m"
        },
        "print": {
          "failure": 4,
          "success": 23,
          "last": {
            "date": "2013-11-18 18:00",
            "success": true
          }
        }
      }

   :param location: The location of the file for which to retrieve the information, either ``local`` or ``sdcard``.
   :param filename: The filename of the file for which to retrieve the information
   :statuscode 200: No error
   :statuscode 404: If `target` is neither ``local`` nor ``sdcard``, ``sdcard`` but SD card support is disabled or the
                    requested file was not found

.. _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:

   select
     Selects a file for printing. Additional parameters are:

     * ``print``: Optional, if set to ``true`` the file will start printing directly after selection. If the printer
       is not operational when this parameter is present and set to ``true``, the request will fail with a response
       of ``409 Conflict``.

   Upon success, a status code of :http:statuscode:`204` and an empty body is returned.

   **Example Select 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": "select",
        "print": true
      }

   :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 ``select`` is supported
   :json boolean print:  ``select`` command: Optional, whether to start printing the file directly after selection,
                         defaults to ``false``.
   :statuscode 200:      No error
   :statuscode 400:      If the `command` is unknown or the request is otherwise invalid
   :statuscode 404:      If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found
   :statuscode 409:      If a selected file is supposed to start printing directly but the printer is not operational.

.. _sec-api-fileops-delete:

Delete file
===========

.. http:delete:: /api/files/(string:target)/(path:filename)

   Delete the selected `filename` on the selected `target`.

   If the file to be deleted is currently being printed, a :http:statuscode:`409` will be returned.

   Returns a :http:statuscode:`204` after successful deletion.

   **Example Request**

   .. sourcecode:: http

      DELETE /api/files/local/whistle_v2.gcode HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...

   :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 204: No error
   :statuscode 404: If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found
   :statuscode 409: 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 <sec-api-fileops-datamodel-fileinfo>`
     - The list of requested files. Might be an empty list if no files are available
   * - ``free``
     - 0..1
     - String
     - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder). Only
       returned if file list was requested for origin ``local`` or all origins.

.. _sec-api-fileops-datamodel-uploadresponse:

Upload response
---------------

.. list-table::
   :widths: 15 5 10 30
   :header-rows: 1

   * - Name
     - Multiplicity
     - Type
     - Description
   * - ``files``
     - 1
     - Object
     - Abridged information regarding the file that was just uploaded. If only uploaded to ``local`` this will only
       contain the ``local`` property. If uploaded to SD card, this will contain both ``local`` and ``sdcard`` properties.
   * - ``files.local``
     - 1
     - :ref:`sec-api-fileops-datamodel-fileinfo`
     - The information regarding the file that was just uploaded to the local storage (only the fields ``name``,
       ``origin`` and ``refs`` will be set).
   * - ``files.sdcard``
     - 0..1
     - :ref:`sec-api-fileops-datamodel-fileinfo`
     - The information regarding the file that was just uploaded to the printer's SD card (only the fields ``name``,
       ``origin`` and ``refs`` will be set).
   * - ``done``
     - 1
     - Boolean
     - Whether the file processing after upload has already finished (``true``) or not, e.g. due to first needing
       to perform a slicing step (``false``). Clients may use this information to direct progress displays related to
       the upload.

.. _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``
     - 0..1
     - Number
     - The size of the file in bytes. Only available for ``local`` files.
   * - ``size``
     - 0..1
     - String
     - The size of the file in a human readable format. Only available for ``local`` files.
   * - ``date``
     - 0..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.
   * - ``origin``
     - 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)
   * - ``refs``
     - 0..1
     - :ref:`<sec-api-fileops-datamodel-ref>`
     - References relevant to this file
   * - ``gcodeAnalysis``
     - 0..1
     - :ref:`GCODE analysis information <sec-api-fileops-datamodel-gcodeanalysis>`
     - Information from the analysis of the GCODE file, if available.
   * - ``prints``
     - 0..1
     - :ref:`Print information <sec-api-fileops-datamodel-prints>`
     - Information regarding prints of this file, if available.

.. _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``)

.. _sec-api-fileops-datamodel-ref:

References
----------

.. list-table::
   :widths: 15 5 10 30
   :header-rows: 1

   * - Name
     - Multiplicity
     - Type
     - Description
   * - ``resource``
     - 1
     - URL
     - The resource that represents the file (e.g. for issuing commands to or for deleting)
   * - ``download``
     - 0..1
     - URL
     - The download URL for the file
   * - ``model``
     - 0..1
     - URL
     - The model from which this file was generated (e.g. an STL, currently not used)