# REST API: schemas > Every request and response schema of the REST API with its fields. Source: https://pithyx.org/docs/reference/api/schemas/ Markdown: https://pithyx.org/docs/reference/api/schemas.md The schemas of the daemon's OpenAPI document, sorted by name. The TypeScript types of `@pithyx/api-client` are generated from the same document. ## AckMessage Confirms a `sub` or `unsub`. For `sub`, the snapshots of matching topics follow. | Field | Type | Required | Description | | ----------- | ------- | -------- | ----------- | | `id` | string | yes | | | `type` | `"ack"` | yes | | | `requestId` | string | yes | | ## ActiveCertificateSource Which certificate the web interface and FTPS present. Type: `"authority"`, `"custom"` ## AddCatalogRequest | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------------------------------------------------------------------------ | | `url` | string | yes | https://host/owner/repository.git, or for a private catalog git@host:owner/repository.git. | ## AdminAppList Every installed app for administrators: the snapshot and every event of `apps/admin`. | Field | Type | Required | Description | | ------ | ------------------------------------------------------- | -------- | ----------------------------------------------- | | `pool` | null \| string | yes | The app pool, or null before the first install. | | `apps` | [AppDetails](https://pithyx.org/docs/reference/api/schemas/#appdetails)[] | yes | Sorted by id. | ## ApiProblem RFC 9457 problem details as returned by every failing API call. The detail text is an English fallback; clients show the translation of the error code instead. | Field | Type | Required | Description | | ----------- | --------------------------------------------------- | -------- | ----------- | | `type` | string | yes | | | `title` | string | yes | | | `status` | integer (int32) | yes | | | `detail` | string | yes | | | `code` | [ErrorCode](https://pithyx.org/docs/reference/api/schemas/#errorcode) | yes | | | `params` | map of object | yes | | | `requestId` | string | yes | | ## AppAccess Who may use an app after its first install: everybody (a grant to the built-in group) or administrators only. Type: `"everybody"`, `"admins"` ## AppContextState The per-user topic `apps/<id>/context`: what the daemon decides about an app for the subscriber, who may use the app (only such a user can subscribe). Its subscription is also the window lease (A15): while a desktop of the user is subscribed, the app is in use. | Field | Type | Required | Description | | ------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------- | | `version` | string | yes | The installed version. | | `permissions` | string[] | yes | The permissions of the manifest that no administrator revoked; the app sees them as `permissionsChange`. | | `logLevel` | `"info"`, `"debug"` | yes | Whether an app's `debug` log entries reach the daemon; `info`, `warn` and `error` always do. | | `backend` | null \| object | yes | The app's backend: the state of its containers and the names of its endpoints. | | `storage` | object[] | yes | The storage requests of the manifest with their state for the user (`storageChange`). | ## AppDetails An installed app for administrators (topic `apps/admin` and `GET /api/apps`). | Field | Type | Required | Description | | ----------------- | ----------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `id` | string | yes | The app id. | | `version` | string | yes | The installed version. | | `source` | string | yes | `sideload` (a package file) or `catalog`. | | `enabled` | boolean | yes | Whether users can open it. | | `manifest` | [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | The installed manifest. | | `permissions` | [AppPermissionState](https://pithyx.org/docs/reference/api/schemas/#apppermissionstate)[] | yes | Each permission of the manifest with whether it is granted. | | `uid` | integer (int64) | yes | The app's own uid. | | `sha256` | string | yes | SHA-256 of the installed package file. | | `installedAt` | string (date-time) | yes | The first install (UTC). | | `updatedAt` | string (date-time) | yes | The last install or update (UTC). | | `busy` | boolean | yes | An install, update or removal runs. | | `available` | boolean | yes | Its data is reachable: the app pool is imported, unlocked and mounted. | | `logLevel` | [AppLogLevel](https://pithyx.org/docs/reference/api/schemas/#apploglevel) | yes | Whether its debug log entries reach the daemon. | | `storage` | [AppStorageMapping](https://pithyx.org/docs/reference/api/schemas/#appstoragemapping)[] | yes | The folders mapped to the storage requests of its manifest; a request without one is not mapped. | | `catalog` | null \| string | yes | The catalog it was installed or last updated from; null for a sideload. | | `updatePolicy` | null \| [UpdatePolicy](https://pithyx.org/docs/reference/api/schemas/#updatepolicy) | yes | Its own update policy; null follows the box's. | | `previousVersion` | null \| string | yes | The version before its last update, which a rollback restores with its data; null when there is none. | ## Appearance How the desktop looks for the user on every device. The theme (light, dark) is a choice of each device. | Field | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------------------------------------------------------- | | `accent` | string | yes | One of the accent presets: `petrol`, `ocean`, `indigo`, `plum`, `moss`, `graphite`. | | `wallpaper` | string | yes | `boxes` (the Pithyx boxes) or `plain`. | ## AppFileEntry A file or folder an app reaches, with whether the app may write it. | Field | Type | Required | Description | | ---------- | ------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `name` | string | yes | Name within its folder. | | `kind` | [FileKind](https://pithyx.org/docs/reference/api/schemas/#filekind) | yes | File, folder, symlink or another kind. | | `size` | integer (int64) | yes | Bytes for files, 0 for folders. | | `modified` | string (date-time) | yes | Last change of the content, UTC. | | `writable` | boolean | yes | The app holds `files.write` (or the storage is mapped read and write) and the user may write there. | ## AppFileOperationRequest An app's copy, move or delete: as FileOperationRequest, with each place a shared folder or a storage request. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `kind` | [FileOperationKind](https://pithyx.org/docs/reference/api/schemas/#fileoperationkind) | yes | copy, move or delete. | | `items` | null \| [AppFileRef](https://pithyx.org/docs/reference/api/schemas/#appfileref)[] | no | The entries to work on, at most 1000. Leave out when `AllIn` is given. | | `target` | null \| [AppFileRef](https://pithyx.org/docs/reference/api/schemas/#appfileref) | no | An entry or folder of an app's file operation, in a shared folder or a storage request of its manifest. | | `onConflict` | null \| [ConflictPolicy](https://pithyx.org/docs/reference/api/schemas/#conflictpolicy) | no | For copy and move; fail when left out. | | `permanent` | boolean | no | For delete: remove for good instead of moving to the shared folder's recycle bin. | | `allIn` | null \| [AppFolderSelection](https://pithyx.org/docs/reference/api/schemas/#appfolderselection) | no | Every entry of an app's folder except some names. | ## AppFileRef An entry or folder of an app's file operation, in a shared folder or a storage request of its manifest. | Field | Type | Required | Description | | --------- | -------------- | -------- | -------------------------------------------------------------- | | `share` | null \| string | no | The shared folder's id, as the app got it from `files/shares`. | | `storage` | null \| string | no | The id of a storage request of the manifest. | | `path` | null \| string | no | The path relative to the shared folder or the mapped folder. | ## AppFileUrl A short-lived address of one file, usable without the desktop's session. | Field | Type | Required | Description | | ----------- | ------------------ | -------- | --------------------------------------------------------------- | | `url` | string | yes | Path on the box with `?pithyx-token=`; supports range requests. | | `expiresAt` | string (date-time) | yes | When it stops working (UTC). | ## AppFileUrlRequest Body of `POST /api/app/files/url`. | Field | Type | Required | Description | | --------- | -------------- | -------- | ------------------------------------- | | `path` | string | yes | The file. | | `share` | null \| string | no | The shared folder's id, or null. | | `storage` | null \| string | no | The id of a storage request, or null. | ## AppFolderPage One page of a folder, relative to its location. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `path` | string | yes | The folder ("" for the location's root). | | `folderId` | string | yes | Stable id of the folder, also after a rename. | | `total` | integer (int32) | yes | Entries in the folder when the page was read. | | `entries` | [FileEntry](https://pithyx.org/docs/reference/api/schemas/#fileentry)[] | yes | This page, in the requested order. | | `nextCursor` | null \| string | yes | Pass as `cursor` for the next page; null on the last page. | | `topic` | string | yes | WebSocket topic with live changes of this folder, for the desktop's `files.watch`; never sent to the app. | ## AppFolderSelection Every entry of an app's folder except some names. | Field | Type | Required | Description | | -------- | ----------------------------------------------------- | -------- | ----------------------------------- | | `folder` | [AppFileRef](https://pithyx.org/docs/reference/api/schemas/#appfileref) | yes | The folder whose entries are meant. | | `except` | null \| string[] | no | Names left out, at most 1000. | ## AppGrants Who may use an app. Administrators only. | Field | Type | Required | Description | | -------- | ------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `grants` | [SubjectGrant](https://pithyx.org/docs/reference/api/schemas/#subjectgrant)[] | yes | The grants of users and groups on it (level `allow`); the editor changes these. The built-in group `users` stands for everybody. | | `users` | [AppUserAccess](https://pithyx.org/docs/reference/api/schemas/#appuseraccess)[] | yes | Every user with whether it may use the app in the end, administrators and deactivated users included. | ## AppGrantsRequest | Field | Type | Required | Description | | -------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `grants` | [SubjectGrant](https://pithyx.org/docs/reference/api/schemas/#subjectgrant)[] | yes | Every grant on the app the users and groups should have (level `allow`); the others go. | ## AppHandleRequest Body of `POST /api/app/files/handles`: a file the user handed to the window in a dialog. | Field | Type | Required | Description | | ------- | ------- | -------- | ---------------------------------------------------------------------------- | | `share` | string | yes | The shared folder's id. | | `path` | string | yes | The one file; the window may read it (needs `files.read`), or also write it. | | `write` | boolean | no | Whether the window may write it (needs `files.write`). | ## AppList The apps the subscriber may use, sorted by id: the snapshot and every event of `apps`. | Field | Type | Required | Description | | ------ | -------- | -------- | ---------------------------------------------------------------------------- | | `apps` | object[] | yes | Enabled apps the user has a grant for; every enabled app for administrators. | ## AppLogBatch | Field | Type | Required | Description | | --------- | --------------------------------------------------------- | -------- | -------------------------------- | | `entries` | [AppLogEntry](https://pithyx.org/docs/reference/api/schemas/#applogentry)[] | yes | At most 100 entries per request. | ## AppLogEntry | Field | Type | Required | Description | | --------- | --------------------------------------------------------- | -------- | -------------------------------------------------- | | `level` | [LogLevelName](https://pithyx.org/docs/reference/api/schemas/#loglevelname) | yes | debug, info, warn or error. | | `message` | string | yes | At most 4000 characters; longer ones are cut. | | `data` | null \| map of string | no | At most 20 fields of at most 1000 characters each. | ## AppLogLevel Whether an app's `debug` log entries reach the daemon; `info`, `warn` and `error` always do. Type: `"info"`, `"debug"` ## AppLogLevelRequest | Field | Type | Required | Description | | ------- | ------------------------------------------------------- | -------- | ----------------------------------------------------- | | `level` | [AppLogLevel](https://pithyx.org/docs/reference/api/schemas/#apploglevel) | yes | Whether the app's debug log entries reach the daemon. | ## AppLogResult | Field | Type | Required | Description | | ---------- | --------------- | -------- | ---------------------------------------------- | | `accepted` | integer (int32) | yes | Entries stored. | | `dropped` | integer (int32) | yes | Entries over the app's rate limit, not stored. | ## AppNotificationAction A button of an app's notification. | Field | Type | Required | Description | | ------- | ------ | -------- | ---------------------------------------------------------------------------------------------- | | `id` | string | yes | Comes back to the app when the user clicks it; 1 to 64 characters, unique in the notification. | | `label` | string | yes | Plain text from the app, 1 to 40 characters. | ## AppNotificationLevel Type: `"info"`, `"success"`, `"warning"`, `"error"`, `null` ## AppNotificationRequest Body of `POST /api/notifications/app`: a notification a core app sends through the SDK. | Field | Type | Required | Description | | ------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `app` | string | yes | Id of the core app (`org.pithyx.*`); third-party apps send theirs to `/api/app/notifications`. | | `title` | string | yes | Plain text from the app, at most 200 characters. | | `body` | null \| string | no | Plain text from the app, at most 1000 characters. | | `tone` | null \| [NotificationTone](https://pithyx.org/docs/reference/api/schemas/#notificationtone) | no | Defaults to `info`. | ## AppNotifyRequest Body of `POST /api/app/notifications`: the SDK's `notify` of a third-party app. | Field | Type | Required | Description | | --------- | ------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- | | `title` | string | yes | Plain text, 1 to 200 characters. | | `body` | null \| string | no | Plain text, at most 1000 characters. | | `level` | null \| [AppNotificationLevel](https://pithyx.org/docs/reference/api/schemas/#appnotificationlevel) | no | Defaults to `info`. | | `actions` | null \| [AppNotificationAction](https://pithyx.org/docs/reference/api/schemas/#appnotificationaction)[] | no | At most 2 buttons. | | `data` | object | no | Any JSON the app gets back with a click, at most 4096 characters. | | `tag` | null \| string | no | Replaces the app's earlier notification with the same tag for this user; 1 to 64 characters. | ## AppPackageAction What installing a checked package does. Type: `"install"`, `"update"`, `"reinstall"`, `"downgrade"` ## AppPackagePreview A checked package, kept for 15 minutes for its installation by the administrator who uploaded it. | Field | Type | Required | Description | | -------------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `packageId` | string | yes | Names it for the install. | | `expiresAt` | string (date-time) | yes | When it is discarded (UTC). | | `id` | string | yes | The app id. | | `version` | string | yes | The version in the package. | | `manifest` | [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | The whole manifest (`pithyx.json`). | | `action` | [AppPackageAction](https://pithyx.org/docs/reference/api/schemas/#apppackageaction) | yes | What installing it does. | | `installedVersion` | null \| string | yes | The installed version, if the app is installed. | | `addedPermissions` | string[] | yes | Permissions the package asks for that the installed version did not (all of them for an install). | | `removedPermissions` | string[] | yes | Permissions the installed version had that the package no longer asks for. | | `pool` | null \| string | yes | The app pool, or null before the first app is installed (the install must name one then). | | `fileCount` | integer (int32) | yes | Regular files in the package. | | `unpackedBytes` | integer (int64) | yes | Their sizes together. | | `packageBytes` | integer (int64) | yes | The size of the package file. | | `sha256` | string | yes | SHA-256 of the package file, lowercase hex. | | `suggestedAccess` | [AppAccess](https://pithyx.org/docs/reference/api/schemas/#appaccess) | yes | Who should use the app after an install: administrators only when it asks for elevated rights, root in a container or `directory.read`, everybody otherwise. An install without access takes it. | | `catalog` | null \| string | no | The catalog the package comes from; null for an uploaded file (a sideload, unverified). | | `keptData` | boolean | no | For an install: an earlier installation was removed with "Keep the data", and the app gets its data and its user id again. | ## AppPermissionsRequest | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `permissions` | [AppPermissionState](https://pithyx.org/docs/reference/api/schemas/#apppermissionstate)[] | yes | Permissions of the app's manifest with whether the app keeps them; the others stay as they are. | ## AppPermissionState | Field | Type | Required | Description | | ------------ | ------- | -------- | ---------------------------------------- | | `permission` | string | yes | For example `notifications`. | | `granted` | boolean | yes | False after an administrator revoked it. | ## AppRenameRequest Body of `POST /api/app/files/rename`. | Field | Type | Required | Description | | --------- | -------------- | -------- | ------------------------------------- | | `path` | string | yes | The entry to rename. | | `name` | string | yes | The new name in the same folder. | | `share` | null \| string | no | The shared folder's id, or null. | | `storage` | null \| string | no | The id of a storage request, or null. | ## AppShareInfo A shared folder the user can use, as an app with `files.shares` sees it: never its place on the host. | Field | Type | Required | Description | | ------------- | ------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `id` | string | yes | The location `{ share: id }`. | | `name` | string | yes | Name shown to users. | | `access` | [ShareAccess](https://pithyx.org/docs/reference/api/schemas/#shareaccess) | yes | The user's access: `read` or `readWrite`. | | `unavailable` | null \| string | yes | Why its files cannot be reached now (`poolMissing`, `poolUnavailable`, `notMounted`), or null. | | `kind` | [ShareKind](https://pithyx.org/docs/reference/api/schemas/#sharekind) | no | A shared folder, or the user's own home (`home`, D348). Apps never get other users' homes. | ## AppStorageAccess How an app may use a folder mapped to one of its storage requests. Type: `"read"`, `"readWrite"` ## AppStorageKeys The keys an app stored for the user. | Field | Type | Required | Description | | ------ | -------- | -------- | ----------- | | `keys` | string[] | yes | Sorted. | ## AppStorageMapping A folder in a shared folder that an administrator mapped to one storage request of an app. | Field | Type | Required | Description | | ----------- | ----------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | | `storageId` | string | yes | The id of the request in the manifest. | | `shareId` | integer (int64) | yes | The shared folder. | | `path` | string | yes | The folder relative to the shared folder's root, empty for the root itself. | | `access` | [AppStorageAccess](https://pithyx.org/docs/reference/api/schemas/#appstorageaccess) | yes | Read-only, or read and write when the request asks for it. | ## AppStorageMappingRequest | Field | Type | Required | Description | | --------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ | | `shareId` | integer (int64) | yes | The shared folder. | | `access` | [AppStorageAccess](https://pithyx.org/docs/reference/api/schemas/#appstorageaccess) | yes | Read-only, or read and write when the storage request asks for it. | | `path` | null \| string | no | An existing folder in it, relative to its root; empty or missing for the root. | ## AppStorageValue A value an app stores for the user; JSON null when there is none. | Field | Type | Required | Description | | ------- | ------------------------------------------------------- | -------- | ------------------------ | | `value` | [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | Any JSON, at most 64 KB. | ## AppTicket A one-time ticket for one WebSocket to the app's backend, as `?pithyx-ticket=`. | Field | Type | Required | Description | | ----------- | ------------------ | -------- | ------------------------------ | | `ticket` | string | yes | Works once, within 30 seconds. | | `expiresAt` | string (date-time) | yes | When it stops working (UTC). | ## AppTicketRequest Body of `POST /api/app/tickets`. | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------ | | `endpoint` | string | yes | A backend endpoint of the app's manifest, for example `api`. | ## AppToken A token for one app, user, session and window. | Field | Type | Required | Description | | ----------- | ------------------ | -------- | ------------------------------------------------------- | | `token` | string | yes | Send as `Authorization: Bearer`; never log or store it. | | `expiresAt` | string (date-time) | yes | When it stops working (UTC); ask for a new one before. | ## AppTokenKind What a token is for. Type: `"host"`, `"backend"`, `"ticket"`, `"file"` ## AppTokenRequest Body of `POST /api/apps/{appId}/tokens`. | Field | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- | | `kind` | [AppTokenKind](https://pithyx.org/docs/reference/api/schemas/#apptokenkind) | yes | `host` for the daemon's API for apps (kept by the desktop), `backend` for the app's backend. | | `instance` | string | yes | The window instance: 1 to 64 letters, digits, dashes and underscores. | ## AppTrashRequest Body of the recycle bin calls of `/api/app/files/trash`. | Field | Type | Required | Description | | ------------ | --------------------------------------------------------------------- | -------- | -------------------------------------------- | | `share` | string | yes | The shared folder's id. | | `ids` | null \| integer (int64)[] | no | The items; all items of the bin for `empty`. | | `onConflict` | null \| [ConflictPolicy](https://pithyx.org/docs/reference/api/schemas/#conflictpolicy) | no | For restore; rename when left out. | ## AppUpdate A newer version of an installed app that a catalog offers. | Field | Type | Required | Description | | ------------------ | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- | | `id` | string | yes | The app. | | `installedVersion` | string | yes | The installed version. | | `version` | string | yes | The newest version for this box. | | `catalog` | string | yes | The catalog that offers it. | | `addedPermissions` | string[] | yes | Permissions the new version asks for that the installed one did not. | | `elevated` | boolean | yes | It asks for root in a container or elevated rights it did not have. | | `policy` | [UpdatePolicy](https://pithyx.org/docs/reference/api/schemas/#updatepolicy) | yes | The app's own policy, or the box's. | | `automatic` | boolean | yes | The next check installs it on its own: the policy is automatic and nothing new is asked for. | ## AppUpdatePolicyRequest | Field | Type | Required | Description | | -------- | ----------------------------------------------------------------- | -------- | ---------------------------------------------------- | | `policy` | null \| [UpdatePolicy](https://pithyx.org/docs/reference/api/schemas/#updatepolicy) | yes | The app's own update policy; null follows the box's. | ## AppUserAccess One user's effective access to an app. | Field | Type | Required | Description | | --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- | | `userId` | integer (int64) | yes | The user's id. | | `username` | string | yes | Login name. | | `displayName` | null \| string | yes | Name shown, if set. | | `administrator` | boolean | yes | Administrators use every app. | | `disabled` | boolean | yes | Deactivated users use none. | | `allowed` | boolean | yes | Whether the user may use the app: by its own grant, one of its groups', or as an administrator. | ## AppVersionRestoreRequest Body of `POST /api/app/files/versions/restore`. | Field | Type | Required | Description | | ----------- | ------- | -------- | ---------------------------------------------------------- | | `share` | string | yes | The shared folder's id. | | `path` | string | yes | The file or folder to bring back. | | `snapshot` | string | yes | The version's snapshot, as listed. | | `overwrite` | boolean | no | Replace the current entry instead of restoring next to it. | ## AuthorityInfo The box's certificate authority. | Field | Type | Required | Description | | --------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- | | `root` | [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | The root that devices trust; download it from `/api/system/tls/root-ca.crt`. | | `intermediate` | [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | The intermediate that signs every certificate; it is renewed a year before it ends. | | `restricted` | boolean | yes | Name Constraints limit what the authority may sign. | | `domains` | string[] | yes | The DNS suffixes it may sign, each with every name below it; empty when unrestricted. | | `addressRanges` | string[] | yes | The address ranges it may sign; empty when unrestricted. | ## AvailableUpdate The newest version of the box's channel when it is newer than the installed one. `Installable`: False when the box is older than MinimumVersion and needs a version in between first. | Field | Type | Required | Description | | ---------------- | ------------------ | -------- | ----------- | | `version` | string | yes | | | `minimumVersion` | string | yes | | | `changelog` | string | yes | | | `size` | integer (int64) | yes | | | `publishedAt` | string (date-time) | yes | | | `installable` | boolean | yes | | ## BackupCategory A part of the configuration that can be restored on its own. Type: `"users"`, `"sharedFolders"`, `"storage"`, `"system"`, `"certificates"`, `"apps"`, `"reverseProxy"` ## BackupSummary A backup the daemon decrypted and checked, kept for a restore for 15 minutes. | Field | Type | Required | Description | | --------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------ | | `restoreId` | string | yes | Names the checked backup in the restore request. | | `createdAt` | string (date-time) | yes | When the backup was created, UTC. | | `hostName` | string | yes | The host name of the box that created it. | | `version` | string | yes | The Pithyx version that created it. | | `categories` | [BackupCategory](https://pithyx.org/docs/reference/api/schemas/#backupcategory)[] | yes | What it holds and can restore. | | `users` | integer (int32) | yes | Users in the backup. | | `groups` | integer (int32) | yes | Groups in the backup, without the built-in one. | | `sharedFolders` | integer (int32) | yes | Shared folders in the backup. | ## BondMode How a bond uses its cards. Type: `"activeBackup"`, `"lacp"`, `"balanceAlb"` ## BondSettings | Field | Type | Required | Description | | ---------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | | `members` | string[] | yes | The network cards in the bond, at least one; none of them has its own configuration. | | `mode` | [BondMode](https://pithyx.org/docs/reference/api/schemas/#bondmode) | yes | How the bond uses its cards. | | `primary` | null \| string | no | For active-backup: the card that carries the traffic while its link is up. | | `lacpRate` | [LacpRate](https://pithyx.org/docs/reference/api/schemas/#lacprate) | no | For LACP: how often the partners exchange their state. | ## CatalogInfo A catalog of the box. | Field | Type | Required | Description | | ------------------ | --------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- | | `key` | integer (int64) | yes | The box's number for it, which the catalog endpoints take. | | `id` | null \| string | yes | The id from its `catalog.json`, or null before a custom catalog's first fetch. | | `kind` | [CatalogKind](https://pithyx.org/docs/reference/api/schemas/#catalogkind) | yes | The project's official or community catalog, or a custom one. | | `url` | string | yes | The repository. | | `enabled` | boolean | yes | Switched on. | | `verified` | boolean | yes | Its index must carry a signature by a key built into the box (the project's catalogs). | | `name` | null \| map of string | yes | Its name by language from `catalog.json`, once fetched. | | `description` | null \| map of string | yes | Its description by language, if it has one. | | `homepage` | null \| string | yes | Its homepage, if it names one. | | `sshPublicKey` | null \| string | yes | The deploy key the box made for an SSH URL; add it to the repository with read access. | | `hostKey` | null \| string | yes | The server's host key the box pinned (for hosts other than GitHub, whose keys are built in). | | `hasRegistryToken` | boolean | yes | A read token for its private images is set (never sent back). | | `status` | [CatalogStatus](https://pithyx.org/docs/reference/api/schemas/#catalogstatus) | yes | Off, new, ok or failed. | | `checkedAt` | null (date-time) \| string (date-time) | yes | When the last fetch ended. | | `verifiedAt` | null (date-time) \| string (date-time) | yes | When a fetch last verified the copy. | | `commit` | null \| string | yes | The commit of the verified copy. | | `sequence` | null (int64) \| integer (int64) | yes | The verified index's sequence on the box's channel. | | `appCount` | integer (int32) | yes | How many apps the verified copy lists. | | `errorCode` | null \| string | yes | Why the last fetch failed. | | `errorParams` | null \| [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | The error's params. | | `busy` | boolean | yes | A fetch runs. | ## CatalogKind Whose catalog it is: the project's two (signed, keys built in) or one an administrator added (unverified). Type: `"official"`, `"community"`, `"custom"` ## CatalogStatus A catalog's state for the Store's settings. Type: `"off"`, `"new"`, `"ok"`, `"failed"` ## CertificateInfo One certificate as Settings shows it. | Field | Type | Required | Description | | ------------- | ------------------ | -------- | -------------------------------------- | | `subject` | string | yes | The subject's distinguished name. | | `issuer` | string | yes | The issuer's distinguished name. | | `names` | string[] | yes | The DNS names and addresses it covers. | | `notBefore` | string (date-time) | yes | The start of its validity. | | `notAfter` | string (date-time) | yes | The end of its validity. | | `fingerprint` | string | yes | SHA-256 as hex pairs with colons. | ## CertificateKeyType The key of a certificate the authority issues. Type: `"ecdsa"`, `"rsa"` ## ClientMessage A message from the client: `sub` or `unsub` for a topic or pattern. | Field | Type | Required | Description | | ------- | ------------------ | -------- | ---------------------------------------------------------------------------------------- | | `type` | `"sub"`, `"unsub"` | yes | | | `id` | string | yes | Chosen by the client; echoed in the ack, snapshots and errors that answer this message. | | `topic` | null \| string | no | Topic name or pattern with `+` and `#`. A message without one is answered with an error. | ## ConflictPolicy Type: `"fail"`, `"skip"`, `"overwrite"`, `"rename"`, `null` ## CopyLayoutRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------- | | `deviceId` | string | yes | | ## CreateAuthorityRequest A new authority; every device has to trust its root again. | Field | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------------------------------------------------- | | `restricted` | boolean | yes | Limit the authority to local names and private addresses (recommended). | | `domains` | string[] | yes | With Restricted: DNS suffixes besides the suggested ones, such as a domain of your own. | ## CreateBackupRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | `password` | string | yes | The backup password: needed to restore, never stored. The same rules as for an account password. | ## CustomCertificateRequest A certificate of your own for the web interface and FTPS. | Field | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------------------------------------- | | `certificatePem` | string | yes | The certificate, followed by its intermediates, in PEM. | | `privateKeyPem` | string | yes | Its private key in PEM (PKCS #8, PKCS #1 or SEC 1), unencrypted. | ## DaemonMode Type: `"real"`, `"simulated"` ## Dataset | Field | Type | Required | Description | | ---------------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------- | | `name` | string | yes | Full dataset name, for example `tank/pithyx/shares/media`. | | `pool` | string | yes | The pool it belongs to. | | `type` | string | yes | `filesystem` or `volume`. | | `usedBytes` | integer (int64) | yes | Space used by the dataset and its children. | | `availableBytes` | integer (int64) | yes | Space available to it. | | `referencedBytes` | integer (int64) | yes | Data the dataset references itself. | | `mountPoint` | null \| string | yes | Mount point of a file system, if it has one. | | `mounted` | boolean | yes | True while the file system is mounted. | | `encryption` | string | yes | Encryption algorithm, or `off`. | | `keyStatus` | null \| string | yes | `available` or `unavailable` for encrypted datasets, otherwise null. | | `encryptionRoot` | null \| string | yes | The dataset whose key unlocks this one, if encrypted. | | `quotaBytes` | null (int64) \| integer (int64) | yes | Limit for the dataset with its children and snapshots, or null for none. | | `reservationBytes` | null (int64) \| integer (int64) | yes | Space guaranteed to the dataset with its children and snapshots, or null for none. | | `compression` | null \| string | yes | Compression algorithm, for example `lz4`, `zstd` or `off`. | | `recordSizeBytes` | null (int64) \| integer (int64) | yes | Largest block of a file system; null for a volume. | | `volumeSizeBytes` | null (int64) \| integer (int64) | yes | Size of a volume; null for a file system. | | `volumeBlockSizeBytes` | null (int64) \| integer (int64) | yes | Block size of a volume; null for a file system. | | `snapshotsUsedBytes` | integer (int64) | yes | Space only its snapshots hold. | ## DebianUpdate A Debian package `apt-get --simulate upgrade` would install. | Field | Type | Required | Description | | ---------- | -------------- | -------- | -------------------------------------------------------------------------------- | | `name` | string | yes | The package. | | `from` | null \| string | yes | The installed version; null for a package the upgrade adds. | | `to` | string | yes | The version it would install. | | `security` | boolean | yes | Whether it comes from a security archive (`Debian-Security:13/stable-security`). | ## DebianUpdates The Debian updates apt offers; the kernel and ZFS never come from Debian. | Field | Type | Required | Description | | ---------- | ----------------------------------------------------------- | -------- | ----------- | | `count` | integer (int32) | yes | | | `security` | integer (int32) | yes | | | `packages` | [DebianUpdate](https://pithyx.org/docs/reference/api/schemas/#debianupdate)[] | yes | | ## DesktopItem An app shortcut or a sticky note on the desktop, shared across the user's devices. | Field | Type | Required | Description | | --------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id of the item. | | `kind` | [DesktopItemKind](https://pithyx.org/docs/reference/api/schemas/#desktopitemkind) | yes | What the item is. | | `app` | null \| string | yes | Shortcuts: the id of the app it opens. | | `name` | null \| string | yes | Shortcuts: the label the user gave it, or null for the app's name in the user's language. | | `text` | null \| string | yes | Notes: the text. | | `column` | integer (int32) | yes | Grid cell of the item, counted from the top left corner of the desktop. | | `row` | integer (int32) | yes | Grid row of the item. | | `version` | integer (int64) | yes | Increments with every change. Send it as `If-Match: "n"` with the next change of this item. | ## DesktopItemChange A change of one item. Fields left out (or null) stay as they are. | Field | Type | Required | Description | | -------- | ------------------------------- | -------- | ---------------------------------------------------------------------- | | `name` | null \| string | no | Shortcuts: the new label; an empty string goes back to the app's name. | | `text` | null \| string | no | Notes: the new text. | | `column` | null (int32) \| integer (int32) | no | New grid column. | | `row` | null (int32) \| integer (int32) | no | New grid row. | ## DesktopItemKind Type: `"shortcut"`, `"note"` ## DesktopState | Field | Type | Required | Description | | --------------- | ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `layout` | null \| [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | The saved layout of this device (schema in the desktop, `version` 1), or null. | | `layoutVersion` | integer (int64) | yes | Increments with every save of this device's layout, 0 without one. Send it as `If-Match: "n"` with the next save. | | `preferences` | [WindowPreference](https://pithyx.org/docs/reference/api/schemas/#windowpreference)[] | yes | Window preferences of the user for every app, shared across devices. | | `appearance` | [Appearance](https://pithyx.org/docs/reference/api/schemas/#appearance) | yes | Accent color and wallpaper of the user, the same on every device. | ## DeviceLayout Another device of the user with a saved layout. | Field | Type | Required | Description | | -------------- | ------------------------------- | -------- | -------------------------------------------------------------------------------- | | `deviceId` | string | yes | Pass to `POST /api/desktop/layout/copy`. | | `browser` | null \| string | yes | Browser product name from the User-Agent, if known. | | `os` | null \| string | yes | Operating system name from the User-Agent, if known. | | `windowCount` | integer (int64) | yes | Windows in the layout. | | `updatedAt` | string (date-time) | yes | When the layout was last saved (UTC). | | `screenWidth` | null (int64) \| integer (int64) | yes | Width of the desktop the layout was saved on, in CSS pixels, if the layout says. | | `screenHeight` | null (int64) \| integer (int64) | yes | Its height. | ## DirectoryGroup A group of the box, for an app with `directory.read`. The built-in group is left out. | Field | Type | Required | Description | | ------------- | --------------- | -------- | ---------------------------------- | | `id` | integer (int64) | yes | Stable id (the group's Linux gid). | | `name` | string | yes | The group name. | | `description` | string | yes | Free text, may be empty. | ## DirectoryUser A user of the box, for an app with `directory.read`. Deactivated users are left out. | Field | Type | Required | Description | | ------------- | ----------------- | -------- | ---------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id. | | `name` | string | yes | The user name. | | `displayName` | null \| string | yes | The name to show, if set. | | `groups` | integer (int64)[] | yes | Ids of the user's groups, without the built-in group every user is in. | ## Disk | Field | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `id` | string | yes | Stable across reboots and device renames: `wwn-...`, else `serial-...`, else `path-...`. | | `name` | string | yes | Kernel name, for example `sda` or `nvme0n1`. Can change between boots. | | `path` | string | yes | Device node, for example `/dev/sda`. | | `serial` | null \| string | yes | Serial number as reported by the drive, if any. | | `wwn` | null \| string | yes | World wide name, if any. | | `model` | null \| string | yes | Model name, if any. | | `vendor` | null \| string | yes | Vendor, if any. | | `sizeBytes` | integer (int64) | yes | Capacity in bytes. | | `rotational` | boolean | yes | True for spinning disks. | | `transport` | null \| string | yes | Bus, for example `sata`, `nvme` or `usb`; null for virtual disks. | | `removable` | boolean | yes | True for removable media. | | `readOnly` | boolean | yes | True when the kernel exposes the disk read-only. | | `partitions` | [Partition](https://pithyx.org/docs/reference/api/schemas/#partition)[] | yes | Partitions in on-disk order. | ## DiskList Snapshot of `storage/disks` and response of `GET /api/disks`. | Field | Type | Required | Description | | ------- | -------- | -------- | ----------- | | `disks` | object[] | yes | | ## DisksChanged Event of `storage/disks`: disks that appeared or changed, and ids of disks that disappeared. | Field | Type | Required | Description | | ---------- | -------- | -------- | ----------- | | `upserts` | object[] | yes | | | `removals` | string[] | yes | | ## ErrorCode Type: `"app.app.busy"`, `"app.app.no_previous"`, `"app.app.not_found"`, `"app.backend.endpoint_unknown"`, `"app.backend.missing"`, `"app.backend.start_failed"`, `"app.backend.storage_unavailable"`, `"app.backend.unavailable"`, `"app.backend.unsupported"`, `"app.compose.key_unsupported"`, `"app.compose.reference_unknown"`, `"app.compose.right_missing"`, `"app.compose.right_unused"`, `"app.compose.storage_mismatch"`, `"app.compose.value_invalid"`, `"app.compose.yaml_invalid"`, `"app.docker.unavailable"`, `"app.elevated.unsupported"`, `"app.icon.invalid"`, `"app.image.mismatch"`, `"app.image.unavailable"`, `"app.manifest.cron_invalid"`, `"app.manifest.duplicate"`, `"app.manifest.id_invalid"`, `"app.manifest.id_reserved"`, `"app.manifest.invalid_json"`, `"app.manifest.pithyx_invalid"`, `"app.manifest.reference_unknown"`, `"app.manifest.schema_violation"`, `"app.manifest.sdk_invalid"`, `"app.manifest.version_unsupported"`, `"app.manifest.window_size_invalid"`, `"app.mapping.invalid"`, `"app.package.box_too_old"`, `"app.package.downgrade_unsupported"`, `"app.package.invalid"`, `"app.package.layout_invalid"`, `"app.package.lock_invalid"`, `"app.package.not_found"`, `"app.package.too_large"`, `"app.permission.denied"`, `"app.permission.not_requested"`, `"app.pool.fixed"`, `"app.pool.required"`, `"app.pool.unavailable"`, `"app.storage.key_invalid"`, `"app.storage.not_found"`, `"app.storage.too_large"`, `"app.token.invalid"`, `"auth.account.disabled"`, `"auth.challenge.expired"`, `"auth.credentials.invalid"`, `"auth.csrf.header_missing"`, `"auth.desktop.not_allowed"`, `"auth.display_name.invalid"`, `"auth.password.too_common"`, `"auth.password.too_long"`, `"auth.password.too_short"`, `"auth.permission.denied"`, `"auth.rate.limited"`, `"auth.recovery.invalid"`, `"auth.session.expired"`, `"auth.setup.already_done"`, `"auth.totp.already_enabled"`, `"auth.totp.invalid"`, `"auth.totp.not_enrolled"`, `"auth.username.invalid"`, `"auth.username.reserved"`, `"desktop.device.not_found"`, `"desktop.item.conflict"`, `"desktop.item.invalid"`, `"desktop.item.limit_reached"`, `"desktop.item.not_found"`, `"desktop.layout.conflict"`, `"desktop.layout.invalid"`, `"desktop.layout.too_large"`, `"desktop.note.too_long"`, `"fileservices.service.unavailable"`, `"fileservices.workgroup.invalid"`, `"fs.cursor.invalid"`, `"fs.entry.access_denied"`, `"fs.entry.exists"`, `"fs.entry.is_folder"`, `"fs.entry.not_folder"`, `"fs.entry.not_found"`, `"fs.folder.not_empty"`, `"fs.io.failed"`, `"fs.name.invalid"`, `"fs.operation.into_itself"`, `"fs.operation.invalid"`, `"fs.path.invalid"`, `"fs.range.not_satisfiable"`, `"fs.share.data_choice_required"`, `"fs.share.dataset_name_invalid"`, `"fs.share.description_invalid"`, `"fs.share.exists"`, `"fs.share.folder_dev_only"`, `"fs.share.invalid"`, `"fs.share.name_mismatch"`, `"fs.share.name_reserved"`, `"fs.share.no_dataset"`, `"fs.share.not_found"`, `"fs.share.path_taken"`, `"fs.share.pool_not_prepared"`, `"fs.share.read_only"`, `"fs.share.unavailable"`, `"fs.thumbnail.not_found"`, `"fs.thumbnail.too_many"`, `"fs.trash.retention_invalid"`, `"fs.upload.incomplete"`, `"fs.version.not_found"`, `"fs.volume.full"`, `"fs.volume.read_only"`, `"homes.choice.invalid"`, `"homes.home.in_use"`, `"homes.home.name_mismatch"`, `"homes.home.not_found"`, `"homes.move.running"`, `"homes.pool.no_space"`, `"homes.pool.taken"`, `"homes.pool.unavailable"`, `"homes.pool.unchanged"`, `"homes.quota.invalid"`, `"installer.check.failed"`, `"installer.claim.required"`, `"installer.claim.taken"`, `"installer.disk.count"`, `"installer.disk.unsuitable"`, `"installer.erase.not_confirmed"`, `"installer.hostname.invalid"`, `"installer.install.failed"`, `"installer.install.running"`, `"installer.keyboard.invalid"`, `"installer.reboot.not_ready"`, `"jobs.job.not_found"`, `"logs.app.invalid"`, `"logs.archive.pool_unavailable"`, `"logs.batch.too_large"`, `"logs.query.invalid"`, `"logs.settings.invalid"`, `"network.address.invalid"`, `"network.apply.failed"`, `"network.bond.member_invalid"`, `"network.bond.members_missing"`, `"network.bond.primary_invalid"`, `"network.change.empty"`, `"network.change.not_found"`, `"network.change.pending"`, `"network.config.unreachable"`, `"network.default_interface.invalid"`, `"network.dns.invalid"`, `"network.dns.too_many"`, `"network.firewall.failed"`, `"network.gateway.invalid"`, `"network.global.not_changeable"`, `"network.host_name.invalid"`, `"network.interface.duplicate"`, `"network.interface.kind_invalid"`, `"network.interface.name_invalid"`, `"network.interface.not_changeable"`, `"network.interface.unknown"`, `"network.mtu.invalid"`, `"network.search_domain.invalid"`, `"network.search_domain.too_many"`, `"network.vlan.duplicate"`, `"network.vlan.id_invalid"`, `"network.vlan.parent_invalid"`, `"notifications.message.invalid"`, `"notifications.notification.not_found"`, `"permissions.grant.invalid"`, `"proxy.access.denied"`, `"proxy.address.denied"`, `"proxy.address.invalid"`, `"proxy.auth.required"`, `"proxy.basic_auth.invalid"`, `"proxy.basic_auth.password_missing"`, `"proxy.certificate.missing"`, `"proxy.certificate.name_mismatch"`, `"proxy.domain.invalid"`, `"proxy.domain.taken"`, `"proxy.domains.missing"`, `"proxy.domains.too_many"`, `"proxy.header.invalid"`, `"proxy.headers.too_many"`, `"proxy.host.not_found"`, `"proxy.host.unknown"`, `"proxy.limit.out_of_range"`, `"proxy.loop.detected"`, `"proxy.redirect.not_found"`, `"proxy.redirect.status_invalid"`, `"proxy.redirect.target_invalid"`, `"proxy.sign_in.address_invalid"`, `"proxy.sign_in.group_not_found"`, `"proxy.sign_in.user_not_found"`, `"proxy.stream.name_invalid"`, `"proxy.stream.not_found"`, `"proxy.stream.port_in_use"`, `"proxy.stream.port_privileged"`, `"proxy.stream.port_reserved"`, `"proxy.stream.port_taken"`, `"proxy.stream.protocol_missing"`, `"proxy.target.invalid"`, `"proxy.target.loop"`, `"proxy.target.on_box"`, `"proxy.target.timeout"`, `"proxy.target.unavailable"`, `"proxy.ticket.target_invalid"`, `"proxy.websockets.disabled"`, `"realtime.message.invalid"`, `"realtime.topic.invalid"`, `"realtime.topic.unknown"`, `"realtime.upgrade.required"`, `"request.body.invalid"`, `"request.media_type.unsupported"`, `"request.method.not_allowed"`, `"request.route.not_found"`, `"storage.alert.not_found"`, `"storage.command.failed"`, `"storage.command.timed_out"`, `"storage.dataset.compression_invalid"`, `"storage.dataset.exists"`, `"storage.dataset.in_use_by_share"`, `"storage.dataset.limit_invalid"`, `"storage.dataset.managed"`, `"storage.dataset.name_invalid"`, `"storage.dataset.name_mismatch"`, `"storage.dataset.not_found"`, `"storage.dataset.property_unsupported"`, `"storage.dataset.protected"`, `"storage.dataset.quota_below_used"`, `"storage.dataset.record_size_invalid"`, `"storage.dataset.reservation_too_large"`, `"storage.dataset.unchanged"`, `"storage.disk.not_found"`, `"storage.disk.refused"`, `"storage.encryption.unavailable"`, `"storage.import.device_unknown"`, `"storage.import.force_required"`, `"storage.import.not_found"`, `"storage.import.not_importable"`, `"storage.import.preview_required"`, `"storage.plan.action_invalid"`, `"storage.plan.expired"`, `"storage.plan.not_found"`, `"storage.plan.stale"`, `"storage.pool.disk_count"`, `"storage.pool.disks_missing"`, `"storage.pool.encryption_required"`, `"storage.pool.expanding"`, `"storage.pool.layout_invalid"`, `"storage.pool.name_invalid"`, `"storage.pool.name_mismatch"`, `"storage.pool.name_taken"`, `"storage.pool.not_found"`, `"storage.pool.not_prepared"`, `"storage.pool.read_only"`, `"storage.pool.suspended"`, `"storage.schedule.invalid"`, `"storage.scrub.not_running"`, `"storage.scrub.running"`, `"storage.snapshot.confirmation_mismatch"`, `"storage.snapshot.dataset_not_found"`, `"storage.snapshot.exists"`, `"storage.snapshot.held"`, `"storage.snapshot.newer_exist"`, `"storage.snapshot.not_found"`, `"storage.snapshot.not_pithyx"`, `"storage.snapshot.schedule_invalid"`, `"storage.vdev.not_found"`, `"storage.vdev.not_raidz"`, `"storage.volume.size_invalid"`, `"storage.volume.too_large"`, `"storage.zfs.unavailable"`, `"store.app.not_found"`, `"store.catalog.architecture_missing"`, `"store.catalog.built_in"`, `"store.catalog.busy"`, `"store.catalog.data_version_decreased"`, `"store.catalog.exists"`, `"store.catalog.id_reserved"`, `"store.catalog.invalid_json"`, `"store.catalog.mismatch"`, `"store.catalog.not_found"`, `"store.catalog.rule_violation"`, `"store.catalog.schema_violation"`, `"store.catalog.sequence_old"`, `"store.catalog.signature_invalid"`, `"store.catalog.unreachable"`, `"store.catalog.url_invalid"`, `"store.catalog.version_unsupported"`, `"store.package.hash_mismatch"`, `"system.backup.category_missing"`, `"system.backup.invalid"`, `"system.backup.password_wrong"`, `"system.backup.restore_expired"`, `"system.backup.restore_failed"`, `"system.backup.restore_running"`, `"system.backup.too_large"`, `"system.backup.too_new"`, `"system.internal.unexpected"`, `"system.origin.forbidden"`, `"system.time.apply_failed"`, `"system.time.server_invalid"`, `"system.time.servers_too_many"`, `"system.time.zone_invalid"`, `"tls.custom.expired"`, `"tls.custom.invalid"`, `"tls.custom.key_mismatch"`, `"tls.issued.not_found"`, `"tls.name.invalid"`, `"tls.name.not_permitted"`, `"tls.names.missing"`, `"tls.names.too_many"`, `"tls.validity.out_of_range"`, `"update.apply.failed"`, `"update.apply.running"`, `"update.channel.invalid"`, `"update.channel.mismatch"`, `"update.channel.sequence_old"`, `"update.channel.signature_invalid"`, `"update.download.mismatch"`, `"update.file.architecture"`, `"update.file.channel"`, `"update.file.hash_mismatch"`, `"update.file.invalid"`, `"update.file.minimum"`, `"update.file.missing_entry"`, `"update.file.not_found"`, `"update.file.older"`, `"update.file.signature_invalid"`, `"update.file.too_large"`, `"update.file.unexpected_entry"`, `"update.none.available"`, `"update.rollback.unconfirmed"`, `"update.snapshot.not_found"`, `"update.source.invalid"`, `"update.source.unreachable"`, `"update.space.insufficient"`, `"update.system.unsupported"`, `"users.account.refused"`, `"users.gid.exhausted"`, `"users.group.builtin"`, `"users.group.description_invalid"`, `"users.group.exists"`, `"users.group.name_invalid"`, `"users.group.name_reserved"`, `"users.group.not_found"`, `"users.group.refused"`, `"users.uid.exhausted"`, `"users.user.exists"`, `"users.user.last_admin"`, `"users.user.not_found"`, `"users.user.self"` ## ErrorMessage A failed client message. `id` is empty when the message could not be parsed. | Field | Type | Required | Description | | ----------- | --------------------------------------------------- | -------- | ----------- | | `id` | string | yes | | | `code` | [ErrorCode](https://pithyx.org/docs/reference/api/schemas/#errorcode) | yes | | | `params` | map of object | yes | | | `type` | `"error"` | yes | | | `requestId` | string | yes | | ## EventMessage A change of a topic. `requestId` is the id of the action that caused it, if any. | Field | Type | Required | Description | | ----------- | --------- | -------- | ----------- | | `topic` | string | yes | | | `data` | object | yes | | | `type` | `"event"` | yes | | | `requestId` | string | yes | | ## FileEntry A file or folder in a share. | Field | Type | Required | Description | | ---------- | ------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `name` | string | yes | Name within its folder. | | `kind` | [FileKind](https://pithyx.org/docs/reference/api/schemas/#filekind) | yes | File, folder, symlink (not followed in listings) or another kind such as a device node. | | `size` | integer (int64) | yes | Bytes for files, 0 for folders. | | `modified` | string (date-time) | yes | Last change of the content, UTC. | ## FileKind Type: `"file"`, `"folder"`, `"symlink"`, `"other"` ## FileLocation | Field | Type | Required | Description | | --------- | --------------- | -------- | --------------------------- | | `shareId` | integer (int64) | yes | The share. | | `path` | string | yes | Path relative to the share. | ## FileOperationKind Type: `"copy"`, `"move"`, `"delete"` ## FileOperationRequest | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `kind` | [FileOperationKind](https://pithyx.org/docs/reference/api/schemas/#fileoperationkind) | yes | copy, move or delete. | | `items` | null \| [FileLocation](https://pithyx.org/docs/reference/api/schemas/#filelocation)[] | no | The files and folders to work on, at most 1000. Leave out when `AllIn` is given. | | `target` | null \| [FileLocation](https://pithyx.org/docs/reference/api/schemas/#filelocation) | no | The folder to copy or move into; not used for delete. | | `onConflict` | null \| [ConflictPolicy](https://pithyx.org/docs/reference/api/schemas/#conflictpolicy) | no | For copy and move; fail when left out. | | `permanent` | boolean | no | For delete: remove for good instead of moving to the share's recycle bin. Only when the user asked for it. | | `allIn` | null \| [FolderSelection](https://pithyx.org/docs/reference/api/schemas/#folderselection) | no | Every entry of a folder except some names: selecting a whole folder without sending its names. | ## FileServiceSettings The file services of the box. Administrators only. | Field | Type | Required | Description | | --------------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `smbEnabled` | boolean | yes | Whether SMB is switched on. | | `workgroup` | string | yes | The SMB workgroup, 1 to 15 letters, digits, dots, dashes and underscores. | | `sftpEnabled` | boolean | yes | Whether SFTP is switched on. | | `smb` | [FileServiceState](https://pithyx.org/docs/reference/api/schemas/#fileservicestate) | yes | How SMB is doing. | | `sftp` | [FileServiceState](https://pithyx.org/docs/reference/api/schemas/#fileservicestate) | yes | How SFTP is doing. | | `sshEnabled` | boolean | yes | Whether users with the SSH login right may sign in over SSH with a shell. Off by default. | | `webDavEnabled` | boolean | yes | Whether WebDAV is switched on, at `/webdav/` of the daemon's address. Off by default. | | `ftpEnabled` | boolean | yes | Whether FTP is switched on, with TLS (FTPS). Off by default. | | `ftpPlainAllowed` | boolean | yes | Whether FTP also works without TLS, at the users' own risk. Off by default. | | `ftp` | [FileServiceState](https://pithyx.org/docs/reference/api/schemas/#fileservicestate) | yes | How FTP is doing. | | `ftpPort` | integer (int32) | yes | The FTP control port. | | `ftpFingerprint` | null \| string | yes | The SHA-256 fingerprint of the FTPS certificate, for clients that ask whether to trust it; null until FTP ran once. | | `privateNetworksOnly` | boolean | yes | Whether the firewall lets only private networks (RFC 1918, ULA, link-local) reach SMB, SFTP, SSH and FTP. Off by default. | | `firewallActive` | boolean | yes | Whether the firewall is applied here; false on a development machine and in simulation, where the rules are only rendered. | ## FileServiceSettingsRequest Changes of the file services; fields left out stay. | Field | Type | Required | Description | | --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------ | | `smbEnabled` | null \| boolean | no | Switches SMB on or off. | | `workgroup` | null \| string | no | A new SMB workgroup. | | `sftpEnabled` | null \| boolean | no | Switches SFTP on or off. | | `sshEnabled` | null \| boolean | no | Switches SSH logins with a shell on or off for users with the SSH login right. | | `webDavEnabled` | null \| boolean | no | Switches WebDAV on or off. | | `ftpEnabled` | null \| boolean | no | Switches FTP (FTPS) on or off. | | `ftpPlainAllowed` | null \| boolean | no | Allows or refuses plain FTP without TLS; refusing it ends every plain session. | | `privateNetworksOnly` | null \| boolean | no | Limits SMB, SFTP, SSH and FTP to private networks, or lets every network reach them again. | ## FileServiceState How a file service is doing. Type: `"off"`, `"running"`, `"failed"`, `"unavailable"` ## FileVersion | Field | Type | Required | Description | | ----------- | ------------------------------------------------- | -------- | --------------------------------------------------- | | `snapshot` | string | yes | The snapshot the version is in; pass it to restore. | | `createdAt` | string (date-time) | yes | When the snapshot was taken (UTC). | | `kind` | [FileKind](https://pithyx.org/docs/reference/api/schemas/#filekind) | yes | File or folder. | | `size` | integer (int64) | yes | Bytes for files, 0 for folders. | | `modified` | string (date-time) | yes | Last change of the content in that version, UTC. | ## FileVersionList Response of `GET /api/files/{shareId}/versions`. | Field | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `path` | string | yes | The file or folder, relative to the share. | | `versions` | [FileVersion](https://pithyx.org/docs/reference/api/schemas/#fileversion)[] | yes | Newest first; empty when the share is not on a ZFS dataset. | ## FileVersionRestoreRequest | Field | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------------------------------------------ | | `path` | string | yes | The file or folder, relative to the share; it may have been deleted since. | | `snapshot` | string | yes | The snapshot to restore from, as listed. | | `overwrite` | boolean | no | Replace the current file (folders are merged) instead of restoring next to it. | ## FolderChanges What a folder topic sends: the names that changed since the last event, or a request to list again. | Field | Type | Required | Description | | --------- | -------- | -------- | --------------------------------------------------------------------------------- | | `changed` | object[] | yes | Entries that appeared or changed, with their current metadata. | | `removed` | string[] | yes | Names that are gone. | | `resync` | boolean | yes | True when changes were lost (the kernel queue overflowed); list the folder again. | | `gone` | boolean | yes | True when the folder itself was deleted or moved away. | ## FolderPage One page of a folder listing. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------ | | `path` | string | yes | The folder, relative to the share ("" for its root). | | `folderId` | string | yes | Stable id of the folder, also after a rename. | | `total` | integer (int32) | yes | Entries in the folder when the listing was made. | | `entries` | [FileEntry](https://pithyx.org/docs/reference/api/schemas/#fileentry)[] | yes | This page, in the requested order. | | `nextCursor` | null \| string | yes | Pass as `cursor` for the next page; null on the last page. | | `topic` | string | yes | WebSocket topic with live changes of this folder while it is subscribed. | ## FolderSelection Every entry of a folder except some names: selecting a whole folder without sending its names. | Field | Type | Required | Description | | -------- | --------------------------------------------------------- | -------- | ----------------------------------- | | `folder` | [FileLocation](https://pithyx.org/docs/reference/api/schemas/#filelocation) | yes | The folder whose entries are meant. | | `except` | string[] | yes | Names left out, at most 1000. | ## FolderWatchState The snapshot of a folder topic: the folder as the watch sees it. | Field | Type | Required | Description | | ---------- | ------- | -------- | ------------------------------------ | | `watching` | boolean | yes | Whether changes are being delivered. | ## GlobalNetworkConfig Settings of the whole box. | Field | Type | Required | Description | | ------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `hostName` | string | yes | The host name: letters, digits and hyphens, 1 to 63 characters. Samba uses its first 15 as the NetBIOS name. | | `dnsServers` | string[] | yes | Name servers, at most four; when set they replace those DHCP and router advertisements announce. | | `searchDomains` | string[] | yes | Domains tried for short names, at most six. | | `defaultInterface` | null \| string | no | The interface whose gateway carries the default route when several have one; null leaves it to the metrics. | ## GrantEntry One grant of a user or a group. | Field | Type | Required | Description | | ---------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `resource` | string | yes | `share:<id>`, `protocol:smb\|sftp\|webdav\|ftp`, `app:<id>` or `right:admin\|desktopLogin\|sshLogin\|power`. | | `level` | [GrantLevel](https://pithyx.org/docs/reference/api/schemas/#grantlevel) | yes | `read` or `readWrite` for a shared folder, `allow` for everything else. | ## GrantLevel How far a grant goes: `read` or `readWrite` for a shared folder, `allow` for everything else. Type: `"read"`, `"readWrite"`, `"allow"` ## GrantsRequest | Field | Type | Required | Description | | -------- | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `grants` | [GrantEntry](https://pithyx.org/docs/reference/api/schemas/#grantentry)[] | yes | Every grant the subject should have; the others go. A subject has at most one grant per resource. | ## GroupGrants The grants of a group. Administrators only. | Field | Type | Required | Description | | -------- | ------------------------------------------------------- | -------- | ------------------------- | | `grants` | [GrantEntry](https://pithyx.org/docs/reference/api/schemas/#grantentry)[] | yes | Every grant of the group. | ## GroupRef A group a user is in. | Field | Type | Required | Description | | ------ | --------------- | -------- | ---------------------------------- | | `id` | integer (int64) | yes | Stable id (the group's Linux gid). | | `name` | string | yes | The group name. | ## GroupSummary A group as the Users page shows it. Administrators only. | Field | Type | Required | Description | | ------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id, and the Linux gid: 30000 to 39999 and never reused, 100 for the built-in group. | | `name` | string | yes | The Linux group name, lower case. | | `description` | string | yes | Free text, may be empty. | | `builtin` | boolean | yes | The built-in group `users`: every user is a member, and it can neither be renamed nor deleted. | | `memberIds` | integer (int64)[] | yes | The ids of its members; every user for the built-in group. | | `createdAt` | string (date-time) | yes | When the group was created, UTC. | ## GroupUpdate Fields left out stay as they are. The built-in group takes none of them. | Field | Type | Required | Description | | ------------- | ------------------------- | -------- | -------------------------------------------------------- | | `name` | null \| string | no | A new name; the gid stays. | | `description` | null \| string | no | An empty text removes the description. | | `memberIds` | null \| integer (int64)[] | no | Every member the group should have; the others leave it. | ## GuardDecision Type: `"allowed"`, `"needsSerialConfirmation"`, `"refused"` ## GuardVerdict | Field | Type | Required | Description | | ---------- | ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `diskId` | string | yes | The disk the verdict is for. | | `decision` | [GuardDecision](https://pithyx.org/docs/reference/api/schemas/#guarddecision) | yes | Whether a destructive command may touch the disk. | | `reason` | string | yes | Why, as a stable code: `system_disk`, `read_only`, `mounted`, `pool_member`, `not_test_disk`, `duplicate_serial`, `no_serial`, `not_checked`, `has_data`, `confirmed` or `empty`; when a pool is imported, `importable` for an allowed disk. | | `pool` | null \| string | yes | The imported pool the disk belongs to, for `pool_member`. | | `contents` | string[] | yes | What was found on the disk: partitions and signature types. | ## HealthResponse | Field | Type | Required | Description | | -------- | ----------------------------------------------------- | -------- | ----------- | | `status` | string | yes | | | `mode` | [DaemonMode](https://pithyx.org/docs/reference/api/schemas/#daemonmode) | yes | | ## HomeInfo A home. | Field | Type | Required | Description | | --------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `shareId` | integer (int64) | yes | Its id as a share: Files opens it with this id. | | `folder` | string | yes | Its folder below `homes`: the user name, or `<name>.deleted-<uid>` after its user was deleted. | | `userId` | null (int64) \| integer (int64) | yes | Its user, or null when the user was deleted. | | `username` | null \| string | yes | The user's name, or null. | | `displayName` | null \| string | yes | The user's display name, or null. | | `pool` | null \| string | yes | The pool it is on. | | `usedBytes` | null (int64) \| integer (int64) | yes | Space it uses with its snapshots, or null while it cannot be read. | | `quotaBytes` | null (int64) \| integer (int64) | yes | Its quota as set on the pool, or null for none. | | `ownQuotaBytes` | null (int64) \| integer (int64) | yes | The user's own quota: null takes the default, 0 means none. | | `unavailable` | null \| string | yes | Why its files cannot be reached now, or null when they can. | ## HomeMoveRequest | Field | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------- | | `pool` | string | yes | The pool the homes move to; it needs the Pithyx layout and room for every home. | ## HomeOverview The homes as Settings shows them. Administrators only. | Field | Type | Required | Description | | ------------------- | --------------------------------------------------- | -------- | --------------------------------------------------------------------------- | | `pool` | null \| string | yes | The home pool, or null before the first pool that can take homes. | | `pools` | [HomePool](https://pithyx.org/docs/reference/api/schemas/#homepool)[] | yes | Every pool with whether it can take the homes. | | `defaultQuotaBytes` | null (int64) \| integer (int64) | yes | The quota of every home without its own, or null for none. | | `homes` | [HomeInfo](https://pithyx.org/docs/reference/api/schemas/#homeinfo)[] | yes | Every home, those of deleted users included. | | `moving` | null (int64) \| integer (int64) | yes | The job that moves the homes to another pool while it runs, otherwise null. | ## HomePool | Field | Type | Required | Description | | ---------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | The pool. | | `availableBytes` | null (int64) \| integer (int64) | yes | Free space for the homes, or null while it cannot be read. | | `unavailable` | null \| string | yes | Why it cannot take the homes (`missing`, `offline`, `read_only`, `not_prepared`, `locked`, `not_mounted`), or null when it can. | ## HomeQuotaRequest | Field | Type | Required | Description | | ------------ | ------------------------------- | -------- | ----------------------------------------------------------------------- | | `quotaBytes` | null (int64) \| integer (int64) | yes | The user's own quota: at least 1 MiB, 0 for none, null for the default. | ## HomeReleaseRequest | Field | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------- | | `shareId` | integer (int64) | yes | The shared folder that gets a folder with the home's files. | ## HomeSettingsRequest | Field | Type | Required | Description | | ------------------- | ------------------------------- | -------- | -------------------------------------------------------------------------- | | `defaultQuotaBytes` | null (int64) \| integer (int64) | yes | The quota of every home without its own: at least 1 MiB, or null for none. | ## ImportablePool | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `name` | string | yes | The pool's name as stored on its disks. | | `poolGuid` | string | yes | The numeric identifier as decimal text; `pool.import.readonly` takes it as `poolGuid`. | | `state` | string | yes | ZFS state as it would be imported: `ONLINE`, `DEGRADED`, `UNAVAIL` or `FAULTED`. | | `status` | null \| string | yes | What ZFS says is wrong, in English, if anything. | | `action` | null \| string | yes | What ZFS says can be done, in English. | | `messageId` | null \| string | yes | ZFS message id, for example `ZFS-8000-2Q` (devices missing) or `ZFS-8000-EY` (last used by another system). | | `canImport` | boolean | yes | True when ZFS can import the pool. | | `needsForce` | boolean | yes | True when it was last used by another system: importing needs `force` and the typed name. | | `nameTaken` | boolean | yes | True when an imported pool has this name: the import needs `newName`. | | `vdevs` | [ImportVdev](https://pithyx.org/docs/reference/api/schemas/#importvdev)[] | yes | The pool's layout with each device's state and disk. | | `disks` | [GuardVerdict](https://pithyx.org/docs/reference/api/schemas/#guardverdict)[] | yes | The guard's import verdict for each disk the pool is on. | | `unknownDevices` | string[] | yes | Present devices that are on no disk the daemon knows; such a pool is not offered. | | `allowed` | boolean | yes | True when the pool can be imported: ZFS can, and every device is on a disk the guard allows. | ## ImportScan Response of `POST /api/storage/import/scan`: pools on the disks that are not imported. Nothing was imported. | Field | Type | Required | Description | | ------- | --------------------------------------------------------------- | -------- | ----------- | | `pools` | [ImportablePool](https://pithyx.org/docs/reference/api/schemas/#importablepool)[] | yes | | ## ImportVdev | Field | Type | Required | Description | | ---------- | ------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Device or vdev name as `zpool import` prints it: `raidz1-0`, a by-id name, a path or, for a missing device, its GUID. | | `state` | null \| string | yes | ZFS state, for example `ONLINE` or `UNAVAIL`; null for the `logs`, `cache`, `spares`, `special` and `dedup` group headings, and for cache and spare devices, which an import lists without one. | | `detail` | null \| string | yes | What ZFS adds after the state, for example `cannot open` or `insufficient replicas`. | | `diskId` | null \| string | yes | The disk this device is on, if it is one the daemon knows. | | `children` | [ImportVdev](https://pithyx.org/docs/reference/api/schemas/#importvdev)[] | yes | Child vdevs. | ## InheritedGrant A grant that reaches a user through one of its groups. | Field | Type | Required | Description | | ----------- | ----------------------------------------------------- | -------- | ------------------------------- | | `resource` | string | yes | The resource, as in GrantEntry. | | `level` | [GrantLevel](https://pithyx.org/docs/reference/api/schemas/#grantlevel) | yes | The level, as in GrantEntry. | | `groupId` | integer (int64) | yes | The group that has the grant. | | `groupName` | string | yes | Its name. | ## InspectBackupRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------- | | `archive` | string | yes | The backup file, base64. | | `password` | string | yes | The password it was created with. | ## InstallAppRequest | Field | Type | Required | Description | | -------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `pool` | null \| string | no | The pool for the app data; required for the first app, and then always the app pool. | | `access` | null \| [AppAccess](https://pithyx.org/docs/reference/api/schemas/#appaccess) | no | Who may use the app after an install; an update keeps who may use it. Defaults to the preview's suggested access. | ## InstallerCheck A requirement the box must meet before the installation starts. | Field | Type | Required | Description | | -------- | ------- | -------- | -------------------------------------------------------------------------------------------- | | `id` | string | yes | `cpu` (x86-64-v2), `uefi`, `memory`, `secure_boot` (off) or `disk` (a suitable disk exists). | | `passed` | boolean | yes | Whether the box meets it. | | `params` | object | yes | Values for the text, for example `minGb` and `foundGb` of `memory`. | ## InstallerDisk A disk as the installer offers it. | Field | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `disk` | [Disk](https://pithyx.org/docs/reference/api/schemas/#disk) | yes | The disk. | | `suitable` | boolean | yes | Whether the system may be installed on it. | | `reason` | null \| string | yes | Why not: `boot_medium`, `read_only`, `in_use` (mounted or swap) or `too_small`. | | `hasData` | boolean | yes | Whether it holds partitions or file systems that the installation erases. | | `caution` | null \| string | yes | Flash that wears out under the system's writes: `usb` (a USB stick or disk) or `card` (a memory card or other removable medium); null otherwise, also for eMMC. | ## InstallerOptions Response of `GET /api/installer/options`: what the steps offer. | Field | Type | Required | Description | | ----------------- | ------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `disks` | [InstallerDisk](https://pithyx.org/docs/reference/api/schemas/#installerdisk)[] | yes | Every disk, suitable or not. | | `network` | [NetworkLink](https://pithyx.org/docs/reference/api/schemas/#networklink)[] | yes | The network cards with their state and addresses. | | `networkConfig` | [NetworkConfig](https://pithyx.org/docs/reference/api/schemas/#networkconfig) | yes | The network settings of the live system (set on the console, for example), the start of step 2. | | `timeZones` | string[] | yes | IANA time zone names. | | `keyboardLayouts` | string[] | yes | XKB layout codes for the console keyboard. | | `minDiskBytes` | integer (int64) | yes | The smallest disk the system fits on. | ## InstallerPhase Type: `"ready"`, `"installing"`, `"installed"`, `"failed"`, `"rebooting"` ## InstallerStatus Response of `GET /api/installer`. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `claimed` | boolean | yes | Whether a browser owns the installation. | | `owner` | boolean | yes | Whether this browser owns it. | | `phase` | [InstallerPhase](https://pithyx.org/docs/reference/api/schemas/#installerphase) | yes | Where the installation is. | | `step` | null \| string | yes | The step that runs or failed: `partition`, `raid`, `filesystems`, `copy`, `configure`, `bootloader` or `finish`. | | `stepIndex` | integer (int32) | yes | Zero-based position of Step. | | `stepCount` | integer (int32) | yes | Number of steps. | | `errorCode` | null \| string | yes | Why the installation failed. | | `errorParams` | object | yes | Values for its text; for `installer.install.failed` the `step`, the `command` and its `exitCode`. | | `installId` | null \| string | yes | Set once installed: the installed system answers it on `http://<address>/api/install-id`. | | `recoveryKey` | null \| string | yes | Set once installed, for the owner only: the administrator's recovery key, shown before the reboot. | | `version` | string | yes | The Pithyx version that gets installed. | | `checks` | [InstallerCheck](https://pithyx.org/docs/reference/api/schemas/#installercheck)[] | yes | The requirements and whether the box meets them. | ## InstallIdResponse Response of `GET /api/install-id` on an installed box. | Field | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `installId` | string | yes | | ## InstallRequest Body of `POST /api/installer/install`. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `hostname` | string | yes | Name of the box, a DNS label. | | `language` | string | yes | System language. | | `region` | null \| string | yes | Country of the formats, or null to follow each user's language. | | `timeZone` | string | yes | IANA time zone. | | `ntpServers` | string[] | yes | Time servers; empty for the defaults. | | `keyboardLayout` | string | yes | XKB layout of the console keyboard. | | `diskIds` | string[] | yes | One disk, or two for a mirror. | | `username` | string | yes | The administrator. | | `password` | string | yes | The administrator's password. | | `displayName` | null \| string | yes | The administrator's display name. | | `eraseConfirmed` | boolean | yes | The user confirmed that every listed disk is erased. | | `network` | null \| [NetworkConfig](https://pithyx.org/docs/reference/api/schemas/#networkconfig) | no | Everything Pithyx configures in the network. Cards that are not listed get their address by DHCP. | ## InstallUpdateRequest | Field | Type | Required | Description | | --------------- | ------- | -------- | --------------------------------------------------------------------- | | `source` | string | yes | `online` installs the channel's newest file, `file` the uploaded one. | | `includeDebian` | boolean | yes | Also install the Debian updates, in the same snapshot. | ## InterfaceConfig The settings Pithyx keeps for one interface. A network card without them gets its address by DHCP. | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `name` | string | yes | The interface: the kernel's name of a card, or the name of a bond or VLAN (1 to 15 characters). | | `kind` | [InterfaceKind](https://pithyx.org/docs/reference/api/schemas/#interfacekind) | yes | Card, bond or VLAN. | | `enabled` | boolean | no | False keeps the link down. | | `ipv4` | [Ipv4Mode](https://pithyx.org/docs/reference/api/schemas/#ipv4mode) | no | DHCP, static or off. | | `ipv4Address` | null \| string | no | For static: the address with prefix length, for example `192.168.1.10/24`. | | `ipv4Gateway` | null \| string | no | For static: the gateway, optional, inside the address's network. | | `ipv6` | [Ipv6Mode](https://pithyx.org/docs/reference/api/schemas/#ipv6mode) | no | Auto (router advertisements and DHCPv6), static or off. | | `ipv6Address` | null \| string | no | For static: the address with prefix length, for example `2001:db8::10/64`. | | `ipv6Gateway` | null \| string | no | For static: the gateway, optional, inside the address's network or link-local. | | `mtu` | null (int32) \| integer (int32) | no | The MTU in bytes, 1280 to 9000 (576 without IPv6); null keeps the default. | | `bond` | null \| [BondSettings](https://pithyx.org/docs/reference/api/schemas/#bondsettings) | no | For a bond: its cards and mode. | | `vlan` | null \| [VlanSettings](https://pithyx.org/docs/reference/api/schemas/#vlansettings) | no | For a VLAN: its parent and id. | ## InterfaceKind What an interface is: a network card, a bond of cards or a VLAN on a card or bond. Type: `"ethernet"`, `"bond"`, `"vlan"` ## Ipv4Mode How an interface gets its IPv4 address. Type: `"dhcp"`, `"static"`, `"off"` ## Ipv6Mode How an interface gets its IPv6 address: automatically (router advertisements and DHCPv6), static or none. Type: `"auto"`, `"static"`, `"off"` ## IssueCertificateRequest A certificate for another device. | Field | Type | Required | Description | | -------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | `names` | string[] | yes | DNS names (a leading `*.` for a wildcard) and addresses, 1 to 100, inside the authority's scope. | | `validityDays` | integer (int32) | yes | 1 to 825 days, never past the intermediate's end. | | `keyType` | [CertificateKeyType](https://pithyx.org/docs/reference/api/schemas/#certificatekeytype) | yes | ECDSA (default) or RSA for devices that take nothing else. | ## IssuedCertificate A certificate the authority issued for another device. Its key was handed out once and is not kept. | Field | Type | Required | Description | | ------------------ | --------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Its number on the box. | | `certificate` | [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | The certificate. | | `keyType` | [CertificateKeyType](https://pithyx.org/docs/reference/api/schemas/#certificatekeytype) | yes | The key it was made with. | | `createdAt` | string (date-time) | yes | When it was issued. | | `createdBy` | null \| string | yes | The administrator who issued it, if the account still had that name. | | `currentAuthority` | boolean | yes | It chains to the current root; false after a new authority replaced the old one. | ## IssuedCertificateFiles A newly issued certificate with its files; the private key is in this answer only. | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | `certificate` | [IssuedCertificate](https://pithyx.org/docs/reference/api/schemas/#issuedcertificate) | yes | The entry in the list. | | `certificatePem` | string | yes | The certificate followed by the intermediate, as servers take it. | | `privateKeyPem` | string | yes | The private key (PKCS #8, unencrypted). | ## Job A long operation of a user, such as copying files. Also the data of the `jobs/{id}` topics. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Also names the job's topic, `jobs/{id}`. | | `kind` | string | yes | What the job does, chosen by the module that started it (for example `files.copy`). | | `state` | [JobState](https://pithyx.org/docs/reference/api/schemas/#jobstate) | yes | Where the job is in its life. | | `progress` | [JobProgress](https://pithyx.org/docs/reference/api/schemas/#jobprogress) | yes | Live in the topic; in REST answers of running jobs at most about a second old. | | `parameters` | null \| [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | What the job was started with, as given by the module that started it. | | `result` | null \| [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | What the job produced, if it set a result. | | `errorCode` | null \| [ErrorCode](https://pithyx.org/docs/reference/api/schemas/#errorcode) | yes | Error code of a failed job. | | `errorParams` | null \| map of object | yes | Parameters of the error message of a failed job. | | `requestId` | string | yes | Request id of the request that started the job; the job's logs carry it. | | `createdAt` | string (date-time) | yes | When the job was queued (UTC). | | `startedAt` | null (date-time) \| string (date-time) | yes | When it started running (UTC). | | `finishedAt` | null (date-time) \| string (date-time) | yes | When it reached a final state (UTC). | ## JobList Snapshot of the `jobs` topic: the signed-in user's queued and running jobs, oldest first. | Field | Type | Required | Description | | ------ | ----------------------------------------- | -------- | ----------- | | `jobs` | [Job](https://pithyx.org/docs/reference/api/schemas/#job)[] | yes | | ## JobProgress How far a job is. Totals are 0 while unknown. | Field | Type | Required | Description | | ------------- | --------------- | -------- | ---------------------------------------------------- | | `itemsDone` | integer (int64) | yes | Items (for example files) finished so far. | | `itemsTotal` | integer (int64) | yes | Items in the whole job. | | `bytesDone` | integer (int64) | yes | Bytes processed so far. | | `bytesTotal` | integer (int64) | yes | Bytes in the whole job. | | `currentItem` | null \| string | yes | What the job works on right now, for example a path. | ## JobState Where a job is in its life. The last four are final and never change again. Type: `"queued"`, `"running"`, `"succeeded"`, `"failed"`, `"cancelled"`, `"interrupted"` ## JsonElement Type: object ## LacpRate How often LACP partners exchange their state: every 30 seconds or every second. Type: `"slow"`, `"fast"` ## LogArchiveState Type: `"off"`, `"ready"`, `"unavailable"` ## LogEntry One log entry of the daemon, a system service or an app. | Field | Type | Required | Description | | ----------- | --------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable within the current logs or the archive it comes from. | | `time` | string (date-time) | yes | When it happened, UTC. | | `level` | [LogLevelName](https://pithyx.org/docs/reference/api/schemas/#loglevelname) | yes | debug, info, warn or error. | | `source` | string | yes | `daemon`, `system/<service>` (for example `system/kernel`, `system/smbd`) or `app/<id>`. | | `message` | string | yes | The rendered message; secrets are masked before it is stored. | | `requestId` | null \| string | yes | The request id (W3C trace id) of the request that caused it, if any. | | `user` | null \| string | yes | The user an app entry was written for, if any. | | `data` | null \| map of string | yes | Further fields (event name, error code, path, the app's own data), as text. | | `archived` | boolean | yes | True when the entry comes from the archive on a pool. | ## LoginRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------- | | `username` | string | yes | | | `password` | string | yes | | ## LoginResponse | Field | Type | Required | Description | | -------------- | --------------------------------------------------------- | -------- | --------------------------------------------------- | | `user` | null \| [UserInfo](https://pithyx.org/docs/reference/api/schemas/#userinfo) | yes | The signed-in user. | | `totpRequired` | boolean | yes | True when a TOTP or recovery code must follow. | | `challenge` | null \| string | yes | Pass to `/api/auth/login/totp` within five minutes. | ## LogLevelName Type: `"debug"`, `"info"`, `"warn"`, `"error"` ## LogPage A page of entries, newest first. | Field | Type | Required | Description | | ------------ | --------------------------------------------------- | -------- | ------------------------------------------------------------------- | | `entries` | [LogEntry](https://pithyx.org/docs/reference/api/schemas/#logentry)[] | yes | At most the requested limit. | | `nextCursor` | null \| string | yes | Pass as `cursor` for the next, older page; null when there is none. | ## LogSettings Retention of the current logs on the system disk and of the optional archive on a pool. | Field | Type | Required | Description | | ---------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `retentionDays` | integer (int32) | yes | Current logs older than this are dropped (1 to 365). | | `maxBytes` | integer (int64) | yes | The current logs of the system and all apps together stay below this (64 MB to 4 GB); the oldest go first. | | `archiveEnabled` | boolean | yes | Whether entries are also kept in an archive on a pool. | | `archivePool` | null \| string | yes | The pool of the archive; null for the first pool. | | `archiveRetentionDays` | integer (int32) | yes | Archived entries older than this are dropped (1 to 3650). | | `archiveMaxBytes` | integer (int64) | yes | The archive stays below this (256 MB to 1 TB). | ## LogStatus The settings with what they hold now. | Field | Type | Required | Description | | --------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------- | | `settings` | [LogSettings](https://pithyx.org/docs/reference/api/schemas/#logsettings) | yes | The retention as set. | | `currentBytes` | integer (int64) | yes | Space the current logs take on the system disk. | | `currentOldest` | null (date-time) \| string (date-time) | yes | The oldest current entry, or null when there is none. | | `archiveState` | [LogArchiveState](https://pithyx.org/docs/reference/api/schemas/#logarchivestate) | yes | Whether the archive is off, written, or waiting for its pool. | | `archivePool` | null \| string | yes | The pool the archive is on or would be on, or null when there is no pool. | | `archiveBytes` | null (int64) \| integer (int64) | yes | Space the archive takes, or null without one. | | `archiveOldest` | null (date-time) \| string (date-time) | yes | The oldest archived entry, or null. | | `archivedAt` | null (date-time) \| string (date-time) | yes | When entries were last copied to the archive, or null. | | `pools` | string[] | yes | Pools that can hold the archive. | ## MarkNotificationsReadRequest Body of `POST /api/notifications/read`. | Field | Type | Required | Description | | ----- | ------------------------- | -------- | -------------------------------------------------------------------------- | | `ids` | null \| integer (int64)[] | no | The notifications to mark as read; null or missing marks every unread one. | ## NetworkChangeOrigin Where a change of the network came from. Type: `"web"`, `"console"` ## NetworkCheck What a change would do, before it is applied. | Field | Type | Required | Description | | -------------------- | ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `config` | [NetworkConfig](https://pithyx.org/docs/reference/api/schemas/#networkconfig) | yes | The settings as they would be stored (canonical form). | | `interfaces` | string[] | yes | The interfaces whose configuration changes. | | `hostNameChanged` | boolean | yes | Whether the host name changes. | | `connectionAffected` | boolean | yes | Whether the interface this browser's connection comes in on changes; the page warns. | | `addresses` | string[] | yes | Static addresses (without prefix) of the changed interfaces, to open after the change. | ## NetworkConfig Everything Pithyx configures in the network. Cards that are not listed get their address by DHCP. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------------- | -------- | ------------------------------------------------------- | | `interfaces` | [InterfaceConfig](https://pithyx.org/docs/reference/api/schemas/#interfaceconfig)[] | yes | Cards with their own settings, bonds and VLANs. | | `global` | [GlobalNetworkConfig](https://pithyx.org/docs/reference/api/schemas/#globalnetworkconfig) | yes | Host name, name servers, search domains, default route. | ## NetworkLink An interface as the system has it now. | Field | Type | Required | Description | | -------------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `name` | string | yes | The kernel's name, for example `enp1s0`. | | `kind` | [InterfaceKind](https://pithyx.org/docs/reference/api/schemas/#interfacekind) | yes | Card, bond or VLAN. | | `macAddress` | null \| string | yes | The hardware address. | | `up` | boolean | yes | Whether the interface is up and its link works. | | `carrier` | boolean | yes | Whether a cable (or the other end) is connected. | | `speedMbps` | null (int32) \| integer (int32) | yes | The link speed in Mbit/s, when the driver reports it. | | `duplex` | null \| string | yes | `full` or `half`, when the driver reports it. | | `mtu` | integer (int32) | yes | The MTU in bytes. | | `addresses` | string[] | yes | IPv4 and global IPv6 addresses with prefix length. | | `gateways` | string[] | yes | The default gateways reached through this interface. | | `dnsServers` | string[] | yes | The name servers this interface announced or was given. | | `defaultRoute` | boolean | yes | Whether this interface carries the default route (the lowest metric). | | `master` | null \| string | yes | The bond this card belongs to. | | `vlanParent` | null \| string | yes | For a VLAN: the interface that carries it. | | `vlanId` | null (int32) \| integer (int32) | yes | For a VLAN: its id. | | `method` | string | yes | `dhcp`, `static`, `off` or `unknown`: how its IPv4 address comes. | | `configured` | boolean | yes | Whether Pithyx keeps settings for it (otherwise a card gets DHCP). | | `changeable` | boolean | yes | Whether Pithyx may change it here; on a development machine only the interfaces in `/etc/pithyx/test-nics`. | ## NetworkState The network of the box. Administrators only. | Field | Type | Required | Description | | --------------------- | --------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `config` | [NetworkConfig](https://pithyx.org/docs/reference/api/schemas/#networkconfig) | yes | What Pithyx configured. | | `links` | [NetworkLink](https://pithyx.org/docs/reference/api/schemas/#networklink)[] | yes | Every card, bond and VLAN; container bridges and virtual cables are left out. | | `hostName` | string | yes | The host name the system has now. | | `globalChangeable` | boolean | yes | Whether Pithyx may change host name, name servers and the default route here; not on a development machine. | | `pending` | null \| [PendingNetworkChange](https://pithyx.org/docs/reference/api/schemas/#pendingnetworkchange) | yes | A change of the network waiting for its confirmation. | | `confirmSeconds` | integer (int32) | yes | How long a change waits for its confirmation before it is rolled back. | | `connectionInterface` | null \| string | yes | The interface this browser's connection comes in on, if known; empty in the live topic. | ## NetworkTestInterface One interface after a connection test of the installer. | Field | Type | Required | Description | | ------------------ | --------------- | -------- | ------------------------------------------------------------------ | | `name` | string | yes | The interface. | | `up` | boolean | yes | Whether its link came up. | | `addresses` | string[] | yes | The addresses it got. | | `gateways` | string[] | yes | Its gateways. | | `gatewayReachable` | null \| boolean | yes | Whether the first gateway answered a ping; null without a gateway. | ## NetworkTestStatus The connection test of the installer: the settings are applied, checked and rolled back. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ | | `running` | boolean | yes | Whether the test still runs; the page may lose its connection meanwhile. | | `interfaces` | [NetworkTestInterface](https://pithyx.org/docs/reference/api/schemas/#networktestinterface)[] | yes | What each tested interface got. | | `errorCode` | null \| string | yes | Why the test could not run. | | `errorParams` | object | yes | Values for its text. | ## NewDesktopItem | Field | Type | Required | Description | | -------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `kind` | [DesktopItemKind](https://pithyx.org/docs/reference/api/schemas/#desktopitemkind) | yes | What to create. | | `column` | integer (int32) | yes | Grid column. | | `row` | integer (int32) | yes | Grid row. | | `app` | null \| string | no | Shortcuts: the id of the app to open. Required for shortcuts, not allowed for notes. | | `name` | null \| string | no | Shortcuts: an own label, or null for the app's name. | | `text` | null \| string | no | Notes: the text, at most 4000 characters. Required for notes, not allowed for shortcuts. | ## NewFolderRequest | Field | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------- | | `path` | string | yes | The new folder, relative to the share. Its parent must exist. | ## NewGroup | Field | Type | Required | Description | | ------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name. | | `description` | null \| string | no | Optional, at most 200 characters. | | `memberIds` | null \| integer (int64)[] | no | The ids of the first members. | ## NewShare | Field | Type | Required | Description | | ------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Letters, digits, spaces, dots, dashes and underscores, 1 to 64 characters, not starting with a dot. | | `path` | string | yes | An existing folder on the host: absolute, without symlinks, outside the system directories and not overlapping another share. | ## NewUser | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `username` | string | yes | Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name. | | `password` | string | yes | At least 8 characters and not one of the most common passwords. | | `displayName` | null \| string | no | Optional, at most 64 characters. | | `groupIds` | null \| integer (int64)[] | no | The groups the user joins, besides the built-in group `users`. | | `grants` | null \| [GrantEntry](https://pithyx.org/docs/reference/api/schemas/#grantentry)[] | no | The user's own grants; when left out, the desktop login, SMB and the apps org.pithyx.files, org.pithyx.viewer and org.pithyx.demo. | ## Notification An entry of a user's notification history. The text is not part of it: the desktop translates `code` with `params` from the `notifications` namespace (`<code>.title`, `.body`). | Field | Type | Required | Description | | ----------- | ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id; never reused. | | `code` | string | yes | Message code, for example `jobs.job.failed`, `storage.alert.poolDegraded`, `storage.alert.resolved` or `app.message` (an app's own plain text in `params.title` and `params.body`). | | `params` | object | yes | Message parameters: strings and numbers, plus nested objects where a code says so. | | `tone` | [NotificationTone](https://pithyx.org/docs/reference/api/schemas/#notificationtone) | yes | How the desktop shows it. | | `app` | null \| string | yes | Id of the app that sent it; null for the system. | | `createdAt` | string (date-time) | yes | When it was created (UTC). | | `readAt` | null (date-time) \| string (date-time) | yes | When the user read it (UTC); null while unread. | ## NotificationEvent Event of the `notifications` topic. Only the user whose notifications changed receives it. | Field | Type | Required | Description | | -------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `change` | `"created"`, `"read"`, `"deleted"` | yes | What changed in a user's notifications. | | `notification` | null \| object | yes | An entry of a user's notification history. The text is not part of it: the desktop translates `code` with `params` from the `notifications` namespace (`<code>.title`, `.body`). | | `ids` | integer (int64)[] | yes | The notifications read or deleted; for `created` the ones dropped. | | `readAt` | null (date-time) \| string (date-time) | yes | When the notifications of a `read` event were read (UTC). | ## NotificationList Snapshot of the `notifications` topic and answer of `GET /api/notifications`. | Field | Type | Required | Description | | ------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `items` | [Notification](https://pithyx.org/docs/reference/api/schemas/#notification)[] | yes | The signed-in user's notifications, newest first; at most 200, none older than 30 days. | ## NotificationTone How a notification looks: the color of its card and toast. Type: `"info"`, `"success"`, `"warning"`, `"critical"` ## Partition | Field | Type | Required | Description | | ------------- | --------------- | -------- | ---------------------------------------------------------------- | | `name` | string | yes | Kernel name, for example `sda1`. | | `path` | string | yes | Device node. | | `sizeBytes` | integer (int64) | yes | Size in bytes. | | `fileSystem` | null \| string | yes | File system or content type, for example `ext4` or `zfs_member`. | | `label` | null \| string | yes | File system label, if any. | | `mountPoints` | string[] | yes | Where the partition is mounted; empty when it is not. | ## PasswordReset | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------- | | `password` | string | yes | The new password, with the same rules as everywhere. | ## PendingNetworkChange A change of the network waiting for its confirmation. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `id` | string (uuid) | yes | Pass to confirm or revert it. | | `deadline` | string (date-time) | yes | When it is rolled back unless confirmed, UTC. | | `interfaces` | string[] | yes | The interfaces it changed. | | `addresses` | string[] | yes | Static addresses (without prefix) it set; open one of them when the old address went away. | | `hostName` | null \| string | yes | The new host name, when it changed. | | `origin` | [NetworkChangeOrigin](https://pithyx.org/docs/reference/api/schemas/#networkchangeorigin) | yes | Settings in a browser or the menu on the console. | ## PermissionCatalog Every resource besides shared folders a grant can name, in the order the editors show them. | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------------------------------------------------------------------- | | `rights` | string[] | yes | The special rights. | | `protocols` | string[] | yes | The file protocols. | | `apps` | string[] | yes | The app ids given to users; the administration apps come with the administrator right. | ## PlannedCommand | Field | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------- | | `program` | string | yes | Program name. | | `arguments` | string[] | yes | Arguments, passed without a shell. | ## Pool | Field | Type | Required | Description | | ---------------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | Pool name. | | `poolGuid` | string | yes | Pool GUID as decimal text (it does not fit a JSON number). | | `state` | string | yes | ZFS state: `ONLINE`, `DEGRADED`, `FAULTED`, `OFFLINE`, `UNAVAIL`, `REMOVED` or `SUSPENDED`; degraded further when disks are gone that ZFS has not noticed yet. | | `sizeBytes` | integer (int64) | yes | Raw size of all vdevs, parity included. | | `allocatedBytes` | integer (int64) | yes | Raw space in use. | | `freeBytes` | integer (int64) | yes | Raw space free. | | `capacityPercent` | integer (int32) | yes | Share of the raw space in use. | | `fragmentationPercent` | null (int32) \| integer (int32) | yes | Free space fragmentation, if known. | | `readOnly` | boolean | yes | True when the pool was imported read-only. | | `dataErrors` | integer (int64) | yes | Number of files with permanent errors. | | `scan` | null \| [PoolScan](https://pithyx.org/docs/reference/api/schemas/#poolscan) | yes | The last or running scrub or resilver, if any. | | `vdevs` | [Vdev](https://pithyx.org/docs/reference/api/schemas/#vdev)[] | yes | Top-level vdevs, including log, cache, special and spare devices. | | `expansion` | null \| [PoolExpansion](https://pithyx.org/docs/reference/api/schemas/#poolexpansion) | no | A RAID-Z expansion (OpenZFS 2.3): a disk attached to a raidz vdev, onto which ZFS spreads the existing data. | ## PoolExpansion A RAID-Z expansion (OpenZFS 2.3): a disk attached to a raidz vdev, onto which ZFS spreads the existing data. | Field | Type | Required | Description | | -------------------- | -------------------------------------- | -------- | -------------------------------------------------------------- | | `state` | string | yes | `scanning` while it runs, then `finished` or `canceled`. | | `vdevGuid` | null \| string | yes | GUID of the raidz vdev that grows, if it is still in the pool. | | `startedAt` | null (date-time) \| string (date-time) | yes | When it started (UTC). | | `endedAt` | null (date-time) \| string (date-time) | yes | When it ended (UTC), if it did. | | `toReflowBytes` | integer (int64) | yes | Bytes to move onto the new layout. | | `reflowedBytes` | integer (int64) | yes | Bytes moved so far. | | `waitingForResilver` | boolean | yes | True while it waits for a resilver to finish. | ## PoolList Snapshot and event of `storage/pools`, and response of `GET /api/storage/pools`. | Field | Type | Required | Description | | ---------- | ------------------------------------------------- | -------- | ----------- | | `pools` | [Pool](https://pithyx.org/docs/reference/api/schemas/#pool)[] | yes | | | `datasets` | [Dataset](https://pithyx.org/docs/reference/api/schemas/#dataset)[] | yes | | ## PoolScan | Field | Type | Required | Description | | ---------------- | -------------------------------------- | -------- | ------------------------------------- | | `kind` | string | yes | Scan kind: `scrub` or `resilver`. | | `state` | string | yes | `scanning`, `finished` or `canceled`. | | `paused` | boolean | yes | True for a paused scrub. | | `startedAt` | null (date-time) \| string (date-time) | yes | When the scan started (UTC). | | `endedAt` | null (date-time) \| string (date-time) | yes | When it ended (UTC), if it did. | | `toExamineBytes` | integer (int64) | yes | Bytes the scan covers. | | `examinedBytes` | integer (int64) | yes | Bytes examined so far. | | `errors` | integer (int64) | yes | Errors the scan found. | ## PowerAction What the power button does. Type: `"restart"`, `"shutdown"` ## PowerRequest | Field | Type | Required | Description | | -------- | ------------------------------------------------------- | -------- | ------------------------ | | `action` | [PowerAction](https://pithyx.org/docs/reference/api/schemas/#poweraction) | yes | `restart` or `shutdown`. | ## ProcessList Snapshot and event of `system/processes`. | Field | Type | Required | Description | | ----------- | ------------------ | -------- | ------------------------------------ | | `at` | string (date-time) | yes | When the list was read (UTC). | | `processes` | object[] | yes | Every process except kernel threads. | ## ProxyBasicAuthUser A user of the host's Basic Auth. | Field | Type | Required | Description | | ---------- | -------------- | -------- | ---------------------------------------------------------------------- | | `username` | string | yes | 1 to 64 characters without a colon. | | `password` | null \| string | no | The password; leave it out to keep the stored one of an existing user. | ## ProxyCertificateSource Which certificate a host presents on 443. Type: `"box"`, `"custom"` ## ProxyHeader A header the proxy sets; an empty value removes it. | Field | Type | Required | Description | | ------- | ------ | -------- | -------------------------------------------------------------------------------- | | `name` | string | yes | The header's name, letters, digits and `-`; never one the proxy controls itself. | | `value` | string | yes | Its value, at most 4096 characters, without line breaks. | ## ProxyHost A proxy host as Settings shows it. | Field | Type | Required | Description | | ------------------------ | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ | | `id` | integer (int64) | yes | Its number on the box. | | `domains` | string[] | yes | The names it answers. | | `enabled` | boolean | yes | It answers. | | `target` | [ProxyTarget](https://pithyx.org/docs/reference/api/schemas/#proxytarget) | yes | Where requests go. | | `webSockets` | boolean | yes | WebSocket upgrades pass. | | `http2` | boolean | yes | HTTP/2 is offered on 443. | | `certificate` | [ProxyCertificateSource](https://pithyx.org/docs/reference/api/schemas/#proxycertificatesource) | yes | Which certificate it presents. | | `presented` | null \| [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | One certificate as Settings shows it. | | `forceHttps` | boolean | yes | Plain HTTP is redirected to HTTPS. | | `hsts` | boolean | yes | HTTPS answers carry `Strict-Transport-Security`. | | `forwardedHeaders` | boolean | yes | `X-Forwarded-*` go to the target. | | `preserveHost` | boolean | yes | The browser's `Host` goes to the target. | | `hostHeader` | null \| string | yes | The `Host` of the administrator's choice, if any. | | `requestHeaders` | [ProxyHeader](https://pithyx.org/docs/reference/api/schemas/#proxyheader)[] | yes | Headers set on requests. | | `responseHeaders` | [ProxyHeader](https://pithyx.org/docs/reference/api/schemas/#proxyheader)[] | yes | Headers set on answers. | | `maxBodyMegabytes` | null (int32) \| integer (int32) | yes | The upload limit in MB, or none. | | `connectTimeoutSeconds` | integer (int32) | yes | The connect timeout. | | `responseTimeoutSeconds` | integer (int32) | yes | The idle timeout of an answer. | | `allowAddresses` | string[] | yes | Only these get in, or everybody when empty. | | `denyAddresses` | string[] | yes | These never get in. | | `basicAuthUsers` | string[] | yes | The user names of the Basic Auth; passwords are never shown. | | `signIn` | [ProxySignInRule](https://pithyx.org/docs/reference/api/schemas/#proxysigninrule) | yes | The Pithyx sign-in in front of the host. | | `accessLog` | boolean | yes | Requests are logged. | | `logSource` | string | yes | The Log Center's source of its requests. | | `createdAt` | string (date-time) | yes | When it was made. | | `updatedAt` | string (date-time) | yes | When it was last saved. | ## ProxyHostRequest A proxy host as an administrator saves it. | Field | Type | Required | Description | | ------------------------ | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `domains` | string[] | yes | 1 to 50 DNS names, a leading `*.` for any one label in front; no name of another host. | | `enabled` | boolean | yes | The host answers; a disabled one is treated as unknown. | | `target` | [ProxyTarget](https://pithyx.org/docs/reference/api/schemas/#proxytarget) | yes | Where requests go. | | `webSockets` | boolean | yes | Pass WebSocket upgrades through. | | `http2` | boolean | yes | Offer HTTP/2 to browsers on 443. | | `certificate` | [ProxyCertificateSource](https://pithyx.org/docs/reference/api/schemas/#proxycertificatesource) | yes | Which certificate the host presents on 443. | | `forceHttps` | boolean | yes | Redirect plain HTTP on 80 to HTTPS on 443. | | `hsts` | boolean | yes | Send `Strict-Transport-Security` on HTTPS; browsers then refuse plain HTTP and any certificate warning for a year. | | `forwardedHeaders` | boolean | yes | Send `X-Forwarded-For`, `-Proto` and `-Host`; incoming ones are always dropped. | | `preserveHost` | boolean | yes | Send the browser's `Host` instead of the target's. | | `hostHeader` | null \| string | yes | A `Host` of your own; overrides PreserveHost. | | `requestHeaders` | [ProxyHeader](https://pithyx.org/docs/reference/api/schemas/#proxyheader)[] | yes | Headers set on the request to the target, at most 20. | | `responseHeaders` | [ProxyHeader](https://pithyx.org/docs/reference/api/schemas/#proxyheader)[] | yes | Headers set on the answer to the browser, at most 20. | | `maxBodyMegabytes` | null (int32) \| integer (int32) | yes | The largest upload in MB (1 to 1048576); none for no limit. | | `connectTimeoutSeconds` | integer (int32) | yes | How long connecting to the target may take, 1 to 300 seconds. | | `responseTimeoutSeconds` | integer (int32) | yes | How long the target may stay silent, 1 to 86400 seconds. | | `allowAddresses` | string[] | yes | Only these addresses or CIDR ranges get in; empty for everybody. | | `denyAddresses` | string[] | yes | These addresses or ranges never get in. | | `basicAuth` | [ProxyBasicAuthUser](https://pithyx.org/docs/reference/api/schemas/#proxybasicauthuser)[] | yes | Users of Basic Auth, at most 20; empty for none. | | `signIn` | [ProxySignInRule](https://pithyx.org/docs/reference/api/schemas/#proxysigninrule) | yes | The Pithyx sign-in in front of the host. | | `accessLog` | boolean | yes | Log every request in the Log Center under `proxy/<first domain>`. | | `certificatePem` | null \| string | no | With ProxyCertificateSource.Custom: the certificate and its chain in PEM; leave it out to keep the uploaded one. | | `privateKeyPem` | null \| string | no | Its unencrypted private key in PEM. | ## ProxyOptionsRequest The settings that apply to every host. | Field | Type | Required | Description | | --------------- | ------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `unknownHosts` | [UnknownHostAction](https://pithyx.org/docs/reference/api/schemas/#unknownhostaction) | yes | What a name no enabled host has gets. | | `signInAddress` | null \| string | no | An `https://` or `http://` origin the box's sign-in answers at, such as a proxy host in front of 7484; none for the requested name on 7484. | ## ProxyRedirect A redirect host as Settings shows it. | Field | Type | Required | Description | | -------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------- | | `id` | integer (int64) | yes | Its number on the box. | | `domains` | string[] | yes | The names it answers. | | `enabled` | boolean | yes | It answers. | | `target` | string | yes | Where it sends browsers. | | `status` | integer (int32) | yes | The redirect's status code. | | `preservePath` | boolean | yes | The path and query are kept. | | `certificate` | [ProxyCertificateSource](https://pithyx.org/docs/reference/api/schemas/#proxycertificatesource) | yes | Which certificate it presents. | | `presented` | null \| [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | One certificate as Settings shows it. | | `createdAt` | string (date-time) | yes | When it was made. | | `updatedAt` | string (date-time) | yes | When it was last saved. | ## ProxyRedirectRequest A redirect host as an administrator saves it. | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `domains` | string[] | yes | 1 to 50 DNS names, as for a proxy host. | | `enabled` | boolean | yes | The host answers. | | `target` | string | yes | An absolute `http` or `https` URL. | | `status` | integer (int32) | yes | 301, 302, 307 or 308. | | `preservePath` | boolean | yes | Append the request's path and query to Target. | | `certificate` | [ProxyCertificateSource](https://pithyx.org/docs/reference/api/schemas/#proxycertificatesource) | yes | Which certificate the host presents on 443. | | `certificatePem` | null \| string | no | With ProxyCertificateSource.Custom: the certificate and chain; leave it out to keep the uploaded one. | | `privateKeyPem` | null \| string | no | Its unencrypted private key. | ## ProxySettings Settings > Reverse proxy. | Field | Type | Required | Description | | --------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `plainPort` | null (int32) \| integer (int32) | yes | The port proxy hosts answer plain HTTP on (80 on a box); none in development unless set. | | `tlsPort` | null (int32) \| integer (int32) | yes | The port proxy hosts answer HTTPS on (443 on a box); none without HTTPS. | | `unknownHosts` | [UnknownHostAction](https://pithyx.org/docs/reference/api/schemas/#unknownhostaction) | yes | What a name no enabled host has gets. | | `signInAddress` | null \| string | yes | Where the Pithyx sign-in of a host sends visitors; none for the requested name on 7484. | | `hosts` | [ProxyHost](https://pithyx.org/docs/reference/api/schemas/#proxyhost)[] | yes | The proxy hosts. | | `redirects` | [ProxyRedirect](https://pithyx.org/docs/reference/api/schemas/#proxyredirect)[] | yes | The redirect hosts. | | `streams` | [ProxyStream](https://pithyx.org/docs/reference/api/schemas/#proxystream)[] | yes | The streams. | ## ProxySignInRule Who may pass the host's Pithyx sign-in. | Field | Type | Required | Description | | ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------- | | `required` | boolean | yes | Visitors sign in with their account on the box first. | | `users` | string[] | yes | User names allowed besides the groups; administrators always are. | | `groups` | string[] | yes | Group names whose members are allowed. With no users and no groups, everybody who may sign in is. | ## ProxyStream A stream as Settings shows it. | Field | Type | Required | Description | | ------------ | ------------------ | -------- | --------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Its number on the box. | | `name` | string | yes | What it is for. | | `enabled` | boolean | yes | The port is open. | | `port` | integer (int32) | yes | The box's port. | | `tcp` | boolean | yes | TCP is forwarded. | | `udp` | boolean | yes | UDP is forwarded. | | `targetHost` | string | yes | Where it forwards to. | | `targetPort` | integer (int32) | yes | The target's port. | | `listening` | boolean | yes | The box listens on the port now; false while disabled or when another program holds it. | | `createdAt` | string (date-time) | yes | When it was made. | | `updatedAt` | string (date-time) | yes | When it was last saved. | ## ProxyStreamRequest A stream as an administrator saves it. | Field | Type | Required | Description | | ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------- | | `name` | string | yes | What it is for, at most 100 characters. | | `enabled` | boolean | yes | The port is open and forwards. | | `port` | integer (int32) | yes | The box's port; not one of the box's own services, below 1024 only with PrivilegedPort. | | `tcp` | boolean | yes | Forward TCP. | | `udp` | boolean | yes | Forward UDP. | | `targetHost` | string | yes | A DNS name or IP address. | | `targetPort` | integer (int32) | yes | 1 to 65535. | | `privilegedPort` | boolean | no | The administrator confirmed a port below 1024. | ## ProxyTarget Where a proxy host forwards to. | Field | Type | Required | Description | | -------- | ------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- | | `scheme` | string | yes | `http` or `https`. | | `host` | string | yes | A DNS name or IP address. | | `port` | integer (int32) | yes | 1 to 65535. | | `tls` | [ProxyTargetTls](https://pithyx.org/docs/reference/api/schemas/#proxytargettls) | yes | How an HTTPS target's certificate is checked. | | `onBox` | boolean | yes | The administrator confirmed that the target is a service of this box itself. | ## ProxyTargetStatus Whether a proxy host's target answers. | Field | Type | Required | Description | | -------------- | ------------------------------- | -------- | ------------------------------------------------------- | | `reachable` | boolean | yes | The target answered with any HTTP status. | | `status` | null (int32) \| integer (int32) | yes | Its status code, if it answered. | | `error` | null \| string | yes | Why not: `timeout`, `refused`, `dns`, `tls` or `other`. | | `milliseconds` | integer (int64) | yes | How long the check took. | ## ProxyTargetTls How the proxy checks the certificate of an HTTPS target. Type: `"system"`, `"box"`, `"none"` ## ProxyTicket Where the browser goes next: the proxy host's sign-in address with a one-time ticket. | Field | Type | Required | Description | | ----- | ------ | -------- | -------------------- | | `url` | string | yes | The address to open. | ## ProxyTicketRequest A browser wants into a proxy host with the Pithyx sign-in. | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------- | | `url` | string | yes | The address it asked for. | ## RecoverRequest | Field | Type | Required | Description | | ------------- | ------ | -------- | ----------- | | `username` | string | yes | | | `recoveryKey` | string | yes | | | `newPassword` | string | yes | | ## RecoverResponse | Field | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------- | | `recoveryKey` | string | yes | The new recovery key. The old one no longer works. | ## RecoveryCodes | Field | Type | Required | Description | | ------- | -------- | -------- | ----------------------------------------------------------------- | | `codes` | string[] | yes | Shown exactly once. Each code replaces a TOTP code for one login. | ## RenameRequest | Field | Type | Required | Description | | ------ | ------ | -------- | -------------------------------- | | `path` | string | yes | The file or folder to rename. | | `name` | string | yes | The new name in the same folder. | ## ResourceSample One second of the box, the event of `system/resources`. Rates are per second since the previous sample. | Field | Type | Required | Description | | --------------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `at` | string (date-time) | yes | When it was measured (UTC). | | `uptimeSeconds` | number (double) | yes | Seconds since boot. | | `loadAverage` | number (double)[] | yes | Over 1, 5 and 15 minutes. | | `cpu` | object | yes | | | `memory` | object | yes | Physical memory split the way the monitor draws it. On Linux the ZFS ARC is not part of the page cache, so the kernel counts it as used; UsedBytes leaves it out and ArcBytes shows it. | | `network` | object[] | yes | Every interface except the loopback and container links. | | `disks` | object[] | yes | Every whole disk (no partitions, zvols or loop devices). | | `temperatures` | object[] | yes | Every sensor found; empty where the hardware or a virtual machine has none. | ## ResourceSnapshot Snapshot of `system/resources`: what the box is and the last hour, as far as someone watched it. | Field | Type | Required | Description | | ------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cpuCount` | integer (int32) | yes | Cores the kernel lists. | | `memoryTotalBytes` | integer (int64) | yes | Installed memory the kernel manages. | | `history` | object | yes | The ring buffer of the last hour, averaged into buckets so the snapshot stays small. Every series has one entry per time; a device that did not exist at a time has null there. | | `latest` | null \| object | yes | One second of the box, the event of `system/resources`. Rates are per second since the previous sample. | ## RestoreBackupRequest | Field | Type | Required | Description | | ------------ | --------------------------------------------------------------- | -------- | --------------------------------------------------------------- | | `restoreId` | string | yes | From the summary of the checked backup. | | `categories` | [BackupCategory](https://pithyx.org/docs/reference/api/schemas/#backupcategory)[] | yes | The parts to restore; each replaces the current one completely. | ## RestorePointsRequest | Field | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------- | | `enabled` | boolean | yes | Daily restore points, kept 7 days, on or off. | ## RestoreProblem A step of a restore that did not work; the rest was restored. | Field | Type | Required | Description | | ---------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `category` | [BackupCategory](https://pithyx.org/docs/reference/api/schemas/#backupcategory) | yes | The part it belongs to. | | `step` | string | yes | `accounts` (Linux accounts and groups), `linuxPasswords`, `sambaPasswords`, `time`, `tls` or `sshKeys`. | ## RestoreResult | Field | Type | Required | Description | | ------------ | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ | | `restored` | [BackupCategory](https://pithyx.org/docs/reference/api/schemas/#backupcategory)[] | yes | The parts that were restored. | | `problems` | [RestoreProblem](https://pithyx.org/docs/reference/api/schemas/#restoreproblem)[] | yes | Steps that failed; details are in the Log Center. | | `restarting` | boolean | yes | The daemon restarts in a few seconds to load the restored configuration. | ## RollbackRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------ | | `snapshot` | string | yes | The snapshot to restore. | | `version` | string | yes | Its version, typed by the administrator as the confirmation. | ## SavedLayout | Field | Type | Required | Description | | --------- | ------------------------------------------------------- | -------- | --------------------------------------------- | | `layout` | [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | The layout now saved for this device. | | `version` | integer (int64) | yes | Its version, for `If-Match` on the next save. | ## ServerMessage Type: [AckMessage](https://pithyx.org/docs/reference/api/schemas/#ackmessage) \| [SnapshotMessage](https://pithyx.org/docs/reference/api/schemas/#snapshotmessage) \| [EventMessage](https://pithyx.org/docs/reference/api/schemas/#eventmessage) \| [ErrorMessage](https://pithyx.org/docs/reference/api/schemas/#errormessage) ## SessionPermissions What the signed-in user may do outside shared folders, for the desktop: which apps it shows and whether the power menu is there. | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------------------------------------------------------------------------- | | `admin` | boolean | yes | Administrators may do everything. | | `rights` | string[] | yes | The special rights: `right:admin`, `right:desktopLogin`, `right:sshLogin`, `right:power`. | | `protocols` | string[] | yes | The file protocols: `protocol:smb`, `protocol:sftp`, `protocol:webdav`, `protocol:ftp`. | | `apps` | string[] | yes | The ids of the apps of IReadOnlyList<string> PermissionCatalog.Apps the user may open. | ## SetupRequest | Field | Type | Required | Description | | ------------- | -------------- | -------- | ----------- | | `username` | string | yes | | | `password` | string | yes | | | `displayName` | null \| string | no | | ## SetupResponse | Field | Type | Required | Description | | ------------- | ------------------------------------------------- | -------- | --------------------------------------------------------------------------- | | `user` | [UserInfo](https://pithyx.org/docs/reference/api/schemas/#userinfo) | yes | The administrator, already signed in. | | `recoveryKey` | string | yes | Shown exactly once. It is the only way to reset the administrator password. | ## SetupStatus | Field | Type | Required | Description | | ----------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `required` | boolean | yes | True until the first administrator exists. | | `hostname` | string | yes | Shown on the setup and sign-in screens, so users with several servers know where they sign in. | | `language` | string | yes | The system language, for the sign-in page and everyone whose browser asks for a language Pithyx does not have. | | `region` | null \| string | yes | The ISO 3166 country code whose formats every user sees, or null to follow each user's language. | | `installer` | boolean | yes | True on the live system of the ISO: the desktop shows the installer (`/api/installer`) instead of the sign-in. | ## ShareAccess Type: `"none"`, `"read"`, `"readWrite"` ## ShareDataChoice Type: `"keep"`, `"destroy"`, `null` ## ShareDetails A share with what the Shared folders page shows. Administrators only. | Field | Type | Required | Description | | ---------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id. | | `name` | string | yes | Name shown to users. | | `description` | string | yes | Free text for administrators and users, may be empty. | | `path` | string | yes | The share root on the host. | | `pool` | null \| string | yes | The pool of the share's dataset; null for a folder share. | | `dataset` | null \| string | yes | Full name of the share's dataset, for example `tank/pithyx/shares/media`; null for a folder share (development only). | | `usedBytes` | null (int64) \| integer (int64) | yes | Space the dataset uses with its snapshots; null for a folder share or while the dataset is not there (pool missing). | | `availableBytes` | null (int64) \| integer (int64) | yes | Space still available to the dataset; null like UsedBytes. | | `quotaBytes` | null (int64) \| integer (int64) | yes | The dataset's quota, or null for none. | | `readUsers` | integer (int32) | yes | Active users other than administrators who may read, through their own grants or their groups. | | `readWriteUsers` | integer (int32) | yes | Active users other than administrators who may read and write, through their own grants or their groups. | | `restorePoints` | null \| boolean | yes | Whether daily restore points (snapshots kept 7 days) are on; null for a folder share. | | `smb` | boolean | yes | Whether SMB offers the shared folder (dataset shares only). | | `sftp` | boolean | yes | Whether SFTP shows the shared folder (dataset shares only). | | `smbEncrypt` | boolean | yes | Whether SMB clients must encrypt. | | `webDav` | boolean | yes | Whether WebDAV offers the shared folder. | | `ftp` | boolean | yes | Whether FTP offers the shared folder. | ## ShareGrants Who may use a shared folder. Administrators only. | Field | Type | Required | Description | | -------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `grants` | [SubjectGrant](https://pithyx.org/docs/reference/api/schemas/#subjectgrant)[] | yes | The grants of users and groups on it; the editor changes these. | | `users` | [ShareUserAccess](https://pithyx.org/docs/reference/api/schemas/#shareuseraccess)[] | yes | Every user with the access it ends up with, administrators and deactivated users included. | ## ShareGrantsRequest | Field | Type | Required | Description | | -------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------- | | `grants` | [SubjectGrant](https://pithyx.org/docs/reference/api/schemas/#subjectgrant)[] | yes | Every grant the shared folder should have; the others go. | ## ShareInfo A share the user can use. | Field | Type | Required | Description | | ------------- | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id; file paths are relative to the share. | | `name` | string | yes | Name shown to users: the shared folder's name, `home` for the caller's home, the folder name for another user's home. | | `access` | [ShareAccess](https://pithyx.org/docs/reference/api/schemas/#shareaccess) | yes | The user's access: read or read and write. | | `path` | null \| string | yes | The share root on the host. Only administrators get it. | | `unavailable` | null \| string | no | Why its files cannot be reached now (ShareAvailability), or null when they can. | | `kind` | [ShareKind](https://pithyx.org/docs/reference/api/schemas/#sharekind) | no | A shared folder, the caller's home or another user's home. | ## ShareKind What a share is. Type: `"share"`, `"home"`, `"userHome"` ## ShareListRevision Snapshot and event of `shares/list`. | Field | Type | Required | Description | | ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------- | | `revision` | integer (int64) | yes | Changes whenever a user's list of usable shares may have changed; compare it, do not count on it. | ## SharePlanRequest A shared folder action to plan. `share.create` needs Name and Pool (Description is optional); `share.delete` needs ShareId, ConfirmName and Data. | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `action` | string | yes | `share.create` or `share.delete`. | | `name` | null \| string | no | Name of the new shared folder; its dataset name is derived from it and shown in the plan. | | `pool` | null \| string | no | Pool of the new shared folder; it needs the Pithyx layout (`<pool>/pithyx/shares`). | | `description` | null \| string | no | Description of the new shared folder. | | `shareId` | null (int64) \| integer (int64) | no | The shared folder to delete. | | `confirmName` | null \| string | no | The shared folder's name, typed by the user to delete it. | | `data` | null \| [ShareDataChoice](https://pithyx.org/docs/reference/api/schemas/#sharedatachoice) | no | `keep` leaves the dataset or folder with its files, `destroy` destroys the dataset and its snapshots (dataset shares only). | ## ShareUpdate Changes of a share; fields left out stay. The dataset is never renamed by this. | Field | Type | Required | Description | | ------------- | --------------- | -------- | ------------------------------------------------------------ | | `name` | null \| string | no | New name shown to users, unique like every share name. | | `description` | null \| string | no | New description, at most 200 characters, empty to remove it. | | `smb` | null \| boolean | no | Offers the shared folder over SMB or stops it. | | `sftp` | null \| boolean | no | Shows the shared folder over SFTP or hides it. | | `smbEncrypt` | null \| boolean | no | Requires SMB clients to encrypt, or lets them choose. | | `webDav` | null \| boolean | no | Offers the shared folder over WebDAV or stops it. | | `ftp` | null \| boolean | no | Offers the shared folder over FTP or stops it. | ## ShareUserAccess One user's effective access to a shared folder. | Field | Type | Required | Description | | --------------- | ------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `userId` | integer (int64) | yes | The user's id. | | `username` | string | yes | Login name. | | `displayName` | null \| string | yes | Name shown, if set. | | `administrator` | boolean | yes | Administrators use every shared folder with read and write. | | `disabled` | boolean | yes | Deactivated users use none. | | `access` | [ShareAccess](https://pithyx.org/docs/reference/api/schemas/#shareaccess) | yes | What the user ends up with: `none`, `read` or `readWrite`. | ## SmartReport SMART health of one disk as last read. The API serves it from memory; reading it never runs a command. | Field | Type | Required | Description | | ---------------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `diskId` | string | yes | The disk's id. | | `state` | string | yes | `passed`, `warning` (reallocated, pending or uncorrectable sectors, media errors or a failed self-test), `failed` (the drive predicts its failure), `unsupported` (no SMART, see Reason) or `unknown` (not read yet, asleep since the daemon started, or the read failed). | | `reason` | null \| string | yes | For `unsupported`: `virtual` (a disk of a virtual machine) or `not_available`. For `unknown`: `asleep`, `not_read` or `read_failed`. Otherwise null. | | `asleep` | boolean | yes | True when the last check found the disk asleep; the values are then from ReadAt. | | `temperatureCelsius` | null (int32) \| integer (int32) | yes | Current temperature, if reported. | | `powerOnHours` | null (int64) \| integer (int64) | yes | Power-on time, if reported. | | `reallocatedSectors` | null (int64) \| integer (int64) | yes | ATA attribute 5, raw value. | | `pendingSectors` | null (int64) \| integer (int64) | yes | ATA attribute 197, raw value. | | `uncorrectableSectors` | null (int64) \| integer (int64) | yes | ATA attribute 198, raw value. | | `mediaErrors` | null (int64) \| integer (int64) | yes | NVMe media and data integrity errors. | | `criticalWarning` | null (int32) \| integer (int32) | yes | NVMe critical warning bits; not 0 means the drive reports a critical condition. | | `lastSelfTest` | null \| string | yes | Result of the newest self-test: `passed`, `failed`, `aborted` or `running`; null without one. | | `readAt` | null (date-time) \| string (date-time) | yes | When SMART data was last read (UTC); null if never. | | `checkedAt` | string (date-time) | yes | When the disk was last checked (UTC), including checks that found it asleep. | ## Snapshot | Field | Type | Required | Description | | ----------------- | ------------------ | -------- | --------------------------------------------------------------------------------------- | | `dataset` | string | yes | The dataset the snapshot belongs to, for example `tank/pithyx/shares/media`. | | `name` | string | yes | The part after `@`, for example `pithyx-daily-20260927T000000Z`. | | `createdAt` | string (date-time) | yes | When ZFS took it (UTC), by the clock the box had then. | | `usedBytes` | integer (int64) | yes | Space only this snapshot holds. | | `referencedBytes` | integer (int64) | yes | Data the snapshot references. | | `holds` | integer (int32) | yes | Number of holds (`userrefs`); a held snapshot cannot be destroyed. | | `createTxg` | integer (int64) | yes | The transaction group it was taken in: the order of snapshots, whatever the clock said. | | `fullName` | null \| string | yes | | | `pithyxKind` | null \| string | yes | The schedule kind of a snapshot Pithyx created, or null for every other snapshot. | ## SnapshotCreateRequest | Field | Type | Required | Description | | --------- | ------ | -------- | ------------------------ | | `dataset` | string | yes | The dataset to snapshot. | ## SnapshotInfo A read-only snapshot of the system (`@` with `/var/lib/pithyx`), taken before an update. | Field | Type | Required | Description | | ----------- | ------------------ | -------- | ---------------------------------------------------------------------------- | | `name` | string | yes | Its folder in `/@snapshots`, the UTC time it was taken (`20261009T214000Z`). | | `version` | string | yes | The Pithyx version it holds. | | `createdAt` | string (date-time) | yes | When it was taken. | | `kernel` | string | yes | The kernel release it booted with; its GRUB entry boots that kernel. | | `reason` | string | yes | Why it was taken, for example `update to 0.2.0`. | ## SnapshotList Response of `GET /api/storage/snapshots`. | Field | Type | Required | Description | | ----------- | --------------------------------------------------- | -------- | ---------------------------- | | `dataset` | string | yes | The dataset. | | `snapshots` | [Snapshot](https://pithyx.org/docs/reference/api/schemas/#snapshot)[] | yes | Its snapshots, oldest first. | ## SnapshotMessage The full current state of a topic, sent after `sub`. Only changes follow as events. | Field | Type | Required | Description | | ----------- | -------- | -------- | ----------- | | `id` | string | yes | | | `topic` | string | yes | | | `data` | object | yes | | | `type` | `"snap"` | yes | | | `requestId` | string | yes | | ## SnapshotRequest | Field | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------- | | `dataset` | string | yes | The dataset. | | `name` | string | yes | The exact snapshot name after `@`. | ## SnapshotSchedule | Field | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------- | | `kind` | string | yes | `hourly`, `daily`, `weekly` or `monthly`. | | `enabled` | boolean | yes | Whether the schedule takes snapshots. | | `keep` | integer (int32) | yes | How many of its snapshots it keeps (1 to 1000). | ## SnapshotScheduleList Schedules of a dataset: all four kinds, in the order hourly, daily, weekly, monthly. | Field | Type | Required | Description | | ----------- | ------------------------------------------------------------------- | -------- | ------------------------------------------------------------- | | `dataset` | string | yes | The dataset. | | `schedules` | [SnapshotSchedule](https://pithyx.org/docs/reference/api/schemas/#snapshotschedule)[] | yes | One entry per kind; kinds left out of a PUT stay as they are. | ## StagedUpdate An uploaded update file that passed every check and waits for "Install". `TrustedSignature`: False only for a development file on a development box. | Field | Type | Required | Description | | ------------------ | ------------------ | -------- | ----------- | | `version` | string | yes | | | `channel` | string | yes | | | `minimumVersion` | string | yes | | | `changelog` | string | yes | | | `size` | integer (int64) | yes | | | `trustedSignature` | boolean | yes | | | `packages` | integer (int32) | yes | | | `kernel` | string | yes | | | `publishedAt` | string (date-time) | yes | | ## StorageAlert A storage problem that exists now. Alerts are derived from the current state, never stored. | Field | Type | Required | Description | | ---------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------- | | `key` | string | yes | Stable key of the cause, for example `pool.degraded:tank` or `disk.smart_failed:wwn-0x5000c500a1b2c3d4`. | | `severity` | string | yes | `warning` or `critical`. | | `code` | string | yes | Message code in the `notifications` namespace (`<code>.title`, `.body`, `.action`). | | `params` | object | yes | Message parameters: strings and numbers. | | `since` | string (date-time) | yes | When the daemon first saw the cause (UTC); a restart starts it again. | | `muted` | boolean | yes | True when the user muted this alert at this severity or higher. | ## StorageDisk A disk with the guard's verdict, for the Storage settings page. | Field | Type | Required | Description | | ------- | --------------------------------------------------------- | -------- | ----------- | | `disk` | [Disk](https://pithyx.org/docs/reference/api/schemas/#disk) | yes | | | `guard` | [GuardVerdict](https://pithyx.org/docs/reference/api/schemas/#guardverdict) | yes | | ## StorageDiskList Response of `GET /api/storage/disks`. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | `disks` | [StorageDisk](https://pithyx.org/docs/reference/api/schemas/#storagedisk)[] | yes | Every disk with its verdict. | | `environment` | string | yes | `dev` or `prod`; on dev only the declared test disks can be used. | ## StorageHealth Snapshot and event of `storage/alerts`, and response of `GET /api/storage/alerts`. | Field | Type | Required | Description | | -------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `alerts` | [StorageAlert](https://pithyx.org/docs/reference/api/schemas/#storagealert)[] | yes | Current alerts, critical first, with the user's mute flags. | | `smart` | [SmartReport](https://pithyx.org/docs/reference/api/schemas/#smartreport)[] | yes | SMART state of every disk. | ## StoragePlanPreview Response of `POST /api/storage/plans`. Nothing was run. | Field | Type | Required | Description | | --------------------- | ----------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `planId` | null \| string | yes | Runs the plan exactly as shown with `POST /api/storage/plans/{planId}/run`; null while a disk is not allowed, and while RequiresConfirmName is true and the name was not typed yet. | | `disks` | [GuardVerdict](https://pithyx.org/docs/reference/api/schemas/#guardverdict)[] | yes | The guard's verdict for every chosen disk, after probing them again. | | `commands` | null \| [PlannedCommand](https://pithyx.org/docs/reference/api/schemas/#plannedcommand)[] | yes | The exact commands, or null while a disk is not allowed. | | `datasets` | string[] | yes | For destroying or exporting a pool: every dataset that goes or becomes unavailable; for `pool.import`: the datasets it mounts. For destroying a dataset: the dataset, its children and every snapshot of them (`dataset@snapshot`), each dataset followed by its snapshots. For renaming a dataset: the dataset and its children, whose names change. For destroying a snapshot: the snapshot (`dataset@snapshot`); for rolling back: every newer snapshot, which goes too. | | `expiresAt` | string (date-time) | yes | Until when the plan may run. | | `warnings` | string[] | yes | Stable codes for what the user must know before running it: `lowers_redundancy`, `replication_mismatch`, `irreversible` and `no_redundancy` (adding a vdev: it tolerates fewer failed disks than the pool, it has a layout ZFS calls a replication mismatch, it can never be removed, it has no redundancy), `irreversible` (RAID-Z expansion), `other_system` (an import forced over another system's claim), `degraded` (the pool is imported with devices missing), `unmounted_datasets` (Unmounted stay unmounted) and `datasets_unavailable` (exporting a pool with datasets in use); for a rollback `changes_lost` (every change since the snapshot is lost) and `newer_snapshots` (the listed newer snapshots are destroyed). | | `requiresConfirmName` | boolean | yes | True when the plan runs only with the pool's name (for a rollback the dataset's full name) typed in `confirmName`. | | `unmounted` | [UnmountedDataset](https://pithyx.org/docs/reference/api/schemas/#unmounteddataset)[] | yes | For `pool.import`: datasets that stay unmounted, and why; those that would hide part of the system also get `canmount=noauto`. | ## StoragePlanRequest A destructive storage action to plan. Which fields an action needs: `pool.create` Pool, Layout, DiskIds, Encryption (and Confirmations for disks that are not empty); `pool.destroy` Pool and ConfirmName; `pool.replace` Pool, Vdev and one disk in DiskIds with its serial in Confirmations; `pool.spare.add` Pool and one disk; `pool.spare.remove`, `pool.offline` and `pool.online` Pool and Vdev; `pool.import.readonly` PoolGuid from the import scan, NewName when the name is taken, and Force with the pool name in ConfirmName when the scan says `needsForce`; `pool.import` Pool (imported read-only), and Force with ConfirmName to force it; `pool.export` Pool; `pool.vdev.add` Pool, Layout (`single`, `mirror`, `raidz1` to `raidz3`), DiskIds, Confirmations, and ConfirmName when the preview says so; `pool.raidz.expand` Pool, Vdev (the raidz vdev), one disk and ConfirmName; `dataset.rename` Pool, Dataset and NewName; `dataset.set` Pool, Dataset and at least one of QuotaBytes, ReservationBytes, Compression and RecordSizeBytes; `dataset.destroy` Pool, Dataset and ConfirmName; `volume.create` Pool, Name, SizeBytes and Sparse; `snapshot.destroy` Pool, Dataset and the snapshot's Name; `snapshot.rollback` Pool, Dataset, the snapshot's Name and the dataset's full name in ConfirmName. | Field | Type | Required | Description | | ------------------ | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | string | yes | `pool.create`, `pool.destroy`, `pool.replace`, `pool.spare.add`, `pool.spare.remove`, `pool.offline`, `pool.online`, `pool.import.readonly`, `pool.import`, `pool.export`, `pool.vdev.add`, `pool.raidz.expand`, `dataset.rename`, `dataset.set`, `dataset.destroy`, `volume.create`, `snapshot.destroy` or `snapshot.rollback`. | | `pool` | string | yes | The pool, or the new pool's name; for `pool.import.readonly` the scanned name (the GUID decides). | | `layout` | null \| string | no | `single`, `stripe`, `mirror`, `mirrors` (pairs), `raidz1`, `raidz2` or `raidz3`. | | `diskIds` | null \| string[] | no | The disks to use, by id. | | `name` | null \| string | no | Name of a new volume (one path component), or the snapshot after `@` for the snapshot actions. Shared folders are created with `POST /api/shares/plans`. | | `vdev` | null \| string | no | GUID of the device to replace, take offline, bring online or remove, or of the raidz vdev to expand. | | `encryption` | null \| string | no | The answer to the encryption question of a new pool: `none`, or `key` once the key vault exists. | | `confirmName` | null \| string | no | The pool's name, or the dataset's full name, typed by the user where the preview says `requiresConfirmName` and to destroy. | | `confirmations` | null \| map of string | no | Serial numbers the user typed, by disk id. | | `dataset` | null \| string | no | Full name of the dataset or volume to rename, change or destroy, on Pool. | | `newName` | null \| string | no | The new last component of a renamed dataset (it stays below the same parent), or for `pool.import.readonly` the name to import the pool under when its own is taken. | | `quotaBytes` | null (int64) \| integer (int64) | no | New quota in bytes (dataset, children and snapshots), 0 for none; null leaves it. | | `reservationBytes` | null (int64) \| integer (int64) | no | New reservation in bytes (dataset, children and snapshots), 0 for none; null leaves it. | | `compression` | null \| string | no | New compression: `off`, `lz4`, `zle`, `zstd`, `zstd-1` to `zstd-19`, `gzip`, `gzip-1` to `gzip-9`; null leaves it. | | `recordSizeBytes` | null (int64) \| integer (int64) | no | New record size of a file system, a power of two from 4 KiB to 1 MiB; null leaves it. | | `sizeBytes` | null (int64) \| integer (int64) | no | Size of a new volume, at least 1 MiB; rounded up to whole 16 KiB blocks. | | `sparse` | null \| boolean | no | True for a volume that reserves no space up front. | | `poolGuid` | null \| string | no | For `pool.import.readonly`: the pool's numeric identifier from the import scan. | | `force` | null \| boolean | no | For imports: import a pool that was last used by another system; needs ConfirmName. | ## StorageSchedule | Field | Type | Required | Description | | ----------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------- | | `kind` | string | yes | `scrub`, `shortSelfTest` or `longSelfTest`. | | `target` | string | yes | The pool name for scrubs; empty for self-tests, which cover every disk with SMART. | | `frequency` | string | yes | `off`, `weekly` or `monthly`. | | `lastRunAt` | null (date-time) \| string (date-time) | yes | When it last ran (UTC); for self-tests the oldest of all disks. Null if never. | | `nextRunAt` | null (date-time) \| string (date-time) | yes | When it runs next (UTC); null when it is off or has nothing to run on. | ## StorageScheduleList Response of `GET /api/storage/schedules`. | Field | Type | Required | Description | | ----------- | ----------------------------------------------------------------- | -------- | ----------- | | `schedules` | [StorageSchedule](https://pithyx.org/docs/reference/api/schemas/#storageschedule)[] | yes | | ## StorageScheduleUpdate Body of `PUT /api/storage/schedules`. | Field | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------------------- | | `kind` | string | yes | `scrub`, `shortSelfTest` or `longSelfTest`. | | `target` | string | yes | The pool name for scrubs; empty for self-tests. | | `frequency` | string | yes | `off`, `weekly` or `monthly`. | ## StoreApp An app of a catalog, at the newest version this box can run. | Field | Type | Required | Description | | ------------------ | ------------------------------------------------------- | -------- | ----------------------------------------------- | | `catalog` | string | yes | The catalog's id. | | `kind` | [CatalogKind](https://pithyx.org/docs/reference/api/schemas/#catalogkind) | yes | The catalog's kind; custom ones are unverified. | | `id` | string | yes | The app id. | | `version` | string | yes | The newest version for this box. | | `name` | map of string | yes | Names by language. | | `description` | null \| map of string | yes | Descriptions by language, if any. | | `author` | null \| string | yes | The author's name, if the manifest has one. | | `license` | string | yes | The SPDX license. | | `icon` | string | yes | The icon's URL. | | `installedVersion` | null \| string | yes | The installed version, if the app is installed. | | `update` | boolean | yes | The installed app is older than Version. | ## StoreAppDetails The detail page of a catalog app. | Field | Type | Required | Description | | ------------- | ----------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `app` | [StoreApp](https://pithyx.org/docs/reference/api/schemas/#storeapp) | yes | The app at its newest fitting version. | | `manifest` | [JsonElement](https://pithyx.org/docs/reference/api/schemas/#jsonelement) | yes | That version's manifest. | | `screenshots` | string[] | yes | URLs of its screenshots, in order. | | `homepage` | null \| string | yes | The manifest's homepage, if any. | | `source` | string | yes | Where its source is: the catalog repository at the commit CI built, in the app's folder. | | `versions` | [StoreAppVersion](https://pithyx.org/docs/reference/api/schemas/#storeappversion)[] | yes | Every published version, newest first. | ## StoreAppList Apps of the enabled catalogs, sorted by name. | Field | Type | Required | Description | | ------ | --------------------------------------------------- | -------- | ----------- | | `apps` | [StoreApp](https://pithyx.org/docs/reference/api/schemas/#storeapp)[] | yes | | ## StoreAppVersion A published version of a catalog app. | Field | Type | Required | Description | | ------------- | ------------------------------- | -------- | ------------------------------------------------------- | | `version` | string | yes | The version. | | `publishedAt` | string (date-time) | yes | When the catalog published it. | | `pithyx` | string | yes | The range of Pithyx versions it runs on. | | `fits` | boolean | yes | This box can install it (its version and architecture). | | `dataVersion` | null (int32) \| integer (int32) | yes | Its data version, if it declares one. | ## StoreChannel Which branch of every catalog the box reads: `catalog` (stable) or `catalog-next` (beta). Type: `"stable"`, `"beta"` ## StoreSettings The Store's settings. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | | `policy` | [UpdatePolicy](https://pithyx.org/docs/reference/api/schemas/#updatepolicy) | yes | What a check does with newer versions; each app may override it. | | `time` | string | yes | The daily check time as HH:mm in the box's time zone; the box adds its own delay of up to an hour. | | `channel` | [StoreChannel](https://pithyx.org/docs/reference/api/schemas/#storechannel) | yes | The branch every catalog is read from. | | `nextCheckAt` | string (date-time) | yes | When the next check runs (UTC), the box's delay included. | | `lastCheckAt` | null (date-time) \| string (date-time) | yes | When the last check ran (UTC), if one did. | ## StoreSettingsRequest | Field | Type | Required | Description | | --------- | --------------------------------------------------------- | -------- | -------------------------------------- | | `policy` | [UpdatePolicy](https://pithyx.org/docs/reference/api/schemas/#updatepolicy) | yes | What a check does with newer versions. | | `time` | string | yes | HH:mm in the box's time zone. | | `channel` | [StoreChannel](https://pithyx.org/docs/reference/api/schemas/#storechannel) | yes | stable or beta. | ## StoreState The Store for administrators: the snapshot and every event of the topic `store/admin`. | Field | Type | Required | Description | | ---------- | ----------------------------------------------------------- | -------- | -------------------------------------------- | | `settings` | [StoreSettings](https://pithyx.org/docs/reference/api/schemas/#storesettings) | yes | The settings with the next check. | | `catalogs` | [CatalogInfo](https://pithyx.org/docs/reference/api/schemas/#cataloginfo)[] | yes | Every catalog, the project's first. | | `updates` | [AppUpdate](https://pithyx.org/docs/reference/api/schemas/#appupdate)[] | yes | Newer versions of installed apps, by app id. | ## SubjectGrant A user's or a group's access to one shared folder. | Field | Type | Required | Description | | ------------- | ------------------------------------------------------- | -------- | ----------------------------- | | `subjectKind` | [SubjectKind](https://pithyx.org/docs/reference/api/schemas/#subjectkind) | yes | `user` or `group`. | | `subjectId` | integer (int64) | yes | The user's or the group's id. | | `level` | [GrantLevel](https://pithyx.org/docs/reference/api/schemas/#grantlevel) | yes | `read` or `readWrite`. | ## SubjectKind Who a grant is for. Apps join in M4; until then nothing grants to them. Type: `"user"`, `"group"`, `"app"` ## SystemInfo | Field | Type | Required | Description | | ---------------------- | -------------------------------- | -------- | ----------------------------------------------------------------------------- | | `hostname` | string | yes | The host name of the box. | | `uptimeSeconds` | number (double) | yes | Seconds since boot. | | `loadAverage` | number (double)[] | yes | Over 1, 5 and 15 minutes. | | `cpuPercent` | null (double) \| number (double) | yes | Usage since the previous sample; null for the very first one. | | `memoryTotalBytes` | integer (int64) | yes | Physical memory. | | `memoryAvailableBytes` | integer (int64) | yes | Memory available for new work without swapping, including reclaimable caches. | ## SystemOverview | Field | Type | Required | Description | | ------------------ | --------------- | -------- | --------------------------------------------------------------------------------- | | `version` | string | yes | The Pithyx version. | | `commit` | null \| string | yes | The git commit it was built from, if known. | | `operatingSystem` | string | yes | The distribution, for example "Debian GNU/Linux 13 (trixie)". | | `kernel` | string | yes | The running Linux kernel. | | `machine` | null \| string | yes | Vendor and product of the board or virtual machine, if the firmware reports them. | | `cpuModel` | null \| string | yes | The processor, if known. | | `cpuCores` | integer (int32) | yes | Logical processors. | | `memoryTotalBytes` | integer (int64) | yes | Physical memory. | | `hostname` | string | yes | The host name. | | `uptimeSeconds` | number (double) | yes | Seconds since boot. | ## SystemRegion The regional settings of the box. | Field | Type | Required | Description | | ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `language` | string | yes | The system language: the sign-in page and every user on "Automatic" whose browser asks for a language Pithyx does not have get it, and so do messages the box sends on its own. One of IReadOnlyList<string> SystemRegion.Languages. | | `region` | null \| string | yes | ISO 3166 country code such as `DE` or `US` whose date, time and number formats every user sees, or null to follow each user's language. | ## ThumbnailRequest Body of `POST /api/files/{shareId}/thumbnails`. | Field | Type | Required | Description | | -------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `folder` | null \| string | yes | The folder shown, relative to the share. | | `names` | string[] | yes | Entries of that folder on screen, at most 200. | | `size` | [ThumbnailSize](https://pithyx.org/docs/reference/api/schemas/#thumbnailsize) | yes | `small` (64 px, list rows) or `large` (256 px, grid tiles). | ## ThumbnailSize The two thumbnail sizes: rows of the list, tiles of the grid (both twice their CSS size for sharp screens). Type: `"small"`, `"large"` ## ThumbnailsReady Event of `thumbnails/<share>/<folder>`: thumbnails that were rendered or refused. | Field | Type | Required | Description | | ------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `items` | object[] | yes | Each with `ready` and its version, or `none`. | | `size` | `"small"`, `"large"` | yes | The two thumbnail sizes: rows of the list, tiles of the grid (both twice their CSS size for sharp screens). | ## ThumbnailState | Field | Type | Required | Description | | --------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | | `name` | string | yes | The entry. | | `status` | [ThumbnailStatus](https://pithyx.org/docs/reference/api/schemas/#thumbnailstatus) | yes | Whether it has a thumbnail. | | `version` | null \| string | yes | For `ready`: changes whenever the file changes; pass it as `v` so a new version is loaded. | ## ThumbnailStates Response of `POST /api/files/{shareId}/thumbnails`. Nothing was rendered while answering. | Field | Type | Required | Description | | ------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------------- | | `topic` | string | yes | Subscribe to it for the thumbnails that are still pending. | | `items` | [ThumbnailState](https://pithyx.org/docs/reference/api/schemas/#thumbnailstate)[] | yes | One state per distinct name asked for. | ## ThumbnailStatus Whether a thumbnail can be shown now. Type: `"ready"`, `"pending"`, `"none"` ## ThumbnailWatch Snapshot of a thumbnail topic; the events carry everything. | Field | Type | Required | Description | | ---------- | ------- | -------- | ------------ | | `watching` | boolean | yes | Always true. | ## TimeSettings | Field | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------------ | | `timeZone` | string | yes | IANA name of the system time zone. | | `synchronized` | boolean | yes | Whether the clock is synchronized with a time server. | | `ntpServers` | string[] | yes | Time servers Pithyx configured; empty means the distribution's defaults. | | `timeZones` | string[] | yes | Every time zone the system knows. | ## TimeSettingsRequest | Field | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------------------------------------------------------- | | `timeZone` | string | yes | IANA name of the new time zone. | | `ntpServers` | string[] | yes | At most eight host names or addresses; empty for the distribution's defaults. | ## TlsNamesRequest Names the box's own certificate covers besides its host name and addresses. | Field | Type | Required | Description | | ------------ | -------- | -------- | ---------------------------------------------------------------- | | `extraNames` | string[] | yes | DNS names or addresses inside the authority's scope, at most 20. | ## TlsSettings Settings > Certificates. | Field | Type | Required | Description | | ------------------ | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `https` | boolean | yes | The web interface speaks HTTPS on 7484 (80 and 443 redirect there); false only in development and simulation. | | `source` | [ActiveCertificateSource](https://pithyx.org/docs/reference/api/schemas/#activecertificatesource) | yes | Which certificate the box presents. | | `active` | [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | The certificate the box presents now. | | `authority` | [AuthorityInfo](https://pithyx.org/docs/reference/api/schemas/#authorityinfo) | yes | The box's own authority. | | `boxNames` | string[] | yes | The names and addresses the box's own certificate covers. | | `extraNames` | string[] | yes | Names an administrator added to the box's own certificate. | | `suggestedDomains` | string[] | yes | The DNS suffixes a new restricted authority starts with: the local ones, the host name and the network's search domains. | | `custom` | null \| [CertificateInfo](https://pithyx.org/docs/reference/api/schemas/#certificateinfo) | yes | One certificate as Settings shows it. | | `issued` | [IssuedCertificate](https://pithyx.org/docs/reference/api/schemas/#issuedcertificate)[] | yes | The certificates issued for other devices, newest first. | ## TopicEvents | Field | Type | Required | Description | | --------------------- | --------------------------------------------------------------------- | -------- | ----------- | | `apps` | [AppList](https://pithyx.org/docs/reference/api/schemas/#applist) | yes | | | `apps/+/context` | [AppContextState](https://pithyx.org/docs/reference/api/schemas/#appcontextstate) | yes | | | `apps/admin` | [AdminAppList](https://pithyx.org/docs/reference/api/schemas/#adminapplist) | yes | | | `files/+/+` | [FolderChanges](https://pithyx.org/docs/reference/api/schemas/#folderchanges) | yes | | | `jobs` | [Job](https://pithyx.org/docs/reference/api/schemas/#job) | yes | | | `jobs/+` | [Job](https://pithyx.org/docs/reference/api/schemas/#job) | yes | | | `notifications` | [NotificationEvent](https://pithyx.org/docs/reference/api/schemas/#notificationevent) | yes | | | `session/permissions` | [SessionPermissions](https://pithyx.org/docs/reference/api/schemas/#sessionpermissions) | yes | | | `shares/list` | [ShareListRevision](https://pithyx.org/docs/reference/api/schemas/#sharelistrevision) | yes | | | `storage/alerts` | [StorageHealth](https://pithyx.org/docs/reference/api/schemas/#storagehealth) | yes | | | `storage/disks` | [DisksChanged](https://pithyx.org/docs/reference/api/schemas/#diskschanged) | yes | | | `storage/pools` | [PoolList](https://pithyx.org/docs/reference/api/schemas/#poollist) | yes | | | `store/admin` | [StoreState](https://pithyx.org/docs/reference/api/schemas/#storestate) | yes | | | `system/info` | [SystemInfo](https://pithyx.org/docs/reference/api/schemas/#systeminfo) | yes | | | `system/network` | [NetworkState](https://pithyx.org/docs/reference/api/schemas/#networkstate) | yes | | | `system/processes` | [ProcessList](https://pithyx.org/docs/reference/api/schemas/#processlist) | yes | | | `system/resources` | [ResourceSample](https://pithyx.org/docs/reference/api/schemas/#resourcesample) | yes | | | `system/updates` | [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus) | yes | | | `thumbnails/+/+` | [ThumbnailsReady](https://pithyx.org/docs/reference/api/schemas/#thumbnailsready) | yes | | ## TopicSnapshots | Field | Type | Required | Description | | --------------------- | --------------------------------------------------------------------- | -------- | ----------- | | `apps` | [AppList](https://pithyx.org/docs/reference/api/schemas/#applist) | yes | | | `apps/+/context` | [AppContextState](https://pithyx.org/docs/reference/api/schemas/#appcontextstate) | yes | | | `apps/admin` | [AdminAppList](https://pithyx.org/docs/reference/api/schemas/#adminapplist) | yes | | | `files/+/+` | [FolderWatchState](https://pithyx.org/docs/reference/api/schemas/#folderwatchstate) | yes | | | `jobs` | [JobList](https://pithyx.org/docs/reference/api/schemas/#joblist) | yes | | | `jobs/+` | [Job](https://pithyx.org/docs/reference/api/schemas/#job) | yes | | | `notifications` | [NotificationList](https://pithyx.org/docs/reference/api/schemas/#notificationlist) | yes | | | `session/permissions` | [SessionPermissions](https://pithyx.org/docs/reference/api/schemas/#sessionpermissions) | yes | | | `shares/list` | [ShareListRevision](https://pithyx.org/docs/reference/api/schemas/#sharelistrevision) | yes | | | `storage/alerts` | [StorageHealth](https://pithyx.org/docs/reference/api/schemas/#storagehealth) | yes | | | `storage/disks` | [DiskList](https://pithyx.org/docs/reference/api/schemas/#disklist) | yes | | | `storage/pools` | [PoolList](https://pithyx.org/docs/reference/api/schemas/#poollist) | yes | | | `store/admin` | [StoreState](https://pithyx.org/docs/reference/api/schemas/#storestate) | yes | | | `system/info` | [SystemInfo](https://pithyx.org/docs/reference/api/schemas/#systeminfo) | yes | | | `system/network` | [NetworkState](https://pithyx.org/docs/reference/api/schemas/#networkstate) | yes | | | `system/processes` | [ProcessList](https://pithyx.org/docs/reference/api/schemas/#processlist) | yes | | | `system/resources` | [ResourceSnapshot](https://pithyx.org/docs/reference/api/schemas/#resourcesnapshot) | yes | | | `system/updates` | [UpdateStatus](https://pithyx.org/docs/reference/api/schemas/#updatestatus) | yes | | | `thumbnails/+/+` | [ThumbnailWatch](https://pithyx.org/docs/reference/api/schemas/#thumbnailwatch) | yes | | ## TotpConfirmRequest | Field | Type | Required | Description | | ------ | ------ | -------- | ----------- | | `code` | string | yes | | ## TotpDisableRequest | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------- | | `password` | string | yes | | ## TotpEnrollment | Field | Type | Required | Description | | -------- | ------ | -------- | ------------------------------- | | `secret` | string | yes | Base32 secret for manual entry. | | `uri` | string | yes | otpauth:// URI for the QR code. | ## TotpLoginRequest | Field | Type | Required | Description | | -------------- | -------------- | -------- | ------------------------------------------------------------------------- | | `challenge` | string | yes | From the login response. | | `code` | null \| string | no | Six-digit code from the authenticator app. | | `recoveryCode` | null \| string | no | One of the recovery codes shown when TOTP was enabled, instead of a code. | ## TrashItem One item in a share's recycle bin. | Field | Type | Required | Description | | -------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Id for restoring or deleting it. | | `name` | string | yes | Its name when it was deleted. | | `originalPath` | string | yes | Where it was, relative to the share; restoring puts it back there. | | `kind` | [FileKind](https://pithyx.org/docs/reference/api/schemas/#filekind) | yes | File, folder, symlink or another kind. | | `size` | integer (int64) | yes | Bytes, for a folder everything inside it. | | `deletedAt` | string (date-time) | yes | When it was deleted, UTC. | | `deletedBy` | null \| string | yes | User name of who deleted it, if that user still exists. | | `expiresAt` | null (date-time) \| string (date-time) | yes | When it is deleted for good, or null when the share keeps deleted items until emptied. | ## TrashItemsRequest | Field | Type | Required | Description | | ------------ | --------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | | `ids` | integer (int64)[] | yes | Items of the share's recycle bin, at most 1000. | | `onConflict` | null \| [ConflictPolicy](https://pithyx.org/docs/reference/api/schemas/#conflictpolicy) | no | For restoring: what happens when the original place is taken; rename when left out. | ## TrashPage | Field | Type | Required | Description | | --------------- | ----------------------------------------------------- | -------- | -------------------------------------------------------------------------- | | `items` | [TrashItem](https://pithyx.org/docs/reference/api/schemas/#trashitem)[] | yes | Newest first. | | `nextCursor` | null \| string | yes | Pass as cursor for the next page; null on the last page. | | `retentionDays` | integer (int32) | yes | Days the share keeps deleted items; 0 keeps them until the bin is emptied. | ## TrashSettingsRequest | Field | Type | Required | Description | | --------------- | --------------- | -------- | ---------------------------------------------------------- | | `retentionDays` | integer (int32) | yes | 0 to 3650; 0 keeps deleted items until the bin is emptied. | ## UnknownHostAction What 443 and 80 do with a name no enabled host has. Type: `"redirect"`, `"notFound"` ## UnmountedDataset | Field | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | yes | The dataset. | | `mountPoint` | string | yes | Its mount point. | | `reason` | string | yes | Why it stays unmounted: `system_path` (`/` or at or below a system directory), `shadows_mount` (it would hide something mounted there or below), `duplicate_mountpoint` (another dataset of the pool mounts there first) or `key_unavailable` (encrypted and locked). | ## UpdateAppRequest | Field | Type | Required | Description | | --------- | ------- | -------- | -------------------------------------------------------------------------------------------- | | `enabled` | boolean | yes | False hides the app from everybody and stops serving its frontend; its data and grants stay. | ## UpdateCatalogRequest | Field | Type | Required | Description | | --------------- | --------------- | -------- | ---------------------------------------------------------------------------------- | | `enabled` | null \| boolean | no | Switches the catalog on or off; null leaves it. | | `registryToken` | null \| string | no | user:token to pull the catalog's private images; empty removes it, null leaves it. | ## UpdateHistoryEntry One update or rollback of the system. `Kind`: `update` or `rollback`. `Source`: `online` (from the channel), `file` (uploaded), `recovery` (the console menu) or `manual` (a rollback from Settings). `Snapshot`: The snapshot taken before an update, or the one a rollback restored. `State`: `running`, `restarting`, `succeeded`, `failed` (nothing changed) or `rolled_back`. | Field | Type | Required | Description | | ------------- | -------------------------------------- | -------- | ----------- | | `id` | integer (int64) | yes | | | `kind` | string | yes | | | `source` | string | yes | | | `fromVersion` | string | yes | | | `toVersion` | string | yes | | | `snapshot` | null \| string | yes | | | `state` | string | yes | | | `errorCode` | null \| string | yes | | | `errorParams` | null \| object | yes | | | `startedAt` | string (date-time) | yes | | | `finishedAt` | null (date-time) \| string (date-time) | yes | | ## UpdatePolicy Type: `"automatic"`, `"notify"`, `"none"`, `null` ## UpdateProblem Why the last check could not read the channel, as an error code with its params. | Field | Type | Required | Description | | -------- | ------ | -------- | ----------- | | `code` | string | yes | | | `params` | object | yes | | ## UpdateSettingsRequest | Field | Type | Required | Description | | -------------- | ------- | -------- | -------------------------------------------------- | | `checkEnabled` | boolean | yes | The daily check (on by default; it only notifies). | | `channel` | string | yes | `stable` or `beta`. | ## UpdateSourceCandidate A source file an administrator saved in Settings for the recovery menu, which alone can switch to it. | Field | Type | Required | Description | | --------- | ----------------------------------------------------------------- | -------- | ----------- | | `name` | string | yes | | | `url` | string | yes | | | `keys` | [UpdateSourceKey](https://pithyx.org/docs/reference/api/schemas/#updatesourcekey)[] | yes | | | `savedBy` | string | yes | | | `savedAt` | string (date-time) | yes | | ## UpdateSourceInfo The update source the box follows. `Official`: True for the Pithyx project's keys; false after a switch to another source in the recovery menu. | Field | Type | Required | Description | | ---------- | ----------------------------------------------------------------- | -------- | ----------- | | `name` | string | yes | | | `url` | string | yes | | | `official` | boolean | yes | | | `keys` | [UpdateSourceKey](https://pithyx.org/docs/reference/api/schemas/#updatesourcekey)[] | yes | | ## UpdateSourceKey A key of an update source as Settings shows it. | Field | Type | Required | Description | | ----------- | -------- | -------- | ----------- | | `keyId` | string | yes | | | `publicKey` | string | yes | | | `channels` | string[] | yes | | ## UpdateStatus Settings > Updates for administrators (topic `system/updates`). `Supported`: Whether updates and rollbacks apply here; false on a machine not laid out by the installer. `UnsupportedReason`: `not_btrfs`, `not_subvolume`, `not_array` or `findmnt`. `RunningJobId`: The job of an update or rollback that runs now. `Snapshots`: The kept snapshots, newest first; each can be restored. `Source`: The update source the box follows; only the recovery menu switches it. `SourceCandidate`: A source file saved in Settings for the recovery menu, or null. | Field | Type | Required | Description | | ------------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installedVersion` | string | yes | | | `channel` | string | yes | | | `checkEnabled` | boolean | yes | | | `lastCheckAt` | null (date-time) \| string (date-time) | yes | | | `nextCheckAt` | null (date-time) \| string (date-time) | yes | | | `checking` | boolean | yes | | | `available` | null \| [AvailableUpdate](https://pithyx.org/docs/reference/api/schemas/#availableupdate) | yes | The newest version of the box's channel when it is newer than the installed one. `Installable`: False when the box is older than MinimumVersion and needs a version in between first. | | `debian` | null \| [DebianUpdates](https://pithyx.org/docs/reference/api/schemas/#debianupdates) | yes | The Debian updates apt offers; the kernel and ZFS never come from Debian. | | `problem` | null \| [UpdateProblem](https://pithyx.org/docs/reference/api/schemas/#updateproblem) | yes | Why the last check could not read the channel, as an error code with its params. | | `supported` | boolean | yes | | | `unsupportedReason` | null \| string | yes | | | `staged` | null \| [StagedUpdate](https://pithyx.org/docs/reference/api/schemas/#stagedupdate) | yes | An uploaded update file that passed every check and waits for "Install". `TrustedSignature`: False only for a development file on a development box. | | `runningJobId` | null (int64) \| integer (int64) | yes | | | `history` | [UpdateHistoryEntry](https://pithyx.org/docs/reference/api/schemas/#updatehistoryentry)[] | yes | | | `snapshots` | [SnapshotInfo](https://pithyx.org/docs/reference/api/schemas/#snapshotinfo)[] | yes | | | `source` | [UpdateSourceInfo](https://pithyx.org/docs/reference/api/schemas/#updatesourceinfo) | yes | | | `sourceCandidate` | null \| [UpdateSourceCandidate](https://pithyx.org/docs/reference/api/schemas/#updatesourcecandidate) | yes | A source file an administrator saved in Settings for the recovery menu, which alone can switch to it. | ## UserDeletion The result of deleting a user. | Field | Type | Required | Description | | ----- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `job` | null \| [Job](https://pithyx.org/docs/reference/api/schemas/#job) | yes | A long operation of a user, such as copying files. Also the data of the `jobs/{id}` topics. | ## UserGrants The rights of a user for the editor. Administrators only. | Field | Type | Required | Description | | ----------- | --------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- | | `grants` | [GrantEntry](https://pithyx.org/docs/reference/api/schemas/#grantentry)[] | yes | The user's own grants; the editor changes these. | | `inherited` | [InheritedGrant](https://pithyx.org/docs/reference/api/schemas/#inheritedgrant)[] | yes | What its groups give it; changed on the group. | | `effective` | [SessionPermissions](https://pithyx.org/docs/reference/api/schemas/#sessionpermissions) | yes | What the user may do: the union of both, or everything for an administrator. | ## UserInfo The signed-in user. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id. | | `username` | string | yes | Login name. | | `displayName` | null \| string | yes | Name shown, if set. | | `isAdmin` | boolean | yes | Whether the user has the administrator right, its own or through a group. | | `totpEnabled` | boolean | yes | Whether the user signs in with a second factor. | | `permissions` | [SessionPermissions](https://pithyx.org/docs/reference/api/schemas/#sessionpermissions) | yes | What the user may do; the topic `session/permissions` sends changes. | | `groups` | [GroupRef](https://pithyx.org/docs/reference/api/schemas/#groupref)[] | yes | The user's groups by name, without the built-in group every user is in; apps get them in their context. | ## UserSummary A user as the Users page shows it. Administrators only. | Field | Type | Required | Description | | --------------------- | ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer (int64) | yes | Stable id. | | `username` | string | yes | The Linux user name, lower case. | | `displayName` | null \| string | yes | Shown instead of the user name, if set. | | `isAdmin` | boolean | yes | Whether the user has the administrator right, its own or through a group; administrators have every right. | | `uid` | null (int64) \| integer (int64) | yes | The Linux uid from the Pithyx range (20000 to 29999), never reused. | | `totpEnabled` | boolean | yes | Whether the user signs in with a second factor. | | `createdAt` | string (date-time) | yes | When the user was created, UTC. | | `home` | null \| string | yes | The user's home folder on a pool, or null when there is no pool yet. | | `disabled` | boolean | yes | Deactivated: cannot sign in, and the Linux account is expired. | | `rights` | string[] | yes | The special rights the user has (`right:admin`, `right:desktopLogin`, `right:sshLogin`, `right:power`), its own and through its groups; a deactivated user gets them back when activated. | | `protocols` | string[] | yes | The file protocols the user may use (`protocol:smb`, `protocol:sftp`, `protocol:webdav`, `protocol:ftp`), the same way. | | `fileServicePassword` | boolean | yes | Whether SMB and SFTP know the user's password. They learn it when the user signs in on the web or an administrator sets it; until then the user cannot use them. | | `groupIds` | integer (int64)[] | yes | The groups the user is a member of; the built-in group `users`, which has everybody, is left out. | ## UserUpdate Fields left out stay as they are. | Field | Type | Required | Description | | ------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `displayName` | null \| string | no | An empty text removes the display name. | | `disabled` | null \| boolean | no | Deactivates or activates the user; deactivating ends the user's sessions. Nobody deactivates themselves or the last active administrator. | | `groupIds` | null \| integer (int64)[] | no | Every group the user should be a member of, besides the built-in group `users`; the user leaves the others. | ## Vdev | Field | Type | Required | Description | | ---------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `name` | string | yes | Vdev name as ZFS shows it: `raidz1-0`, `mirror-1` or the device's by-id name. | | `vdevGuid` | string | yes | Vdev GUID as decimal text; names a device in commands even when it is missing. | | `type` | string | yes | ZFS vdev type: `disk`, `file`, `mirror`, `raidz`, `draid`, `spare`, `replacing` and so on. | | `role` | string | yes | What the vdev is for: `data`, `log`, `cache`, `special`, `dedup` or `spare`. | | `state` | string | yes | ZFS state of the vdev. | | `path` | null \| string | yes | Device path of a leaf vdev, usually below `/dev/disk/by-id`. | | `parityDisks` | null (int32) \| integer (int32) | yes | Parity level of a raidz vdev (1 to 3), otherwise null. | | `readErrors` | integer (int64) | yes | Read errors since import or the last clear. | | `writeErrors` | integer (int64) | yes | Write errors since import or the last clear. | | `checksumErrors` | integer (int64) | yes | Checksum errors since import or the last clear. | | `children` | [Vdev](https://pithyx.org/docs/reference/api/schemas/#vdev)[] | yes | Child vdevs. | | `missing` | boolean | no | True for a leaf whose disk is not connected, also while ZFS has not noticed yet (see PoolHealth). | | `serial` | null \| string | no | Serial of the disk a leaf is on, as last seen connected, if known. | ## VlanSettings | Field | Type | Required | Description | | -------- | --------------- | -------- | --------------------------------------------------------------- | | `parent` | string | yes | The network card or bond that carries the VLAN's tagged frames. | | `id` | integer (int32) | yes | The 802.1Q VLAN id, 1 to 4094. | ## WebSocketCloseCode Type: `1000`, `1001`, `1008`, `1009`, `4401`, `4403` ## WindowPreference | Field | Type | Required | Description | | -------- | --------------- | -------- | --------------------------------------------------- | | `appId` | string | yes | The app the preference belongs to. | | `width` | integer (int32) | yes | Last free width of the app's windows in CSS pixels. | | `height` | integer (int32) | yes | Last free height in CSS pixels. | ## WindowPreferenceRequest | Field | Type | Required | Description | | -------- | --------------- | -------- | ----------- | | `width` | integer (int32) | yes | | | `height` | integer (int32) | yes | |