REST-API: Schemas

Die Schemas aus dem OpenAPI-Dokument des Daemons, nach Namen sortiert. Die TypeScript-Typen von @pithyx/api-client werden aus demselben Dokument erzeugt.

AckMessage

Confirms a sub or unsub. For sub, the snapshots of matching topics follow.

Feld	Typ	Pflicht	Beschreibung
id	string	ja
type	"ack"	ja
requestId	string	ja

ActiveCertificateSource

Which certificate the web interface and FTPS present.

Typ: "authority", "custom"

AddCatalogRequest

Feld	Typ	Pflicht	Beschreibung
url	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
pool	null | string	ja	The app pool, or null before the first install.
apps	AppDetails[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
type	string	ja
title	string	ja
status	integer (int32)	ja
detail	string	ja
code	ErrorCode	ja
params	map of object	ja
requestId	string	ja

AppAccess

Who may use an app after its first install: everybody (a grant to the built-in group) or administrators only.

Typ: "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.

Feld	Typ	Pflicht	Beschreibung
version	string	ja	The installed version.
permissions	string[]	ja	The permissions of the manifest that no administrator revoked; the app sees them as permissionsChange.
logLevel	"info", "debug"	ja	Whether an app’s debug log entries reach the daemon; info, warn and error always do.
backend	null | object	ja	The app’s backend: the state of its containers and the names of its endpoints.
storage	object[]	ja	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).

Feld	Typ	Pflicht	Beschreibung
id	string	ja	The app id.
version	string	ja	The installed version.
source	string	ja	sideload (a package file) or catalog.
enabled	boolean	ja	Whether users can open it.
manifest	JsonElement	ja	The installed manifest.
permissions	AppPermissionState[]	ja	Each permission of the manifest with whether it is granted.
uid	integer (int64)	ja	The app’s own uid.
sha256	string	ja	SHA-256 of the installed package file.
installedAt	string (date-time)	ja	The first install (UTC).
updatedAt	string (date-time)	ja	The last install or update (UTC).
busy	boolean	ja	An install, update or removal runs.
available	boolean	ja	Its data is reachable: the app pool is imported, unlocked and mounted.
logLevel	AppLogLevel	ja	Whether its debug log entries reach the daemon.
storage	AppStorageMapping[]	ja	The folders mapped to the storage requests of its manifest; a request without one is not mapped.
catalog	null | string	ja	The catalog it was installed or last updated from; null for a sideload.
updatePolicy	null | UpdatePolicy	ja	Its own update policy; null follows the box’s.
previousVersion	null | string	ja	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.

Feld	Typ	Pflicht	Beschreibung
accent	string	ja	One of the accent presets: petrol, ocean, indigo, plum, moss, graphite.
wallpaper	string	ja	boxes (the Pithyx boxes) or plain.

AppFileEntry

A file or folder an app reaches, with whether the app may write it.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Name within its folder.
kind	FileKind	ja	File, folder, symlink or another kind.
size	integer (int64)	ja	Bytes for files, 0 for folders.
modified	string (date-time)	ja	Last change of the content, UTC.
writable	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
kind	FileOperationKind	ja	copy, move or delete.
items	null | AppFileRef[]	nein	The entries to work on, at most 1000. Leave out when AllIn is given.
target	null | AppFileRef	nein	An entry or folder of an app’s file operation, in a shared folder or a storage request of its manifest.
onConflict	null | ConflictPolicy	nein	For copy and move; fail when left out.
permanent	boolean	nein	For delete: remove for good instead of moving to the shared folder’s recycle bin.
allIn	null | AppFolderSelection	nein	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.

Feld	Typ	Pflicht	Beschreibung
share	null | string	nein	The shared folder’s id, as the app got it from files/shares.
storage	null | string	nein	The id of a storage request of the manifest.
path	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
url	string	ja	Path on the box with ?pithyx-token=; supports range requests.
expiresAt	string (date-time)	ja	When it stops working (UTC).

AppFileUrlRequest

Body of POST /api/app/files/url.

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The file.
share	null | string	nein	The shared folder’s id, or null.
storage	null | string	nein	The id of a storage request, or null.

AppFolderPage

One page of a folder, relative to its location.

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The folder (“” for the location’s root).
folderId	string	ja	Stable id of the folder, also after a rename.
total	integer (int32)	ja	Entries in the folder when the page was read.
entries	FileEntry[]	ja	This page, in the requested order.
nextCursor	null | string	ja	Pass as cursor for the next page; null on the last page.
topic	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
folder	AppFileRef	ja	The folder whose entries are meant.
except	null | string[]	nein	Names left out, at most 1000.

AppGrants

Who may use an app. Administrators only.

Feld	Typ	Pflicht	Beschreibung
grants	SubjectGrant[]	ja	The grants of users and groups on it (level allow); the editor changes these. The built-in group users stands for everybody.
users	AppUserAccess[]	ja	Every user with whether it may use the app in the end, administrators and deactivated users included.

AppGrantsRequest

