REST API: System
Generated from the daemon’s OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on API.
GET /api/health
Section titled “GET /api/health”Responses
- 200:
application/json: HealthResponse
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/proxy/tickets
Section titled “POST /api/proxy/tickets”Signed-in users. A one-time ticket (30 seconds) into a proxy host behind the Pithyx sign-in, for the address the browser asked for; the answer is the address to open on that host. Refused with proxy.access.denied when the host does not let the user in.
Request body: application/json: ProxyTicketRequest
Responses
- 200:
application/json: ProxyTicket
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/backup
Section titled “POST /api/system/backup”Administrators only. The configuration of the box (users, groups, passwords, shared folders, rights, file services, storage schedules, regional settings, certificates and SSH host keys) as one file, encrypted with the password. Files on the pools are not part of it.
Request body: application/json: CreateBackupRequest
Responses
- 200:
application/octet-stream: string (byte)
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/backup/inspect
Section titled “POST /api/system/backup/inspect”Administrators only. Decrypts and checks a backup file and keeps it for 15 minutes for a restore by the same administrator; returns what it holds.
Request body: application/json: InspectBackupRequest
Responses
- 200:
application/json: BackupSummary
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/backup/restore
Section titled “POST /api/system/backup/restore”Administrators only. Replaces the chosen parts of the configuration with those of the checked backup, then restarts the daemon. Restoring users signs everybody out.
Request body: application/json: RestoreBackupRequest
Responses
- 200:
application/json: RestoreResult
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/network
Section titled “GET /api/system/network”Administrators only. What Pithyx configured, every card, bond and VLAN with link, speed, addresses, gateways and name servers, whether Pithyx may change it here, the interface this connection comes in on and the change that waits for its confirmation. The topic system/network sends the same without the connection’s interface.
Responses
- 200:
application/json: NetworkState
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/network
Section titled “PUT /api/system/network”Administrators only. Applies new settings as one change (systemd-networkd and resolved files, host name). The change is rolled back after 60 seconds unless confirmed; open one of the answer’s addresses to confirm when the old address went away.
Request body: application/json: NetworkConfig
Responses
- 200:
application/json: PendingNetworkChange
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/network/changes/{changeId}/confirm
Section titled “POST /api/system/network/changes/{changeId}/confirm”Administrators only. Keeps the change that waits for its confirmation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId |
path | string (uuid) | yes |
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/network/changes/{changeId}/revert
Section titled “POST /api/system/network/changes/{changeId}/revert”Administrators only. Rolls the change that waits for its confirmation back at once.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
changeId |
path | string (uuid) | yes |
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/network/check
Section titled “POST /api/system/network/check”Administrators only. Checks new settings without applying them: the stored form, the interfaces that change, whether the host name changes, whether this connection’s interface changes, and the static addresses to open afterwards.
Request body: application/json: NetworkConfig
Responses
- 200:
application/json: NetworkCheck
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/overview
Section titled “GET /api/system/overview”Administrators only. Version and commit, operating system, kernel, machine, processor, memory, host name and uptime.
Responses
- 200:
application/json: SystemOverview
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/power
Section titled “POST /api/system/power”Users with the right to restart and shut down, and administrators. Restarts or shuts the box down a few seconds after the answer.
Request body: application/json: PowerRequest
Responses
- 202
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/proxy
Section titled “GET /api/system/proxy”Administrators only. The ports proxy hosts answer on, what unknown names get, the sign-in address, and every proxy host, redirect host and stream.
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/proxy/hosts
Section titled “POST /api/system/proxy/hosts”Administrators only. A proxy host: domains on 443 and 80 forwarded to a target. Applies to the next request.
Request body: application/json: ProxyHostRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/proxy/hosts/{id}
Section titled “PUT /api/system/proxy/hosts/{id}”Administrators only. Replaces a proxy host’s settings; Basic Auth users without a password keep theirs, an uploaded certificate stays unless a new one comes along.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Request body: application/json: ProxyHostRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/proxy/hosts/{id}
Section titled “DELETE /api/system/proxy/hosts/{id}”Administrators only. Removes a proxy host with its uploaded certificate; its names become unknown.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/proxy/hosts/{id}/check
Section titled “POST /api/system/proxy/hosts/{id}/check”Administrators only. Whether a proxy host’s target answers one request, with the host’s TLS settings.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 200:
application/json: ProxyTargetStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/proxy/options
Section titled “PUT /api/system/proxy/options”Administrators only. What a name no enabled host has gets on 443 and 80 (a redirect to 7484, or 404), and where the Pithyx sign-in of a host sends visitors.
Request body: application/json: ProxyOptionsRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/proxy/redirects
Section titled “POST /api/system/proxy/redirects”Administrators only. A redirect host: domains on 443 and 80 redirected to an address.
Request body: application/json: ProxyRedirectRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/proxy/redirects/{id}
Section titled “PUT /api/system/proxy/redirects/{id}”Administrators only. Replaces a redirect host’s settings.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Request body: application/json: ProxyRedirectRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/proxy/redirects/{id}
Section titled “DELETE /api/system/proxy/redirects/{id}”Administrators only. Removes a redirect host.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/proxy/streams
Section titled “POST /api/system/proxy/streams”Administrators only. A stream: a TCP and/or UDP port of the box forwarded to a host and port; the firewall opens the port.
Request body: application/json: ProxyStreamRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/proxy/streams/{id}
Section titled “PUT /api/system/proxy/streams/{id}”Administrators only. Replaces a stream’s settings.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Request body: application/json: ProxyStreamRequest
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/proxy/streams/{id}
Section titled “DELETE /api/system/proxy/streams/{id}”Administrators only. Removes a stream; the firewall closes its port.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 200:
application/json: ProxySettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/region
Section titled “GET /api/system/region”Administrators only. The system language and the region whose formats every user sees. GET /api/setup carries both for the sign-in page.
Responses
- 200:
application/json: SystemRegion
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/region
Section titled “PUT /api/system/region”Administrators only. Sets the system language (en, de) and the region (an ISO 3166 country code, or null to follow each user’s language).
Request body: application/json: SystemRegion
Responses
- 200:
application/json: SystemRegion
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/time
Section titled “GET /api/system/time”Administrators only. Time zone, synchronization state, the configured time servers and every time zone the system knows.
Responses
- 200:
application/json: TimeSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/time
Section titled “PUT /api/system/time”Administrators only. Sets the time zone and the time servers (an empty list means the distribution’s defaults).
Request body: application/json: TimeSettingsRequest
Responses
- 200:
application/json: TimeSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/tls
Section titled “GET /api/system/tls”Administrators only. Whether the web interface speaks HTTPS, the certificate it presents, the box’s certificate authority with its scope, the names of the box’s own certificate, an uploaded certificate and the certificates issued for other devices.
Responses
- 200:
application/json: TlsSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/tls/authority
Section titled “POST /api/system/tls/authority”Administrators only. Replaces the certificate authority with a new root and intermediate and issues the box’s certificate from them. Every device has to trust the new root; certificates issued for other devices stay valid only where the old root is still trusted.
Request body: application/json: CreateAuthorityRequest
Responses
- 200:
application/json: TlsSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/tls/custom
Section titled “PUT /api/system/tls/custom”Administrators only. Presents a certificate of your own (with its chain and unencrypted key, in PEM) on the web ports and for FTPS while it is valid; after it ends the box presents its own again.
Request body: application/json: CustomCertificateRequest
Responses
- 200:
application/json: TlsSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/tls/custom
Section titled “DELETE /api/system/tls/custom”Administrators only. Removes the uploaded certificate; the box presents its own again.
Responses
- 200:
application/json: TlsSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/tls/issued
Section titled “POST /api/system/tls/issued”Administrators only. Issues a server certificate for another device from the box’s authority. The answer holds the private key; the box does not keep it.
Request body: application/json: IssueCertificateRequest
Responses
- 200:
application/json: IssuedCertificateFiles
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/tls/issued/{id}
Section titled “DELETE /api/system/tls/issued/{id}”Administrators only. Removes an issued certificate from the list. The box keeps no revocation list, so the certificate stays valid until it ends.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 204
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/tls/issued/{id}/certificate.pem
Section titled “GET /api/system/tls/issued/{id}/certificate.pem”Administrators only. An issued certificate with the intermediate it was issued under, without its key.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer (int64) | yes |
Responses
- 200:
application/x-pem-file: string (byte)
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/tls/names
Section titled “PUT /api/system/tls/names”Administrators only. Names (such as a domain pointing at the box) the box’s own certificate covers besides its host name and addresses; they must lie inside the authority’s scope. The certificate is issued again at once.
Request body: application/json: TlsNamesRequest
Responses
- 200:
application/json: TlsSettings
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/tls/root-ca.crt
Section titled “GET /api/system/tls/root-ca.crt”Anyone, also before signing in. The root of the box’s certificate authority in PEM, to install on a device so it trusts the box.
Responses
- 200:
application/x-x509-ca-cert: string (byte)
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
GET /api/system/updates
Section titled “GET /api/system/updates”Administrators only. The installed version, the channel and the daily check, what the last check found (the channel’s newer version with its changelog, the Debian updates with the security fixes, or why the channel could not be read), an uploaded file waiting for its installation, the running update, the history and the snapshots that can be restored. Whether updates apply here at all (a machine not installed by the installer cannot). The topic system/updates sends the same.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/updates/check
Section titled “POST /api/system/updates/check”Administrators only. Reads the channel and Debian’s lists now. Installs nothing.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/updates/file
Section titled “PUT /api/system/updates/file”Administrators only. Streams a .pithyxupdate as the raw body (at most 4 GB) and checks it completely before anything changes: its signature by a key the box trusts for its channel (a development box also takes unsigned files), every package’s size and SHA-256, and that it is newer than the installed version and fits it. Keeps it for “Install” until another upload or a restart.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/updates/file
Section titled “DELETE /api/system/updates/file”Administrators only. Forgets the uploaded file.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/updates/install
Section titled “POST /api/system/updates/install”Administrators only. Installs the uploaded file or the channel’s newest version as a job of the box: a snapshot of the system, the packages (optionally Debian’s updates in the same snapshot), GRUB on every disk, then the restart and the health check, which rolls back to the snapshot by itself when the new version does not come up within five minutes.
Request body: application/json: InstallUpdateRequest
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
POST /api/system/updates/rollback
Section titled “POST /api/system/updates/rollback”Administrators only. Restores a snapshot (the version typed as the confirmation) and restarts into it. Settings changed since the snapshot are lost; pools and their files are not touched.
Request body: application/json: RollbackRequest
Responses
- 202:
application/json: Job
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/updates/settings
Section titled “PUT /api/system/updates/settings”Administrators only. Switches the daily check (it only notifies) and the channel (stable or beta).
Request body: application/json: UpdateSettingsRequest
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
PUT /api/system/updates/source
Section titled “PUT /api/system/updates/source”Administrators only. Checks a pithyx-source.json (another update source, for example a fork, D339) sent as the raw body and keeps it for the recovery menu. It changes nothing the box trusts: only the recovery menu at the console (GRUB entry “Pithyx recovery”, “Change the update source”) switches to it.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.
DELETE /api/system/updates/source
Section titled “DELETE /api/system/updates/source”Administrators only. Forgets the source file saved for the recovery menu.
Responses
- 200:
application/json: UpdateStatus
Any failure answers with problem details (application/problem+json) and a stable code from the error reference.