File operations¶

Retrieve all files¶

Retrieve data of specific storage¶

Upload file or create folder¶

Retrieve a specific file’s or folder’s information¶

GET /api/files/(string: location)/(path: filename)¶

Retrieves the selected file’s or folder’s information.

If the file is unknown, a 404 Not Found is returned.

If the targeted path is a folder, by default only its direct children will be returned. If recursive is provided and set to true, all sub folders and their children will be returned too.

On success, a 200 OK is returned, with a File entry as the response body.

Requires the FILES_LIST permission.

Example

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

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

{
  "name": "whistle_v2.gcode",
  "size": 1468987,
  "date": 1378847754,
  "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": 1188,
    "filament": {
      "length": 810,
      "volume": 5.36
    }
  },
  "print": {
    "failure": 4,
    "success": 23,
    "last": {
      "date": 1387144346,
      "success": true
    }
  }
}

Parameters:¶

• location – The location of the file for which to retrieve the information, either local or sdcard.

• filename – The filename of the file for which to retrieve the information

Status Codes:¶

• 200 OK – No error

• 404 Not Found – If target is neither local nor sdcard, sdcard but SD card support is disabled or the requested file was not found

Issue a file command¶

POST /api/files/(string: location)/(path: path)¶

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 204 No Content and an empty body is returned. If there already is an active print job, a 409 Conflict is returned.

Requires the FILES_SELECT permission.

unselect

Unselects the currently selected file for printing.

Upon success, a status code of 204 No Content and an empty body is returned. If no file is selected or there already is an active print job, a 409 Conflict is returned. If path isn’t current or the filename of the current selection, a 400 Bad Request is returned

Requires the FILES_SELECT permission.

copy

Copies the file or folder to a new destination on the same location or another storage. Additional parameters are:

• destination: The path of the parent folder to which to copy the file or folder. It must already exist. Mandatory.

• storage: The optional target storage to copy the file to.

Note

Whether this command is supported depends on the involved storage’s capabilities.

For an in-storage move, the storage needs to support copy_file or copy_folder respectively.

For a cross-storage file move, the source needs to support read_file and the target needs to support write_file. Cross-storage folder copies are currently not supported.

If there already exists a file or folder of the same name at destination, the request will return a 409 Conflict. If the destination folder does not exist, a 404 Not Found will be returned.

A 400 Bad Request will be returned if:

• the destination is missing from the request

• the cross-storage target storage is not available

• the cross-storage operation’s destination is a folder

• the targeted path is neither a file nor a folder

• the involved storages lack the necessary capabilities to perform the operation

Upon success, a status code of 201 Created and a Uploaded entry in the response body will be returned.

Requires the FILES_UPLOAD permission.

Changed in version 1.12.0: cross-storage support

move

Moves the file or folder to a new destination on the same location or another storage. Additional parameters are:

• destination: The path of the parent folder to which to move the file or folder.

• storage: The optional target storage to move the file to.

Note

Whether this command is supported depends on the involved storage’s capabilities.

For an in-storage move, the storage needs to support move_file or move_folder respectively.

For a cross-storage file move, the source needs to support read_file and remove_file and the target needs to support write_file. Cross-storage folder moves are currently not supported.

If there already exists a file or folder of the same name at destination, the request will return a 409 Conflict. If the destination folder does not exist, a 404 Not Found will be returned. If the path is currently in use by OctoPrint (e.g. it is a GCODE file that’s currently being printed) a 409 Conflict will be returned.

A 400 Bad Request will be returned if:

• the destination is missing from the request

• the cross-storage target storage is not available

• the cross-storage operation’s destination is a folder

• the targeted path is neither a file nor a folder

• the involved storages lack the necessary capabilities to perform the operation

Upon success, a status code of 201 Created and a Uploaded entry in the response body will be returned.

Requires the FILES_UPLOAD permission.

Changed in version 1.12.0: cross-storage support

refresh_thumbnails

Forces a refresh of the thumbnail of the targeted file, or the files contained in the targeted folder.

Additional parameters are:

• force: If true, a thumbnail refresh will be even done if a thumbnail already exists.

• recursive: If true and targeting a folder, any contained subfolders will also be fully processed.

Upon success, a status code of 204 No Content and empty body is returned. The request will only return after the refresh has been processed - it thus might be long running!

Requires the FILES_UPLOAD permission.

Added in version 1.12.0.

slice

Slices an STL file into GCODE. Note that this is an asynchronous operation that will take place in the background after the response has been sent back to the client. Additional parameters are:

• slicer: The slicing engine to use, defaults to cura if not set, which is also the only supported slicer right now.

• gcode: Name of the GCODE file to generated, in the same location as the STL file. Defaults to the STL file name with extension .gco if not set.

• position: Position of the object-to-slice’s center on the print bed. A dictionary containing both x and y coordinate in mm is expected

• printerProfile: Name of the printer profile to use, if not set the default printer profile will be used.

• profile: Name of the slicing profile to use, if not set the default slicing profile of the slicer will be used.

• profile.*: Override parameters, the profile. prefix will be stripped and the matching profile key will be overridden with the supplied value. Use this if you want to specify things that change often like a different temperature, filament diameter or infill percentage. Profile keys are slicer specific.

• select: Optional, if set to true the file be selected for printing right after the slicing has finished. If the printer is not operational or already printing when this parameter is present and set to true, the request will fail with a response of 409 Conflict