Feld	Typ	Pflicht	Beschreibung
grants	SubjectGrant[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
share	string	ja	The shared folder’s id.
path	string	ja	The one file; the window may read it (needs files.read), or also write it.
write	boolean	nein	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.

Feld	Typ	Pflicht	Beschreibung
apps	object[]	ja	Enabled apps the user has a grant for; every enabled app for administrators.

AppLogBatch

Feld	Typ	Pflicht	Beschreibung
entries	AppLogEntry[]	ja	At most 100 entries per request.

AppLogEntry

Feld	Typ	Pflicht	Beschreibung
level	LogLevelName	ja	debug, info, warn or error.
message	string	ja	At most 4000 characters; longer ones are cut.
data	null | map of string	nein	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.

Typ: "info", "debug"

AppLogLevelRequest

Feld	Typ	Pflicht	Beschreibung
level	AppLogLevel	ja	Whether the app’s debug log entries reach the daemon.

AppLogResult

Feld	Typ	Pflicht	Beschreibung
accepted	integer (int32)	ja	Entries stored.
dropped	integer (int32)	ja	Entries over the app’s rate limit, not stored.

AppNotificationAction

A button of an app’s notification.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	Comes back to the app when the user clicks it; 1 to 64 characters, unique in the notification.
label	string	ja	Plain text from the app, 1 to 40 characters.

AppNotificationLevel

Typ: "info", "success", "warning", "error", null

AppNotificationRequest

Body of POST /api/notifications/app: a notification a core app sends through the SDK.

Feld	Typ	Pflicht	Beschreibung
app	string	ja	Id of the core app (org.pithyx.*); third-party apps send theirs to /api/app/notifications.
title	string	ja	Plain text from the app, at most 200 characters.
body	null | string	nein	Plain text from the app, at most 1000 characters.
tone	null | NotificationTone	nein	Defaults to info.

AppNotifyRequest

Body of POST /api/app/notifications: the SDK’s notify of a third-party app.

Feld	Typ	Pflicht	Beschreibung
title	string	ja	Plain text, 1 to 200 characters.
body	null | string	nein	Plain text, at most 1000 characters.
level	null | AppNotificationLevel	nein	Defaults to info.
actions	null | AppNotificationAction[]	nein	At most 2 buttons.
data	object	nein	Any JSON the app gets back with a click, at most 4096 characters.
tag	null | string	nein	Replaces the app’s earlier notification with the same tag for this user; 1 to 64 characters.

AppPackageAction

What installing a checked package does.

Typ: "install", "update", "reinstall", "downgrade"

AppPackagePreview

A checked package, kept for 15 minutes for its installation by the administrator who uploaded it.

Feld	Typ	Pflicht	Beschreibung
packageId	string	ja	Names it for the install.
expiresAt	string (date-time)	ja	When it is discarded (UTC).
id	string	ja	The app id.
version	string	ja	The version in the package.
manifest	JsonElement	ja	The whole manifest (pithyx.json).
action	AppPackageAction	ja	What installing it does.
installedVersion	null | string	ja	The installed version, if the app is installed.
addedPermissions	string[]	ja	Permissions the package asks for that the installed version did not (all of them for an install).
removedPermissions	string[]	ja	Permissions the installed version had that the package no longer asks for.
pool	null | string	ja	The app pool, or null before the first app is installed (the install must name one then).
fileCount	integer (int32)	ja	Regular files in the package.
unpackedBytes	integer (int64)	ja	Their sizes together.
packageBytes	integer (int64)	ja	The size of the package file.
sha256	string	ja	SHA-256 of the package file, lowercase hex.
suggestedAccess	AppAccess	ja	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	nein	The catalog the package comes from; null for an uploaded file (a sideload, unverified).
keptData	boolean	nein	For an install: an earlier installation was removed with “Keep the data”, and the app gets its data and its user id again.

AppPermissionsRequest

Feld	Typ	Pflicht	Beschreibung
permissions	AppPermissionState[]	ja	Permissions of the app’s manifest with whether the app keeps them; the others stay as they are.

AppPermissionState

Feld	Typ	Pflicht	Beschreibung
permission	string	ja	For example notifications.
granted	boolean	ja	False after an administrator revoked it.

AppRenameRequest

Body of POST /api/app/files/rename.

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The entry to rename.
name	string	ja	The new name in the same folder.
share	null | string	nein	The shared folder’s id, or null.
storage	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	The location { share: id }.
name	string	ja	Name shown to users.
access	ShareAccess	ja	The user’s access: read or readWrite.
unavailable	null | string	ja	Why its files cannot be reached now (poolMissing, poolUnavailable, notMounted), or null.
kind	ShareKind	nein	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.

Typ: "read", "readWrite"

AppStorageKeys

The keys an app stored for the user.

Feld	Typ	Pflicht	Beschreibung
keys	string[]	ja	Sorted.

AppStorageMapping

A folder in a shared folder that an administrator mapped to one storage request of an app.

Feld	Typ	Pflicht	Beschreibung
storageId	string	ja	The id of the request in the manifest.
shareId	integer (int64)	ja	The shared folder.
path	string	ja	The folder relative to the shared folder’s root, empty for the root itself.
access	AppStorageAccess	ja	Read-only, or read and write when the request asks for it.

AppStorageMappingRequest

Feld	Typ	Pflicht	Beschreibung
shareId	integer (int64)	ja	The shared folder.
access	AppStorageAccess	ja	Read-only, or read and write when the storage request asks for it.
path	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
value	JsonElement	ja	Any JSON, at most 64 KB.

AppTicket

A one-time ticket for one WebSocket to the app’s backend, as ?pithyx-ticket=.

Feld	Typ	Pflicht	Beschreibung
ticket	string	ja	Works once, within 30 seconds.
expiresAt	string (date-time)	ja	When it stops working (UTC).

AppTicketRequest

Body of POST /api/app/tickets.

Feld	Typ	Pflicht	Beschreibung
endpoint	string	ja	A backend endpoint of the app’s manifest, for example api.

AppToken

A token for one app, user, session and window.

Feld	Typ	Pflicht	Beschreibung
token	string	ja	Send as Authorization: Bearer; never log or store it.
expiresAt	string (date-time)	ja	When it stops working (UTC); ask for a new one before.

AppTokenKind

What a token is for.

Typ: "host", "backend", "ticket", "file"

AppTokenRequest

Body of POST /api/apps/{appId}/tokens.

Feld	Typ	Pflicht	Beschreibung
kind	AppTokenKind	ja	host for the daemon’s API for apps (kept by the desktop), backend for the app’s backend.
instance	string	ja	The window instance: 1 to 64 letters, digits, dashes and underscores.

AppTrashRequest

Body of the recycle bin calls of /api/app/files/trash.

Feld	Typ	Pflicht	Beschreibung
share	string	ja	The shared folder’s id.
ids	null | integer (int64)[]	nein	The items; all items of the bin for empty.
onConflict	null | ConflictPolicy	nein	For restore; rename when left out.

AppUpdate

A newer version of an installed app that a catalog offers.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	The app.
installedVersion	string	ja	The installed version.
version	string	ja	The newest version for this box.
catalog	string	ja	The catalog that offers it.
addedPermissions	string[]	ja	Permissions the new version asks for that the installed one did not.
elevated	boolean	ja	It asks for root in a container or elevated rights it did not have.
policy	UpdatePolicy	ja	The app’s own policy, or the box’s.
automatic	boolean	ja	The next check installs it on its own: the policy is automatic and nothing new is asked for.

AppUpdatePolicyRequest

Feld	Typ	Pflicht	Beschreibung
policy	null | UpdatePolicy	ja	The app’s own update policy; null follows the box’s.

AppUserAccess

One user’s effective access to an app.

Feld	Typ	Pflicht	Beschreibung
userId	integer (int64)	ja	The user’s id.
username	string	ja	Login name.
displayName	null | string	ja	Name shown, if set.
administrator	boolean	ja	Administrators use every app.
disabled	boolean	ja	Deactivated users use none.
allowed	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
share	string	ja	The shared folder’s id.
path	string	ja	The file or folder to bring back.
snapshot	string	ja	The version’s snapshot, as listed.
overwrite	boolean	nein	Replace the current entry instead of restoring next to it.

AuthorityInfo

The box’s certificate authority.

Feld	Typ	Pflicht	Beschreibung
root	CertificateInfo	ja	The root that devices trust; download it from /api/system/tls/root-ca.crt.
intermediate	CertificateInfo	ja	The intermediate that signs every certificate; it is renewed a year before it ends.
restricted	boolean	ja	Name Constraints limit what the authority may sign.
domains	string[]	ja	The DNS suffixes it may sign, each with every name below it; empty when unrestricted.
addressRanges	string[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
version	string	ja
minimumVersion	string	ja
changelog	string	ja
size	integer (int64)	ja
publishedAt	string (date-time)	ja
installable	boolean	ja

BackupCategory

A part of the configuration that can be restored on its own.

Typ: "users", "sharedFolders", "storage", "system", "certificates", "apps", "reverseProxy"

BackupSummary

A backup the daemon decrypted and checked, kept for a restore for 15 minutes.

Feld	Typ	Pflicht	Beschreibung
restoreId	string	ja	Names the checked backup in the restore request.
createdAt	string (date-time)	ja	When the backup was created, UTC.
hostName	string	ja	The host name of the box that created it.
version	string	ja	The Pithyx version that created it.
categories	BackupCategory[]	ja	What it holds and can restore.
users	integer (int32)	ja	Users in the backup.
groups	integer (int32)	ja	Groups in the backup, without the built-in one.
sharedFolders	integer (int32)	ja	Shared folders in the backup.

BondMode

How a bond uses its cards.

Typ: "activeBackup", "lacp", "balanceAlb"

BondSettings

Feld	Typ	Pflicht	Beschreibung
members	string[]	ja	The network cards in the bond, at least one; none of them has its own configuration.
mode	BondMode	ja	How the bond uses its cards.
primary	null | string	nein	For active-backup: the card that carries the traffic while its link is up.
lacpRate	LacpRate	nein	For LACP: how often the partners exchange their state.

CatalogInfo

A catalog of the box.

Feld	Typ	Pflicht	Beschreibung
key	integer (int64)	ja	The box’s number for it, which the catalog endpoints take.
id	null | string	ja	The id from its catalog.json, or null before a custom catalog’s first fetch.
kind	CatalogKind	ja	The project’s official or community catalog, or a custom one.
url	string	ja	The repository.
enabled	boolean	ja	Switched on.
verified	boolean	ja	Its index must carry a signature by a key built into the box (the project’s catalogs).
name	null | map of string	ja	Its name by language from catalog.json, once fetched.
description	null | map of string	ja	Its description by language, if it has one.
homepage	null | string	ja	Its homepage, if it names one.
sshPublicKey	null | string	ja	The deploy key the box made for an SSH URL; add it to the repository with read access.
hostKey	null | string	ja	The server’s host key the box pinned (for hosts other than GitHub, whose keys are built in).
hasRegistryToken	boolean	ja	A read token for its private images is set (never sent back).
status	CatalogStatus	ja	Off, new, ok or failed.
checkedAt	null (date-time) | string (date-time)	ja	When the last fetch ended.
verifiedAt	null (date-time) | string (date-time)	ja	When a fetch last verified the copy.
commit	null | string	ja	The commit of the verified copy.
sequence	null (int64) | integer (int64)	ja	The verified index’s sequence on the box’s channel.
appCount	integer (int32)	ja	How many apps the verified copy lists.
errorCode	null | string	ja	Why the last fetch failed.
errorParams	null | JsonElement	ja	The error’s params.
busy	boolean	ja	A fetch runs.

CatalogKind

Whose catalog it is: the project’s two (signed, keys built in) or one an administrator added (unverified).

Typ: "official", "community", "custom"

CatalogStatus

A catalog’s state for the Store’s settings.

Typ: "off", "new", "ok", "failed"

CertificateInfo

One certificate as Settings shows it.

Feld	Typ	Pflicht	Beschreibung
subject	string	ja	The subject’s distinguished name.
issuer	string	ja	The issuer’s distinguished name.
names	string[]	ja	The DNS names and addresses it covers.
notBefore	string (date-time)	ja	The start of its validity.
notAfter	string (date-time)	ja	The end of its validity.
fingerprint	string	ja	SHA-256 as hex pairs with colons.

CertificateKeyType

The key of a certificate the authority issues.

Typ: "ecdsa", "rsa"

ClientMessage

A message from the client: sub or unsub for a topic or pattern.

Feld	Typ	Pflicht	Beschreibung
type	"sub", "unsub"	ja
id	string	ja	Chosen by the client; echoed in the ack, snapshots and errors that answer this message.
topic	null | string	nein	Topic name or pattern with + and #. A message without one is answered with an error.

ConflictPolicy

Typ: "fail", "skip", "overwrite", "rename", null

CopyLayoutRequest

Feld	Typ	Pflicht	Beschreibung
deviceId	string	ja

CreateAuthorityRequest

A new authority; every device has to trust its root again.

Feld	Typ	Pflicht	Beschreibung
restricted	boolean	ja	Limit the authority to local names and private addresses (recommended).
domains	string[]	ja	With Restricted: DNS suffixes besides the suggested ones, such as a domain of your own.

CreateBackupRequest

Feld	Typ	Pflicht	Beschreibung
password	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
certificatePem	string	ja	The certificate, followed by its intermediates, in PEM.
privateKeyPem	string	ja	Its private key in PEM (PKCS #8, PKCS #1 or SEC 1), unencrypted.

DaemonMode

Typ: "real", "simulated"

Dataset

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Full dataset name, for example tank/pithyx/shares/media.
pool	string	ja	The pool it belongs to.
type	string	ja	filesystem or volume.
usedBytes	integer (int64)	ja	Space used by the dataset and its children.
availableBytes	integer (int64)	ja	Space available to it.
referencedBytes	integer (int64)	ja	Data the dataset references itself.
mountPoint	null | string	ja	Mount point of a file system, if it has one.
mounted	boolean	ja	True while the file system is mounted.
encryption	string	ja	Encryption algorithm, or off.
keyStatus	null | string	ja	available or unavailable for encrypted datasets, otherwise null.
encryptionRoot	null | string	ja	The dataset whose key unlocks this one, if encrypted.
quotaBytes	null (int64) | integer (int64)	ja	Limit for the dataset with its children and snapshots, or null for none.
reservationBytes	null (int64) | integer (int64)	ja	Space guaranteed to the dataset with its children and snapshots, or null for none.
compression	null | string	ja	Compression algorithm, for example lz4, zstd or off.
recordSizeBytes	null (int64) | integer (int64)	ja	Largest block of a file system; null for a volume.
volumeSizeBytes	null (int64) | integer (int64)	ja	Size of a volume; null for a file system.
volumeBlockSizeBytes	null (int64) | integer (int64)	ja	Block size of a volume; null for a file system.
snapshotsUsedBytes	integer (int64)	ja	Space only its snapshots hold.

DebianUpdate

A Debian package apt-get --simulate upgrade would install.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The package.
from	null | string	ja	The installed version; null for a package the upgrade adds.
to	string	ja	The version it would install.
security	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
count	integer (int32)	ja
security	integer (int32)	ja
packages	DebianUpdate[]	ja

DesktopItem

An app shortcut or a sticky note on the desktop, shared across the user’s devices.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id of the item.
kind	DesktopItemKind	ja	What the item is.
app	null | string	ja	Shortcuts: the id of the app it opens.
name	null | string	ja	Shortcuts: the label the user gave it, or null for the app’s name in the user’s language.
text	null | string	ja	Notes: the text.
column	integer (int32)	ja	Grid cell of the item, counted from the top left corner of the desktop.
row	integer (int32)	ja	Grid row of the item.
version	integer (int64)	ja	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.

Feld	Typ	Pflicht	Beschreibung
name	null | string	nein	Shortcuts: the new label; an empty string goes back to the app’s name.
text	null | string	nein	Notes: the new text.
column	null (int32) | integer (int32)	nein	New grid column.
row	null (int32) | integer (int32)	nein	New grid row.

DesktopItemKind

Typ: "shortcut", "note"

DesktopState

Feld	Typ	Pflicht	Beschreibung
layout	null | JsonElement	ja	The saved layout of this device (schema in the desktop, version 1), or null.
layoutVersion	integer (int64)	ja	Increments with every save of this device’s layout, 0 without one. Send it as If-Match: "n" with the next save.
preferences	WindowPreference[]	ja	Window preferences of the user for every app, shared across devices.
appearance	Appearance	ja	Accent color and wallpaper of the user, the same on every device.

DeviceLayout

Another device of the user with a saved layout.

Feld	Typ	Pflicht	Beschreibung
deviceId	string	ja	Pass to POST /api/desktop/layout/copy.
browser	null | string	ja	Browser product name from the User-Agent, if known.
os	null | string	ja	Operating system name from the User-Agent, if known.
windowCount	integer (int64)	ja	Windows in the layout.
updatedAt	string (date-time)	ja	When the layout was last saved (UTC).
screenWidth	null (int64) | integer (int64)	ja	Width of the desktop the layout was saved on, in CSS pixels, if the layout says.
screenHeight	null (int64) | integer (int64)	ja	Its height.

DirectoryGroup

A group of the box, for an app with directory.read. The built-in group is left out.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id (the group’s Linux gid).
name	string	ja	The group name.
description	string	ja	Free text, may be empty.

DirectoryUser

A user of the box, for an app with directory.read. Deactivated users are left out.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id.
name	string	ja	The user name.
displayName	null | string	ja	The name to show, if set.
groups	integer (int64)[]	ja	Ids of the user’s groups, without the built-in group every user is in.

Disk

Feld	Typ	Pflicht	Beschreibung
id	string	ja	Stable across reboots and device renames: wwn-..., else serial-..., else path-....
name	string	ja	Kernel name, for example sda or nvme0n1. Can change between boots.
path	string	ja	Device node, for example /dev/sda.
serial	null | string	ja	Serial number as reported by the drive, if any.
wwn	null | string	ja	World wide name, if any.
model	null | string	ja	Model name, if any.
vendor	null | string	ja	Vendor, if any.
sizeBytes	integer (int64)	ja	Capacity in bytes.
rotational	boolean	ja	True for spinning disks.
transport	null | string	ja	Bus, for example sata, nvme or usb; null for virtual disks.
removable	boolean	ja	True for removable media.
readOnly	boolean	ja	True when the kernel exposes the disk read-only.
partitions	Partition[]	ja	Partitions in on-disk order.

DiskList

Snapshot of storage/disks and response of GET /api/disks.

Feld	Typ	Pflicht	Beschreibung
disks	object[]	ja

DisksChanged

Event of storage/disks: disks that appeared or changed, and ids of disks that disappeared.

Feld	Typ	Pflicht	Beschreibung
upserts	object[]	ja
removals	string[]	ja

ErrorCode

Typ: "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.

Feld	Typ	Pflicht	Beschreibung
id	string	ja
code	ErrorCode	ja
params	map of object	ja
type	"error"	ja
requestId	string	ja

EventMessage

A change of a topic. requestId is the id of the action that caused it, if any.

Feld	Typ	Pflicht	Beschreibung
topic	string	ja
data	object	ja
type	"event"	ja
requestId	string	ja

FileEntry

A file or folder in a share.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Name within its folder.
kind	FileKind	ja	File, folder, symlink (not followed in listings) or another kind such as a device node.
size	integer (int64)	ja	Bytes for files, 0 for folders.
modified	string (date-time)	ja	Last change of the content, UTC.

FileKind

Typ: "file", "folder", "symlink", "other"

FileLocation

Feld	Typ	Pflicht	Beschreibung
shareId	integer (int64)	ja	The share.
path	string	ja	Path relative to the share.

FileOperationKind

Typ: "copy", "move", "delete"

FileOperationRequest

Feld	Typ	Pflicht	Beschreibung
kind	FileOperationKind	ja	copy, move or delete.
items	null | FileLocation[]	nein	The files and folders to work on, at most 1000. Leave out when AllIn is given.
target	null | FileLocation	nein	The folder to copy or move into; not used for delete.
onConflict	null | ConflictPolicy	nein	For copy and move; fail when left out.
permanent	boolean	nein	For delete: remove for good instead of moving to the share’s recycle bin. Only when the user asked for it.
allIn	null | FolderSelection	nein	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.

Feld	Typ	Pflicht	Beschreibung
smbEnabled	boolean	ja	Whether SMB is switched on.
workgroup	string	ja	The SMB workgroup, 1 to 15 letters, digits, dots, dashes and underscores.
sftpEnabled	boolean	ja	Whether SFTP is switched on.
smb	FileServiceState	ja	How SMB is doing.
sftp	FileServiceState	ja	How SFTP is doing.
sshEnabled	boolean	ja	Whether users with the SSH login right may sign in over SSH with a shell. Off by default.
webDavEnabled	boolean	ja	Whether WebDAV is switched on, at /webdav/ of the daemon’s address. Off by default.
ftpEnabled	boolean	ja	Whether FTP is switched on, with TLS (FTPS). Off by default.
ftpPlainAllowed	boolean	ja	Whether FTP also works without TLS, at the users’ own risk. Off by default.
ftp	FileServiceState	ja	How FTP is doing.
ftpPort	integer (int32)	ja	The FTP control port.
ftpFingerprint	null | string	ja	The SHA-256 fingerprint of the FTPS certificate, for clients that ask whether to trust it; null until FTP ran once.
privateNetworksOnly	boolean	ja	Whether the firewall lets only private networks (RFC 1918, ULA, link-local) reach SMB, SFTP, SSH and FTP. Off by default.
firewallActive	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
smbEnabled	null | boolean	nein	Switches SMB on or off.
workgroup	null | string	nein	A new SMB workgroup.
sftpEnabled	null | boolean	nein	Switches SFTP on or off.
sshEnabled	null | boolean	nein	Switches SSH logins with a shell on or off for users with the SSH login right.
webDavEnabled	null | boolean	nein	Switches WebDAV on or off.
ftpEnabled	null | boolean	nein	Switches FTP (FTPS) on or off.
ftpPlainAllowed	null | boolean	nein	Allows or refuses plain FTP without TLS; refusing it ends every plain session.
privateNetworksOnly	null | boolean	nein	Limits SMB, SFTP, SSH and FTP to private networks, or lets every network reach them again.

FileServiceState

How a file service is doing.

Typ: "off", "running", "failed", "unavailable"

FileVersion

Feld	Typ	Pflicht	Beschreibung
snapshot	string	ja	The snapshot the version is in; pass it to restore.
createdAt	string (date-time)	ja	When the snapshot was taken (UTC).
kind	FileKind	ja	File or folder.
size	integer (int64)	ja	Bytes for files, 0 for folders.
modified	string (date-time)	ja	Last change of the content in that version, UTC.

FileVersionList

Response of GET /api/files/{shareId}/versions.

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The file or folder, relative to the share.
versions	FileVersion[]	ja	Newest first; empty when the share is not on a ZFS dataset.

FileVersionRestoreRequest

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The file or folder, relative to the share; it may have been deleted since.
snapshot	string	ja	The snapshot to restore from, as listed.
overwrite	boolean	nein	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.

Feld	Typ	Pflicht	Beschreibung
changed	object[]	ja	Entries that appeared or changed, with their current metadata.
removed	string[]	ja	Names that are gone.
resync	boolean	ja	True when changes were lost (the kernel queue overflowed); list the folder again.
gone	boolean	ja	True when the folder itself was deleted or moved away.

FolderPage

One page of a folder listing.

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The folder, relative to the share (“” for its root).
folderId	string	ja	Stable id of the folder, also after a rename.
total	integer (int32)	ja	Entries in the folder when the listing was made.
entries	FileEntry[]	ja	This page, in the requested order.
nextCursor	null | string	ja	Pass as cursor for the next page; null on the last page.
topic	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
folder	FileLocation	ja	The folder whose entries are meant.
except	string[]	ja	Names left out, at most 1000.

FolderWatchState

The snapshot of a folder topic: the folder as the watch sees it.

Feld	Typ	Pflicht	Beschreibung
watching	boolean	ja	Whether changes are being delivered.

GlobalNetworkConfig

Settings of the whole box.

Feld	Typ	Pflicht	Beschreibung
hostName	string	ja	The host name: letters, digits and hyphens, 1 to 63 characters. Samba uses its first 15 as the NetBIOS name.
dnsServers	string[]	ja	Name servers, at most four; when set they replace those DHCP and router advertisements announce.
searchDomains	string[]	ja	Domains tried for short names, at most six.
defaultInterface	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
resource	string	ja	share:<id>, protocol:smb|sftp|webdav|ftp, app:<id> or right:admin|desktopLogin|sshLogin|power.
level	GrantLevel	ja	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.

Typ: "read", "readWrite", "allow"

GrantsRequest

Feld	Typ	Pflicht	Beschreibung
grants	GrantEntry[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
grants	GrantEntry[]	ja	Every grant of the group.

GroupRef

A group a user is in.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id (the group’s Linux gid).
name	string	ja	The group name.

GroupSummary

A group as the Users page shows it. Administrators only.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id, and the Linux gid: 30000 to 39999 and never reused, 100 for the built-in group.
name	string	ja	The Linux group name, lower case.
description	string	ja	Free text, may be empty.
builtin	boolean	ja	The built-in group users: every user is a member, and it can neither be renamed nor deleted.
memberIds	integer (int64)[]	ja	The ids of its members; every user for the built-in group.
createdAt	string (date-time)	ja	When the group was created, UTC.

GroupUpdate

Fields left out stay as they are. The built-in group takes none of them.

Feld	Typ	Pflicht	Beschreibung
name	null | string	nein	A new name; the gid stays.
description	null | string	nein	An empty text removes the description.
memberIds	null | integer (int64)[]	nein	Every member the group should have; the others leave it.

GuardDecision

Typ: "allowed", "needsSerialConfirmation", "refused"

GuardVerdict

Feld	Typ	Pflicht	Beschreibung
diskId	string	ja	The disk the verdict is for.
decision	GuardDecision	ja	Whether a destructive command may touch the disk.
reason	string	ja	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	ja	The imported pool the disk belongs to, for pool_member.
contents	string[]	ja	What was found on the disk: partitions and signature types.

HealthResponse

Feld	Typ	Pflicht	Beschreibung
status	string	ja
mode	DaemonMode	ja

HomeInfo

A home.

Feld	Typ	Pflicht	Beschreibung
shareId	integer (int64)	ja	Its id as a share: Files opens it with this id.
folder	string	ja	Its folder below homes: the user name, or <name>.deleted-<uid> after its user was deleted.
userId	null (int64) | integer (int64)	ja	Its user, or null when the user was deleted.
username	null | string	ja	The user’s name, or null.
displayName	null | string	ja	The user’s display name, or null.
pool	null | string	ja	The pool it is on.
usedBytes	null (int64) | integer (int64)	ja	Space it uses with its snapshots, or null while it cannot be read.
quotaBytes	null (int64) | integer (int64)	ja	Its quota as set on the pool, or null for none.
ownQuotaBytes	null (int64) | integer (int64)	ja	The user’s own quota: null takes the default, 0 means none.
unavailable	null | string	ja	Why its files cannot be reached now, or null when they can.

HomeMoveRequest

Feld	Typ	Pflicht	Beschreibung
pool	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
pool	null | string	ja	The home pool, or null before the first pool that can take homes.
pools	HomePool[]	ja	Every pool with whether it can take the homes.
defaultQuotaBytes	null (int64) | integer (int64)	ja	The quota of every home without its own, or null for none.
homes	HomeInfo[]	ja	Every home, those of deleted users included.
moving	null (int64) | integer (int64)	ja	The job that moves the homes to another pool while it runs, otherwise null.

HomePool

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The pool.
availableBytes	null (int64) | integer (int64)	ja	Free space for the homes, or null while it cannot be read.
unavailable	null | string	ja	Why it cannot take the homes (missing, offline, read_only, not_prepared, locked, not_mounted), or null when it can.

HomeQuotaRequest

Feld	Typ	Pflicht	Beschreibung
quotaBytes	null (int64) | integer (int64)	ja	The user’s own quota: at least 1 MiB, 0 for none, null for the default.

HomeReleaseRequest

Feld	Typ	Pflicht	Beschreibung
shareId	integer (int64)	ja	The shared folder that gets a folder with the home’s files.

HomeSettingsRequest

Feld	Typ	Pflicht	Beschreibung
defaultQuotaBytes	null (int64) | integer (int64)	ja	The quota of every home without its own: at least 1 MiB, or null for none.

ImportablePool

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The pool’s name as stored on its disks.
poolGuid	string	ja	The numeric identifier as decimal text; pool.import.readonly takes it as poolGuid.
state	string	ja	ZFS state as it would be imported: ONLINE, DEGRADED, UNAVAIL or FAULTED.
status	null | string	ja	What ZFS says is wrong, in English, if anything.
action	null | string	ja	What ZFS says can be done, in English.
messageId	null | string	ja	ZFS message id, for example ZFS-8000-2Q (devices missing) or ZFS-8000-EY (last used by another system).
canImport	boolean	ja	True when ZFS can import the pool.
needsForce	boolean	ja	True when it was last used by another system: importing needs force and the typed name.
nameTaken	boolean	ja	True when an imported pool has this name: the import needs newName.
vdevs	ImportVdev[]	ja	The pool’s layout with each device’s state and disk.
disks	GuardVerdict[]	ja	The guard’s import verdict for each disk the pool is on.
unknownDevices	string[]	ja	Present devices that are on no disk the daemon knows; such a pool is not offered.
allowed	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
pools	ImportablePool[]	ja

ImportVdev

Feld	Typ	Pflicht	Beschreibung
name	string	ja	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	ja	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	ja	What ZFS adds after the state, for example cannot open or insufficient replicas.
diskId	null | string	ja	The disk this device is on, if it is one the daemon knows.
children	ImportVdev[]	ja	Child vdevs.

InheritedGrant

A grant that reaches a user through one of its groups.

Feld	Typ	Pflicht	Beschreibung
resource	string	ja	The resource, as in GrantEntry.
level	GrantLevel	ja	The level, as in GrantEntry.
groupId	integer (int64)	ja	The group that has the grant.
groupName	string	ja	Its name.

InspectBackupRequest

Feld	Typ	Pflicht	Beschreibung
archive	string	ja	The backup file, base64.
password	string	ja	The password it was created with.

InstallAppRequest

Feld	Typ	Pflicht	Beschreibung
pool	null | string	nein	The pool for the app data; required for the first app, and then always the app pool.
access	null | AppAccess	nein	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.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	cpu (x86-64-v2), uefi, memory, secure_boot (off) or disk (a suitable disk exists).
passed	boolean	ja	Whether the box meets it.
params	object	ja	Values for the text, for example minGb and foundGb of memory.

InstallerDisk

A disk as the installer offers it.

Feld	Typ	Pflicht	Beschreibung
disk	Disk	ja	The disk.
suitable	boolean	ja	Whether the system may be installed on it.
reason	null | string	ja	Why not: boot_medium, read_only, in_use (mounted or swap) or too_small.
hasData	boolean	ja	Whether it holds partitions or file systems that the installation erases.
caution	null | string	ja	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.

Feld	Typ	Pflicht	Beschreibung
disks	InstallerDisk[]	ja	Every disk, suitable or not.
network	NetworkLink[]	ja	The network cards with their state and addresses.
networkConfig	NetworkConfig	ja	The network settings of the live system (set on the console, for example), the start of step 2.
timeZones	string[]	ja	IANA time zone names.
keyboardLayouts	string[]	ja	XKB layout codes for the console keyboard.
minDiskBytes	integer (int64)	ja	The smallest disk the system fits on.

InstallerPhase

Typ: "ready", "installing", "installed", "failed", "rebooting"

InstallerStatus

Response of GET /api/installer.

Feld	Typ	Pflicht	Beschreibung
claimed	boolean	ja	Whether a browser owns the installation.
owner	boolean	ja	Whether this browser owns it.
phase	InstallerPhase	ja	Where the installation is.
step	null | string	ja	The step that runs or failed: partition, raid, filesystems, copy, configure, bootloader or finish.
stepIndex	integer (int32)	ja	Zero-based position of Step.
stepCount	integer (int32)	ja	Number of steps.
errorCode	null | string	ja	Why the installation failed.
errorParams	object	ja	Values for its text; for installer.install.failed the step, the command and its exitCode.
installId	null | string	ja	Set once installed: the installed system answers it on http://<address>/api/install-id.
recoveryKey	null | string	ja	Set once installed, for the owner only: the administrator’s recovery key, shown before the reboot.
version	string	ja	The Pithyx version that gets installed.
checks	InstallerCheck[]	ja	The requirements and whether the box meets them.

InstallIdResponse

Response of GET /api/install-id on an installed box.

Feld	Typ	Pflicht	Beschreibung
installId	string	ja

InstallRequest

Body of POST /api/installer/install.

Feld	Typ	Pflicht	Beschreibung
hostname	string	ja	Name of the box, a DNS label.
language	string	ja	System language.
region	null | string	ja	Country of the formats, or null to follow each user’s language.
timeZone	string	ja	IANA time zone.
ntpServers	string[]	ja	Time servers; empty for the defaults.
keyboardLayout	string	ja	XKB layout of the console keyboard.
diskIds	string[]	ja	One disk, or two for a mirror.
username	string	ja	The administrator.
password	string	ja	The administrator’s password.
displayName	null | string	ja	The administrator’s display name.
eraseConfirmed	boolean	ja	The user confirmed that every listed disk is erased.
network	null | NetworkConfig	nein	Everything Pithyx configures in the network. Cards that are not listed get their address by DHCP.

InstallUpdateRequest

Feld	Typ	Pflicht	Beschreibung
source	string	ja	online installs the channel’s newest file, file the uploaded one.
includeDebian	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The interface: the kernel’s name of a card, or the name of a bond or VLAN (1 to 15 characters).
kind	InterfaceKind	ja	Card, bond or VLAN.
enabled	boolean	nein	False keeps the link down.
ipv4	Ipv4Mode	nein	DHCP, static or off.
ipv4Address	null | string	nein	For static: the address with prefix length, for example 192.168.1.10/24.
ipv4Gateway	null | string	nein	For static: the gateway, optional, inside the address’s network.
ipv6	Ipv6Mode	nein	Auto (router advertisements and DHCPv6), static or off.
ipv6Address	null | string	nein	For static: the address with prefix length, for example 2001:db8::10/64.
ipv6Gateway	null | string	nein	For static: the gateway, optional, inside the address’s network or link-local.
mtu	null (int32) | integer (int32)	nein	The MTU in bytes, 1280 to 9000 (576 without IPv6); null keeps the default.
bond	null | BondSettings	nein	For a bond: its cards and mode.
vlan	null | VlanSettings	nein	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.

Typ: "ethernet", "bond", "vlan"

Ipv4Mode

How an interface gets its IPv4 address.

Typ: "dhcp", "static", "off"

Ipv6Mode

How an interface gets its IPv6 address: automatically (router advertisements and DHCPv6), static or none.

Typ: "auto", "static", "off"

IssueCertificateRequest

A certificate for another device.

Feld	Typ	Pflicht	Beschreibung
names	string[]	ja	DNS names (a leading *. for a wildcard) and addresses, 1 to 100, inside the authority’s scope.
validityDays	integer (int32)	ja	1 to 825 days, never past the intermediate’s end.
keyType	CertificateKeyType	ja	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Its number on the box.
certificate	CertificateInfo	ja	The certificate.
keyType	CertificateKeyType	ja	The key it was made with.
createdAt	string (date-time)	ja	When it was issued.
createdBy	null | string	ja	The administrator who issued it, if the account still had that name.
currentAuthority	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
certificate	IssuedCertificate	ja	The entry in the list.
certificatePem	string	ja	The certificate followed by the intermediate, as servers take it.
privateKeyPem	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Also names the job’s topic, jobs/{id}.
kind	string	ja	What the job does, chosen by the module that started it (for example files.copy).
state	JobState	ja	Where the job is in its life.
progress	JobProgress	ja	Live in the topic; in REST answers of running jobs at most about a second old.
parameters	null | JsonElement	ja	What the job was started with, as given by the module that started it.
result	null | JsonElement	ja	What the job produced, if it set a result.
errorCode	null | ErrorCode	ja	Error code of a failed job.
errorParams	null | map of object	ja	Parameters of the error message of a failed job.
requestId	string	ja	Request id of the request that started the job; the job’s logs carry it.
createdAt	string (date-time)	ja	When the job was queued (UTC).
startedAt	null (date-time) | string (date-time)	ja	When it started running (UTC).
finishedAt	null (date-time) | string (date-time)	ja	When it reached a final state (UTC).

JobList

Snapshot of the jobs topic: the signed-in user’s queued and running jobs, oldest first.

Feld	Typ	Pflicht	Beschreibung
jobs	Job[]	ja

JobProgress

How far a job is. Totals are 0 while unknown.

Feld	Typ	Pflicht	Beschreibung
itemsDone	integer (int64)	ja	Items (for example files) finished so far.
itemsTotal	integer (int64)	ja	Items in the whole job.
bytesDone	integer (int64)	ja	Bytes processed so far.
bytesTotal	integer (int64)	ja	Bytes in the whole job.
currentItem	null | string	ja	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.

Typ: "queued", "running", "succeeded", "failed", "cancelled", "interrupted"

JsonElement

Typ: object

LacpRate

How often LACP partners exchange their state: every 30 seconds or every second.

Typ: "slow", "fast"

LogArchiveState

Typ: "off", "ready", "unavailable"

LogEntry

One log entry of the daemon, a system service or an app.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable within the current logs or the archive it comes from.
time	string (date-time)	ja	When it happened, UTC.
level	LogLevelName	ja	debug, info, warn or error.
source	string	ja	daemon, system/<service> (for example system/kernel, system/smbd) or app/<id>.
message	string	ja	The rendered message; secrets are masked before it is stored.
requestId	null | string	ja	The request id (W3C trace id) of the request that caused it, if any.
user	null | string	ja	The user an app entry was written for, if any.
data	null | map of string	ja	Further fields (event name, error code, path, the app’s own data), as text.
archived	boolean	ja	True when the entry comes from the archive on a pool.

LoginRequest

Feld	Typ	Pflicht	Beschreibung
username	string	ja
password	string	ja

LoginResponse

Feld	Typ	Pflicht	Beschreibung
user	null | UserInfo	ja	The signed-in user.
totpRequired	boolean	ja	True when a TOTP or recovery code must follow.
challenge	null | string	ja	Pass to /api/auth/login/totp within five minutes.

LogLevelName

Typ: "debug", "info", "warn", "error"

LogPage

A page of entries, newest first.

Feld	Typ	Pflicht	Beschreibung
entries	LogEntry[]	ja	At most the requested limit.
nextCursor	null | string	ja	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.

Feld	Typ	Pflicht	Beschreibung
retentionDays	integer (int32)	ja	Current logs older than this are dropped (1 to 365).
maxBytes	integer (int64)	ja	The current logs of the system and all apps together stay below this (64 MB to 4 GB); the oldest go first.
archiveEnabled	boolean	ja	Whether entries are also kept in an archive on a pool.
archivePool	null | string	ja	The pool of the archive; null for the first pool.
archiveRetentionDays	integer (int32)	ja	Archived entries older than this are dropped (1 to 3650).
archiveMaxBytes	integer (int64)	ja	The archive stays below this (256 MB to 1 TB).

LogStatus

The settings with what they hold now.

Feld	Typ	Pflicht	Beschreibung
settings	LogSettings	ja	The retention as set.
currentBytes	integer (int64)	ja	Space the current logs take on the system disk.
currentOldest	null (date-time) | string (date-time)	ja	The oldest current entry, or null when there is none.
archiveState	LogArchiveState	ja	Whether the archive is off, written, or waiting for its pool.
archivePool	null | string	ja	The pool the archive is on or would be on, or null when there is no pool.
archiveBytes	null (int64) | integer (int64)	ja	Space the archive takes, or null without one.
archiveOldest	null (date-time) | string (date-time)	ja	The oldest archived entry, or null.
archivedAt	null (date-time) | string (date-time)	ja	When entries were last copied to the archive, or null.
pools	string[]	ja	Pools that can hold the archive.

MarkNotificationsReadRequest

Body of POST /api/notifications/read.

Feld	Typ	Pflicht	Beschreibung
ids	null | integer (int64)[]	nein	The notifications to mark as read; null or missing marks every unread one.

NetworkChangeOrigin

Where a change of the network came from.

Typ: "web", "console"

NetworkCheck

What a change would do, before it is applied.

Feld	Typ	Pflicht	Beschreibung
config	NetworkConfig	ja	The settings as they would be stored (canonical form).
interfaces	string[]	ja	The interfaces whose configuration changes.
hostNameChanged	boolean	ja	Whether the host name changes.
connectionAffected	boolean	ja	Whether the interface this browser’s connection comes in on changes; the page warns.
addresses	string[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
interfaces	InterfaceConfig[]	ja	Cards with their own settings, bonds and VLANs.
global	GlobalNetworkConfig	ja	Host name, name servers, search domains, default route.

NetworkLink

An interface as the system has it now.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The kernel’s name, for example enp1s0.
kind	InterfaceKind	ja	Card, bond or VLAN.
macAddress	null | string	ja	The hardware address.
up	boolean	ja	Whether the interface is up and its link works.
carrier	boolean	ja	Whether a cable (or the other end) is connected.
speedMbps	null (int32) | integer (int32)	ja	The link speed in Mbit/s, when the driver reports it.
duplex	null | string	ja	full or half, when the driver reports it.
mtu	integer (int32)	ja	The MTU in bytes.
addresses	string[]	ja	IPv4 and global IPv6 addresses with prefix length.
gateways	string[]	ja	The default gateways reached through this interface.
dnsServers	string[]	ja	The name servers this interface announced or was given.
defaultRoute	boolean	ja	Whether this interface carries the default route (the lowest metric).
master	null | string	ja	The bond this card belongs to.
vlanParent	null | string	ja	For a VLAN: the interface that carries it.
vlanId	null (int32) | integer (int32)	ja	For a VLAN: its id.
method	string	ja	dhcp, static, off or unknown: how its IPv4 address comes.
configured	boolean	ja	Whether Pithyx keeps settings for it (otherwise a card gets DHCP).
changeable	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
config	NetworkConfig	ja	What Pithyx configured.
links	NetworkLink[]	ja	Every card, bond and VLAN; container bridges and virtual cables are left out.
hostName	string	ja	The host name the system has now.
globalChangeable	boolean	ja	Whether Pithyx may change host name, name servers and the default route here; not on a development machine.
pending	null | PendingNetworkChange	ja	A change of the network waiting for its confirmation.
confirmSeconds	integer (int32)	ja	How long a change waits for its confirmation before it is rolled back.
connectionInterface	null | string	ja	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.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The interface.
up	boolean	ja	Whether its link came up.
addresses	string[]	ja	The addresses it got.
gateways	string[]	ja	Its gateways.
gatewayReachable	null | boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
running	boolean	ja	Whether the test still runs; the page may lose its connection meanwhile.
interfaces	NetworkTestInterface[]	ja	What each tested interface got.
errorCode	null | string	ja	Why the test could not run.
errorParams	object	ja	Values for its text.

NewDesktopItem

Feld	Typ	Pflicht	Beschreibung
kind	DesktopItemKind	ja	What to create.
column	integer (int32)	ja	Grid column.
row	integer (int32)	ja	Grid row.
app	null | string	nein	Shortcuts: the id of the app to open. Required for shortcuts, not allowed for notes.
name	null | string	nein	Shortcuts: an own label, or null for the app’s name.
text	null | string	nein	Notes: the text, at most 4000 characters. Required for notes, not allowed for shortcuts.

NewFolderRequest

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The new folder, relative to the share. Its parent must exist.

NewGroup

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name.
description	null | string	nein	Optional, at most 200 characters.
memberIds	null | integer (int64)[]	nein	The ids of the first members.

NewShare

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Letters, digits, spaces, dots, dashes and underscores, 1 to 64 characters, not starting with a dot.
path	string	ja	An existing folder on the host: absolute, without symlinks, outside the system directories and not overlapping another share.

NewUser

Feld	Typ	Pflicht	Beschreibung
username	string	ja	Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name.
password	string	ja	At least 8 characters and not one of the most common passwords.
displayName	null | string	nein	Optional, at most 64 characters.
groupIds	null | integer (int64)[]	nein	The groups the user joins, besides the built-in group users.
grants	null | GrantEntry[]	nein	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).

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id; never reused.
code	string	ja	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	ja	Message parameters: strings and numbers, plus nested objects where a code says so.
tone	NotificationTone	ja	How the desktop shows it.
app	null | string	ja	Id of the app that sent it; null for the system.
createdAt	string (date-time)	ja	When it was created (UTC).
readAt	null (date-time) | string (date-time)	ja	When the user read it (UTC); null while unread.

NotificationEvent

Event of the notifications topic. Only the user whose notifications changed receives it.

Feld	Typ	Pflicht	Beschreibung
change	"created", "read", "deleted"	ja	What changed in a user’s notifications.
notification	null | object	ja	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)[]	ja	The notifications read or deleted; for created the ones dropped.
readAt	null (date-time) | string (date-time)	ja	When the notifications of a read event were read (UTC).

NotificationList

Snapshot of the notifications topic and answer of GET /api/notifications.

Feld	Typ	Pflicht	Beschreibung
items	Notification[]	ja	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.

Typ: "info", "success", "warning", "critical"

Partition

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Kernel name, for example sda1.
path	string	ja	Device node.
sizeBytes	integer (int64)	ja	Size in bytes.
fileSystem	null | string	ja	File system or content type, for example ext4 or zfs_member.
label	null | string	ja	File system label, if any.
mountPoints	string[]	ja	Where the partition is mounted; empty when it is not.

PasswordReset

Feld	Typ	Pflicht	Beschreibung
password	string	ja	The new password, with the same rules as everywhere.

PendingNetworkChange

A change of the network waiting for its confirmation.

Feld	Typ	Pflicht	Beschreibung
id	string (uuid)	ja	Pass to confirm or revert it.
deadline	string (date-time)	ja	When it is rolled back unless confirmed, UTC.
interfaces	string[]	ja	The interfaces it changed.
addresses	string[]	ja	Static addresses (without prefix) it set; open one of them when the old address went away.
hostName	null | string	ja	The new host name, when it changed.
origin	NetworkChangeOrigin	ja	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.

Feld	Typ	Pflicht	Beschreibung
rights	string[]	ja	The special rights.
protocols	string[]	ja	The file protocols.
apps	string[]	ja	The app ids given to users; the administration apps come with the administrator right.

PlannedCommand

Feld	Typ	Pflicht	Beschreibung
program	string	ja	Program name.
arguments	string[]	ja	Arguments, passed without a shell.

Pool

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Pool name.
poolGuid	string	ja	Pool GUID as decimal text (it does not fit a JSON number).
state	string	ja	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)	ja	Raw size of all vdevs, parity included.
allocatedBytes	integer (int64)	ja	Raw space in use.
freeBytes	integer (int64)	ja	Raw space free.
capacityPercent	integer (int32)	ja	Share of the raw space in use.
fragmentationPercent	null (int32) | integer (int32)	ja	Free space fragmentation, if known.
readOnly	boolean	ja	True when the pool was imported read-only.
dataErrors	integer (int64)	ja	Number of files with permanent errors.
scan	null | PoolScan	ja	The last or running scrub or resilver, if any.
vdevs	Vdev[]	ja	Top-level vdevs, including log, cache, special and spare devices.
expansion	null | PoolExpansion	nein	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.

Feld	Typ	Pflicht	Beschreibung
state	string	ja	scanning while it runs, then finished or canceled.
vdevGuid	null | string	ja	GUID of the raidz vdev that grows, if it is still in the pool.
startedAt	null (date-time) | string (date-time)	ja	When it started (UTC).
endedAt	null (date-time) | string (date-time)	ja	When it ended (UTC), if it did.
toReflowBytes	integer (int64)	ja	Bytes to move onto the new layout.
reflowedBytes	integer (int64)	ja	Bytes moved so far.
waitingForResilver	boolean	ja	True while it waits for a resilver to finish.

PoolList

Snapshot and event of storage/pools, and response of GET /api/storage/pools.

Feld	Typ	Pflicht	Beschreibung
pools	Pool[]	ja
datasets	Dataset[]	ja

PoolScan

Feld	Typ	Pflicht	Beschreibung
kind	string	ja	Scan kind: scrub or resilver.
state	string	ja	scanning, finished or canceled.
paused	boolean	ja	True for a paused scrub.
startedAt	null (date-time) | string (date-time)	ja	When the scan started (UTC).
endedAt	null (date-time) | string (date-time)	ja	When it ended (UTC), if it did.
toExamineBytes	integer (int64)	ja	Bytes the scan covers.
examinedBytes	integer (int64)	ja	Bytes examined so far.
errors	integer (int64)	ja	Errors the scan found.

PowerAction

What the power button does.

Typ: "restart", "shutdown"

PowerRequest

Feld	Typ	Pflicht	Beschreibung
action	PowerAction	ja	restart or shutdown.

ProcessList

Snapshot and event of system/processes.

Feld	Typ	Pflicht	Beschreibung
at	string (date-time)	ja	When the list was read (UTC).
processes	object[]	ja	Every process except kernel threads.

ProxyBasicAuthUser

A user of the host’s Basic Auth.

Feld	Typ	Pflicht	Beschreibung
username	string	ja	1 to 64 characters without a colon.
password	null | string	nein	The password; leave it out to keep the stored one of an existing user.

ProxyCertificateSource

Which certificate a host presents on 443.

Typ: "box", "custom"

ProxyHeader

A header the proxy sets; an empty value removes it.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The header’s name, letters, digits and -; never one the proxy controls itself.
value	string	ja	Its value, at most 4096 characters, without line breaks.

ProxyHost

A proxy host as Settings shows it.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Its number on the box.
domains	string[]	ja	The names it answers.
enabled	boolean	ja	It answers.
target	ProxyTarget	ja	Where requests go.
webSockets	boolean	ja	WebSocket upgrades pass.
http2	boolean	ja	HTTP/2 is offered on 443.
certificate	ProxyCertificateSource	ja	Which certificate it presents.
presented	null | CertificateInfo	ja	One certificate as Settings shows it.
forceHttps	boolean	ja	Plain HTTP is redirected to HTTPS.
hsts	boolean	ja	HTTPS answers carry Strict-Transport-Security.
forwardedHeaders	boolean	ja	X-Forwarded-* go to the target.
preserveHost	boolean	ja	The browser’s Host goes to the target.
hostHeader	null | string	ja	The Host of the administrator’s choice, if any.
requestHeaders	ProxyHeader[]	ja	Headers set on requests.
responseHeaders	ProxyHeader[]	ja	Headers set on answers.
maxBodyMegabytes	null (int32) | integer (int32)	ja	The upload limit in MB, or none.
connectTimeoutSeconds	integer (int32)	ja	The connect timeout.
responseTimeoutSeconds	integer (int32)	ja	The idle timeout of an answer.
allowAddresses	string[]	ja	Only these get in, or everybody when empty.
denyAddresses	string[]	ja	These never get in.
basicAuthUsers	string[]	ja	The user names of the Basic Auth; passwords are never shown.
signIn	ProxySignInRule	ja	The Pithyx sign-in in front of the host.
accessLog	boolean	ja	Requests are logged.
logSource	string	ja	The Log Center’s source of its requests.
createdAt	string (date-time)	ja	When it was made.
updatedAt	string (date-time)	ja	When it was last saved.

ProxyHostRequest

A proxy host as an administrator saves it.

Feld	Typ	Pflicht	Beschreibung
domains	string[]	ja	1 to 50 DNS names, a leading *. for any one label in front; no name of another host.
enabled	boolean	ja	The host answers; a disabled one is treated as unknown.
target	ProxyTarget	ja	Where requests go.
webSockets	boolean	ja	Pass WebSocket upgrades through.
http2	boolean	ja	Offer HTTP/2 to browsers on 443.
certificate	ProxyCertificateSource	ja	Which certificate the host presents on 443.
forceHttps	boolean	ja	Redirect plain HTTP on 80 to HTTPS on 443.
hsts	boolean	ja	Send Strict-Transport-Security on HTTPS; browsers then refuse plain HTTP and any certificate warning for a year.
forwardedHeaders	boolean	ja	Send X-Forwarded-For, -Proto and -Host; incoming ones are always dropped.
preserveHost	boolean	ja	Send the browser’s Host instead of the target’s.
hostHeader	null | string	ja	A Host of your own; overrides PreserveHost.
requestHeaders	ProxyHeader[]	ja	Headers set on the request to the target, at most 20.
responseHeaders	ProxyHeader[]	ja	Headers set on the answer to the browser, at most 20.
maxBodyMegabytes	null (int32) | integer (int32)	ja	The largest upload in MB (1 to 1048576); none for no limit.
connectTimeoutSeconds	integer (int32)	ja	How long connecting to the target may take, 1 to 300 seconds.
responseTimeoutSeconds	integer (int32)	ja	How long the target may stay silent, 1 to 86400 seconds.
allowAddresses	string[]	ja	Only these addresses or CIDR ranges get in; empty for everybody.
denyAddresses	string[]	ja	These addresses or ranges never get in.
basicAuth	ProxyBasicAuthUser[]	ja	Users of Basic Auth, at most 20; empty for none.
signIn	ProxySignInRule	ja	The Pithyx sign-in in front of the host.
accessLog	boolean	ja	Log every request in the Log Center under proxy/<first domain>.
certificatePem	null | string	nein	With ProxyCertificateSource.Custom: the certificate and its chain in PEM; leave it out to keep the uploaded one.
privateKeyPem	null | string	nein	Its unencrypted private key in PEM.

ProxyOptionsRequest

The settings that apply to every host.

Feld	Typ	Pflicht	Beschreibung
unknownHosts	UnknownHostAction	ja	What a name no enabled host has gets.
signInAddress	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Its number on the box.
domains	string[]	ja	The names it answers.
enabled	boolean	ja	It answers.
target	string	ja	Where it sends browsers.
status	integer (int32)	ja	The redirect’s status code.
preservePath	boolean	ja	The path and query are kept.
certificate	ProxyCertificateSource	ja	Which certificate it presents.
presented	null | CertificateInfo	ja	One certificate as Settings shows it.
createdAt	string (date-time)	ja	When it was made.
updatedAt	string (date-time)	ja	When it was last saved.

ProxyRedirectRequest

A redirect host as an administrator saves it.

Feld	Typ	Pflicht	Beschreibung
domains	string[]	ja	1 to 50 DNS names, as for a proxy host.
enabled	boolean	ja	The host answers.
target	string	ja	An absolute http or https URL.
status	integer (int32)	ja	301, 302, 307 or 308.
preservePath	boolean	ja	Append the request’s path and query to Target.
certificate	ProxyCertificateSource	ja	Which certificate the host presents on 443.
certificatePem	null | string	nein	With ProxyCertificateSource.Custom: the certificate and chain; leave it out to keep the uploaded one.
privateKeyPem	null | string	nein	Its unencrypted private key.

ProxySettings

Settings > Reverse proxy.

Feld	Typ	Pflicht	Beschreibung
plainPort	null (int32) | integer (int32)	ja	The port proxy hosts answer plain HTTP on (80 on a box); none in development unless set.
tlsPort	null (int32) | integer (int32)	ja	The port proxy hosts answer HTTPS on (443 on a box); none without HTTPS.
unknownHosts	UnknownHostAction	ja	What a name no enabled host has gets.
signInAddress	null | string	ja	Where the Pithyx sign-in of a host sends visitors; none for the requested name on 7484.
hosts	ProxyHost[]	ja	The proxy hosts.
redirects	ProxyRedirect[]	ja	The redirect hosts.
streams	ProxyStream[]	ja	The streams.

ProxySignInRule

Who may pass the host’s Pithyx sign-in.

Feld	Typ	Pflicht	Beschreibung
required	boolean	ja	Visitors sign in with their account on the box first.
users	string[]	ja	User names allowed besides the groups; administrators always are.
groups	string[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Its number on the box.
name	string	ja	What it is for.
enabled	boolean	ja	The port is open.
port	integer (int32)	ja	The box’s port.
tcp	boolean	ja	TCP is forwarded.
udp	boolean	ja	UDP is forwarded.
targetHost	string	ja	Where it forwards to.
targetPort	integer (int32)	ja	The target’s port.
listening	boolean	ja	The box listens on the port now; false while disabled or when another program holds it.
createdAt	string (date-time)	ja	When it was made.
updatedAt	string (date-time)	ja	When it was last saved.

ProxyStreamRequest

A stream as an administrator saves it.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	What it is for, at most 100 characters.
enabled	boolean	ja	The port is open and forwards.
port	integer (int32)	ja	The box’s port; not one of the box’s own services, below 1024 only with PrivilegedPort.
tcp	boolean	ja	Forward TCP.
udp	boolean	ja	Forward UDP.
targetHost	string	ja	A DNS name or IP address.
targetPort	integer (int32)	ja	1 to 65535.
privilegedPort	boolean	nein	The administrator confirmed a port below 1024.

ProxyTarget

Where a proxy host forwards to.

Feld	Typ	Pflicht	Beschreibung
scheme	string	ja	http or https.
host	string	ja	A DNS name or IP address.
port	integer (int32)	ja	1 to 65535.
tls	ProxyTargetTls	ja	How an HTTPS target’s certificate is checked.
onBox	boolean	ja	The administrator confirmed that the target is a service of this box itself.

ProxyTargetStatus

Whether a proxy host’s target answers.

Feld	Typ	Pflicht	Beschreibung
reachable	boolean	ja	The target answered with any HTTP status.
status	null (int32) | integer (int32)	ja	Its status code, if it answered.
error	null | string	ja	Why not: timeout, refused, dns, tls or other.
milliseconds	integer (int64)	ja	How long the check took.

ProxyTargetTls

How the proxy checks the certificate of an HTTPS target.

Typ: "system", "box", "none"

ProxyTicket

Where the browser goes next: the proxy host’s sign-in address with a one-time ticket.

Feld	Typ	Pflicht	Beschreibung
url	string	ja	The address to open.

ProxyTicketRequest

A browser wants into a proxy host with the Pithyx sign-in.

Feld	Typ	Pflicht	Beschreibung
url	string	ja	The address it asked for.

RecoverRequest

Feld	Typ	Pflicht	Beschreibung
username	string	ja
recoveryKey	string	ja
newPassword	string	ja

RecoverResponse

Feld	Typ	Pflicht	Beschreibung
recoveryKey	string	ja	The new recovery key. The old one no longer works.

RecoveryCodes

Feld	Typ	Pflicht	Beschreibung
codes	string[]	ja	Shown exactly once. Each code replaces a TOTP code for one login.

RenameRequest

Feld	Typ	Pflicht	Beschreibung
path	string	ja	The file or folder to rename.
name	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
at	string (date-time)	ja	When it was measured (UTC).
uptimeSeconds	number (double)	ja	Seconds since boot.
loadAverage	number (double)[]	ja	Over 1, 5 and 15 minutes.
cpu	object	ja
memory	object	ja	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[]	ja	Every interface except the loopback and container links.
disks	object[]	ja	Every whole disk (no partitions, zvols or loop devices).
temperatures	object[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
cpuCount	integer (int32)	ja	Cores the kernel lists.
memoryTotalBytes	integer (int64)	ja	Installed memory the kernel manages.
history	object	ja	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	ja	One second of the box, the event of system/resources. Rates are per second since the previous sample.

RestoreBackupRequest

Feld	Typ	Pflicht	Beschreibung
restoreId	string	ja	From the summary of the checked backup.
categories	BackupCategory[]	ja	The parts to restore; each replaces the current one completely.

RestorePointsRequest

Feld	Typ	Pflicht	Beschreibung
enabled	boolean	ja	Daily restore points, kept 7 days, on or off.

RestoreProblem

A step of a restore that did not work; the rest was restored.

Feld	Typ	Pflicht	Beschreibung
category	BackupCategory	ja	The part it belongs to.
step	string	ja	accounts (Linux accounts and groups), linuxPasswords, sambaPasswords, time, tls or sshKeys.

RestoreResult

Feld	Typ	Pflicht	Beschreibung
restored	BackupCategory[]	ja	The parts that were restored.
problems	RestoreProblem[]	ja	Steps that failed; details are in the Log Center.
restarting	boolean	ja	The daemon restarts in a few seconds to load the restored configuration.

RollbackRequest

Feld	Typ	Pflicht	Beschreibung
snapshot	string	ja	The snapshot to restore.
version	string	ja	Its version, typed by the administrator as the confirmation.

SavedLayout

Feld	Typ	Pflicht	Beschreibung
layout	JsonElement	ja	The layout now saved for this device.
version	integer (int64)	ja	Its version, for If-Match on the next save.

ServerMessage

Typ: AckMessage | SnapshotMessage | EventMessage | 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.

Feld	Typ	Pflicht	Beschreibung
admin	boolean	ja	Administrators may do everything.
rights	string[]	ja	The special rights: right:admin, right:desktopLogin, right:sshLogin, right:power.
protocols	string[]	ja	The file protocols: protocol:smb, protocol:sftp, protocol:webdav, protocol:ftp.
apps	string[]	ja	The ids of the apps of IReadOnlyList<string> PermissionCatalog.Apps the user may open.

SetupRequest

Feld	Typ	Pflicht	Beschreibung
username	string	ja
password	string	ja
displayName	null | string	nein

SetupResponse

Feld	Typ	Pflicht	Beschreibung
user	UserInfo	ja	The administrator, already signed in.
recoveryKey	string	ja	Shown exactly once. It is the only way to reset the administrator password.

SetupStatus

Feld	Typ	Pflicht	Beschreibung
required	boolean	ja	True until the first administrator exists.
hostname	string	ja	Shown on the setup and sign-in screens, so users with several servers know where they sign in.
language	string	ja	The system language, for the sign-in page and everyone whose browser asks for a language Pithyx does not have.
region	null | string	ja	The ISO 3166 country code whose formats every user sees, or null to follow each user’s language.
installer	boolean	ja	True on the live system of the ISO: the desktop shows the installer (/api/installer) instead of the sign-in.

ShareAccess

Typ: "none", "read", "readWrite"

ShareDataChoice

Typ: "keep", "destroy", null

ShareDetails

A share with what the Shared folders page shows. Administrators only.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id.
name	string	ja	Name shown to users.
description	string	ja	Free text for administrators and users, may be empty.
path	string	ja	The share root on the host.
pool	null | string	ja	The pool of the share’s dataset; null for a folder share.
dataset	null | string	ja	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)	ja	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)	ja	Space still available to the dataset; null like UsedBytes.
quotaBytes	null (int64) | integer (int64)	ja	The dataset’s quota, or null for none.
readUsers	integer (int32)	ja	Active users other than administrators who may read, through their own grants or their groups.
readWriteUsers	integer (int32)	ja	Active users other than administrators who may read and write, through their own grants or their groups.
restorePoints	null | boolean	ja	Whether daily restore points (snapshots kept 7 days) are on; null for a folder share.
smb	boolean	ja	Whether SMB offers the shared folder (dataset shares only).
sftp	boolean	ja	Whether SFTP shows the shared folder (dataset shares only).
smbEncrypt	boolean	ja	Whether SMB clients must encrypt.
webDav	boolean	ja	Whether WebDAV offers the shared folder.
ftp	boolean	ja	Whether FTP offers the shared folder.

ShareGrants

Who may use a shared folder. Administrators only.

Feld	Typ	Pflicht	Beschreibung
grants	SubjectGrant[]	ja	The grants of users and groups on it; the editor changes these.
users	ShareUserAccess[]	ja	Every user with the access it ends up with, administrators and deactivated users included.

ShareGrantsRequest

Feld	Typ	Pflicht	Beschreibung
grants	SubjectGrant[]	ja	Every grant the shared folder should have; the others go.

ShareInfo

A share the user can use.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id; file paths are relative to the share.
name	string	ja	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	ja	The user’s access: read or read and write.
path	null | string	ja	The share root on the host. Only administrators get it.
unavailable	null | string	nein	Why its files cannot be reached now (ShareAvailability), or null when they can.
kind	ShareKind	nein	A shared folder, the caller’s home or another user’s home.

ShareKind

What a share is.

Typ: "share", "home", "userHome"

ShareListRevision

Snapshot and event of shares/list.

Feld	Typ	Pflicht	Beschreibung
revision	integer (int64)	ja	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.

Feld	Typ	Pflicht	Beschreibung
action	string	ja	share.create or share.delete.
name	null | string	nein	Name of the new shared folder; its dataset name is derived from it and shown in the plan.
pool	null | string	nein	Pool of the new shared folder; it needs the Pithyx layout (<pool>/pithyx/shares).
description	null | string	nein	Description of the new shared folder.
shareId	null (int64) | integer (int64)	nein	The shared folder to delete.
confirmName	null | string	nein	The shared folder’s name, typed by the user to delete it.
data	null | ShareDataChoice	nein	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.

Feld	Typ	Pflicht	Beschreibung
name	null | string	nein	New name shown to users, unique like every share name.
description	null | string	nein	New description, at most 200 characters, empty to remove it.
smb	null | boolean	nein	Offers the shared folder over SMB or stops it.
sftp	null | boolean	nein	Shows the shared folder over SFTP or hides it.
smbEncrypt	null | boolean	nein	Requires SMB clients to encrypt, or lets them choose.
webDav	null | boolean	nein	Offers the shared folder over WebDAV or stops it.
ftp	null | boolean	nein	Offers the shared folder over FTP or stops it.

ShareUserAccess

One user’s effective access to a shared folder.

Feld	Typ	Pflicht	Beschreibung
userId	integer (int64)	ja	The user’s id.
username	string	ja	Login name.
displayName	null | string	ja	Name shown, if set.
administrator	boolean	ja	Administrators use every shared folder with read and write.
disabled	boolean	ja	Deactivated users use none.
access	ShareAccess	ja	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.

Feld	Typ	Pflicht	Beschreibung
diskId	string	ja	The disk’s id.
state	string	ja	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	ja	For unsupported: virtual (a disk of a virtual machine) or not_available. For unknown: asleep, not_read or read_failed. Otherwise null.
asleep	boolean	ja	True when the last check found the disk asleep; the values are then from ReadAt.
temperatureCelsius	null (int32) | integer (int32)	ja	Current temperature, if reported.
powerOnHours	null (int64) | integer (int64)	ja	Power-on time, if reported.
reallocatedSectors	null (int64) | integer (int64)	ja	ATA attribute 5, raw value.
pendingSectors	null (int64) | integer (int64)	ja	ATA attribute 197, raw value.
uncorrectableSectors	null (int64) | integer (int64)	ja	ATA attribute 198, raw value.
mediaErrors	null (int64) | integer (int64)	ja	NVMe media and data integrity errors.
criticalWarning	null (int32) | integer (int32)	ja	NVMe critical warning bits; not 0 means the drive reports a critical condition.
lastSelfTest	null | string	ja	Result of the newest self-test: passed, failed, aborted or running; null without one.
readAt	null (date-time) | string (date-time)	ja	When SMART data was last read (UTC); null if never.
checkedAt	string (date-time)	ja	When the disk was last checked (UTC), including checks that found it asleep.

Snapshot

Feld	Typ	Pflicht	Beschreibung
dataset	string	ja	The dataset the snapshot belongs to, for example tank/pithyx/shares/media.
name	string	ja	The part after @, for example pithyx-daily-20260927T000000Z.
createdAt	string (date-time)	ja	When ZFS took it (UTC), by the clock the box had then.
usedBytes	integer (int64)	ja	Space only this snapshot holds.
referencedBytes	integer (int64)	ja	Data the snapshot references.
holds	integer (int32)	ja	Number of holds (userrefs); a held snapshot cannot be destroyed.
createTxg	integer (int64)	ja	The transaction group it was taken in: the order of snapshots, whatever the clock said.
fullName	null | string	ja
pithyxKind	null | string	ja	The schedule kind of a snapshot Pithyx created, or null for every other snapshot.

SnapshotCreateRequest

Feld	Typ	Pflicht	Beschreibung
dataset	string	ja	The dataset to snapshot.

SnapshotInfo

A read-only snapshot of the system (@ with /var/lib/pithyx), taken before an update.

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Its folder in /@snapshots, the UTC time it was taken (20261009T214000Z).
version	string	ja	The Pithyx version it holds.
createdAt	string (date-time)	ja	When it was taken.
kernel	string	ja	The kernel release it booted with; its GRUB entry boots that kernel.
reason	string	ja	Why it was taken, for example update to 0.2.0.

SnapshotList

Response of GET /api/storage/snapshots.

Feld	Typ	Pflicht	Beschreibung
dataset	string	ja	The dataset.
snapshots	Snapshot[]	ja	Its snapshots, oldest first.

SnapshotMessage

The full current state of a topic, sent after sub. Only changes follow as events.

Feld	Typ	Pflicht	Beschreibung
id	string	ja
topic	string	ja
data	object	ja
type	"snap"	ja
requestId	string	ja

SnapshotRequest

Feld	Typ	Pflicht	Beschreibung
dataset	string	ja	The dataset.
name	string	ja	The exact snapshot name after @.

SnapshotSchedule

Feld	Typ	Pflicht	Beschreibung
kind	string	ja	hourly, daily, weekly or monthly.
enabled	boolean	ja	Whether the schedule takes snapshots.
keep	integer (int32)	ja	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.

Feld	Typ	Pflicht	Beschreibung
dataset	string	ja	The dataset.
schedules	SnapshotSchedule[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
version	string	ja
channel	string	ja
minimumVersion	string	ja
changelog	string	ja
size	integer (int64)	ja
trustedSignature	boolean	ja
packages	integer (int32)	ja
kernel	string	ja
publishedAt	string (date-time)	ja

StorageAlert

A storage problem that exists now. Alerts are derived from the current state, never stored.

Feld	Typ	Pflicht	Beschreibung
key	string	ja	Stable key of the cause, for example pool.degraded:tank or disk.smart_failed:wwn-0x5000c500a1b2c3d4.
severity	string	ja	warning or critical.
code	string	ja	Message code in the notifications namespace (<code>.title, .body, .action).
params	object	ja	Message parameters: strings and numbers.
since	string (date-time)	ja	When the daemon first saw the cause (UTC); a restart starts it again.
muted	boolean	ja	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.

Feld	Typ	Pflicht	Beschreibung
disk	Disk	ja
guard	GuardVerdict	ja

StorageDiskList

Response of GET /api/storage/disks.

Feld	Typ	Pflicht	Beschreibung
disks	StorageDisk[]	ja	Every disk with its verdict.
environment	string	ja	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.

Feld	Typ	Pflicht	Beschreibung
alerts	StorageAlert[]	ja	Current alerts, critical first, with the user’s mute flags.
smart	SmartReport[]	ja	SMART state of every disk.

StoragePlanPreview

Response of POST /api/storage/plans. Nothing was run.

Feld	Typ	Pflicht	Beschreibung
planId	null | string	ja	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[]	ja	The guard’s verdict for every chosen disk, after probing them again.
commands	null | PlannedCommand[]	ja	The exact commands, or null while a disk is not allowed.
datasets	string[]	ja	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)	ja	Until when the plan may run.
warnings	string[]	ja	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	ja	True when the plan runs only with the pool’s name (for a rollback the dataset’s full name) typed in confirmName.
unmounted	UnmountedDataset[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
action	string	ja	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	ja	The pool, or the new pool’s name; for pool.import.readonly the scanned name (the GUID decides).
layout	null | string	nein	single, stripe, mirror, mirrors (pairs), raidz1, raidz2 or raidz3.
diskIds	null | string[]	nein	The disks to use, by id.
name	null | string	nein	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	nein	GUID of the device to replace, take offline, bring online or remove, or of the raidz vdev to expand.
encryption	null | string	nein	The answer to the encryption question of a new pool: none, or key once the key vault exists.
confirmName	null | string	nein	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	nein	Serial numbers the user typed, by disk id.
dataset	null | string	nein	Full name of the dataset or volume to rename, change or destroy, on Pool.
newName	null | string	nein	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)	nein	New quota in bytes (dataset, children and snapshots), 0 for none; null leaves it.
reservationBytes	null (int64) | integer (int64)	nein	New reservation in bytes (dataset, children and snapshots), 0 for none; null leaves it.
compression	null | string	nein	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)	nein	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)	nein	Size of a new volume, at least 1 MiB; rounded up to whole 16 KiB blocks.
sparse	null | boolean	nein	True for a volume that reserves no space up front.
poolGuid	null | string	nein	For pool.import.readonly: the pool’s numeric identifier from the import scan.
force	null | boolean	nein	For imports: import a pool that was last used by another system; needs ConfirmName.

