REST API - Duet3D/DuetSoftwareFramework GitHub Wiki

DuetWebServer provides a RESTful API that is primarily targeted at Duet Web Control. In the following these endpoints are described. Note that these endpoints differ from those provided by RepRapFirmware's native network interface.

Note: Starting from v3.4.1 there are OpenAPI definition files for SBC and standalone mode. If you are using .NET, check out the DuetHttpClient package.

GET /machine/connect?password={password}

Establish a connection to the SBC and check the given password. The default password (in case none is set) is reprap. If no password is expected, the password key can be omitted.

If the password is OK, HTTP code 200 followed by a JSON object is returned:

{
  "sessionKey": <KEY>
}

For following HTTP requests, the session key must be added to the HTTP headers via X-Session-Key. For WebSocket requests, it must be appended to the URL using the sessionKey parameter (e.g. ws://duet3/machine?sessionKey=<KEY>).

The resulting session is maintained at least 8 seconds but it may last as long as

  • a WebSocket is open
  • a long-running HTTP request is being processed (code, upload, and package requests) When the session has expired, HTTP code 403 is returned by other requests.

Returns one of these HTTP status codes:

  • 200: Request OK, response returned as application/json
  • 403: Forbidden (invalid password)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

GET /machine/noop

Do nothing. May be used to ping the machine or to keep the HTTP session alive

Returns one of these HTTP status codes:

  • 204: No Content
  • 403: Forbidden (missing or invalid X-Session-Key header)

GET /machine/disconnect

Disconnect from the machine again. Make sure to have X-Session-Key set if you use this request.

Returns one of these HTTP status codes:

  • 204: No Content
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

WS /machine(?sessionKey={sessionKey})

If password protection is enabled, make sure to pass the optional sessionKey parameter as described in the GET /machine/connect request

WebSocket request for object model subscriptions. When a client connects, the web server registers a new HTTP user session in the object model. After that, the whole object model is sent from the web server to a client in JSON format. When the client has processed this response, it responds by sending OK\n (\n is NL) to acknowledge the receipt. When further object model changes are detected, the web server sends a JSON object (patch) representing the changes in the object model back to the client so that it can update the object model again. Note that these changes are only returned as a partial object model which may not be confused with a JSON Patch as defined by proposed RFC 6902). To see this behaviour in action (except for the first full model transfer), check out the ModelObserver.

If the client does not receive an update for a while, it may send a PING\n message to the server. When the server receives this message, it responds with PONG\n at last after the time specified via ObjectModelUpdateTimeout. Although the WebSocket server implements a server-side keep-alive interval, this mechanism is useful for clients to detect unexpected connection aborts (e.g. when the machine is suddenly powered off).

If the query is no WebSocket request, HTTP code 400 is returned. In case password protection is enabled and the session key is missing or invalid, HTTP code 403 is returned.

GET /machine/status

Query the full object model. The model is returned as a JSON object.

Returns one of these HTTP status codes:

  • 200: Query OK, current object model is returned as application/json
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

POST /machine/code?async={true/false}

Execute plain G/M/T-code(s) from the raw request body and return the G-code response when done.

The optional async parameter defines whether the request shall block until the code has been executed. If it is set to true and a code reply is generated, the reply is output as a generic message.

Returns one of these HTTP status codes:

  • 200: Code(s) have finished, reply is returned as text/plain
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

GET /machine/file/{filename}

Download a file. The file path is translated to a physical file path.

Returns one of these HTTP status codes:

  • 200: File content
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 404: File not found
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

PUT /machine/file/{filename}?timeModified={timeModified}

Upload a file. The file path is translated to a physical file path. The body payload is the file content.

The time modified is optional, if it is present it must be in ISO 8601 format. The last written timestamp will be set to this when the upload is complete.

Returns one of these HTTP status codes:

  • 201: File created
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

GET /machine/fileinfo/{filename}?readThumbnailContent={true/false}

Parse a given G-code file and return information about this job file as a JSON object. See API Documentation for further information about the object returned.

By default, no thumbnail data is returned. Set readThumbnailContent to true if you need that.

Returns one of these HTTP status codes:

  • 200: Parsed file information as application/json
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

DELETE /machine/file/{filename}(?recursive={true/false})

Delete a file or directory. The file path is translated to a physical file path. Version 3.5b3 and newer support the optional recursive parameter to recursively delete a directory (must be either true or false, defaults to false)

Returns one of these HTTP status codes:

  • 204: File or directory succesfully deleted
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 404: File or directory not found
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

POST /machine/file/move

Move a file or directory from a to b. The file paths are translated to physical file paths. This query uses the following parameters as an application/x-www-form-urlencoded:

  • from: Source file path
  • to: Destination file path
  • force (optional): If the destination file already exists, delete it first. Defaults to false

Returns one of these HTTP status codes:

  • 204: File or directory succesfully moved
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 404: File or directory not found
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

GET /machine/directory/{directory}

Get a file list of the given directory. The directory path is translated to a physical file path.

The format of the returned file list is a JSON array and it looks like:

[
    {
        type: 'd',
        name: 'sys',
        date: '2019-10-21T23:47:59+01:00'
    },
    {
        type: 'f',
        name: 'some file.gcode',
        size: 23534,
        date: '2019-10-21T23:47:59+01:00'
    }
]

type can be either d if the item is a directory or f if it is a file. size is always the number of bytes.

PUT /machine/directory/{directory}

Create the given directory. The directory path is translated to a physical directory path.

Returns one of these HTTP status codes:

  • 201: Directory created
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

PUT /machine/plugin

Install or upgrade a plugin ZIP file. The body payload is the ZIP file content.

Returns one of these HTTP status codes:

  • 204: Plugin has been installed
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

DELETE /machine/plugin

Uninstall a plugin. The body payload is the name of the plugin to remove.

Returns one of these HTTP status codes:

  • 204: Plugin has been uninstalled
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

PATCH /machine/plugin

Set plugin data in the object model if there is no SBC executable. The body payload is JSON in the format

{
    "plugin": "<PluginName>",
    "key": "<Key>",
    "value": <JSON value>
}

If there is an SBC executable, expose your own HTTP endpoints to modify shared plugin data.

Returns one of these HTTP status codes:

  • 204: Data has been set
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

POST /machine/startPlugin

Start a plugin on the SBC. The body payload is the name of the plugin to start. This does nothing if a plugin has already been started.

  • 204: Plugin has been started
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable

POST /machine/stopPlugin

Stop a plugin on the SBC. The body payload is the name of the plugin to stop. This does nothing if a plugin has already been stopped.

  • 204: Plugin has been stopped
  • 403: Forbidden (missing or invalid X-Session-Key header)
  • 500: Generic error
  • 502: Incompatible DCS version
  • 503: DCS is unavailable
⚠️ **GitHub.com Fallback** ⚠️