diff --git a/docs/api.md b/docs/api.md index 46d89a22..c0cc25a7 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,19 +1,18 @@ -# API +--- +title: HTTP API reference +#description: Getting started with PiKVM V4 Mini & Plus +--- -This document describes the PiKVM API. Since the system consists of microservices, here is a common API with a common entry point provided by Nginx. The examples above use `curl` and [`websocat`](https://github.com/vi/websocat) with the `-k` option to disable SSL certificate verification, since the self-signed certificateis used in the default installation. - -There is a [third-party library](https://github.com/guanana/pikvm-lib) for using the PiKVM API. -Please note that this is an unofficial library, so use it carefully. +This document describes the PiKVM API. Since the system consists of microservices, here is a common API with a common entry point provided by Nginx. The below examples use `curl` and [`websocat`](https://github.com/vi/websocat) with the `-k` option disables SSL certificate verification, since the self-signed certificateis are used in the default installation. +There is a [third-party library](https://github.com/guanana/pikvm-lib) for using the PiKVM API. Please note that this is an unofficial library, so use it carefully. ----- ## Authentication -All APIs are restricted to authentication. To make requests, you either need to auth each request individually, -or get a token and pass it as a cookie with each request. +All APIs are restricted to authentication. To make requests, you either need to auth each request individually, or get a token and pass it as a cookie with each request. -With enabled [2FA](auth.md#two-factor-authentication), you will need to add the one-time code to the password without spaces. -That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password. +With enabled [2FA](auth.md#two-factor-authentication), you will need to add the one-time code to the password without spaces. That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password. The code can be generated using any TOTP library, for example in Python: @@ -48,8 +47,7 @@ now = int(time.time()) remaining = now - (now % totp.interval) ``` - -### Single request auth +### Single-request authentication There are two options here: @@ -61,16 +59,15 @@ There are two options here: * **Using HTTP Basic Auth.** Please note: contrary to the standard, this method DOES NOT use the `WWW-Authenticate` header. HTTP Basic Auth in this implementation is intended only for compatibility with other systems, such as [Prometheus](prometheus.md). - ``` + ```console $ curl -k -u admin:admin https:///api/auth/check ``` - ### Session-based cookie auth 1. Get the access token for the user using `POST /api/auth/login`: - ``` + ```console $ curl -k -v -X POST --data user=admin --data passwd=admin https://pikvm/api/auth/login ... < Set-Cookie: auth_token=796cb83b11de4fcb749bc1bad14a91fb06dede84672b2f847fef1e988e6900de; Path=/ @@ -83,7 +80,6 @@ There are two options here: 3. The handle `POST /api/auth/logout` can be used to invalidate session token. The response codes will be similar to the previous handle. - ----- ## WebSocket events @@ -93,7 +89,7 @@ In a normal situation, opening a socket session triggers the video streamer to s It is possible create a session that will not start the streamer and will not be counted when counting clients to stop the streamer. To do this, use the URL parameter `stream=0`: -``` +```console $ websocat -k wss:///api/ws?stream=0 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin ``` @@ -135,58 +131,49 @@ Another type of event is `ping`, which can be sent by the client: `{"event_type" ws.close() ``` - ----- ## System functions ### Get system info -The `GET /api/info` handle returns the general information about the PiKVM device. +**Method**: `GET` -Parameters: +**Route**: `/api/info` -* `fields=...` *(optional)* - Only specified categories will be returned, for example `fields=system,hw`. By default all categories will be displayed. +**Description**: Returns the general information about the PiKVM device. -``` -$ curl -k -u admin:admin https:///api/info +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `fields` | string | optional | Return only specified categories | `auth`, `extras`, `fan`, `hw`, `meta`, `system` | + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/info?fields=hw ``` -??? note "Click to expand" - ```js +??? note "Example output" + ```json { "ok": true, "result": { - "extras": { // Installed applications; null on internal error - "ipmi": { - "daemon": "kvmd-ipmi", - "description": "Show IPMI information", - "enabled": true, - "icon": "share/svg/ipmi.svg", - "keyboard_cap": false, - "name": "IPMI", - "path": "ipmi", - "place": 21, - "port": 623 - }, - "vnc": { - "daemon": "kvmd-vnc", - "description": "Show VNC information", - "enabled": true, - "icon": "share/svg/vnc.svg", - "keyboard_cap": false, - "name": "VNC", - "path": "vnc", - "place": 20, - "port": 5900 - } - }, - "hw": { // Hardware info + "hw": { "health": { - "temp": { - "cpu": 36.511, // /sys/class/thermal/thermal_zone0/temp / 1000; null on error - "gpu": 35.0 // vcgencmd measure_temp; null on error + "cpu": { + "percent": 2 }, - "throttling": { // vcgencmd get_throttled; null on error + "mem": { + "available": 1568993280, + "percent": 14.6, + "total": 1836331008 + }, + "temp": { + "cpu": 45.277 + }, + "throttling": { + "ignore_past": false, "parsed_flags": { "freq_capped": { "now": false, @@ -205,72 +192,509 @@ $ curl -k -u admin:admin https:///api/info } }, "platform": { - "base": "Raspberry Pi 4 Model B Rev 1.1", // /proc/device-tree/model; null on error - "serial": "0000000000000000", // /proc/device-tree/serial-number; null on error - "type": "rpi" - } - }, - "meta": { // /etc/kvmd/meta.yaml; null on error - "kvm": {}, - "server": { - "host": "localhost.localdomain" - } - }, - "system": { - "kernel": { - "machine": "x86_64", - "release": "5.8.14-arch1-1", - "system": "Linux", - "version": "#1 SMP PREEMPT Wed, 07 Oct 2020 23:59:46 +0000" - }, - "kvmd": { - "version": "2.1" - }, - "streamer": { - "app": "ustreamer", - "features": { // {} on error - "HAS_PDEATHSIG": true, - "WITH_GPIO": false, - "WITH_OMX": false, - "WITH_PTHREAD_NP": true, - "WITH_SETPROCTITLE": true - }, - "version": "2.1" // "" on error + "base": "Raspberry Pi 4 Model B Rev 1.5", + "board": "rpi4", + "model": "v3", + "serial": "10000000C8DA432D", + "type": "rpi", + "video": "hdmi" } } } - } + }⏎ ``` -Each category is represented by its own event in the websocket (`info_hw_state`, `info_system_state`, etc). The event content has the same format as the category content in API. - +Each category is represented by its own event in the websocket (`info_hw_state`, `info_system_state`, etc). The event content has the same format as the category content in the API. ### Get system log -The `GET /api/log` handle displays logs from all KVMD services as plain text. +**Method**: `GET` -Parameters: +**Route**: `/api/log` -* `follow=1` *(optional)* - Turns the request into long-polling mode and follow log messages in real time. -* `seek=N` *(optional)* - Runs the log for the specified time in seconds, for example `seek=3600` will show the log for the last hour. +**Description**: Displays logs from all KVMD services as plain text. +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `follow` | boolean | optional | Turns the request into long-polling mode and follow log messages in real time | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `seek` | integer | optional | Runs the log for the specified time in seconds | `≥0` | + +**Example of use**: the following query returns commit messages for the last 1 hour and enables the long-polling mode: + +```console +$ curl -k -u admin:admin 'https:///api/log?follow=1&seek=3600' ``` -$ curl -k -u admin:admin https:///api/log + +??? note "Example output" + ``` + [2025-06-10 22:38:07 kvmd.service] --- kvmd.apps.kvmd.auth INFO --- Authorized user 'admin' via auth service 'htpasswd' + [2025-06-10 22:38:15 kvmd.service] --- kvmd.apps.kvmd.auth INFO --- Authorized user 'admin' via auth service 'htpasswd' + ``` + +----- +## HID + +The PiKVM HID (Human Interface Device) API provides remote control capabilities for keyboard and mouse input devices. It allows users to perform the following operations: + +- Get the device state and set/reset parameters. +- Send keyboard shortcuts and text to be typed in the host system. +- Send various mouse events: move to absolute coordinates and relatively, click virtual mouse buttons, and scroll the virtual mouse wheel. + +### Get devices state + +**Method**: `GET` + +**Route**: `/api/hid` + +**Description**: Gets the current HID devices state. + +**Query parameters**: none. + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/hid ``` +??? note "Example output" + ```json + { + "ok": true, + "result": { + "busy": false, + "connected": null, + "enabled": true, + "jiggler": { + "active": false, + "enabled": true, + "interval": 60 + }, + "keyboard": { + "leds": { + "caps": false, + "num": false, + "scroll": false + }, + "online": false, + "outputs": { + "active": "", + "available": [] + } + }, + "mouse": { + "absolute": true, + "online": false, + "outputs": { + "active": "usb", + "available": [ + "usb", + "usb_rel" + ] + } + }, + "online": true + } + }⏎ + ``` + +### Set parameters + +**Method**: `POST` + +**Route**: `/api/hid/set_params` + +**Description**: Configures HID device parameters, such as the type of emulated keyboard and mouse. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `keyboard_output` | string | optional | Sets the type of the emulated keyboard | `usb`, `ps2`, `disabled` | +| `mouse_output` | string | optional | Sets the type of the emulated mouse | `usb`, `usb_win98`, `usb_rel`, `ps2`, `disabled` | +| `jiggler` | boolean | optional | Enable/disable [mouse jiggler](mouse_jiggler.md) functionality | `true` + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/hid/set_params?jiggler=0 +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Set the connected state + +**Method**: `POST` + +**Route**: `/api/hid/set_connected` + +**Description**: Sets the HID devices connection state. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `connected` | boolean | required | Sets the connection state | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/hid/set_connected?connected=0 +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Reset devices' state + +**Method**: `POST` + +**Route**: `/api/hid/reset` + +**Description**: Resets HID devices to their initial state. + +**Query parameters**: none + +**Example of use**: + +```console +$ curl -k -X POST -u admin:admin https:///api/hid/reset +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Get keyboard layouts + +**Method**: `GET` + +**Route**: `/api/hid/keymaps` + +**Description**: Gets available keyboard layouts and the current defaults for use with `POST /api/hid/print`. + +**Query parameters**: none + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/hid/keymaps +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": { + "keymaps": { + "available": [ + "ar", + "bepo", + "cz", + "da", + "de", + "de-ch", + "en-gb", + "en-us", + "en-us-altgr-intl", + "en-us-colemak", + "es", + "et", + "fi", + "fo", + "fr", + "fr-be", + "fr-ca", + "fr-ch", + "hr", + "hu", + "is", + "it", + "ja", + "lt", + "lv", + "mk", + "nl", + "no", + "pl", + "pt", + "pt-br", + "ru", + "sl", + "sv", + "th", + "tr" + ], + "default": "de" + } + } + }⏎ + ``` + +### Type text remotely + +**Method**: `POST` + +**Route**: `/api/hid/print` + +**Description**: Transmits user-defined text to emulate typing it on the PiKVM by sequencing key presses. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `limit` | integer | optional | Maximum characters to process | 0 = no limit. No maximum value. Default: 1024 | +| `keymap` | string | optional | Keymap to use (defaults to system default) | Any keymap listed in the output of `GET /hid/keymaps` | +| `slow` | boolean | optional | Enables slow typing mode (regular large intervals between key presses), `false` by default | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + -d "Einige Worte" \ + https:///api/hid/print?keymap=de +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Send a keyboard shortcut + +**Method**: `POST` + +**Route**: `/api/hid/events/send_shortcut` + +**Description**: Sends a keyboard shortcut, or key combination, to be typed on the PiKVM. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `keys` | string | required | Comma-separated list of key names | For a full list of supported values, please [see here](https://github.com/pikvm/kvmd/blob/master/keymap.csv). Use values from the `web_name` column | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/hid/events/send_shortcut?keys=ControlLeft,KeyL +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Send a single key event + +**Method**: `POST` + +**Route**: `/api/hid/events/send_key` + +**Description**: Transmits a command to emulate a single key press on the PiKVM. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `key` | string | required | Key identifier to send | For a full list of supported values, please [see here](https://github.com/pikvm/kvmd/blob/master/keymap.csv) | +| `state` | boolean | optional | Key state: `true` for press, `false` for release | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `finish` | boolean | optional | Releases non-modifier keys right after pressing them so that they don't get stuck when the connection is not stable. Defaults to `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/hid/events/send_key?key=Delete +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Send mouse button events + +**Method**: `POST` + +**Route**: `/api/hid/events/send_mouse_button` + +**Description**: Sends mouse button press/release events. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `button` | string | required | Mouse button identifier | `left`, `middle`, `right`, `up`, `down` | +| `state` | boolean | optional | Mouse button state: `true` for press, `false` for release | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/hid/events/send_mouse_button?button=left +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Move the mouse pointer + +**Method**: `POST` + +**Route**: `/api/hid/events/send_mouse_move` + +**Description**: Sends a command to move the mouse pointer to user-defined coordinates where 0,0 is the center of the screen. Only works if the mouse mode is set to `absolute` in the configuration. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `to_x` | integer | required | Target X coordinate | Any negative or positive integer value | +| `to_y` | integer | required | Target Y coordinate | Any negative or positive integer value | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/hid/send_mouse_move?to_x=0&to_y=50' +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Move the mouse ppinter relatively + +**Method**: `POST` + +**Route**: `/api/hid/events/send_mouse_relative` + +**Description**: Sends a command to move the mouse pointer by a relative offset in pixels. Only works if the mouse mode is set to `absolute` in the configuration. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `delta_x` | integer | required | Horizontal movement delta | Any negative or positive integer value | +| `delta_y` | integer | required | Vertical movement delta | Any negative or positive integer value | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/hid/send_mouse_relative?delta_x=20&delta_y=200' +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Send mouse wheel scroll events + +**Method**: `POST` + +**Route**: `/api/hid/events/send_mouse_wheel` + +**Description**: Sends mouse wheel scroll events to be emulated on the host by PiKVM. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `delta_x` | integer | required | Horizontal scroll delta | Any negative or positive integer value | +| `delta_y` | integer | required | Vertical scroll delta | Any negative or positive integer value | + +**Example of use**: Sends mouse wheel scroll events. + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/hid/send_mouse_wheel?delta_x=0&delta_y=200' +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + ----- ## ATX power management +The PiKVM ATX API provides control over ATX (Advanced Technology eXtended) power management functions. It allows users perform the following operations: + +- Get the current ATX state. +- Change the ATX state. +- Send an ATX button press event. + ### Get ATX state -The `GET /api/atx` handle shows the current ATX state. +**Method**: `GET` -``` +**Route**: `/api/atx` + +**Description**: Shows the current ATX state + +**Query parameters**: None. + +**Example of use**: + +```console $ curl -k -u admin:admin https:///api/atx ``` -??? note "Click to expand" - ```js +??? note "Example output" + ```json { "ok": true, "result": { @@ -284,177 +708,1216 @@ $ curl -k -u admin:admin https:///api/atx } ``` - ### Set ATX power -The `POST /api/atx/power` handle changes ATX power state to desired. +**Method**: `POST` -Parameters: +**Route**: `/api/atx/power` -* `action=...` - Describes desired state: - * `on` - Turn on (do nothing in case PSU is already on). - * `off` - Turn off (aka soft-off), emulates click on the power button. - * `off_hard` - Perform long press on the power button (5+ seconds). - * `reset_hard` - Emulates pressing reset button (hardware hot reset). -* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation. +**Description**: Changes the ATX power state to desired. -``` -$ curl -X POST -k -u admin:admin https:///api/atx/power?action=on +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `action` | string | optional | Specifies desired state | `on` - Turn on (do nothing in case PSU is already on). `off` - Turn off (aka soft-off), emulates click on the power button. `off_hard` - Perform long press on the power button (5+ seconds). `reset_hard` - Emulate pressing reset button (hardware hot reset) | +| `wait` | boolean | optional | Says if call should return immediately or just after finishing operation. | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/atx/power?action=on ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Click ATX button -The `POST /api/atx/click` handle sends the ATX button press event. +**Method**: `POST` -Parameters: +**Route**: `/api/atx/click` -* `button=...` - Specifies the desired PC case button: - * `power` - Short click on the power button. - * `power_long` - Long press on the power button (5+ seconds). - * `reset` - Short click on the reset button. -* `wait=1` *(Optional)* - Says if call should return immediately or just after finishing operation. +**Description**: Sends the ATX button press event. -``` -$ curl -X POST -k -u admin:admin https:///api/atx/click?button=power +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `button` | string | optional | Specifies the desired PC case button | `power` - Short click on the power button. `power_long` - Long press on the power button (5+ seconds). `reset` - Short click on the reset button. | +| `wait` | boolean | optional | Says if call should return immediately or just after finishing operation. | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/atx/click?button=power ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ----- ## Mass Storage Drive +The PiKVM Mass Storage Drive API provides controls for remote management of disk images that can be mounted as virtual storage devices. It allows users perform the following operations: + +- Get current MSD status and configuration +- Upload, download, and delete disk images +- Fetch disk images directly from URLs with progress streaming +- Connect/disconnect virtual storages, enable CD-ROM and read-write modes +- Set image names, access modes, and device type settings + ### Get MSD state -The `GET /api/msd` handle shows the current MSD state. +**Method**: `GET` -``` +**Route**: `/api/msd` + +**Description**: Retrieves the current state of the Mass Storage Device. + +**Query parameters**: None. + +**Example of use**: + +```console $ curl -k -u admin:admin https:///api/msd ``` +??? note "Example output" + ``` json + { + "ok": true, + "result": { + "busy": false, + "drive": { + "cdrom": true, + "connected": false, + "image": null, + "rw": false + }, + "enabled": true, + "online": true, + "storage": { + "downloading": null, + "images": {}, + "parts": { + "": { + "free": 24358789120, + "size": 24375590912, + "writable": true + } + }, + "uploading": null + } + } + }⏎ + ``` ### Upload MSD image -The `POST /api/msd/write` uploads an image to MSD. +**Method**: `POST` -Parameters: +**Route**: `/api/msd/write` -* `image=...` - Specifies the name of the image. -* Binary data should be passed to the POST body. +**Description**: uploads an ISO to the Mass Storage Device. -``` +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `image` | string | required | Specifies the name of the image. Binary data should be passed to the POST body | `filename.iso` | + +**Example of use**: + +```console $ # create a test image $ dd if=/dev/zero of=test.iso bs=1M count=1 $ # upload it to pikvm -$ curl -v -X POST --data-binary @test.iso -k -u admin:admin https:///api/msd/write?image=test.iso +$ curl -v -X POST --data-binary @test.iso -k \ + -u admin:admin \ + https:///api/msd/write?image=test.iso ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Upload MSD image by URL -The `POST /api/msd/write_remote` handle downloads an image from HTTP(S) URL to the MSD. +**Method**: `POST` -Parameters: +**Route**: `/api/msd/write_remote` -* `url=...` - Image URL. -* `image=...` *(optional)* - Image name. -* `timeout=N` *(optional)* - Remote request timeout, 10 seconds by default. +**Description**: Downloads an image from HTTP(S) URL to the MSD. !!! note This is a long-polling request. Do not interrupt the request until the download is complete, otherwise the download will stop. -``` +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `url` | string | required | Image URL | Any URL using HTTP(S) | +| `image` | string | optional | Image name | Any alphanumeric name like `image321.iso` | +| `timeout` | integer | optional | Remote request timeout, 10 seconds by default | `≥0` | + +**Example of use**: + +```console $ # create test image $ dd if=/dev/zero of=test.iso bs=1M count=1 $ # upload it to pikvm -$ curl -v -X POST -k -u admin:admin https:///api/msd/write_remote?url=http://example.com/test.iso +$ curl -v -X POST -k \ + -u admin:admin \ + https:///api/msd/write_remote?url=http://example.com/test.iso ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Set MSD parameters -The `POST /api/msd/set_params` handle changes the current image and/or set drive parameters +**Method**: `POST` -Parameters: +**Route**: `/api/msd/set_params` -* `image=...` *(optional)* - Change the current image. -* `cdrom=1|0` *(optional)* - Change the media type to the CD-ROM on `1`, otherwise to the Flash. -* `rw=0|1` *(optional)* - Make the MSD read-write on `1`, otherwise read-only. Ignored (always read-only) when `cdrom=1`. +**Description**: Changes the current image and/or set drive parameters. -``` -$ curl -X POST -k -u admin:admin "https:///api/msd/set_params?image=test.iso&cdrom=1" +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `image` | string | optional | Change the current image | `filename.iso` | +| `cdrom` | boolean | optional | Change the media type to the CD-ROM or Flash. | `1` (CD-ROM) or `0` (Flash) | +| `rw` | boolean | optional | Sets read-write or read-only mode. Ignored (always read-only) when `cdrom=1` | `1` (read-write) or `0` (read-only) | + +**Example of use**: + +```console +$ curl -X POST -k \ + -u admin:admin \ + 'https:///api/msd/set_params?image=test.iso&cdrom=1' ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Control MSD -The `POST /api/msd/set_connected` connects or disconnect the MSD to the host. +**Method**: `POST` -Parameters: +**Route**: `/api/msd/set_connected` -* `connected=1|0` - Change the state. +**Description**: Connects or disconnects the MSD to/from the host. -``` -$ curl -X POST -k -u admin:admin https:///api/msd/set_connected?connected=1 +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `connected` | boolean | required | Changes the state | `1` connects the MSD, `0` disconnects it | + +**Example of use**: + +```console +$ curl -X POST -k \ + -u admin:admin \ + https:///api/msd/set_connected?connected=1 ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Remove MSD image -The `POST /api/msd/remove` handle removes the specified image. +**Method**: `POST` -Parameters: +**Route**: `/api/msd/remove` -* `image=...` - The image name. +**Description**: Removes the specified image. -``` -$ curl -X POST -k -u admin:admin https:///api/msd/remove?image=test.iso +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `image` | string | required | Name of the image to remove | `filename.iso` | + +**Example of use**: + +```console +$ curl -X POST -k \ + -u admin:admin \ + https:///api/msd/remove?image=test.iso ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ### Reset MSD -The `POST /api/msd/reset` handle resets the drive. +**Method**: `POST` -``` -$ curl -X POST -k -u admin:admin https:///api/msd/reset +**Route**: `/api/msd/reset` + +**Description**: Drops all the custom parameters you set before and resets the Mass Storage Device to its default state. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -X POST -k \ + -u admin:admin \ + https:///api/msd/reset ``` +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` ----- ## GPIO +This is a PiKVP API for controlling User GPIO (General Purpose Input/Output) pins. It allows users perform the following operations: + +- Read GPIO states. +- Switch pins on/off. +- Send pulses to GPIO channels. + ### Get GPIO state -The `GET /api/gpio` handle shows the current GPIO state. +**Method**: `GET` -``` +**Route**: `/api/gpio` + +**Description**: Retrieves the current state of all GPIO channels. + +**Query parameters**: None. + +**Example of use**: + +```console $ curl -k -u admin:admin https:///api/gpio ``` +??? note "Example output" + ``` json + { + "ok": true, + "result": { + "model": { + "scheme": { + "inputs": {}, + "outputs": { + "__v3_usb_breaker__": { + "hw": { + "driver": "__gpio__", + "pin": "5" + }, + "pulse": { + "delay": 0.0, + "max_delay": 0.0, + "min_delay": 0.0 + }, + "switch": true + } + } + }, + "view": { + "header": { + "title": [ + { + "text": "GPIO", + "type": "label" + } + ] + }, + "table": [] + } + }, + "state": { + "inputs": {}, + "outputs": { + "__v3_usb_breaker__": { + "busy": false, + "online": true, + "state": true + } + } + } + } + }⏎ + ``` ### Switch GPIO channel -The `POST /api/gpio/switch` handle interacts with selected GPIO driver channel in `switch` mode. +**Method**: `POST` -Parameters: +**Route**: `/gpio/switch` -* `channel=...` - The GPIO driver channel. -* `state=1|0` - The new switch state. -* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation. +**Description**: Sets a GPIO channel to a specific state (on/off). +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `channel` | string | required | The GPIO driver channel | Alphanumeric channel name, e.g., `__v3_usb_breaker__` | +| `state` | boolean | required | The new switch state | `1` to switch on, `0` to switch off | +| `wait` | boolean | optional | Defines when a call should return | `1` return immediately, `0` return after finishing operation | + +**Example of use**: + +```console +# Switch GPIO channel led1 to OFF state without waiting +$ curl -k -X POST \ + -u admin:admin \ + https:///api/gpio/switch?channel=led1&state=0&wait=0 +``` + +??? note "Example output" + ``` json + { + "ok": true, + "result": {} + }⏎ + ``` ### Pulse GPIO channel -The `POST /api/gpio/pulse` handle interacts with selected GPIO driver channel in `pulse` mode. +**Method**: `POST` -Parameters: +**Route**: `/api/gpio/pulse` -* `channel=...` - The GPIO driver channel. -* `delay=N.N` *(optional)* - The pulse time in seconds (float), `0` for default delay. -* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation. +**Description**: Sends a pulse signal to a GPIO channel (briefly activates then deactivates). Only works for channels that support the pulse mode. +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `channel` | string | required | The GPIO driver channel | Alphanumeric channel name, e.g., `led1` | +| `delay` | float | optional | The pulse time in seconds | Any float number, `0` for default delay | +| `wait` | boolean | optional | Defines when a call should return | `1` return immediately, `0` return after finishing operation | + +**Example of use**: + +```console +# Send a pulse to GPIO channel led1 with 2 sec delay without waiting +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/gpio/pulse?channel=led1&delay=2.0&wait=0' +``` + +??? note "Example output" + ``` json + { + "ok": true, + "result": {} + }⏎ + ``` + +---- +## Streamer + +The PiKVM Streamer API provides remote access to video stream capture and management functionality of PiKVM devices. It allows users perform the following operations: + +- Capture screenshots. +- Perform optical character recognition (OCR) on captured images. +- Monitor the streamer's operational status. + +### Get streamer state + +**Method**: `GET` + +**Route**: `/api/streamer` + +**Description**: Retrieves the current state of the streamer. + +**Query parameters**: None + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/streamer +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": { + "features": { + "h264": true, + "quality": true, + "resolution": false + }, + "limits": { + "desired_fps": { + "max": 70, + "min": 0 + }, + "h264_bitrate": { + "max": 20000, + "min": 25 + }, + "h264_gop": { + "max": 60, + "min": 0 + } + }, + "params": { + "desired_fps": 40, + "h264_bitrate": 5000, + "h264_gop": 30, + "quality": 80 + }, + "snapshot": { + "saved": null + }, + "streamer": { + "encoder": { + "quality": 80, + "type": "M2M-IMAGE" + }, + "h264": { + "bitrate": 5000, + "fps": 60, + "gop": 30, + "online": true + }, + "instance_id": "", + "sinks": { + "h264": { + "has_clients": true + }, + "jpeg": { + "has_clients": false + } + }, + "source": { + "captured_fps": 59, + "desired_fps": 40, + "online": true, + "resolution": { + "height": 720, + "width": 1280 + } + }, + "stream": { + "clients": 0, + "clients_stat": {}, + "queued_fps": 0 + } + } + } + }⏎ + ``` + +### Take snapshot + +**Method**: `GET` + +**Route**: `/api/streamer/snapshot` + +**Description**: Captures a snapshot from the video stream. Can optionally perform OCR text recognition or generate a preview image. For optical character recognition, the coordinates origin starts at top left. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `save` | boolean | optional | Whether to save the snapshot, default: `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `load` | boolean | optional | Whether to load an existing snapshot, default: `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `allow_offline` | boolean | optional | Whether to allow taking snapshots when offline, default: `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `ocr` | boolean | optional | Whether to perform OCR text recognition on the snapshot, default: `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `ocr_langs` | string | optional | Comma-separated list of language codes for OCR recognition | Typically, a 3-letter code, such as `eng` for English or `deu` for German. Run `pacman -Ss tesseract-data` on PiKVM to get the full list | +| `ocr_left` | integer | optional | X coordinate of the top left corner of the OCR region, default: `-1` | `≥0` | +| `ocr_top` | integer | optional | Y coordinate of the top left corner of the OCR region, default: `-1` | `≥0` | +| `ocr_right` | integer | optional | Width of the OCR region, default: `-1` | `≥0` | +| `ocr_bottom` | integer | optional | Height of the OCR region, default: `-1` | `≥0` | +| `preview` | boolean | optional | Whether to generate a preview image, default: `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `preview_max_width` | integer | optional | Maximum width for preview image, default: `0` | Any positive integer value | +| `preview_max_height` | integer | optional | Maximum height for preview image, default: `0` | Any positive integer value | +| `preview_quality` | integer | optional | JPEG quality for preview (valid stream quality value), default: `80` | Any integer value in the 0..100 range | + +**Example of use**: the following command will capture a snapshot of the current video stream and save it to a JPEG file. + +```console +$ curl -k \ + -u admin:admin \ + 'https:///api/streamer/snapshot?save=1&preview_quality=95' \ + --output=file.jpg +``` + +??? note "Example output" + ```console + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 107k 100 107k 0 0 619k 0 --:--:-- --:--:-- --:--:-- 619k + ``` + +**Example of use**: the following command will capture a region of the current video stream (left corner starts at the top left, extends 1000px to the right and 150px to the bottom), run it through Tesseract for optical character recognition (language defined as English), and output the recognized text into the console. + +```console +$ curl -k \ + -u admin:admin \ + 'https:///api/streamer/snapshot?ocr=true&ocr_left=0&ocr_top=0&ocr_right=1000&ocr_bottom=150&ocr_langs=eng' +``` + +**Responses**: + +- When `ocr=true`: + - Content-Type: `text/plain` + - Body: Recognized text from the image +- When `preview=true` or default: + - Content-Type: `image/jpeg` + - Body: JPEG image data (either preview or full snapshot) +- When snapshot unavailable: + - Status: 503 Service Unavailable + - Error: UnavailableError + +### Remove snapshot + +**Method**: `DELETE` + +**Route**: `/api/streamer/snapshot` + +**Description**: Removes/deletes the current snapshot from memory. + +**Query parameters**: None + +**Example of use**: + +```console +$ curl -k -X DELETE \ + -u admin:admin \ + https:///api/streamer/snapshot +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": {} + }⏎ + ``` + +### Get OCR state + +**Method**: GET + +**Route**: `/api/streamer/ocr` + +**Description**: Retrieves the current state and configuration of the optical character recognition (OCR) service. + +**Query parameters**: None + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/streamer/ocr +``` + +??? note "Example output" + ```json + { + "ok": true, + "result": { + "ocr": { + "enabled": true, + "langs": { + "available": [ + "eng", + "osd" + ], + "default": [ + "eng" + ] + } + } + } + }⏎ + ``` + +---- +## Switch + +The PiKVM Switch API provides handles to control the [PiKVM Switch](switch.md): get information, set active ports, and control beacons. + +The API heavily relies on specifying ports on the PiKVM Switch. There are two ways to do that: with continuous numbering or with float numbers. Both options are equally valid and supported. + +1. With continuous numbering, ports enumeration starts at 0 and ends at 19, because you can create up to 20 ports by adding more PiKVM Switch devices to the first Switch's downlink. +2. If you use a float value, the integer part specifies the number of the unit in the downlink, while the fractional part specifies the number of the port on that unit. + +### Get Switch state + +**Method**: `GET` + +**Route**: `/api/switch` + +**Description**: Returns the information about the PiKVM Switch state. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/switch +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set active port (previous) + +**Method**: `POST` + +**Route**: `/api/switch/set_active_prev` + +**Description**: Switches to the previous active port. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/switch/set_active_prev +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set active port (next) + +**Method**: `POST` + +**Route**: `/api/switch/set_active_next` + +**Description**: Switches to the next active port. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/switch/set_active_next +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set active port (specific) + +**Method**: `POST` + +**Route**: `/api/switch/set_active` + +**Description**: Switches to a specific port. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `port` | float | required | Specifies the port number | Integer in the 0..19 range or float (0,0 through 4,3) | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/switch/set_active?port=2,2 +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set beacon + +**Method**: `POST` + +**Route**: `/api/switch/set_beacon` + +**Description**: Controls beacon lights on ports or uplink/downlink units. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `state` | boolean | required | Turn beacon on/off | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `port` | float | optional | Specify the port beacon | Integer in the 0..19 range or float (0,0 through 4,3) | +| `uplink` | integer | optional | Number of the uplink beacon, same as the port | Integer in the 0..19 range or float (0,0 through 4,3) | +| `downlink` | integer | optional | Number of the downlink beacon, same as the port | Integer in the 0..19 range or float (0,0 through 4,3) | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/switch/set_beacon +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set port parameters + +**Method**: `POST` + +**Route**: `/api/switch/set_port_params` + +**Description**: Configures parameters for a specific port. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `port` | float | required | Specifies the port number | `0..19` | +| `edid_id` | string | optional | EDID identifier (allows default value) | Alphanumeric string like `ca3d7114-79ca-47fc-80b4-b80ac63fc329` | +| `dummy` | boolean | optional | When enabled, the switch will pretend the host has a display attached | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | +| `name` | string | optional | String port name, none set by default | Any combination of ASCII letters and numbers | +| `atx_click_power_delay` | float | optional | ATX power click delay value | `0..10` | +| `atx_click_power_long_delay` | float | optional | ATX long power click delay value | `0..10` | +| `atx_click_reset_delay` | float | optional | ATX reset click delay value | `0..10` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/set_port_params?port=2&name=PORT3' +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Set beacon color + +**Method**: `POST` + +**Route**: `/api/switch/set_colors` + +**Description**: Sets the beacon color for the PiKVM Switch and all switches in the downlink (where applicable). + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `beacon` | hex | required | Sets color, brightness, and blink interval (ms) | A valid hex value (see example below) | + +**Example of use**: Let's set the beacon to be orange at 75% of full brightness, blinking with an interval of 40ms. + +```console +$ curl -k -X POST \ + -u admin:admin \ + -d "FFA500:BF:0028" \ + https:///api/switch/set_colors +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Reboot the device + +**Method**: `POST` + +**Route**: `/api/switch/reset` + +**Description**: Reboots the PiKVM Switch with an option to enter the reflashing mode after the reboot. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `unit` | integer | required | Specifies the unit number | `0..4` | +| `bootloader` | boolean | optional | Whether to enter the reflashing mode after rebooting, defaults to `false` | Enable: `1`, `true`, or `yes`. Disable: `0`, `false`, or `no` | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/reset?unit=0&bootloader=1' +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Create a new EDID configuration + +**Method**: `POST` + +**Route**: `/api/switch/edids/create` + +**Description**: Creates a new EDID configuration from user-specified EDID name and data. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `name` | string | required | EDID name | Alphanumeric name (see example below) | +| `data` | string | required | EDID data | Hexadecimal string (see example below) | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/edids/create?name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045' +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Change EDID configuration + +**Method**: `POST` + +**Route**: `/api/switch/edids/change` + +**Description**: Modifies an existing EDID configuration. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `id` | string | required | EDID identifier | Alphanumeric id (see example below) | +| `name` | string | optional | New EDID name | Alphanumeric name (see example below) | +| `data` | string | optional | New EDID data | Hexadecimal string (see example below) | + + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/edids/change?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329&name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045' +``` + +??? note "Example output" + ```json + FIXME + ``` + +### Remove EDID configuration + +**Method**: `POST` + +**Route**: `/api/switch/edids/remove` + +**Description**: Deletes an EDID configuration. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `id` | string | required | EDID identifier | Alphanumeric id (see example below) | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + https:///api/switch/edids/remove?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329 +``` + +??? note "Example output" + ```json + FIXME + ``` + +### ATX Power Control + +**Method**: `POST` + +**Route**: `/api/switch/atx/power` + +**Description**: Controls ATX power states for a specific port. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `port` | float | required | Specifies the port number | 0..19 | +| `action` | string | required | Power action | `on` - Power on, `off` - Power off, `off_hard` - Hard power off, `reset_hard` - Hard reset | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/atx/power?port=0&action=reset_hard' +``` + +??? note "Example output" + ```json + FIXME + ``` + +### ATX Button Click + +**Method**: `POST` + +**Route**: `/api/switch/atx/click` + +**Description**: Simulates ATX button clicks for a specific port. + +**Query parameters**: + +| Parameter | Type | Optionality | Description | Acceptable values | +|-----------|------|-------------|-------------|-------------------| +| `port` | float | required | Specifies the port number | `0..19` | +| `button` | string | required | Power action | `power` - Power button click, `power_long` - Long power button press, `reset` - Reset button click | + +**Example of use**: + +```console +$ curl -k -X POST \ + -u admin:admin \ + 'https:///api/switch/atx/click?port=0&button=power_long' +``` + +??? note "Example output" + ```json + FIXME + ``` + +---- +## Redfish + +The PiKVM Redfish API implements the industry-standard [DMTF Redfish specification](https://www.dmtf.org/standards/redfish) for remote server control. It allows you to monitor and control the power of the target system. + +Most endpoints require authentication using your PiKVM credentials. You can interact with the API using standard HTTP clients, `curl`, or the [specialized Redfish tools](https://github.com/DMTF/Redfishtool). + +### Root service discovery + +**Method**: `GET` + +**Route**: `/api/redfish/v1` + +**Description**: Returns the basic Redfish service information and links to available resources. Doesn't require authentication. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k https:///api/redfish/v1 +``` + +??? note "Example output" + ```json + { + "@odata.id": "/redfish/v1", + "@odata.type": "#ServiceRoot.v1_6_0.ServiceRoot", + "Id": "RootService", + "Name": "Root Service", + "RedfishVersion": "1.6.0", + "Systems": { + "@odata.id": "/redfish/v1/Systems" + } + }⏎ + ``` + +### Systems collection + +**Method**: `GET` + +**Route**: `/api/redfish/v1/Systems` + +**Description**: Returns collection of available computer systems. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/redfish/v1/Systems +``` + +??? note "Example output" + ```json + { + "@odata.id": "/redfish/v1/Systems", + "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", + "Members": [ + { + "@odata.id": "/redfish/v1/Systems/0" + } + ], + "Members@odata.count": 1, + "Name": "Computer System Collection" + }⏎ + ``` + +### Individual system information + +**Method**: `GET` + +**Route**: `/api/redfish/v1/Systems/0` + +**Description**: Returns detailed information about the specific system, including power state, hostname, and available actions. + +**Query parameters**: None. + +**Example of use**: + +```console +$ curl -k -u admin:admin https:///api/redfish/v1/Systems/0 +``` + +??? note "Example output" + ```json + { + "@odata.id": "/redfish/v1/Systems/0", + "@odata.type": "#ComputerSystem.v1_10_0.ComputerSystem", + "Actions": { + "#ComputerSystem.Reset": { + "ResetType@Redfish.AllowableValues": [ + "On", + "ForceOff", + "GracefulShutdown", + "ForceRestart", + "ForceOn", + "PushPowerButton" + ], + "target": "/redfish/v1/Systems/0/Actions/ComputerSystem.Reset" + }, + "#ComputerSystem.SetDefaultBootOrder": { + "target": "/redfish/v1/Systems/0/Actions/ComputerSystem.SetDefaultBootOrder" + } + }, + "Boot": { + "BootSourceOverrideEnabled": "Disabled", + "BootSourceOverrideTarget": null + }, + "HostName": "pikvm", + "Id": "0", + "PowerState": "Off" + }⏎ + ``` + +### System configuration update + +**Method**: `PATCH` + +**Route**: `/api/redfish/v1/Systems/0` + +**Description**: This handle was added to aid in scenarios where installing OKD (Kubernetes) using installer-provisioned infrastructure involves expecting two fields to be returned and the patch request to return a 204. Hence, this handle is currently a no-op that just returns success. + +**Query parameters**: None + +**Example of use**: + +```console +$ curl -k -X PATCH -u admin:admin https:///api/redfish/v1/Systems/0 +``` + +There will be zero output for this command by design. + +**Responses**: + +| Code | Description | +|------|-------------| +| 204 | Returns success | + +### System power control + +**Method**: `POST` + +**Route**: `/api/redfish/v1/Systems/0/Actions/ComputerSystem.Reset` + +**Description**: Performs power control actions on the system. + +**Query parameters**: This handles expects JSON with `ResetType` in the request body and one of the following values: + +- `On` - Power on +- `ForceOff` - Hard power off +- `GracefulShutdown` - Graceful power off +- `ForceRestart` - Hard reset +- `ForceOn` - Force power on +- `PushPowerButton` - Simulate power button press + +**Example of use**: + +```console +$ curl -k -X POST \ + -H "Content-Type: application/json" \ + -u admin:admin \ + -d '{"ResetType": "ForceRestart"}' \ + https:///api/redfish/v1/Systems/0/Actions/ComputerSystem.Reset +``` + +There will be zero output for this command by design. + +**Responses**: + +| Code | Description | +|------|-------------| +| 204 | Success | +| 400 | Invalid or missing ResetType | ---- ## Misc @@ -463,11 +1926,6 @@ Parameters: The `GET /api/export/prometheus/metrics` handle returns the Prometheus metrics. Also see [here](prometheus.md) for details. -``` +```console $ curl -k -u admin:admin https:///api/export/prometheus/metrics -``` - ------ -# To be continued ===> - -You can find all existing APIs in the [KVMD source tree](https://github.com/pikvm/kvmd/tree/master/kvmd/apps/kvmd/api). We would appreciate your help with documentation. +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 0c3b2ff6..4bee8625 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,7 @@ theme: - search.highlight - search.share - search.suggest + - content.code.copy extra_css: - _assets/user.css