StorageSchedule

Feld	Typ	Pflicht	Beschreibung
kind	string	ja	scrub, shortSelfTest or longSelfTest.
target	string	ja	The pool name for scrubs; empty for self-tests, which cover every disk with SMART.
frequency	string	ja	off, weekly or monthly.
lastRunAt	null (date-time) | string (date-time)	ja	When it last ran (UTC); for self-tests the oldest of all disks. Null if never.
nextRunAt	null (date-time) | string (date-time)	ja	When it runs next (UTC); null when it is off or has nothing to run on.

StorageScheduleList

Response of GET /api/storage/schedules.

Feld	Typ	Pflicht	Beschreibung
schedules	StorageSchedule[]	ja

StorageScheduleUpdate

Body of PUT /api/storage/schedules.

Feld	Typ	Pflicht	Beschreibung
kind	string	ja	scrub, shortSelfTest or longSelfTest.
target	string	ja	The pool name for scrubs; empty for self-tests.
frequency	string	ja	off, weekly or monthly.

StoreApp

An app of a catalog, at the newest version this box can run.

Feld	Typ	Pflicht	Beschreibung
catalog	string	ja	The catalog’s id.
kind	CatalogKind	ja	The catalog’s kind; custom ones are unverified.
id	string	ja	The app id.
version	string	ja	The newest version for this box.
name	map of string	ja	Names by language.
description	null | map of string	ja	Descriptions by language, if any.
author	null | string	ja	The author’s name, if the manifest has one.
license	string	ja	The SPDX license.
icon	string	ja	The icon’s URL.
installedVersion	null | string	ja	The installed version, if the app is installed.
update	boolean	ja	The installed app is older than Version.

