The API
Everything the page does, it does through this interface, and so can any other program: a script, a monitoring system, a program of its own that shows a wall. The paths are under /api/v1/, and the v1 is the version of the interface. Within v1, requests and fields are added and none is taken away or given another meaning; a change that would break a program written against it gets a path of its own (/api/v2/) beside this one. GET /healthz says which versions a qKVM speaks ("api"). What this chapter lists is promised that way; the other requests under /api/v1/ are the page's own and change with it (they are named at the end). A client takes what it knows from an answer and leaves the rest: a field or a word it has not met is one that was added since.
Who may
Three roles, each including the ones below it: admin, operator, viewer. Three ways in:
- A person, with an account:
POST /api/v1/login, which answers with the cookieqkvm_session(HttpOnly, SameSite=Strict, Secure over HTTPS), to be sent with every request. Every request that changes something (anything but GET) then has to carry the headerX-QKVM: 1, and noOriginof another host; without it: 403forbidden. - A script, with a token an admin made (see above):
Authorization: Bearer qkvm_...with every request, no cookie and noX-QKVMheader. It is a viewer or an operator, never an admin, and has no account of its own to change or to sign out of. - A wall screen, with its link:
POST /api/v1/displaywith the key behind#key=, which answers with the cookie of a viewer that is not a person ("token": true).
Bodies are JSON with a Content-Length (sent chunked: 411 length_required), at most 64 KiB (413 too_large), except the two that carry a file. A field that is wrong is answered 422 invalid, and the message names the field and the rule, never the value. A field the request does not need is left out.
Errors
Every refusal is {"code": "...", "message": "..."} with a status that fits. code is one word, for a program; message is a sentence fit to show to a person. Every code the wall answers with is listed in words.json (see Clients and versions) with the statuses it comes with; the ones the requests below answer:
| Status | Codes | Whose fault |
|---|---|---|
| 400, 408 | disconnected (the body was not sent in full), timeout (it took too long to arrive) | the request |
| 401 | unauthorized (sign in first; in the middle of things: the session ended, sign in again and do not loop), bad_password, bad_code, code_required, bad_key, bad_recovery | the session |
| 403 | forbidden (the header), not_allowed (the role, or a token), totp_required (set the second step up first), suspended, stopped (whoever asked lost the right while it was under way) | |
| 404 | not_found (also: a machine this account was not given), no_picture, no_console, no_live (no live picture of this machine) | |
| 409 | busy (something else is being done to that machine), changed, no_text, in_use, console_held, enabled, not_enabled, not_started, not_initialized, no_second_step, no_password (the account has no password here: it is signed in by the identity proxy) | the state of things |
| 411, 413 | length_required (a body sent without its length), too_large (a body over 64 KiB, or a file over what a file may be) | the request |
| 422 | invalid, name_required; for a file: not_a_file, damaged, newer, passphrase_needed, wrong_passphrase, too_large | the request |
| 429 | rate_limited, with Retry-After in seconds, which is meant; busy (too many passwords being checked at once: try again shortly) | |
| 500, 501 | internal (the details are in the wall's log); missing_driver (a JetKVM, where the Python that runs qKVM lacks the aiortc package qKVM is installed with) | the wall's |
| 502 | the device's: unreachable, dropped, auth_failed, no_password, not_set_up, cert_mismatch, cert_invalid, plain_only, another_machine (another machine answers at the address than the one the tile was added for, a PC with Intel AMT by its PlatformGUID, a server by its UUID and its controller's, or has its guest's number on its Proxmox, by the guest's SMBIOS UUID: nothing was sent; 422 from an edit), bad_response, action_failed, console_time_up | the device |
| 503 | no_stream (not yet: ask again), no_sign_in (the device answers, and does not sign qKVM in), locked (qKVM cannot open the saved passwords just now), busy (no memory to check a password with) | |
| 504 | timeout: no answer from the device | |
| 507 | not_saved: the change could not be written down (a full disk), and was taken back | the wall's disk |
After an action, unreachable and no_stream mean that nothing was sent; timeout and dropped mean that the request went out and its answer did not come, or came broken: it may have been done, so do not offer a blind retry of a power button for either. Every request may answer, beside what its row names: unauthorized, not_allowed, forbidden and totp_required (who may); invalid, too_large and length_required (the request); rate_limited and busy (429, 503) wherever a password is checked; no_password (409) wherever one's own password is asked for of an account that has none here; not_saved wherever something is written down; locked; and the device's own wherever a device is asked, in_use (409) and missing_driver (501) among them.
The requests
* marks what a request must have. "A person": not a token.
| Request | Who | Body | Answers |
|---|---|---|---|
GET /healthz | nobody | status ("ok"), version, api (the versions spoken: ["v1"]), page (a mark of the page's own files, of no use to another program), locked (true: restarted with --locked-start and nobody has signed in since, so it reaches no device). Never refuses | |
GET /api/v1/session | nobody | initialized (false: nobody has set this wall up, which is done on its page), authenticated, user (the account, below, or null), ask_name (true: more than one account, and signing in needs the name), recovery (a recovery key exists), recovery_created (to an admin: when, in seconds since 1970; otherwise null), setup_code_required, min_password, unlocks_at_start. Started with --sso-header: sso (on, name, known), and whoever the proxy signed in is signed in here by this answer, cookie included | |
POST /api/v1/login | nobody | password*, name (where ask_name), code (where asked for), remember (30 days) | ok, user, and the cookie. 401 bad_password; 401 code_required: the password was right and the account has a second step, send the same request again with code; 401 bad_code; 403 suspended; 409 not_initialized; 409 no_second_step (the key of the account's second step does not open any more: qkvm --disable-2fa where qKVM runs); 422 name_required; 429 rate_limited |
POST /api/v1/logout | viewer, a person | scope: "this" (default), "others" (the account's other sessions), "all" | ok; the cookie is cleared, except for "others". 507 not_saved: signed out all the same, and a restart may undo it |
POST /api/v1/password | viewer, a person | current, new (10 to 256 characters) | ok; the account's other sessions end. 401 bad_password; 409 no_password |
POST /api/v1/totp/begin | viewer, a person | password* | secret (the key, in groups of four), uri (otpauth://..., for a QR code), qr (that code drawn, a text per row, "1" for a dark module). 409 enabled; 401 bad_password |
POST /api/v1/totp/enable | viewer, a person | code* (from the app, for the key just shown) | ok, user, recovery_codes (ten one-time codes, shown this once); the account's other sessions end. 409 not_started; 401 bad_code |
POST /api/v1/totp/codes | viewer, a person | password* | ok, user, recovery_codes (ten new ones; the old stop working). 409 not_enabled; 401 bad_password |
POST /api/v1/totp/disable | viewer, a person | password* | ok, user. 401 bad_password |
POST /api/v1/recover | nobody | recovery_key, new_password, name (where there are several accounts) | ok; every session of that account ends. 401 bad_recovery; 409 not_initialized; 422 name_required; 429 rate_limited |
POST /api/v1/display | nobody | key* | ok, user (token true), and the cookie. 401 bad_key: the link was taken back or has run out |
GET /api/v1/about | viewer | version, licence; to an admin also what it runs on | |
GET /api/v1/wall | viewer | interval (seconds between two pictures of a tile, as set for this wall), live (the form of the live line this qKVM speaks, as a number: 2; a program that speaks another form asks for no live picture, see Live view and control), devices (the machines this account may see, each as below). Never waits for a device | |
GET /api/v1/status | viewer | by device id, how each is (below), from what is known: it waits for no device, except up to a second and a half for one's very first look | |
GET /api/v1/devices/{id}/history?what=summary&since=&until=&limit=&every= | viewer | what the wall saw of the machine, kept beside the settings (the chapter History). what: "summary" (default), "states", "samples" or "events"; since and until in seconds since 1970 (left out: the last week, for samples the last day); limit 1 to 5000 (1000 left out); every 0 to 86400: samples averaged over spans of that many seconds. A summary: since, until, first_seen, last_seen (seconds since 1970, or null), state and power ("on", "off", or null) as last seen, watched, online, answering (seconds of the window), share, answering_share (online, and answering, over watched; null where nothing was seen), changes, events (how many in the window), sensors (the names of its readings of the last day). The rest: since, until, rows (oldest first; a state t, state, code; an event t, kind ("pressed": a power button pressed from the wall, "power": a change of power state seen), what, ok (null: nobody heard how it went), note; a sample t, sensor, unit, value), more (the page was cut: narrow the window), and for samples every; with every given, series in place of rows, one per sensor: sensor, unit, points of [t, average, min, max] (a sensor whose series does not fit whole is left out). 404 not_found; 503 busy (three reads at once are answered, from everybody together, and one at a time of each account or token, whose next waits its turn for eight seconds at the most and, after a read, as long again as that read took; Retry-After says when); 503 history_unavailable (the file is being opened or replaced, or the read took too long) | |
GET /api/v1/devices/{id}/snapshot?w=640&age=1 | viewer | the screen as image/jpeg or image/png, with X-KVM-Signal 1 or 0 (0: a placeholder, the computer shows nothing) and Cache-Control: no-store. A still kept between sessions (a PC with Intel AMT whose tile is only shown) carries X-KVM-Still: 1 and X-KVM-Age: <seconds>, how old the still is. w: the width wanted, 1 to 16384 (the source's own is never exceeded); age: how old, in seconds, the frame may be (0 to 3600; viewers asking within that window share one frame). 404 not_found; 404 no_picture (a server whose controller gives none); 503 no_stream (not yet: ask again); 409 in_use (a JetKVM whose one viewer is somebody else); the device's | |
POST /api/v1/devices/{id}/live | viewer | {} | v (the form of the live line this qKVM speaks: 2), ticket (a pass for one live line to this machine, good for half a minute and for one use: 16 to 200 letters, digits, - or _; it is in no log, and is not to be kept). A viewer, a wall screen and a token may ask, and may watch; taking keyboard and mouse over the line takes an operator or an admin, by cookie or by token. 404 not_found; 404 no_live (a server whose console is not read: live is not in its can); 429 busy (this account, token or wall screen has 32 live lines open, the passes it has not used counted with them; or the wall 256 passes out: Retry-After); 503 locked |
a WebSocket at /api/v1/devices/{id}/live (GET, upgraded) | by the pass | the first message, text: {"t": "hello", "v": 2, "ticket": "...", "video": ["h264", "jpeg"], "max_w": 1920, "max_fps": 30} | the live line: the machine's picture down, keyboard and mouse up, with the messages Live view and control lists. It carries no cookie, and is asked for from the address the pass was given to. A line whose first message is not a pass this qKVM gave for this machine is told {"t": "bye", "code": "no_pass", "message": ...} and closed; one from a page of another host, or for a host this wall does not answer to, is refused 403 before anything is read |
GET /api/v1/actions | operator | actions: each id, name, kind ("keys" or "text"), keys, enter, danger, changed (how often it was edited). Never the text a saved action types | |
GET /api/v1/devices/{id}/wol | operator | targets: each mac, name (what the device calls it, which a KVM fills with the address where it has no name; empty where it has nothing). A machine without wol in can answers an empty list. 404 not_found; the device's | |
POST /api/v1/devices/{id}/actions | operator | action*, and what that one needs (the table below); batch (any id of letters, digits and "-", up to forty: ties several requests together as one act in the activity log) | ok, note (null; or "already on", "already off" for a server that was so; or "pressed, but the computer is still off", "held, but the computer is still on", "pressed; its board has not said since", "pressed; not seen: its connection ended" (the tile was edited or removed, or the wall locked itself; and "held; ..." of the same) for a KVM's power button whose change its board did not show: it was pressed). 404 not_found (also: the saved action is gone); 409 busy (with by, the name of whoever has the machine's keyboard and mouse over a live line, where that is why: an account's, or a token's with "(token)"; to an admin in person the message adds that they can take them over in the live view: an action never takes over by itself); 409 conflict (it waited for the last holder of the keyboard to be let go of, and meanwhile the tile was changed or taken off the wall: nothing was sent); 409 changed (the saved action was edited since it was listed); 409 no_text; 403 not_allowed (a token and a saved text); 403 stopped; 422 invalid (also: an action this machine cannot do); 502 action_failed (the device refused); 504 timeout and 502 dropped (it may have been done); the device's. Every action is written to the activity log with the account |
POST /api/v1/devices/{id}/console | operator, a person | {} | url: a way into a server's own console, signed in, good for one use, for the browser of whoever asked; it is in no log, and is not to be kept. 403 not_allowed (a token); 404 not_found; 404 no_console (no such way in from this device); the device's |
PUT /api/v1/wall/order | admin | ids* (device ids, first to last; the rest keep their order after them) | ok, ids (the whole order, as it is now, for every browser). 507 not_saved |
POST /api/v1/devices/remove | admin | ids* (1 to 5000 device ids, within the 64 KiB a body may have; one given twice is one machine) | takes every one of them off the wall, or none: ok, removed (their ids, in the wall's order). Each one's saved password and history go with it, and each gets a line of its own in the activity log (device_removed), as one removed on its own does. An action on its way to one of them is answered as one cut off by an edit of the tile (it may have been done), and a live line to one is told gone, the keys it held let go of first. 404 not_found with unknown (the ids that are not on the wall: nothing was removed); 507 not_saved (nothing was removed, and nothing on them was cut off) |
GET /api/v1/tokens | admin | tokens: each id, name, kind ("api" or "display"), role, devices (ids, or null for all), groups, created, expires (null: never), used (null: not yet). Never the token itself | |
POST /api/v1/tokens | admin | name*, kind ("api" default, "display"), role ("viewer" default, "operator"; never admin), devices, groups, days (1 to 3650; left out: until taken back) | 201 token (shown this once), record (as listed). 507 not_saved |
DELETE /api/v1/tokens/{id} | admin | ok; a screen showing with it goes dark. 404 not_found | |
POST /api/v1/export | admin, a person | password* (the account's own, again), parts* (of "devices", "actions", "alerts", "wall"), passphrase (10 characters or more: an encrypted file with the passwords in it; empty: a plain file without them) | the file as application/json with a Content-Disposition name (qkvm-<date>.qkvm or .json), and the header X-QKVM-Not-Opened: how many saved passwords or texts are not in it because they do not open any more. 401 bad_password; 422 invalid, too_large (more in the wall than a file holds); 503 locked |
POST /api/v1/import/read | admin, a person | file* (its text), passphrase (of an encrypted one) | what the file holds, changing nothing: encrypted, secrets (a plain file with passwords in it), made (seconds since 1970, 0 where it does not say), program (the version that wrote it), devices (null where the file has no such part; else each name, host, kind, group, password (whether one is in the file), tls, open_url, new (this wall would take it), same_as (the name of the tile here that is the same device, or empty)), actions (null, or each name, kind, keys, text (of the new ones; what a button will type is read before it is taken), enter, danger, new), alerts (null, or enabled, address (the file names one), host (of that address), format, kinds), wall (null, or interval, update_check), left_out (a sentence for each entry that did not pass). 422 not_a_file, damaged, newer, passphrase_needed, wrong_passphrase, too_large |
POST /api/v1/import | admin, a person | file*, passphrase, take (which parts, of the four; left out: the file is read and nothing is taken) | what was taken: devices, actions (how many were added), alerts, wall (whether they were replaced), left_out. 422 not_a_file, damaged, newer, passphrase_needed, wrong_passphrase, too_large; 503 locked; 507 not_saved |
A machine, as the wall lists it
In devices of GET /api/v1/wall:
| Field | Is |
|---|---|
id | eight hexadecimal digits: what every other request names the machine by |
name, host, group | as shown on its tile; host is the name or address and port the wall talks to |
kind | kvmd (GL.iNet Comet, PiKVM and alike), jetkvm, redfish (a server's controller), amt (a business PC's Intel AMT engine), vnc (a VNC server), proxmox (a virtual machine on Proxmox VE) |
picture | false: a server, whose tile shows how it is doing where a KVM's shows a screen (it may still have a picture: screen in can) |
open_url | where a browser reaches the machine's own page |
same_as | other tiles that are the same machine under another address: each id, name, host |
can | what this tile can be asked, as words (below) |
| to an admin only | url, custom_open_url, username, tls (pinned, system, insecure), fingerprint, has_password, alerts, fingerbot_strength (how hard a Fingerbot paired with the KVM presses: firm or light). The password is never sent to anybody |
can says what this machine can be asked: from its driver, and from what the wall last found at the device (a power board, several inputs, a light). It is in the wall's answer and in the status, and the status's is the fresher: a client that acts goes by that one, and by the wall's until there is a status. No client has to guess it from the kind of device, and none should: a server whose controller is not AMI's has a power button and no keyboard, and a KVM without a power board has no power button either. Each word opens these requests:
| Word | Opens |
|---|---|
screen | a picture: GET .../snapshot (a server: as long as its controller is not known to give none, which asking finds out; a PC with Intel AMT: where its KVM may be used; a virtual machine on Proxmox: while it runs; the status's screen says the same) |
keys | keys, ctrl_alt_del, and a saved action that presses keys (a server: once its console is known to be AMI's, and while nobody at the controller's own console has it) |
text | text, and a saved action that types |
jiggler | jiggler_on, jiggler_off |
power | the power button: atx_power, atx_power_long (a KVM with a power board; a server; a virtual machine on Proxmox, where holding it stops the machine at once) |
reset | the reset button: atx_reset |
fingerbot | the power button pressed by a Fingerbot paired with the KVM: fingerbot_power, fingerbot_power_long (beside power, where the KVM has a power board as well) |
power_state | switching on, or asking to shut down, by what is wanted: power_on, power_off (a server, which knows whether it is on; a PC with Intel AMT; a virtual machine on Proxmox) |
bios_setup | bios_setup: start into the BIOS setup once, then switch on or restart (a PC with Intel AMT whose engine offers it; a server over Redfish whose controller allows the "BiosSetup" boot override); one machine at a time, not a bulk run |
wol | wol, and GET .../wol for what the KVM has saved to wake |
ports | port (the status's ports says which inputs there are and which is on screen) |
reboot | reboot: the KVM itself, or a server's controller |
resume | resume: a JetKVM that stepped aside for whoever opened its own page is taken up again |
locator | locate_on, locate_off: a server's light to find it by |
console | POST .../console: a signed-in way into a server's own console |
live | the live picture: POST .../live for a pass, then the WebSocket at the same path (a KVM; a server whose console the wall reads, once that is known; a PC with Intel AMT whose KVM may be used; a virtual machine on Proxmox while it runs) |
control | keyboard and mouse over that line: control with on true, and with take true to take them over (an admin in person) (a KVM; a PC with Intel AMT; a virtual machine on Proxmox; a server whose console is AMI's, as keys; not an OpenBMC console, which answers no_input) |
A word not in this list was added since: a client leaves out what it does not know. And can is what the wall would send, not a promise that the machine takes it: a controller set up without a reset of that kind still answers 502 action_failed.
How a machine is
In GET /api/v1/status, by id. Any value may be null: a device that does not say is not guessed at.
| Field | Is |
|---|---|
can | as above, as of this look |
state | online, no_signal (there, and its computer shows nothing; a server: switched off), offline, auth (it refuses the saved password), error (its certificate changed, it does not sign qKVM in, a server reports a critical fault, and the like: error.code says which), busy (a JetKVM whose one viewer is somebody else), connecting (nothing known yet) |
error | null, or code and message (the message fit to show) |
last_seen_ago | seconds since the device last answered; null: never |
video | signal (true or false), width, height, fps |
usb | keyboard, mouse: whether the computer sees them |
atx | enabled (a power board, or a server), power (the computer is on; asleep counts as on; null where the board does not say, at this look), hdd |
fingerbot | a KVM's: null, or, where a Fingerbot is paired with it, battery (percent; null until it was asked, which is once an hour) and low (below 25). Nothing of the computer's power comes from a Fingerbot |
health | temp (the KVM's own, or a server's hottest processor, in degrees Celsius), cpu, mem (percent) |
about | model, version, as the device says them |
ports | null, or active (counted from 0) and list (each name, signal) for a KVM with several inputs |
kind | said by a JetKVM's and a server's status; a KVM's says neither this nor picture (the wall says both for every tile) |
picture | said by a server's status: false |
Before the first look at a device there is only can, state (connecting), error and last_seen_ago; while it cannot be reached, those with error filled in, and kind (and a server's picture) where the status says them at all. A server adds screen (a picture of its screen can be asked for), console (a signed-in way into its console can be asked for) and server: power (the controller's own word: "On", "Off" and others), health ("OK", "Warning", "Critical", or null), processor, processors, memory_gib, temperatures (each name, celsius, ok), fans (each name, reading, unit, ok), unwell (the names of the sensors it is not happy with), locator (the light: true, false, or null where there is none), no_screen (null, or the sentence why its screen is not shown where it could be), rfb_console (where the controller is OpenBMC with its KVM, the path on it of the WebSocket that carries its console as VNC, /kvm/0, which is where the wall takes that server's screen from; else null).
A business PC with Intel AMT (kind amt) is said as a server is, with no temperatures, fans or light (empty, or null), screen true where its screen can be had through its KVM (and screen, keys, text, live and control in its can), else false with no_screen saying why, and one more record in server, amt: power (the engine's own number for the power state, of which server's power is the word), control (how the engine was set up: "none", "client", "admin", or null where it did not say), kvm ("enabled", "disabled", "mebx" where it was switched off in the PC's MEBx, "absent" on vPro Essentials, which has none, or null), consent (true where a KVM session needs the code the PC shows on its own screen, false, or null), listener (true where the engine's redirection listener is on, which its KVM is reached through; false, or null), session_timeout (the minutes after which the engine ends a KVM session, 0 for never, or null), make, model, serial and bios as the engine says them, and plain (true where the wall reaches the engine over plain HTTP).
A virtual machine on Proxmox VE (kind proxmox) is said as a server is: state online while it runs and no_signal while it is stopped, atx.power the same, no temperatures, fans or light, health.cpu and health.mem (percent of what it was given, while it runs), screen true while it runs and its console can be had (and screen, keys, text, live and control in its can), else false, with no_screen saying why where it runs; in server, power ("Running", "Paused", "Stopped"), processor ("vCPU"), processors and memory_gib as it was given them, and one more record, proxmox: node (the node it is on, followed where it was moved), vmid, status ("running" or "stopped", Proxmox's own word), qmpstatus (what QEMU says of it: "running", "paused" and others) and uptime (seconds).
An account
user in a sign-in and in the session: id, name, role (admin, operator, viewer), totp (a second step is on), must_enroll (one is required and not set up: every request but signing out and setting it up answers 403 totp_required), sso (signed in by the identity proxy: there is nothing to sign out of here), recovery_codes (one-time codes left), token (not a person: a wall screen opened with its link).
Doing something
POST /api/v1/devices/{id}/actions, {"action": "..."} and what that one needs. The last column says the word of can it takes. Any action may also say "watching": true: whoever sends it has the machine's large view or live view open (a PC with Intel AMT then opens a session to its screen before switching on, or starting into its BIOS setup, so the start shows from the first moment). It is not heard with a "batch": an entry of a bulk run comes from the selection, not from a view.
action | Does | Also give | Needs |
|---|---|---|---|
keys | a key combination | "keys": "MetaLeft,KeyL" (names as browsers and kvmd spell them, up to eight) | keys |
ctrl_alt_del | that one | keys | |
text | type text | "text": "...", "enter": true (up to 2000 characters, US keyboard layout; on a JetKVM, the layout it says its computer uses, and 422 invalid before anything is typed for a character that layout cannot type) | text |
custom | a saved action | "custom_id": "...", and "custom_changed": the action's changed as it was listed, refused with 409 changed if it was edited since, or edited or removed while it waited for what the last holder of the keyboard had down to be let go of (saved text is typed by people only: a token that types it could read it back off the screen) | keys or text |
atx_power, atx_power_long | press the power button, hold it; answered once the button is let go, and where it must switch the computer on (or off) once that is seen; the KVM's refusal (a 4xx) is 502 action_failed, anything else that is not its yes 504 timeout or 502 dropped (it may have pressed), after which a press of the board's (or a Fingerbot's) is 409 busy for eight seconds and the button's hold | power | |
atx_reset | press reset; an answer that is neither yes nor no as for the power button | reset | |
fingerbot_power, fingerbot_power_long | a Fingerbot presses the power button for half a second, or holds it for eight, as hard as the machine's fingerbot_strength says; answered once the KVM has said the Fingerbot took the press and the press's own time is over (some three and eleven seconds); the KVM's refusal ("Failed to click") is 502 action_failed, anything else that is not its yes 504 timeout or 502 dropped (it may have pressed), after which a press is 409 busy for as long as that one can last; 422 invalid where the KVM said no Fingerbot is paired | fingerbot | |
power_on, power_off | a server: switch on, or ask it to shut down; one that is so already is left alone and answers "note": "already on" or "already off" | power_state | |
bios_setup | start into the BIOS setup once, then switch on (if off) or restart (if on); 422 invalid with a "batch" (one machine at a time); 409 action_failed where another boot override, or a boot option that destroys data, is already set | "watching": true (as for any action: see below) | bios_setup |
locate_on, locate_off | a server's locator light | locator | |
reboot | restart the KVM itself (for a server: its controller) | reboot | |
jiggler_on, jiggler_off | keep the computer awake, or let it sleep | jiggler | |
wol | Wake-on-LAN from the KVM | "mac": "aa:bb:cc:dd:ee:ff" | wol |
port | show another input of a multi-port KVM | "port": 0 | ports |
resume | a JetKVM: take its picture back from whoever opened its own page | resume |
The page asks before power, reset, a restart, and anything marked danger, and before anything sent to several machines: a program should do no less. One thing at a time per machine: while an action is on its way, a second one for the same machine is refused with 409 busy, whoever sends it.
Manners
- One viewer's worth of asking: the status no more often than
interval, a picture per tile no more often than that, withageset to the interval. Asking for pictures is what keeps the wall connected to its devices; a program that stops asking lets a JetKVM's one viewer go back to whoever wants it. - Do not ask in the background for a window nobody sees.
- 401
unauthorizedin the middle of things means the session ended (signed out elsewhere, ended by an admin): sign in again, do not loop.Retry-Afteris meant.
The page's own
These are under /api/v1/ as well, take an admin (but for the first-run setup, which takes nobody), and change with the page: setup; devices (adding, changing and removing one), devices/{id}/certificate, devices/{id}/trust, devices/{id}/kvm (switching a PC's Intel AMT KVM on or off on its engine, {"on": true}; 409 busy with by as for an action), discover; proxmox (proxmox/guests, {"url", "username", "password"}: the virtual machines an API token may see on a Proxmox, to pick from when adding them, and named, the one an address names by its ID); actions (saving one); users; security; recovery; settings; alerts; audit (the activity log, and audit/export to download it: q, kind, before, since, until, user, device, limit, as the chapter Activity log says); metrics (the token for /metrics); update. A program written against them is written against this version. Their codes are in words.json all the same.