• print: Optional, if set to true the file be selected and start printing right after the slicing has finished. If the printer is not operational or already printing when this parameter is present and set to true, the request will fail with a response of 409 Conflict. Note that if this parameter is set, the parameter select does not need to be set, it is automatically assumed to be true too, otherwise no printing would be possible.

If consecutive slicing calls are made targeting the same GCODE filename (that also holds true if the default is used), the slicing job already running in the background will be cancelled before the new one is started. Note that this will also mean that if it was supposed to be directly selected and start printing after the slicing finished, this will not take place anymore and whether this will happen with the new sliced file depends entirely on the new request!

Upon success, a status code of 202 Accepted and a Uploaded entry in the response body will be returned.

Requires the SLICE permission.

Example Select Request

POST /api/files/local/whistle_v2.gcode HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "select",
  "print": true
}

HTTP/1.1 204 No Content

Example Slice Request

POST /api/files/local/some_folder/some_model.stl HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "slice",
  "slicer": "cura",
  "gcode": "some_model.first_try.gcode",
  "printerProfile": "my_custom_reprap",
  "profile": "high_quality",
  "profile.infill": 75,
  "profile.fill_density": 15,
  "position": {"x": 100, "y": 100},
  "print": true
}

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "origin": "local",
  "name": "some_model.first_try.gcode",
  "path": "some_folder/some_model.first_try.gcode",
  "refs": {
    "download": "http://example.com/downloads/files/local/some_folder/some_model.first_try.gcode",
    "resource": "http://example.com/api/files/local/some_folder/some_model.first_try.gcode"
  }
}

Example in-storage Copy Request

POST /api/files/local/some_folder/some_model.gcode HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "copy",
  "destination": "some_other_folder/subfolder"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/api/files/local/some_other_folder/subfolder/some_model.gcode

{
  "origin": "local",
  "name": "some_model.gcode",
  "path": "some_other_folder/subfolder/some_model.gcode",
  "refs": {
    "download": "http://example.com/downloads/files/local/some_other_folder/subfolder/some_model.gcode",
    "resource": "http://example.com/api/files/local/some_other_folder/subfolder/some_model.gcode"
  }
}

Example in-storage Move Request

POST /api/files/local/some_folder/and_a_subfolder HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "move",
  "destination": "some_other_folder"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/api/files/local/some_other_folder/and_a_subfolder

{
  "origin": "local",
  "name": "and_a_subfolder",
  "path": "some_other_folder/and_a_subfolder",
  "refs": {
    "resource": "http://example.com/api/files/local/some_other_folder/and_a_subfolder"
  }
}

Example cross-storage Copy Request

POST /api/files/local/some_folder/some_model.gcode HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "copy",
  "destination": "/",
  "storage": "printer"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/api/files/printer/some_mo~1.gco

{
  "origin": "printer",
  "name": "some_mo~1.gco",
  "path": "some_mo~1.gco",
  "refs": {
    "resource": "http://example.com/api/files/printer/some_mo~1.gco"
  }
}

Parameters:¶

• location – The target location on which to send the command for is located, either local (for OctoPrint’s uploads folder) or sdcard for the printer’s SD card (if available)

• path – The path of the file for which to issue the command

JSON Parameters:¶

• command (string) – The command to issue for the file, currently only select is supported

• print (boolean) – select and slice command: Optional, whether to start printing the file directly after selection or slicing, defaults to false.

• slicer (string) – slice command: The slicer to use, defaults to the default slicer.

• gcode (string) – slice command: The name of the gcode file to create, defaults to the targeted stl’s file name with its extension changed to .gco (e.g. “test.stl” will be sliced to “test.gco” if not specified otherwise)

• profile (string) – slice command: The slicing profile to use, defaults to the selected slicer’s default profile.

• profile.* (string) – slice command: Overrides for the selected slicing profile, e.g. to specify a different temperature or filament diameter.

• printerProfile (string) – slice command: The printer profile to use, defaults to the default printer profile.

• select (boolean) – slice command: Optional, whether to select the file for printing directly after slicing, defaults to false

Status Codes:¶

• 200 OK – No error for a select command.

• 202 Accepted – No error for a slice command.

• 400 Bad Request – If the command is unknown or the request is otherwise invalid

• 415 Unsupported Media Type – If a slice command was issued against something other than an STL file.

• 404 Not Found – If location is neither local nor sdcard or the requested file was not found

• 409 Conflict – If a selected file is supposed to start printing directly but the printer is not operational or if a file is to be selected but the printer is already printing or if a file to be sliced is supposed to be selected or start printing directly but the printer is not operational or already printing.

Delete file¶

DELETE /api/files/(string: location)/(path: path)¶

Delete the selected path on the selected location.

If the file to be deleted is currently being printed, a 409 Conflict will be returned.

Returns a 204 No Content after successful deletion.

Requires the FILES_DELETE permission.

Example Request

DELETE /api/files/local/whistle_v2.gcode HTTP/1.1
Host: example.com
Authorization: Bearer abcdef...

Parameters:¶

• location – 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)

• path – The path of the file to delete

Status Codes:¶

• 204 No Content – No error

• 404 Not Found – If location is neither local nor sdcard or the requested file was not found

• 409 Conflict – If the file to be deleted is currently being printed

Data model¶

Files response (pre 1.12.0)¶

Files for storage response (pre 1.12.0)¶

Upload response¶

Upload response (pre 1.12.0)¶

Storage data¶

Storage capabilities¶

Usage data¶

File entry¶

Folder entry¶

Uploaded entry¶

Analysis result¶

Filament use¶

Volume¶

Dimensions¶