StoreAppDetails

The detail page of a catalog app.

Feld	Typ	Pflicht	Beschreibung
app	StoreApp	ja	The app at its newest fitting version.
manifest	JsonElement	ja	That version’s manifest.
screenshots	string[]	ja	URLs of its screenshots, in order.
homepage	null | string	ja	The manifest’s homepage, if any.
source	string	ja	Where its source is: the catalog repository at the commit CI built, in the app’s folder.
versions	StoreAppVersion[]	ja	Every published version, newest first.

StoreAppList

Apps of the enabled catalogs, sorted by name.

Feld	Typ	Pflicht	Beschreibung
apps	StoreApp[]	ja

StoreAppVersion

A published version of a catalog app.

Feld	Typ	Pflicht	Beschreibung
version	string	ja	The version.
publishedAt	string (date-time)	ja	When the catalog published it.
pithyx	string	ja	The range of Pithyx versions it runs on.
fits	boolean	ja	This box can install it (its version and architecture).
dataVersion	null (int32) | integer (int32)	ja	Its data version, if it declares one.

StoreChannel

Which branch of every catalog the box reads: catalog (stable) or catalog-next (beta).

Typ: "stable", "beta"

StoreSettings

The Store’s settings.

Feld	Typ	Pflicht	Beschreibung
policy	UpdatePolicy	ja	What a check does with newer versions; each app may override it.
time	string	ja	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	ja	The branch every catalog is read from.
nextCheckAt	string (date-time)	ja	When the next check runs (UTC), the box’s delay included.
lastCheckAt	null (date-time) | string (date-time)	ja	When the last check ran (UTC), if one did.

