# List of supported HTTP requests

RepRapFirmware provides an HTTP interface for dealing with client requests.
These requests are tailored for Duet Web Control in the first place but they may be used by third-party applications, too.

Every request except for `rr_connect` returns HTTP status code `401` if the client does not have a valid session.
If no machine password is set, a user session is created whenever an arbitrary HTTP request is made.
Besides, RepRapFirmware may run short on memory and may not be able to respond properly. In this case, HTTP status code `503` is returned.

In the following requests datetime strings may be used. These datetime strings are very similar to ISO8601-encoded strings but they do not contain timezone details.
An example for such a string is `2019-12-13T21:27:00`. Make sure to follow this format where applicable.

*Note: Starting from v3.4.1 there are OpenAPI definition files for [SBC](https://github.com/Duet3D/DuetSoftwareFramework/blob/v3.4-dev/OpenAPI.yaml) and [standalone](https://github.com/Duet3D/RepRapFirmware/blob/v3-chrishamm/Developer-documentation/OpenAPI.yaml) mode. If you are using .NET, check out the [DuetHttpClient](https://www.nuget.org/packages/DuetHttpClient/) package. If you want to explore the api using swagger, paste the .yaml file into : https://editor.swagger.io/*

## GET /rr_connect

Attempt to create a new connection and log in using the (optional) password.

Supported parameters:

- `password` (optional): Machine password to log in with. If omitted, this defaults to `reprap`
- `time` (optional): Current datetime that will be used to update RepRapFirmware's internal clock
- `sessionKey` (optional): Either `yes` or `no`, if set to `yes`, RRF will generate a unique HTTP session (supported in RRF 3.5-b4 and later)

Returns

```
{
    "err": code
}
```

where `code` may be one of the following:

- `0`: Password is valid and the client's IP address is added to the list of HTTP sessions
- `1`: Password is invalid
- `2`: No more user sessions available. This may occur when too many client devices are connected at the same time

If the password is valid, extra fields are returned:

```
{
    "err": 0,
    "sessionTimeout": 8000,
    "boardType": "duetwifi102",
    "sessionKey": 123456
}
```

- `sessionTimeout` is the idle timeout in milliseconds before a client is removed again from the list of client sessions
- `boardType` represents the board's type

Officially supported board types are:

| boardType | Board | Remarks |
| --------- | ----- | ------- |
| duet06 | Duet 0.6 | deprecated |
| duet07 | Duet 0.7 | deprecated |
| duet085 | Duet 0.8.5 | deprecated |
| duetwifi10 | Duet WiFi v1.0 ||
| duetwifi102 | Duet WiFi v1.02 ||
| duetethernet10 | Duet Ethernet v1.0 ||
| duetethernet102 | Duet Ethernet v1.02 ||
| duetmaestro100 | Duet Maestro v1.0 ||
| duet3mb6hc100| Duet 3 MB6HC v0.6 and v1.0 ||
| duet3mb6hc101 | Duet 3 MB6HC v1.01 ||
| duet3mb6xd | Duet 3 MB6XD v1.0 ||
| duet5lcwifi | Duet 3 Mini 5+ WiFi ||
| duet5lcethernet | Duet 3 Mini 5+ Ethernet ||

### HTTP Client:
A HTTP Client is defined as a source IP address connecting to the HTTP Interface. If you have multiple applications that need to connect to the HTTP interface then they should be bound to a different IP address or use some other mechanism to manage replies.

### HTTP Sessions:
Up to v3.5-b3 only one session per IP / HTTP Client is supported, further calls to rr_connect when an active session exists will be result in a "err" code of "0" returned but no additional session will be created. The same limitation applies if a client connects in 3.5-b4 and later if no `sessionKey` parameter with value `yes` is present. If a session key is used, the client must set the `X-Session-Key` header to the returned `sessionKey` value in all following HTTP requests in order to authenticate itself.

Since IP-based sessions cannot keep the G-code reply for more than a single session per IP address, the usage of session keys is encouraged in v3.5-b4 and later.

### example /rr_connect
```
curl http://<address>/rr_connect?password=
```


## GET /rr_disconnect

Disconnect again from the RepRapFirmware controller.

Returns

```
{
    "err": code
}
```

where `code` may be `0` if the session could be removed, else it is `1`.

### example /rr_disconnect
```
curl http://<address>/rr_disconnect
```

## GET /rr_status (deprecated, scheduled for removal in RRF 3.6)

Retrieve a status response from RepRapFirmware in JSON format. Deprecated in RRF 3.0 and later, use `rr_model` instead.

Supported parameters:

- `type`: Type of the status response

The value of `type` can be one of:

- 1: Standard status response
- 2: Advanced status response. This also contains fields from the standard status response
- 3: Print status response. This contains fields from the standard status response as well as information about the current (print) job

See [JSON responses](https://github.com/Duet3D/RepRapFirmware/blob/v3-dev/JSON%20responses.md) for further information.

## Get /rr_config (deprecated, scheduled for removal in RRF 3.6)

Retrieve the configuration response. This request provides a JSON object with values that are expected to change rarely. Deprecated in RRF 3.0 and later, use rr_model instead.

See [JSON responses](https://github.com/Duet3D/RepRapFirmware/blob/v3-dev/JSON%20responses.md) for further information.

## GET /rr_gcode

Execute arbitrary G/M/T-code(s).

Supported parameters:

- `gcode`: G/M/T-code to execute. This parameter must be present although it can be empty

Returns

```
{
    "buff": bufferSpace
}
```

where `bufferSpace` indicates how much buffer space for new G/M/T-codes is still available.

If a file is supposed to be streamed over the HTTP interface, call this repeatedly and transfer only as many bytes as allowed.

### example /rr_gcode
```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_gcode?gcode=G28
```

## GET /rr_reply

Retrieve the last G-code reply. The G-code reply is buffered per connected HTTP client and it is discarded when every HTTP client has fetched it or
when the firmware is short on memory and the client has not requested it within reasonable time (1 second).

Client should keep querying `rr_model?key=seqs` and monitor `seqs.reply`. When its value is incremented, that means there is new reply data available to fetch.

The G-code reply is always returned as `text/plain`.

### example /rr_reply

in this example we send the M115 gcode in order to generate a reply to fetch
```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_gcode?gcode=M115
curl http://<address>/rr_reply
```

## GET /rr_upload

Get the last file upload result.

Returns

```
{
    "err": code
}
```

where `code` can be either `0` if the last upload successfully finished or `1` if an error occurred.

### example GET /rr_upload
assuming sent immediately after a file upload
```
curl http://<address>/rr_upload
```


## POST /rr_upload

Upload a file.

Supported URL parameters:

- `name`: Path to the file to upload
- `time` (optional): ISO8601-like representation of the time the file was last modified
- `crc32` (optional): CRC32 checksum of the file content as hex string *without* leading `0x`. Usage of this parameter is encouraged

The raw HTTP body contains the file content. Binary file uploads are supported as well.
Make sure to set `Content-Length` to the length of the HTTP body if your HTTP client does not already do that.

Returns

```
{
    "err": code
}
```

where `code` can be either `0` if the last upload successfully finished or `1` if an error occurred (e.g. CRC mismatch).

### example POST /rr_upload

```
curl http://<address>/rr_connect?password=
curl --data-binary @"<path_and_filename.gcode>" "http://<address>/rr_upload?name=/gcodes/<filename.gcode>"
```

## GET /rr_download

Download a file.

Supported parameters:

- `name`: Filename to download

If the file could not be found, HTTP status code 404 is returned, else the file content is sent to the client.

### example /rr_download

```
curl http://<address>/rr_connect?password=
curl "http://<address>/rr_download?name=/sys/config.g" > <path_to_config_backup>/config.g
```

## GET /rr_delete

Delete a file or directory.

Supported parameters:

- `name`: Filename to delete
- `recursive` (optional): Set this to `yes` to delete the directory recursively if applicable. Defaults to `no` (requires 3.5b3 and newer)

Returns

```
{
    "err": {code}
}
```

where code is either `0` on success or `1` on error.

### example /rr_delete

```
curl http://<address>/rr_connect?password=
curl "http://<address>/rr_delete?name=/macros/<file to delete>"
```

## GET /rr_filelist

Retrieve a (partial) file list.

Supported parameters:

- `dir`: Directory to query
- `first` (optional): First item index to return. Defaults to `0`
- `max` (optional): Maximum number of items to return (RRF 3.6.0-beta.2 and newer). Defaults to `-1`

Returns
```
{
    "dir": dir,
    "first": first,
    "files": [
        {
            "type": itemType,
            "name": itemName,
            "size": itemSize,
            "date": itemDate
        },
        ...
    ],
    "next": next,
    "err": code
}
```

where `dir` and `first` equal the query parameters. `err` can be one of:

- `0`: List query successful
- `1`: Drive is not mounted
- `2`: Directory does not exist

The `next` field may be missing if the query was not successful. It is `0` if there are no further items. If there are more items than could be returned, this value should be used for the `first` parameter of a following `rr_filelist` request to retrieve the next block of items.

Retrieved files are returned as part of the `files` array. Every item has the following properties, except that `date` may not be present if it is invalid:

- `type`: Type of the file item. This is `d` for directories and `f` for files
- `name`: Name of the file or directory
- `size`: Size of the file. This is always `0` for directories
- `date`: Datetime of the last file modification

### example /rr_filelist

```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_filelist?dir=/macros/
```

## GET /rr_files

Retrieve a list of files without any attributes.

Supported parameters:

- `dir`: Directory to query
- `first` (optional): First item index to return. Defaults to `0`
- `max` (optional): Maximum number of items to return (RRF 3.6.0-beta.2 and newer). Defaults to `-1`
- `flagDirs` (optional): Set this to `1` to prefix directory items with `*`. Defaults to `0`

Returns

```
{
    "dir": dir,
    "first": first,
    "files": [
        "file1",
        "file2",
        ...
    ],
    "next": next,
    "err": err
}
```

where `dir` and `first` equal the query parameters. `err` can be one of:

- `0`: List query successful
- `1`: Drive is not mounted
- `2`: Directory does not exist

The `next` field may be omitted if the query was not successful and it is `0` if the query has finished. If there are more items to query, this value can be used for the `first` parameter of a successive `rr_files` request.

### example /rr_files

```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_files?dir=/macros/
```

## GET /rr_model

Retrieve [object model](https://github.com/Duet3D/RepRapFirmware/wiki/Object-Model-Documentation) information like [M409](https://duet3d.dozuki.com/Wiki/Gcode#Section_M409_Query_object_model). Supported in RRF 3. and later.

Supported parameters:
- `key`: Key to query
- `flags`: Query flags

Returns

```
{
    "key": <key>,
    "flags": <flags>,
    "result": <object model JSON>
}
```

or HTTP code 503 if the response could not be written due to a lack of memory.

The flags string may include one or more of the following letters (see the M409 documentation linked above for more information):

f: return only those values in the object model that typically change frequently during a job
v: Verbose: include values that are rarely needed and not normally returned
n: include fields with null values
o: include obsolete fields (v3.3 and newer)
d: limit the depth of the reported tree to the specified number following the letter d. Objects at the maximum depth will be returned as {}.

### example /rr_model

```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_model?key=boards[0]
```

## GET /rr_move

Move a file or directory.

Supported parameters:

- `old`: Current path to the file or directory
- `new`: New path of the file or directory
- `deleteexisting` (optional): Set this to `yes` to delete the new file if it already exists. Defaults to `no`

Returns

```
{
    "err": code
}
```

where code is either `0` on success or `1` on error.

### example /rr_move

```
curl http://<address>/rr_connect?password=
curl -G http://<address>/rr_move -d old="/macros/<file name>" -d new="/sys/<file name>"
```

## GET /rr_mkdir

Create a new directory.

Supported parameters:

- `dir`: Path to the new directory

Returns

```
{
    "err": code
|
```

where code is either `0` on success or `1` on error.

### example /rr_mkdir

```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_mkdir?dir=/macros/sub_directory
```

## GET /rr_fileinfo

Parse a G-code job file and return retrieved information. If no file is specified, information about the file being printed is returned.

Supported parameters:

- `name` (optional): Path to the file to parse

Returns

```
{
    "err": code,
    "size": size,
    "lastModified": lastModified,
    "height": height,
    "layerHeight": layerHeight,
    "printTime": printTime,
    "simulatedTime": simulatedTime,
    "filament": filament,
    "printDuration": printDuration,
    "fileName": fileName,
    "generatedBy": generatedBy,
    "thumbnails": [{width: 0, height: 0, format: "png", offset: 0, size: 0}, ...]
}
```

where `code` is either `0` on success or `1` on error. If the file could not be parsed, all other fields are omitted.

Other fields are:

| Field | Unit | Description | Default value if invalid | Present if `name` is omitted |
| ----- | ---- | ----------- | ------------------------ | --------------------------- |
| size | bytes | Size of the file in bytes | not applicable | yes |
| lastModified | datetime | Datetime of the last file modification | omitted | maybe |
| height | mm | Final print height of the object | 0.00 | yes |
| layerHeight | mm | Layer height | 0.00 | yes |
| printTime | seconds | Estimated print time | omitted | maybe |
| simulatedTime | seconds | Estimated print time according to the last simulation | omitted | maybe |
| filament | array of mm | Total filament consumption per extruder | empty array | yes |
| printDuration | seconds | Total print time so far | not applicable | yes |
| fileName | file path | Absolute path to the file being printed | not applicable | yes |
| generatedBy | text | Slicer or toolchain which generated this file | empty string | yes |
| thumbnails | array | Info about embedded thumbnails | empty array | yes |

### example /rr_fileinfo

```
curl http://<address>/rr_connect?password=
curl http://<address>/rr_fileinfo?name=/gcodes/<print_file_name>
```

## GET /rr_thumbnail

Query a thumbnail from a G-code file.

Supported parameters:
- `name`: Path to the file to query
- `offset`: Start offset of the thumbnail to query (from rr_fileinfo response)

the offset parameter should be retreved from the rr_fileinfo response, e.g.

```
"thumbnails":[{"width":30,"height":30,"format":"qoi","offset":106,"size":3348},{"width":300,"height":300,"format":"qoi","offset":3644,"size":37148}]
```
two thumbnails are present in the above example, one starting at 106 and the other at 3644

Returns:

```
{
  "fileName": name,
  "offset": offset,
  "data": "base64-encoded thumbnail data",
  "next": 0,
  "err": 0
}
```

where `next` is the offset of the following data or `0` if the thumbnail is complete and `err` indicates an error if present (non-zero on error).

### example /rr_thumbnail

```
curl http://<address>/rr_connect?password=
curl -G http://<address>/rr_rr_thumbnail -d name=/gcodes/<print_file_name> -d offset=106
```