public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cleanup, part 3 of N: 

- Standardize the markup for code blocks and CLI commands
- Enable the 'copy code' button in the theme
This commit is contained in:
Aleksandr Prokudin 2025-06-23 17:48:55 +02:00
parent 19b613034e
commit 7a3161ebdd
1 changed files with 120 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
docs/api.md
View File

@ -58,7 +58,7 @@ 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://<pikvm-ip>/api/auth/check
```
@ -66,7 +66,7 @@ There are two options here:
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=/
@ -88,7 +88,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://<pikvm-ip>/api/ws?stream=0 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin
```
@ -149,7 +149,7 @@ Another type of event is `ping`, which can be sent by the client: `{"event_type"
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/info?fields=hw
```
@ -228,7 +228,7 @@ Each category is represented by its own event in the websocket (`info_hw_state`,
**Example of use**: the following query returns commit messages for the last 1 hour and enables the long-polling mode:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/log?follow=1&seek=3600
```
@ -259,7 +259,7 @@ The PiKVM HID (Human Interface Device) API provides remote control capabilities
**Method**: `GET`
**Route**: `/hid`
**Route**: `/api/hid`
**Description**: Gets the current HID devices state.
@ -267,7 +267,7 @@ The PiKVM HID (Human Interface Device) API provides remote control capabilities
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/hid
```
@ -324,7 +324,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid
**Method**: `POST`
**Route**: `/hid/set_params`
**Route**: `/api/hid/set_params`
**Description**: Configures HID device parameters, such as the type of emulated keyboard and mouse.
@ -338,7 +338,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/set_params?jiggler=0
@ -364,7 +364,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/set_connected`
**Route**: `/api/hid/set_connected`
**Description**: Sets the HID devices connection state.
@ -376,7 +376,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/set_connected?connected=0
@ -402,7 +402,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/reset`
**Route**: `/api/hid/reset`
**Description**: Resets HID devices to their initial state.
@ -410,7 +410,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/reset
```
@ -434,7 +434,7 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/reset
**Method**: `GET`
**Route**: `/hid/keymaps`
**Route**: `/api/hid/keymaps`
**Description**: Gets available keyboard layouts and the current defaults.
@ -442,7 +442,7 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/reset
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/hid/keymaps
```
@ -508,7 +508,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid/keymaps
**Method**: `POST`
**Route**: `/hid/print`
**Route**: `/api/hid/print`
**Description**: Transmits user-defined text to emulate typing it on the PiKVM by sequencing key presses.
@ -522,7 +522,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid/keymaps
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
-d "Einige Worte" \
@ -549,7 +549,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_shortcut`
**Route**: `/api/hid/events/send_shortcut`
**Description**: Sends a keyboard shortcut, or key combination, to be typed on the PiKVM.
@ -561,7 +561,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_shortcut?keys=ControlLeft,KeyL
@ -587,7 +587,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_key`
**Route**: `/api/hid/events/send_key`
**Description**: Transmits a command to emulate a single key press on the PiKVM.
@ -601,7 +601,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_key?key=Delete
@ -627,7 +627,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_mouse_button`
**Route**: `/api/hid/events/send_mouse_button`
**Description**: Sends mouse button press/release events.
@ -640,7 +640,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_mouse_button?button=left
@ -666,7 +666,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_mouse_move`
**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.
@ -679,7 +679,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_move?to_x=0&to_y=50
@ -705,7 +705,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_mouse_relative`
**Route**: `/api/hid/events/send_mouse_relative`
**Description**: Sends a command to move the mouse pointer by a relative offset in pixels.
@ -718,7 +718,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_relative?delta_x=20&delta_y=200
@ -744,7 +744,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/hid/events/send_mouse_wheel`
**Route**: `/api/hid/events/send_mouse_wheel`
**Description**: Sends mouse wheel scroll events to be emulated on the host by PiKVM.
@ -757,7 +757,7 @@ $ curl -k -X POST \
**Example of use**: Sends mouse wheel scroll events.
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_wheel?delta_x=0&delta_y=200
@ -800,7 +800,7 @@ The PiKVM ATX API provides control over ATX (Advanced Technology eXtended) power
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/atx
```
@ -844,7 +844,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/atx
**Example of use**:
```sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/atx/power?action=on
@ -879,7 +879,7 @@ $ curl -k -X POST \
**Example of use**:
```sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/atx/click?button=power
@ -917,7 +917,6 @@ The `GET /api/msd` handle shows the current MSD state.
$ curl -k -u admin:admin https://<pikvm-ip>/api/msd
```
### Upload MSD image
The `POST /api/msd/write` uploads an image to MSD.
@ -935,7 +934,6 @@ $ # upload it to pikvm
$ curl -v -X POST --data-binary @test.iso -k -u admin:admin https://<pikvm-ip>/api/msd/write?image=test.iso
```
### Upload MSD image by URL
The `POST /api/msd/write_remote` handle downloads an image from HTTP(S) URL to the MSD.
@ -949,7 +947,7 @@ Parameters:
!!! note
This is a long-polling request. Do not interrupt the request until the download is complete, otherwise the download will stop.
```sh
```console
$ # create test image
$ dd if=/dev/zero of=test.iso bs=1M count=1
@ -957,7 +955,6 @@ $ # upload it to pikvm
$ curl -v -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/write_remote?url=http://example.com/test.iso
```
### Set MSD parameters
The `POST /api/msd/set_params` handle changes the current image and/or set drive parameters
@ -968,11 +965,10 @@ Parameters:
* `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`.
```
```console
$ curl -X POST -k -u admin:admin "https://<pikvm-ip>/api/msd/set_params?image=test.iso&cdrom=1"
```
### Control MSD
The `POST /api/msd/set_connected` connects or disconnect the MSD to the host.
@ -981,11 +977,10 @@ Parameters:
* `connected=1|0` - Change the state.
```
```console
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/set_connected?connected=1
```
### Remove MSD image
The `POST /api/msd/remove` handle removes the specified image.
@ -994,7 +989,7 @@ Parameters:
* `image=...` - The image name.
```
```console
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/remove?image=test.iso
```
@ -1003,7 +998,7 @@ $ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/remove?image=test.is
The `POST /api/msd/reset` handle resets the drive.
```
```console
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/reset
```
@ -1014,7 +1009,7 @@ $ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/reset
The `GET /api/gpio` handle shows the current GPIO state.
```
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/gpio
```
@ -1053,7 +1048,7 @@ The PiKVM Streamer API provides remote access to video stream capture and manage
**Method**: `GET`
**Route**: `/streamer`
**Route**: `/api/streamer`
**Description**: Retrieves the current state of the streamer.
@ -1061,7 +1056,7 @@ The PiKVM Streamer API provides remote access to video stream capture and manage
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/streamer
```
@ -1115,7 +1110,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/streamer
**Method**: `GET`
**Route**: `/streamer/snapshot`
**Route**: `/api/streamer/snapshot`
**Description**: Captures a snapshot from the video stream. Can optionally perform OCR text recognition or generate a preview image.
@ -1139,7 +1134,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/streamer
**Example of use**:
``` sh
```console
$ curl -k \
-u admin:admin \
https://<pikvm-ip>/api/streamer/snapshot?save=1&preview_quality=95
@ -1166,7 +1161,7 @@ $ curl -k \
**Method**: `DELETE`
**Route**: `/streamer/snapshot`
**Route**: `/api/streamer/snapshot`
**Description**: Removes/deletes the current snapshot from memory.
@ -1174,7 +1169,7 @@ $ curl -k \
**Example of use**:
``` sh
```console
$ curl -k -X DELETE \
-u admin:admin \
https://<pikvm-ip>/api/streamer/snapshot
@ -1200,7 +1195,7 @@ $ curl -k -X DELETE \
**Method**: GET
**Route**: /streamer/ocr
**Route**: `/api/streamer/ocr`
**Description**: Retrieves the current state and configuration of the optical character recognition (OCR) service.
@ -1208,7 +1203,7 @@ $ curl -k -X DELETE \
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/streamer/ocr
```
@ -1239,7 +1234,7 @@ The API heavily relies on specifying ports on the PiKVM Switch. There are two wa
**Method**: `GET`
**Route**: `/switch`
**Route**: `/api/switch`
**Description**: Returns the information about the PiKVM Switch state.
@ -1247,7 +1242,7 @@ The API heavily relies on specifying ports on the PiKVM Switch. There are two wa
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/switch
```
@ -1268,7 +1263,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/switch
**Method**: `POST`
**Route**: `/switch/set_active_prev`
**Route**: `/api/switch/set_active_prev`
**Description**: Switches to the previous active port.
@ -1276,7 +1271,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/switch
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/set_active_prev
@ -1299,7 +1294,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/set_active_next`
**Route**: `/api/switch/set_active_next`
**Description**: Switches to the next active port.
@ -1307,7 +1302,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/set_active_next
@ -1330,7 +1325,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/set_active`
**Route**: `/api/switch/set_active`
**Description**: Switches to a specific port.
@ -1342,7 +1337,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/set_active?port=2,2
@ -1365,7 +1360,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/set_beacon`
**Route**: `/api/switch/set_beacon`
**Description**: Controls beacon lights on ports or uplink/downlink units.
@ -1380,7 +1375,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/set_beacon
@ -1403,7 +1398,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/set_port_params`
**Route**: `/api/switch/set_port_params`
**Description**: Configures parameters for a specific port.
@ -1421,7 +1416,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/set_port_params?port=2&name=PORT3
@ -1444,7 +1439,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/set_colors`
**Route**: `/api/switch/set_colors`
**Description**: Sets the beacon color for the PiKVM Switch and all switches in the downlink (where applicable).
@ -1456,7 +1451,7 @@ $ curl -k -X POST \
**Example of use**: Let's set the beacon to be orange at 75% of full brightness, blinking with an interval of 40ms.
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
-d "FFA500:BF:0028" \
@ -1480,7 +1475,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/reset`
**Route**: `/api/switch/reset`
**Description**: Reboots the PiKVM Switch with an option to enter the reflashing mode after the reboot.
@ -1493,7 +1488,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/reset?unit=0&bootloader=1
@ -1516,7 +1511,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/edids/create`
**Route**: `/api/switch/edids/create`
**Description**: Creates a new EDID configuration from user-specified EDID name and data.
@ -1529,7 +1524,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/edids/create?name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045
@ -1552,7 +1547,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/edids/change`
**Route**: `/api/switch/edids/change`
**Description**: Modifies an existing EDID configuration.
@ -1567,7 +1562,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/edids/change?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329&name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045
@ -1590,7 +1585,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/edids/remove`
**Route**: `/api/switch/edids/remove`
**Description**: Deletes an EDID configuration.
@ -1602,7 +1597,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/edids/remove?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329
@ -1625,7 +1620,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/atx/power`
**Route**: `/api/switch/atx/power`
**Description**: Controls ATX power states for a specific port.
@ -1638,7 +1633,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/atx/power?port=0&action=reset_hard
@ -1661,7 +1656,7 @@ $ curl -k -X POST \
**Method**: `POST`
**Route**: `/switch/atx/click`
**Route**: `/api/switch/atx/click`
**Description**: Simulates ATX button clicks for a specific port.
@ -1674,7 +1669,7 @@ $ curl -k -X POST \
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/switch/atx/click?port=0&button=power_long
@ -1704,7 +1699,7 @@ Most endpoints require authentication using your PiKVM credentials. You can inte
**Method**: `GET`
**Route**: `/redfish/v1`
**Route**: `/api/redfish/v1`
**Description**: Returns the basic Redfish service information and links to available resources. Doesn't require authentication.
@ -1712,7 +1707,7 @@ Most endpoints require authentication using your PiKVM credentials. You can inte
**Example of use**:
``` sh
```console
$ curl -k https://<pikvm-ip>/api/redfish/v1
```
@ -1733,7 +1728,7 @@ $ curl -k https://<pikvm-ip>/api/redfish/v1
**Method**: `GET`
**Route**: `/redfish/v1/Systems`
**Route**: `/api/redfish/v1/Systems`
**Description**: Returns collection of available computer systems.
@ -1741,7 +1736,7 @@ $ curl -k https://<pikvm-ip>/api/redfish/v1
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems
```
@ -1762,7 +1757,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems
**Method**: `GET`
**Route**: `/redfish/v1/Systems/0`
**Route**: `/api/redfish/v1/Systems/0`
**Description**: Returns detailed information about the specific system, including power state, hostname, and available actions.
@ -1770,7 +1765,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems
**Example of use**:
``` sh
```console
$ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
```
@ -1791,7 +1786,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
**Method**: `PATCH`
**Route**: `/redfish/v1/Systems/0`
**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.
@ -1799,7 +1794,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
**Example of use**:
``` sh
```console
$ curl -k -X PATCH -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
```
@ -1818,7 +1813,7 @@ $ curl -k -X PATCH -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
**Method**: `POST`
**Route**: `/redfish/v1/Systems/0/Actions/ComputerSystem.Reset`
**Route**: `/api/redfish/v1/Systems/0/Actions/ComputerSystem.Reset`
**Description**: Performs power control actions on the system.
@ -1833,7 +1828,7 @@ $ curl -k -X PATCH -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0
**Example of use**:
``` sh
```console
$ curl -k -X POST \
-H "Content-Type: application/json" \
-u admin:admin \
@ -1860,11 +1855,6 @@ $ curl -k -X POST \
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://<pikvm-ip>/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.