StoreSettingsRequest

Feld	Typ	Pflicht	Beschreibung
policy	UpdatePolicy	ja	What a check does with newer versions.
time	string	ja	HH:mm in the box’s time zone.
channel	StoreChannel	ja	stable or beta.

StoreState

The Store for administrators: the snapshot and every event of the topic store/admin.

Feld	Typ	Pflicht	Beschreibung
settings	StoreSettings	ja	The settings with the next check.
catalogs	CatalogInfo[]	ja	Every catalog, the project’s first.
updates	AppUpdate[]	ja	Newer versions of installed apps, by app id.

SubjectGrant

A user’s or a group’s access to one shared folder.

Feld	Typ	Pflicht	Beschreibung
subjectKind	SubjectKind	ja	user or group.
subjectId	integer (int64)	ja	The user’s or the group’s id.
level	GrantLevel	ja	read or readWrite.

SubjectKind

Who a grant is for. Apps join in M4; until then nothing grants to them.

Typ: "user", "group", "app"

SystemInfo

Feld	Typ	Pflicht	Beschreibung
hostname	string	ja	The host name of the box.
uptimeSeconds	number (double)	ja	Seconds since boot.
loadAverage	number (double)[]	ja	Over 1, 5 and 15 minutes.
cpuPercent	null (double) | number (double)	ja	Usage since the previous sample; null for the very first one.
memoryTotalBytes	integer (int64)	ja	Physical memory.
memoryAvailableBytes	integer (int64)	ja	Memory available for new work without swapping, including reclaimable caches.

