# REST API: System

> The 46 operations of the area System, with parameters, bodies and responses.

Source: https://pithyx.org/docs/reference/api/system/
Markdown: https://pithyx.org/docs/reference/api/system.md

Generated from the daemon's OpenAPI document. Conventions, sign-in, the CSRF header and the WebSocket are on [API](https://pithyx.org/docs/developers/daemon/api/).

## GET /api/health

**Responses**

- 200: `application/json`: [HealthResponse](https://pithyx.org/docs/reference/api/schemas/#healthresponse)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxyticketrequest)

**Responses**

- 200: `application/json`: [ProxyTicket](https://pithyx.org/docs/reference/api/schemas/#proxyticket)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#inspectbackuprequest)

**Responses**

- 200: `application/json`: [BackupSummary](https://pithyx.org/docs/reference/api/schemas/#backupsummary)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#restorebackuprequest)

**Responses**

- 200: `application/json`: [RestoreResult](https://pithyx.org/docs/reference/api/schemas/#restoreresult)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#networkstate)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#networkconfig)

**Responses**

- 200: `application/json`: [PendingNetworkChange](https://pithyx.org/docs/reference/api/schemas/#pendingnetworkchange)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#networkconfig)

**Responses**

- 200: `application/json`: [NetworkCheck](https://pithyx.org/docs/reference/api/schemas/#networkcheck)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## GET /api/system/overview

Administrators only. Version and commit, operating system, kernel, machine, processor, memory, host name and uptime.

**Responses**

- 200: `application/json`: [SystemOverview](https://pithyx.org/docs/reference/api/schemas/#systemoverview)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#powerrequest)

**Responses**

- 202

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxyhostrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxyhostrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxytargetstatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxyoptionsrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/system/proxy/redirects

Administrators only. A redirect host: domains on 443 and 80 redirected to an address.

**Request body**: `application/json`: [ProxyRedirectRequest](https://pithyx.org/docs/reference/api/schemas/#proxyredirectrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxyredirectrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxystreamrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxystreamrequest)

**Responses**

- 200: `application/json`: [ProxySettings](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#proxysettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#systemregion)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#systemregion)

**Responses**

- 200: `application/json`: [SystemRegion](https://pithyx.org/docs/reference/api/schemas/#systemregion)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#timesettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#timesettingsrequest)

**Responses**

- 200: `application/json`: [TimeSettings](https://pithyx.org/docs/reference/api/schemas/#timesettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#tlssettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#createauthorityrequest)

**Responses**

- 200: `application/json`: [TlsSettings](https://pithyx.org/docs/reference/api/schemas/#tlssettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#customcertificaterequest)

**Responses**

- 200: `application/json`: [TlsSettings](https://pithyx.org/docs/reference/api/schemas/#tlssettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/system/tls/custom

Administrators only. Removes the uploaded certificate; the box presents its own again.

**Responses**

- 200: `application/json`: [TlsSettings](https://pithyx.org/docs/reference/api/schemas/#tlssettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#issuecertificaterequest)

**Responses**

- 200: `application/json`: [IssuedCertificateFiles](https://pithyx.org/docs/reference/api/schemas/#issuedcertificatefiles)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#tlsnamesrequest)

**Responses**

- 200: `application/json`: [TlsSettings](https://pithyx.org/docs/reference/api/schemas/#tlssettings)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## POST /api/system/updates/check

Administrators only. Reads the channel and Debian's lists now. Installs nothing.

**Responses**

- 200: `application/json`: [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/system/updates/file

Administrators only. Forgets the uploaded file.

**Responses**

- 200: `application/json`: [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#installupdaterequest)

**Responses**

- 202: `application/json`: [Job](https://pithyx.org/docs/reference/api/schemas/#job)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#rollbackrequest)

**Responses**

- 202: `application/json`: [Job](https://pithyx.org/docs/reference/api/schemas/#job)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#updatesettingsrequest)

**Responses**

- 200: `application/json`: [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## 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](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).

## DELETE /api/system/updates/source

Administrators only. Forgets the source file saved for the recovery menu.

**Responses**

- 200: `application/json`: [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus)

Any failure answers with problem details (`application/problem+json`) and a stable code from the [error reference](https://pithyx.org/docs/reference/errors/).