SystemOverview

Feld	Typ	Pflicht	Beschreibung
version	string	ja	The Pithyx version.
commit	null | string	ja	The git commit it was built from, if known.
operatingSystem	string	ja	The distribution, for example “Debian GNU/Linux 13 (trixie)”.
kernel	string	ja	The running Linux kernel.
machine	null | string	ja	Vendor and product of the board or virtual machine, if the firmware reports them.
cpuModel	null | string	ja	The processor, if known.
cpuCores	integer (int32)	ja	Logical processors.
memoryTotalBytes	integer (int64)	ja	Physical memory.
hostname	string	ja	The host name.
uptimeSeconds	number (double)	ja	Seconds since boot.

SystemRegion

The regional settings of the box.

Feld	Typ	Pflicht	Beschreibung
language	string	ja	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	ja	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.

Feld	Typ	Pflicht	Beschreibung
folder	null | string	ja	The folder shown, relative to the share.
names	string[]	ja	Entries of that folder on screen, at most 200.
size	ThumbnailSize	ja	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).

Typ: "small", "large"

ThumbnailsReady

Event of thumbnails/<share>/<folder>: thumbnails that were rendered or refused.

Feld	Typ	Pflicht	Beschreibung
items	object[]	ja	Each with ready and its version, or none.
size	"small", "large"	ja	The two thumbnail sizes: rows of the list, tiles of the grid (both twice their CSS size for sharp screens).

ThumbnailState

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The entry.
status	ThumbnailStatus	ja	Whether it has a thumbnail.
version	null | string	ja	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.

Feld	Typ	Pflicht	Beschreibung
topic	string	ja	Subscribe to it for the thumbnails that are still pending.
items	ThumbnailState[]	ja	One state per distinct name asked for.

ThumbnailStatus

Whether a thumbnail can be shown now.

Typ: "ready", "pending", "none"

ThumbnailWatch

Snapshot of a thumbnail topic; the events carry everything.

Feld	Typ	Pflicht	Beschreibung
watching	boolean	ja	Always true.

TimeSettings

Feld	Typ	Pflicht	Beschreibung
timeZone	string	ja	IANA name of the system time zone.
synchronized	boolean	ja	Whether the clock is synchronized with a time server.
ntpServers	string[]	ja	Time servers Pithyx configured; empty means the distribution’s defaults.
timeZones	string[]	ja	Every time zone the system knows.

TimeSettingsRequest

Feld	Typ	Pflicht	Beschreibung
timeZone	string	ja	IANA name of the new time zone.
ntpServers	string[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
extraNames	string[]	ja	DNS names or addresses inside the authority’s scope, at most 20.

TlsSettings

Settings > Certificates.

Feld	Typ	Pflicht	Beschreibung
https	boolean	ja	The web interface speaks HTTPS on 7484 (80 and 443 redirect there); false only in development and simulation.
source	ActiveCertificateSource	ja	Which certificate the box presents.
active	CertificateInfo	ja	The certificate the box presents now.
authority	AuthorityInfo	ja	The box’s own authority.
boxNames	string[]	ja	The names and addresses the box’s own certificate covers.
extraNames	string[]	ja	Names an administrator added to the box’s own certificate.
suggestedDomains	string[]	ja	The DNS suffixes a new restricted authority starts with: the local ones, the host name and the network’s search domains.
custom	null | CertificateInfo	ja	One certificate as Settings shows it.
issued	IssuedCertificate[]	ja	The certificates issued for other devices, newest first.

TopicEvents

Feld	Typ	Pflicht	Beschreibung
apps	AppList	ja
apps/+/context	AppContextState	ja
apps/admin	AdminAppList	ja
files/+/+	FolderChanges	ja
jobs	Job	ja
jobs/+	Job	ja
notifications	NotificationEvent	ja
session/permissions	SessionPermissions	ja
shares/list	ShareListRevision	ja
storage/alerts	StorageHealth	ja
storage/disks	DisksChanged	ja
storage/pools	PoolList	ja
store/admin	StoreState	ja
system/info	SystemInfo	ja
system/network	NetworkState	ja
system/processes	ProcessList	ja
system/resources	ResourceSample	ja
system/updates	UpdateStatus	ja
thumbnails/+/+	ThumbnailsReady	ja

TopicSnapshots

Feld	Typ	Pflicht	Beschreibung
apps	AppList	ja
apps/+/context	AppContextState	ja
apps/admin	AdminAppList	ja
files/+/+	FolderWatchState	ja
jobs	JobList	ja
jobs/+	Job	ja
notifications	NotificationList	ja
session/permissions	SessionPermissions	ja
shares/list	ShareListRevision	ja
storage/alerts	StorageHealth	ja
storage/disks	DiskList	ja
storage/pools	PoolList	ja
store/admin	StoreState	ja
system/info	SystemInfo	ja
system/network	NetworkState	ja
system/processes	ProcessList	ja
system/resources	ResourceSnapshot	ja
system/updates	UpdateStatus	ja
thumbnails/+/+	ThumbnailWatch	ja

TotpConfirmRequest

Feld	Typ	Pflicht	Beschreibung
code	string	ja

TotpDisableRequest

Feld	Typ	Pflicht	Beschreibung
password	string	ja

TotpEnrollment

Feld	Typ	Pflicht	Beschreibung
secret	string	ja	Base32 secret for manual entry.
uri	string	ja	otpauth:// URI for the QR code.

TotpLoginRequest

Feld	Typ	Pflicht	Beschreibung
challenge	string	ja	From the login response.
code	null | string	nein	Six-digit code from the authenticator app.
recoveryCode	null | string	nein	One of the recovery codes shown when TOTP was enabled, instead of a code.

TrashItem

One item in a share’s recycle bin.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Id for restoring or deleting it.
name	string	ja	Its name when it was deleted.
originalPath	string	ja	Where it was, relative to the share; restoring puts it back there.
kind	FileKind	ja	File, folder, symlink or another kind.
size	integer (int64)	ja	Bytes, for a folder everything inside it.
deletedAt	string (date-time)	ja	When it was deleted, UTC.
deletedBy	null | string	ja	User name of who deleted it, if that user still exists.
expiresAt	null (date-time) | string (date-time)	ja	When it is deleted for good, or null when the share keeps deleted items until emptied.

TrashItemsRequest

Feld	Typ	Pflicht	Beschreibung
ids	integer (int64)[]	ja	Items of the share’s recycle bin, at most 1000.
onConflict	null | ConflictPolicy	nein	For restoring: what happens when the original place is taken; rename when left out.

TrashPage

Feld	Typ	Pflicht	Beschreibung
items	TrashItem[]	ja	Newest first.
nextCursor	null | string	ja	Pass as cursor for the next page; null on the last page.
retentionDays	integer (int32)	ja	Days the share keeps deleted items; 0 keeps them until the bin is emptied.

TrashSettingsRequest

Feld	Typ	Pflicht	Beschreibung
retentionDays	integer (int32)	ja	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.

Typ: "redirect", "notFound"

UnmountedDataset

Feld	Typ	Pflicht	Beschreibung
name	string	ja	The dataset.
mountPoint	string	ja	Its mount point.
reason	string	ja	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

Feld	Typ	Pflicht	Beschreibung
enabled	boolean	ja	False hides the app from everybody and stops serving its frontend; its data and grants stay.

UpdateCatalogRequest

Feld	Typ	Pflicht	Beschreibung
enabled	null | boolean	nein	Switches the catalog on or off; null leaves it.
registryToken	null | string	nein	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja
kind	string	ja
source	string	ja
fromVersion	string	ja
toVersion	string	ja
snapshot	null | string	ja
state	string	ja
errorCode	null | string	ja
errorParams	null | object	ja
startedAt	string (date-time)	ja
finishedAt	null (date-time) | string (date-time)	ja

UpdatePolicy

Typ: "automatic", "notify", "none", null

UpdateProblem

Why the last check could not read the channel, as an error code with its params.

Feld	Typ	Pflicht	Beschreibung
code	string	ja
params	object	ja

UpdateSettingsRequest

Feld	Typ	Pflicht	Beschreibung
checkEnabled	boolean	ja	The daily check (on by default; it only notifies).
channel	string	ja	stable or beta.

UpdateSourceCandidate

A source file an administrator saved in Settings for the recovery menu, which alone can switch to it.

Feld	Typ	Pflicht	Beschreibung
name	string	ja
url	string	ja
keys	UpdateSourceKey[]	ja
savedBy	string	ja
savedAt	string (date-time)	ja

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.

Feld	Typ	Pflicht	Beschreibung
name	string	ja
url	string	ja
official	boolean	ja
keys	UpdateSourceKey[]	ja

UpdateSourceKey

A key of an update source as Settings shows it.

Feld	Typ	Pflicht	Beschreibung
keyId	string	ja
publicKey	string	ja
channels	string[]	ja

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.

Feld	Typ	Pflicht	Beschreibung
installedVersion	string	ja
channel	string	ja
checkEnabled	boolean	ja
lastCheckAt	null (date-time) | string (date-time)	ja
nextCheckAt	null (date-time) | string (date-time)	ja
checking	boolean	ja
available	null | AvailableUpdate	ja	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	ja	The Debian updates apt offers; the kernel and ZFS never come from Debian.
problem	null | UpdateProblem	ja	Why the last check could not read the channel, as an error code with its params.
supported	boolean	ja
unsupportedReason	null | string	ja
staged	null | StagedUpdate	ja	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)	ja
history	UpdateHistoryEntry[]	ja
snapshots	SnapshotInfo[]	ja
source	UpdateSourceInfo	ja
sourceCandidate	null | UpdateSourceCandidate	ja	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.

Feld	Typ	Pflicht	Beschreibung
job	null | Job	ja	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.

Feld	Typ	Pflicht	Beschreibung
grants	GrantEntry[]	ja	The user’s own grants; the editor changes these.
inherited	InheritedGrant[]	ja	What its groups give it; changed on the group.
effective	SessionPermissions	ja	What the user may do: the union of both, or everything for an administrator.

UserInfo

The signed-in user.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id.
username	string	ja	Login name.
displayName	null | string	ja	Name shown, if set.
isAdmin	boolean	ja	Whether the user has the administrator right, its own or through a group.
totpEnabled	boolean	ja	Whether the user signs in with a second factor.
permissions	SessionPermissions	ja	What the user may do; the topic session/permissions sends changes.
groups	GroupRef[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
id	integer (int64)	ja	Stable id.
username	string	ja	The Linux user name, lower case.
displayName	null | string	ja	Shown instead of the user name, if set.
isAdmin	boolean	ja	Whether the user has the administrator right, its own or through a group; administrators have every right.
uid	null (int64) | integer (int64)	ja	The Linux uid from the Pithyx range (20000 to 29999), never reused.
totpEnabled	boolean	ja	Whether the user signs in with a second factor.
createdAt	string (date-time)	ja	When the user was created, UTC.
home	null | string	ja	The user’s home folder on a pool, or null when there is no pool yet.
disabled	boolean	ja	Deactivated: cannot sign in, and the Linux account is expired.
rights	string[]	ja	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[]	ja	The file protocols the user may use (protocol:smb, protocol:sftp, protocol:webdav, protocol:ftp), the same way.
fileServicePassword	boolean	ja	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)[]	ja	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.

Feld	Typ	Pflicht	Beschreibung
displayName	null | string	nein	An empty text removes the display name.
disabled	null | boolean	nein	Deactivates or activates the user; deactivating ends the user’s sessions. Nobody deactivates themselves or the last active administrator.
groupIds	null | integer (int64)[]	nein	Every group the user should be a member of, besides the built-in group users; the user leaves the others.

Vdev

Feld	Typ	Pflicht	Beschreibung
name	string	ja	Vdev name as ZFS shows it: raidz1-0, mirror-1 or the device’s by-id name.
vdevGuid	string	ja	Vdev GUID as decimal text; names a device in commands even when it is missing.
type	string	ja	ZFS vdev type: disk, file, mirror, raidz, draid, spare, replacing and so on.
role	string	ja	What the vdev is for: data, log, cache, special, dedup or spare.
state	string	ja	ZFS state of the vdev.
path	null | string	ja	Device path of a leaf vdev, usually below /dev/disk/by-id.
parityDisks	null (int32) | integer (int32)	ja	Parity level of a raidz vdev (1 to 3), otherwise null.
readErrors	integer (int64)	ja	Read errors since import or the last clear.
writeErrors	integer (int64)	ja	Write errors since import or the last clear.
checksumErrors	integer (int64)	ja	Checksum errors since import or the last clear.
children	Vdev[]	ja	Child vdevs.
missing	boolean	nein	True for a leaf whose disk is not connected, also while ZFS has not noticed yet (see PoolHealth).
serial	null | string	nein	Serial of the disk a leaf is on, as last seen connected, if known.

VlanSettings

Feld	Typ	Pflicht	Beschreibung
parent	string	ja	The network card or bond that carries the VLAN’s tagged frames.
id	integer (int32)	ja	The 802.1Q VLAN id, 1 to 4094.

WebSocketCloseCode

Typ: 1000, 1001, 1008, 1009, 4401, 4403

WindowPreference

Feld	Typ	Pflicht	Beschreibung
appId	string	ja	The app the preference belongs to.
width	integer (int32)	ja	Last free width of the app’s windows in CSS pixels.
height	integer (int32)	ja	Last free height in CSS pixels.

WindowPreferenceRequest

Feld	Typ	Pflicht	Beschreibung
width	integer (int32)	ja
height	integer (int32)	ja