REST API: schemas

The schemas of the daemon’s OpenAPI document, sorted by name. The TypeScript types of @pithyx/api-client are generated from the same document.

AckMessage

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

Field	Type	Required	Description
id	string	yes
type	"ack"	yes
requestId	string	yes

ActiveCertificateSource

Which certificate the web interface and FTPS present.

Type: "authority", "custom"

AddCatalogRequest

Field	Type	Required	Description
url	string	yes	https://host/owner/repository.git, or for a private catalog git@host:owner/repository.git.

AdminAppList

Every installed app for administrators: the snapshot and every event of apps/admin.

Field	Type	Required	Description
pool	null | string	yes	The app pool, or null before the first install.
apps	AppDetails[]	yes	Sorted by id.

ApiProblem

RFC 9457 problem details as returned by every failing API call. The detail text is an English fallback; clients show the translation of the error code instead.

Field	Type	Required	Description
type	string	yes
title	string	yes
status	integer (int32)	yes
detail	string	yes
code	ErrorCode	yes
params	map of object	yes
requestId	string	yes

AppAccess

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

Type: "everybody", "admins"

AppContextState

The per-user topic apps/<id>/context: what the daemon decides about an app for the subscriber, who may use the app (only such a user can subscribe). Its subscription is also the window lease (A15): while a desktop of the user is subscribed, the app is in use.

Field	Type	Required	Description
version	string	yes	The installed version.
permissions	string[]	yes	The permissions of the manifest that no administrator revoked; the app sees them as permissionsChange.
logLevel	"info", "debug"	yes	Whether an app’s debug log entries reach the daemon; info, warn and error always do.
backend	null | object	yes	The app’s backend: the state of its containers and the names of its endpoints.
storage	object[]	yes	The storage requests of the manifest with their state for the user (storageChange).

AppDetails

An installed app for administrators (topic apps/admin and GET /api/apps).

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

Appearance

How the desktop looks for the user on every device. The theme (light, dark) is a choice of each device.

Field	Type	Required	Description
accent	string	yes	One of the accent presets: petrol, ocean, indigo, plum, moss, graphite.
wallpaper	string	yes	boxes (the Pithyx boxes) or plain.

AppFileEntry

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

Field	Type	Required	Description
name	string	yes	Name within its folder.
kind	FileKind	yes	File, folder, symlink or another kind.
size	integer (int64)	yes	Bytes for files, 0 for folders.
modified	string (date-time)	yes	Last change of the content, UTC.
writable	boolean	yes	The app holds files.write (or the storage is mapped read and write) and the user may write there.

AppFileOperationRequest

An app’s copy, move or delete: as FileOperationRequest, with each place a shared folder or a storage request.

Field	Type	Required	Description
kind	FileOperationKind	yes	copy, move or delete.
items	null | AppFileRef[]	no	The entries to work on, at most 1000. Leave out when AllIn is given.
target	null | AppFileRef	no	An entry or folder of an app’s file operation, in a shared folder or a storage request of its manifest.
onConflict	null | ConflictPolicy	no	For copy and move; fail when left out.
permanent	boolean	no	For delete: remove for good instead of moving to the shared folder’s recycle bin.
allIn	null | AppFolderSelection	no	Every entry of an app’s folder except some names.

AppFileRef

An entry or folder of an app’s file operation, in a shared folder or a storage request of its manifest.

Field	Type	Required	Description
share	null | string	no	The shared folder’s id, as the app got it from files/shares.
storage	null | string	no	The id of a storage request of the manifest.
path	null | string	no	The path relative to the shared folder or the mapped folder.

AppFileUrl

A short-lived address of one file, usable without the desktop’s session.

Field	Type	Required	Description
url	string	yes	Path on the box with ?pithyx-token=; supports range requests.
expiresAt	string (date-time)	yes	When it stops working (UTC).

AppFileUrlRequest

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

Field	Type	Required	Description
path	string	yes	The file.
share	null | string	no	The shared folder’s id, or null.
storage	null | string	no	The id of a storage request, or null.

AppFolderPage

One page of a folder, relative to its location.

Field	Type	Required	Description
path	string	yes	The folder (“” for the location’s root).
folderId	string	yes	Stable id of the folder, also after a rename.
total	integer (int32)	yes	Entries in the folder when the page was read.
entries	FileEntry[]	yes	This page, in the requested order.
nextCursor	null | string	yes	Pass as cursor for the next page; null on the last page.
topic	string	yes	WebSocket topic with live changes of this folder, for the desktop’s files.watch; never sent to the app.

AppFolderSelection

Every entry of an app’s folder except some names.

Field	Type	Required	Description
folder	AppFileRef	yes	The folder whose entries are meant.
except	null | string[]	no	Names left out, at most 1000.

AppGrants

Who may use an app. Administrators only.

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

AppGrantsRequest

Field	Type	Required	Description
grants	SubjectGrant[]	yes	Every grant on the app the users and groups should have (level allow); the others go.

AppHandleRequest

Body of POST /api/app/files/handles: a file the user handed to the window in a dialog.

Field	Type	Required	Description
share	string	yes	The shared folder’s id.
path	string	yes	The one file; the window may read it (needs files.read), or also write it.
write	boolean	no	Whether the window may write it (needs files.write).

AppList

The apps the subscriber may use, sorted by id: the snapshot and every event of apps.

Field	Type	Required	Description
apps	object[]	yes	Enabled apps the user has a grant for; every enabled app for administrators.

AppLogBatch

Field	Type	Required	Description
entries	AppLogEntry[]	yes	At most 100 entries per request.

AppLogEntry

Field	Type	Required	Description
level	LogLevelName	yes	debug, info, warn or error.
message	string	yes	At most 4000 characters; longer ones are cut.
data	null | map of string	no	At most 20 fields of at most 1000 characters each.

AppLogLevel

Whether an app’s debug log entries reach the daemon; info, warn and error always do.

Type: "info", "debug"

AppLogLevelRequest

Field	Type	Required	Description
level	AppLogLevel	yes	Whether the app’s debug log entries reach the daemon.

AppLogResult

Field	Type	Required	Description
accepted	integer (int32)	yes	Entries stored.
dropped	integer (int32)	yes	Entries over the app’s rate limit, not stored.

AppNotificationAction

A button of an app’s notification.

Field	Type	Required	Description
id	string	yes	Comes back to the app when the user clicks it; 1 to 64 characters, unique in the notification.
label	string	yes	Plain text from the app, 1 to 40 characters.

AppNotificationLevel

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

AppNotificationRequest

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

Field	Type	Required	Description
app	string	yes	Id of the core app (org.pithyx.*); third-party apps send theirs to /api/app/notifications.
title	string	yes	Plain text from the app, at most 200 characters.
body	null | string	no	Plain text from the app, at most 1000 characters.
tone	null | NotificationTone	no	Defaults to info.

AppNotifyRequest

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

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

AppPackageAction

What installing a checked package does.

Type: "install", "update", "reinstall", "downgrade"

AppPackagePreview

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

Field	Type	Required	Description
packageId	string	yes	Names it for the install.
expiresAt	string (date-time)	yes	When it is discarded (UTC).
id	string	yes	The app id.
version	string	yes	The version in the package.
manifest	JsonElement	yes	The whole manifest (pithyx.json).
action	AppPackageAction	yes	What installing it does.
installedVersion	null | string	yes	The installed version, if the app is installed.
addedPermissions	string[]	yes	Permissions the package asks for that the installed version did not (all of them for an install).
removedPermissions	string[]	yes	Permissions the installed version had that the package no longer asks for.
pool	null | string	yes	The app pool, or null before the first app is installed (the install must name one then).
fileCount	integer (int32)	yes	Regular files in the package.
unpackedBytes	integer (int64)	yes	Their sizes together.
packageBytes	integer (int64)	yes	The size of the package file.
sha256	string	yes	SHA-256 of the package file, lowercase hex.
suggestedAccess	AppAccess	yes	Who should use the app after an install: administrators only when it asks for elevated rights, root in a container or directory.read, everybody otherwise. An install without access takes it.
catalog	null | string	no	The catalog the package comes from; null for an uploaded file (a sideload, unverified).
keptData	boolean	no	For an install: an earlier installation was removed with “Keep the data”, and the app gets its data and its user id again.

AppPermissionsRequest

Field	Type	Required	Description
permissions	AppPermissionState[]	yes	Permissions of the app’s manifest with whether the app keeps them; the others stay as they are.

AppPermissionState

Field	Type	Required	Description
permission	string	yes	For example notifications.
granted	boolean	yes	False after an administrator revoked it.

AppRenameRequest

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

Field	Type	Required	Description
path	string	yes	The entry to rename.
name	string	yes	The new name in the same folder.
share	null | string	no	The shared folder’s id, or null.
storage	null | string	no	The id of a storage request, or null.

AppShareInfo

A shared folder the user can use, as an app with files.shares sees it: never its place on the host.

Field	Type	Required	Description
id	string	yes	The location { share: id }.
name	string	yes	Name shown to users.
access	ShareAccess	yes	The user’s access: read or readWrite.
unavailable	null | string	yes	Why its files cannot be reached now (poolMissing, poolUnavailable, notMounted), or null.
kind	ShareKind	no	A shared folder, or the user’s own home (home, D348). Apps never get other users’ homes.

AppStorageAccess

How an app may use a folder mapped to one of its storage requests.

Type: "read", "readWrite"

AppStorageKeys

The keys an app stored for the user.

Field	Type	Required	Description
keys	string[]	yes	Sorted.

AppStorageMapping

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

Field	Type	Required	Description
storageId	string	yes	The id of the request in the manifest.
shareId	integer (int64)	yes	The shared folder.
path	string	yes	The folder relative to the shared folder’s root, empty for the root itself.
access	AppStorageAccess	yes	Read-only, or read and write when the request asks for it.

AppStorageMappingRequest

Field	Type	Required	Description
shareId	integer (int64)	yes	The shared folder.
access	AppStorageAccess	yes	Read-only, or read and write when the storage request asks for it.
path	null | string	no	An existing folder in it, relative to its root; empty or missing for the root.

AppStorageValue

A value an app stores for the user; JSON null when there is none.

Field	Type	Required	Description
value	JsonElement	yes	Any JSON, at most 64 KB.

AppTicket

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

Field	Type	Required	Description
ticket	string	yes	Works once, within 30 seconds.
expiresAt	string (date-time)	yes	When it stops working (UTC).

AppTicketRequest

Body of POST /api/app/tickets.

Field	Type	Required	Description
endpoint	string	yes	A backend endpoint of the app’s manifest, for example api.

AppToken

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

Field	Type	Required	Description
token	string	yes	Send as Authorization: Bearer; never log or store it.
expiresAt	string (date-time)	yes	When it stops working (UTC); ask for a new one before.

AppTokenKind

What a token is for.

Type: "host", "backend", "ticket", "file"

AppTokenRequest

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

Field	Type	Required	Description
kind	AppTokenKind	yes	host for the daemon’s API for apps (kept by the desktop), backend for the app’s backend.
instance	string	yes	The window instance: 1 to 64 letters, digits, dashes and underscores.

AppTrashRequest

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

Field	Type	Required	Description
share	string	yes	The shared folder’s id.
ids	null | integer (int64)[]	no	The items; all items of the bin for empty.
onConflict	null | ConflictPolicy	no	For restore; rename when left out.

AppUpdate

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

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

AppUpdatePolicyRequest

Field	Type	Required	Description
policy	null | UpdatePolicy	yes	The app’s own update policy; null follows the box’s.

AppUserAccess

One user’s effective access to an app.

Field	Type	Required	Description
userId	integer (int64)	yes	The user’s id.
username	string	yes	Login name.
displayName	null | string	yes	Name shown, if set.
administrator	boolean	yes	Administrators use every app.
disabled	boolean	yes	Deactivated users use none.
allowed	boolean	yes	Whether the user may use the app: by its own grant, one of its groups’, or as an administrator.

AppVersionRestoreRequest

Body of POST /api/app/files/versions/restore.

Field	Type	Required	Description
share	string	yes	The shared folder’s id.
path	string	yes	The file or folder to bring back.
snapshot	string	yes	The version’s snapshot, as listed.
overwrite	boolean	no	Replace the current entry instead of restoring next to it.

AuthorityInfo

The box’s certificate authority.

Field	Type	Required	Description
root	CertificateInfo	yes	The root that devices trust; download it from /api/system/tls/root-ca.crt.
intermediate	CertificateInfo	yes	The intermediate that signs every certificate; it is renewed a year before it ends.
restricted	boolean	yes	Name Constraints limit what the authority may sign.
domains	string[]	yes	The DNS suffixes it may sign, each with every name below it; empty when unrestricted.
addressRanges	string[]	yes	The address ranges it may sign; empty when unrestricted.

AvailableUpdate

The newest version of the box’s channel when it is newer than the installed one. Installable: False when the box is older than MinimumVersion and needs a version in between first.

Field	Type	Required	Description
version	string	yes
minimumVersion	string	yes
changelog	string	yes
size	integer (int64)	yes
publishedAt	string (date-time)	yes
installable	boolean	yes

BackupCategory

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

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

BackupSummary

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

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

BondMode

How a bond uses its cards.

Type: "activeBackup", "lacp", "balanceAlb"

BondSettings

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

CatalogInfo

A catalog of the box.

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

CatalogKind

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

Type: "official", "community", "custom"

CatalogStatus

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

Type: "off", "new", "ok", "failed"

CertificateInfo

One certificate as Settings shows it.

Field	Type	Required	Description
subject	string	yes	The subject’s distinguished name.
issuer	string	yes	The issuer’s distinguished name.
names	string[]	yes	The DNS names and addresses it covers.
notBefore	string (date-time)	yes	The start of its validity.
notAfter	string (date-time)	yes	The end of its validity.
fingerprint	string	yes	SHA-256 as hex pairs with colons.

CertificateKeyType

The key of a certificate the authority issues.

Type: "ecdsa", "rsa"

ClientMessage

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

Field	Type	Required	Description
type	"sub", "unsub"	yes
id	string	yes	Chosen by the client; echoed in the ack, snapshots and errors that answer this message.
topic	null | string	no	Topic name or pattern with + and #. A message without one is answered with an error.

ConflictPolicy

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

CopyLayoutRequest

Field	Type	Required	Description
deviceId	string	yes

CreateAuthorityRequest

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

Field	Type	Required	Description
restricted	boolean	yes	Limit the authority to local names and private addresses (recommended).
domains	string[]	yes	With Restricted: DNS suffixes besides the suggested ones, such as a domain of your own.

CreateBackupRequest

Field	Type	Required	Description
password	string	yes	The backup password: needed to restore, never stored. The same rules as for an account password.

CustomCertificateRequest

A certificate of your own for the web interface and FTPS.

Field	Type	Required	Description
certificatePem	string	yes	The certificate, followed by its intermediates, in PEM.
privateKeyPem	string	yes	Its private key in PEM (PKCS #8, PKCS #1 or SEC 1), unencrypted.

DaemonMode

Type: "real", "simulated"

Dataset

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

DebianUpdate

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

Field	Type	Required	Description
name	string	yes	The package.
from	null | string	yes	The installed version; null for a package the upgrade adds.
to	string	yes	The version it would install.
security	boolean	yes	Whether it comes from a security archive (Debian-Security:13/stable-security).

DebianUpdates

The Debian updates apt offers; the kernel and ZFS never come from Debian.

Field	Type	Required	Description
count	integer (int32)	yes
security	integer (int32)	yes
packages	DebianUpdate[]	yes

DesktopItem

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

Field	Type	Required	Description
id	integer (int64)	yes	Stable id of the item.
kind	DesktopItemKind	yes	What the item is.
app	null | string	yes	Shortcuts: the id of the app it opens.
name	null | string	yes	Shortcuts: the label the user gave it, or null for the app’s name in the user’s language.
text	null | string	yes	Notes: the text.
column	integer (int32)	yes	Grid cell of the item, counted from the top left corner of the desktop.
row	integer (int32)	yes	Grid row of the item.
version	integer (int64)	yes	Increments with every change. Send it as If-Match: "n" with the next change of this item.

DesktopItemChange

A change of one item. Fields left out (or null) stay as they are.

Field	Type	Required	Description
name	null | string	no	Shortcuts: the new label; an empty string goes back to the app’s name.
text	null | string	no	Notes: the new text.
column	null (int32) | integer (int32)	no	New grid column.
row	null (int32) | integer (int32)	no	New grid row.

DesktopItemKind

Type: "shortcut", "note"

DesktopState

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

DeviceLayout

Another device of the user with a saved layout.

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

DirectoryGroup

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

Field	Type	Required	Description
id	integer (int64)	yes	Stable id (the group’s Linux gid).
name	string	yes	The group name.
description	string	yes	Free text, may be empty.

DirectoryUser

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

Field	Type	Required	Description
id	integer (int64)	yes	Stable id.
name	string	yes	The user name.
displayName	null | string	yes	The name to show, if set.
groups	integer (int64)[]	yes	Ids of the user’s groups, without the built-in group every user is in.

Disk

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

DiskList

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

Field	Type	Required	Description
disks	object[]	yes

DisksChanged

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

Field	Type	Required	Description
upserts	object[]	yes
removals	string[]	yes

ErrorCode

Type: "app.app.busy", "app.app.no_previous", "app.app.not_found", "app.backend.endpoint_unknown", "app.backend.missing", "app.backend.start_failed", "app.backend.storage_unavailable", "app.backend.unavailable", "app.backend.unsupported", "app.compose.key_unsupported", "app.compose.reference_unknown", "app.compose.right_missing", "app.compose.right_unused", "app.compose.storage_mismatch", "app.compose.value_invalid", "app.compose.yaml_invalid", "app.docker.unavailable", "app.elevated.unsupported", "app.icon.invalid", "app.image.mismatch", "app.image.unavailable", "app.manifest.cron_invalid", "app.manifest.duplicate", "app.manifest.id_invalid", "app.manifest.id_reserved", "app.manifest.invalid_json", "app.manifest.pithyx_invalid", "app.manifest.reference_unknown", "app.manifest.schema_violation", "app.manifest.sdk_invalid", "app.manifest.version_unsupported", "app.manifest.window_size_invalid", "app.mapping.invalid", "app.package.box_too_old", "app.package.downgrade_unsupported", "app.package.invalid", "app.package.layout_invalid", "app.package.lock_invalid", "app.package.not_found", "app.package.too_large", "app.permission.denied", "app.permission.not_requested", "app.pool.fixed", "app.pool.required", "app.pool.unavailable", "app.storage.key_invalid", "app.storage.not_found", "app.storage.too_large", "app.token.invalid", "auth.account.disabled", "auth.challenge.expired", "auth.credentials.invalid", "auth.csrf.header_missing", "auth.desktop.not_allowed", "auth.display_name.invalid", "auth.password.too_common", "auth.password.too_long", "auth.password.too_short", "auth.permission.denied", "auth.rate.limited", "auth.recovery.invalid", "auth.session.expired", "auth.setup.already_done", "auth.totp.already_enabled", "auth.totp.invalid", "auth.totp.not_enrolled", "auth.username.invalid", "auth.username.reserved", "desktop.device.not_found", "desktop.item.conflict", "desktop.item.invalid", "desktop.item.limit_reached", "desktop.item.not_found", "desktop.layout.conflict", "desktop.layout.invalid", "desktop.layout.too_large", "desktop.note.too_long", "fileservices.service.unavailable", "fileservices.workgroup.invalid", "fs.cursor.invalid", "fs.entry.access_denied", "fs.entry.exists", "fs.entry.is_folder", "fs.entry.not_folder", "fs.entry.not_found", "fs.folder.not_empty", "fs.io.failed", "fs.name.invalid", "fs.operation.into_itself", "fs.operation.invalid", "fs.path.invalid", "fs.range.not_satisfiable", "fs.share.data_choice_required", "fs.share.dataset_name_invalid", "fs.share.description_invalid", "fs.share.exists", "fs.share.folder_dev_only", "fs.share.invalid", "fs.share.name_mismatch", "fs.share.name_reserved", "fs.share.no_dataset", "fs.share.not_found", "fs.share.path_taken", "fs.share.pool_not_prepared", "fs.share.read_only", "fs.share.unavailable", "fs.thumbnail.not_found", "fs.thumbnail.too_many", "fs.trash.retention_invalid", "fs.upload.incomplete", "fs.version.not_found", "fs.volume.full", "fs.volume.read_only", "homes.choice.invalid", "homes.home.in_use", "homes.home.name_mismatch", "homes.home.not_found", "homes.move.running", "homes.pool.no_space", "homes.pool.taken", "homes.pool.unavailable", "homes.pool.unchanged", "homes.quota.invalid", "installer.check.failed", "installer.claim.required", "installer.claim.taken", "installer.disk.count", "installer.disk.unsuitable", "installer.erase.not_confirmed", "installer.hostname.invalid", "installer.install.failed", "installer.install.running", "installer.keyboard.invalid", "installer.reboot.not_ready", "jobs.job.not_found", "logs.app.invalid", "logs.archive.pool_unavailable", "logs.batch.too_large", "logs.query.invalid", "logs.settings.invalid", "network.address.invalid", "network.apply.failed", "network.bond.member_invalid", "network.bond.members_missing", "network.bond.primary_invalid", "network.change.empty", "network.change.not_found", "network.change.pending", "network.config.unreachable", "network.default_interface.invalid", "network.dns.invalid", "network.dns.too_many", "network.firewall.failed", "network.gateway.invalid", "network.global.not_changeable", "network.host_name.invalid", "network.interface.duplicate", "network.interface.kind_invalid", "network.interface.name_invalid", "network.interface.not_changeable", "network.interface.unknown", "network.mtu.invalid", "network.search_domain.invalid", "network.search_domain.too_many", "network.vlan.duplicate", "network.vlan.id_invalid", "network.vlan.parent_invalid", "notifications.message.invalid", "notifications.notification.not_found", "permissions.grant.invalid", "proxy.access.denied", "proxy.address.denied", "proxy.address.invalid", "proxy.auth.required", "proxy.basic_auth.invalid", "proxy.basic_auth.password_missing", "proxy.certificate.missing", "proxy.certificate.name_mismatch", "proxy.domain.invalid", "proxy.domain.taken", "proxy.domains.missing", "proxy.domains.too_many", "proxy.header.invalid", "proxy.headers.too_many", "proxy.host.not_found", "proxy.host.unknown", "proxy.limit.out_of_range", "proxy.loop.detected", "proxy.redirect.not_found", "proxy.redirect.status_invalid", "proxy.redirect.target_invalid", "proxy.sign_in.address_invalid", "proxy.sign_in.group_not_found", "proxy.sign_in.user_not_found", "proxy.stream.name_invalid", "proxy.stream.not_found", "proxy.stream.port_in_use", "proxy.stream.port_privileged", "proxy.stream.port_reserved", "proxy.stream.port_taken", "proxy.stream.protocol_missing", "proxy.target.invalid", "proxy.target.loop", "proxy.target.on_box", "proxy.target.timeout", "proxy.target.unavailable", "proxy.ticket.target_invalid", "proxy.websockets.disabled", "realtime.message.invalid", "realtime.topic.invalid", "realtime.topic.unknown", "realtime.upgrade.required", "request.body.invalid", "request.media_type.unsupported", "request.method.not_allowed", "request.route.not_found", "storage.alert.not_found", "storage.command.failed", "storage.command.timed_out", "storage.dataset.compression_invalid", "storage.dataset.exists", "storage.dataset.in_use_by_share", "storage.dataset.limit_invalid", "storage.dataset.managed", "storage.dataset.name_invalid", "storage.dataset.name_mismatch", "storage.dataset.not_found", "storage.dataset.property_unsupported", "storage.dataset.protected", "storage.dataset.quota_below_used", "storage.dataset.record_size_invalid", "storage.dataset.reservation_too_large", "storage.dataset.unchanged", "storage.disk.not_found", "storage.disk.refused", "storage.encryption.unavailable", "storage.import.device_unknown", "storage.import.force_required", "storage.import.not_found", "storage.import.not_importable", "storage.import.preview_required", "storage.plan.action_invalid", "storage.plan.expired", "storage.plan.not_found", "storage.plan.stale", "storage.pool.disk_count", "storage.pool.disks_missing", "storage.pool.encryption_required", "storage.pool.expanding", "storage.pool.layout_invalid", "storage.pool.name_invalid", "storage.pool.name_mismatch", "storage.pool.name_taken", "storage.pool.not_found", "storage.pool.not_prepared", "storage.pool.read_only", "storage.pool.suspended", "storage.schedule.invalid", "storage.scrub.not_running", "storage.scrub.running", "storage.snapshot.confirmation_mismatch", "storage.snapshot.dataset_not_found", "storage.snapshot.exists", "storage.snapshot.held", "storage.snapshot.newer_exist", "storage.snapshot.not_found", "storage.snapshot.not_pithyx", "storage.snapshot.schedule_invalid", "storage.vdev.not_found", "storage.vdev.not_raidz", "storage.volume.size_invalid", "storage.volume.too_large", "storage.zfs.unavailable", "store.app.not_found", "store.catalog.architecture_missing", "store.catalog.built_in", "store.catalog.busy", "store.catalog.data_version_decreased", "store.catalog.exists", "store.catalog.id_reserved", "store.catalog.invalid_json", "store.catalog.mismatch", "store.catalog.not_found", "store.catalog.rule_violation", "store.catalog.schema_violation", "store.catalog.sequence_old", "store.catalog.signature_invalid", "store.catalog.unreachable", "store.catalog.url_invalid", "store.catalog.version_unsupported", "store.package.hash_mismatch", "system.backup.category_missing", "system.backup.invalid", "system.backup.password_wrong", "system.backup.restore_expired", "system.backup.restore_failed", "system.backup.restore_running", "system.backup.too_large", "system.backup.too_new", "system.internal.unexpected", "system.origin.forbidden", "system.time.apply_failed", "system.time.server_invalid", "system.time.servers_too_many", "system.time.zone_invalid", "tls.custom.expired", "tls.custom.invalid", "tls.custom.key_mismatch", "tls.issued.not_found", "tls.name.invalid", "tls.name.not_permitted", "tls.names.missing", "tls.names.too_many", "tls.validity.out_of_range", "update.apply.failed", "update.apply.running", "update.channel.invalid", "update.channel.mismatch", "update.channel.sequence_old", "update.channel.signature_invalid", "update.download.mismatch", "update.file.architecture", "update.file.channel", "update.file.hash_mismatch", "update.file.invalid", "update.file.minimum", "update.file.missing_entry", "update.file.not_found", "update.file.older", "update.file.signature_invalid", "update.file.too_large", "update.file.unexpected_entry", "update.none.available", "update.rollback.unconfirmed", "update.snapshot.not_found", "update.source.invalid", "update.source.unreachable", "update.space.insufficient", "update.system.unsupported", "users.account.refused", "users.gid.exhausted", "users.group.builtin", "users.group.description_invalid", "users.group.exists", "users.group.name_invalid", "users.group.name_reserved", "users.group.not_found", "users.group.refused", "users.uid.exhausted", "users.user.exists", "users.user.last_admin", "users.user.not_found", "users.user.self"

ErrorMessage

A failed client message. id is empty when the message could not be parsed.

Field	Type	Required	Description
id	string	yes
code	ErrorCode	yes
params	map of object	yes
type	"error"	yes
requestId	string	yes

EventMessage

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

Field	Type	Required	Description
topic	string	yes
data	object	yes
type	"event"	yes
requestId	string	yes

FileEntry

A file or folder in a share.

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

FileKind

Type: "file", "folder", "symlink", "other"

FileLocation

Field	Type	Required	Description
shareId	integer (int64)	yes	The share.
path	string	yes	Path relative to the share.

FileOperationKind

Type: "copy", "move", "delete"

FileOperationRequest

Field	Type	Required	Description
kind	FileOperationKind	yes	copy, move or delete.
items	null | FileLocation[]	no	The files and folders to work on, at most 1000. Leave out when AllIn is given.
target	null | FileLocation	no	The folder to copy or move into; not used for delete.
onConflict	null | ConflictPolicy	no	For copy and move; fail when left out.
permanent	boolean	no	For delete: remove for good instead of moving to the share’s recycle bin. Only when the user asked for it.
allIn	null | FolderSelection	no	Every entry of a folder except some names: selecting a whole folder without sending its names.

FileServiceSettings

The file services of the box. Administrators only.

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

FileServiceSettingsRequest

Changes of the file services; fields left out stay.

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

FileServiceState

How a file service is doing.

Type: "off", "running", "failed", "unavailable"

FileVersion

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

FileVersionList

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

Field	Type	Required	Description
path	string	yes	The file or folder, relative to the share.
versions	FileVersion[]	yes	Newest first; empty when the share is not on a ZFS dataset.

FileVersionRestoreRequest

Field	Type	Required	Description
path	string	yes	The file or folder, relative to the share; it may have been deleted since.
snapshot	string	yes	The snapshot to restore from, as listed.
overwrite	boolean	no	Replace the current file (folders are merged) instead of restoring next to it.

FolderChanges

What a folder topic sends: the names that changed since the last event, or a request to list again.

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

FolderPage

One page of a folder listing.

Field	Type	Required	Description
path	string	yes	The folder, relative to the share (“” for its root).
folderId	string	yes	Stable id of the folder, also after a rename.
total	integer (int32)	yes	Entries in the folder when the listing was made.
entries	FileEntry[]	yes	This page, in the requested order.
nextCursor	null | string	yes	Pass as cursor for the next page; null on the last page.
topic	string	yes	WebSocket topic with live changes of this folder while it is subscribed.

FolderSelection

Every entry of a folder except some names: selecting a whole folder without sending its names.

Field	Type	Required	Description
folder	FileLocation	yes	The folder whose entries are meant.
except	string[]	yes	Names left out, at most 1000.

FolderWatchState

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

Field	Type	Required	Description
watching	boolean	yes	Whether changes are being delivered.

GlobalNetworkConfig

Settings of the whole box.

Field	Type	Required	Description
hostName	string	yes	The host name: letters, digits and hyphens, 1 to 63 characters. Samba uses its first 15 as the NetBIOS name.
dnsServers	string[]	yes	Name servers, at most four; when set they replace those DHCP and router advertisements announce.
searchDomains	string[]	yes	Domains tried for short names, at most six.
defaultInterface	null | string	no	The interface whose gateway carries the default route when several have one; null leaves it to the metrics.

GrantEntry

One grant of a user or a group.

Field	Type	Required	Description
resource	string	yes	share:<id>, protocol:smb|sftp|webdav|ftp, app:<id> or right:admin|desktopLogin|sshLogin|power.
level	GrantLevel	yes	read or readWrite for a shared folder, allow for everything else.

GrantLevel

How far a grant goes: read or readWrite for a shared folder, allow for everything else.

Type: "read", "readWrite", "allow"

GrantsRequest

Field	Type	Required	Description
grants	GrantEntry[]	yes	Every grant the subject should have; the others go. A subject has at most one grant per resource.

GroupGrants

The grants of a group. Administrators only.

Field	Type	Required	Description
grants	GrantEntry[]	yes	Every grant of the group.

GroupRef

A group a user is in.

Field	Type	Required	Description
id	integer (int64)	yes	Stable id (the group’s Linux gid).
name	string	yes	The group name.

GroupSummary

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

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

GroupUpdate

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

Field	Type	Required	Description
name	null | string	no	A new name; the gid stays.
description	null | string	no	An empty text removes the description.
memberIds	null | integer (int64)[]	no	Every member the group should have; the others leave it.

GuardDecision

Type: "allowed", "needsSerialConfirmation", "refused"

GuardVerdict

Field	Type	Required	Description
diskId	string	yes	The disk the verdict is for.
decision	GuardDecision	yes	Whether a destructive command may touch the disk.
reason	string	yes	Why, as a stable code: system_disk, read_only, mounted, pool_member, not_test_disk, duplicate_serial, no_serial, not_checked, has_data, confirmed or empty; when a pool is imported, importable for an allowed disk.
pool	null | string	yes	The imported pool the disk belongs to, for pool_member.
contents	string[]	yes	What was found on the disk: partitions and signature types.

HealthResponse

Field	Type	Required	Description
status	string	yes
mode	DaemonMode	yes

HomeInfo

A home.

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

HomeMoveRequest

Field	Type	Required	Description
pool	string	yes	The pool the homes move to; it needs the Pithyx layout and room for every home.

HomeOverview

The homes as Settings shows them. Administrators only.

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

HomePool

Field	Type	Required	Description
name	string	yes	The pool.
availableBytes	null (int64) | integer (int64)	yes	Free space for the homes, or null while it cannot be read.
unavailable	null | string	yes	Why it cannot take the homes (missing, offline, read_only, not_prepared, locked, not_mounted), or null when it can.

HomeQuotaRequest

Field	Type	Required	Description
quotaBytes	null (int64) | integer (int64)	yes	The user’s own quota: at least 1 MiB, 0 for none, null for the default.

HomeReleaseRequest

Field	Type	Required	Description
shareId	integer (int64)	yes	The shared folder that gets a folder with the home’s files.

HomeSettingsRequest

Field	Type	Required	Description
defaultQuotaBytes	null (int64) | integer (int64)	yes	The quota of every home without its own: at least 1 MiB, or null for none.

ImportablePool

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

ImportScan

Response of POST /api/storage/import/scan: pools on the disks that are not imported. Nothing was imported.

Field	Type	Required	Description
pools	ImportablePool[]	yes

ImportVdev

Field	Type	Required	Description
name	string	yes	Device or vdev name as zpool import prints it: raidz1-0, a by-id name, a path or, for a missing device, its GUID.
state	null | string	yes	ZFS state, for example ONLINE or UNAVAIL; null for the logs, cache, spares, special and dedup group headings, and for cache and spare devices, which an import lists without one.
detail	null | string	yes	What ZFS adds after the state, for example cannot open or insufficient replicas.
diskId	null | string	yes	The disk this device is on, if it is one the daemon knows.
children	ImportVdev[]	yes	Child vdevs.

InheritedGrant

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

Field	Type	Required	Description
resource	string	yes	The resource, as in GrantEntry.
level	GrantLevel	yes	The level, as in GrantEntry.
groupId	integer (int64)	yes	The group that has the grant.
groupName	string	yes	Its name.

InspectBackupRequest

Field	Type	Required	Description
archive	string	yes	The backup file, base64.
password	string	yes	The password it was created with.

InstallAppRequest

Field	Type	Required	Description
pool	null | string	no	The pool for the app data; required for the first app, and then always the app pool.
access	null | AppAccess	no	Who may use the app after an install; an update keeps who may use it. Defaults to the preview’s suggested access.

InstallerCheck

A requirement the box must meet before the installation starts.

Field	Type	Required	Description
id	string	yes	cpu (x86-64-v2), uefi, memory, secure_boot (off) or disk (a suitable disk exists).
passed	boolean	yes	Whether the box meets it.
params	object	yes	Values for the text, for example minGb and foundGb of memory.

InstallerDisk

A disk as the installer offers it.

Field	Type	Required	Description
disk	Disk	yes	The disk.
suitable	boolean	yes	Whether the system may be installed on it.
reason	null | string	yes	Why not: boot_medium, read_only, in_use (mounted or swap) or too_small.
hasData	boolean	yes	Whether it holds partitions or file systems that the installation erases.
caution	null | string	yes	Flash that wears out under the system’s writes: usb (a USB stick or disk) or card (a memory card or other removable medium); null otherwise, also for eMMC.

InstallerOptions

Response of GET /api/installer/options: what the steps offer.

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

InstallerPhase

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

InstallerStatus

Response of GET /api/installer.

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

InstallIdResponse

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

Field	Type	Required	Description
installId	string	yes

InstallRequest

Body of POST /api/installer/install.

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

InstallUpdateRequest

Field	Type	Required	Description
source	string	yes	online installs the channel’s newest file, file the uploaded one.
includeDebian	boolean	yes	Also install the Debian updates, in the same snapshot.

InterfaceConfig

The settings Pithyx keeps for one interface. A network card without them gets its address by DHCP.

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

InterfaceKind

What an interface is: a network card, a bond of cards or a VLAN on a card or bond.

Type: "ethernet", "bond", "vlan"

Ipv4Mode

How an interface gets its IPv4 address.

Type: "dhcp", "static", "off"

Ipv6Mode

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

Type: "auto", "static", "off"

IssueCertificateRequest

A certificate for another device.

Field	Type	Required	Description
names	string[]	yes	DNS names (a leading *. for a wildcard) and addresses, 1 to 100, inside the authority’s scope.
validityDays	integer (int32)	yes	1 to 825 days, never past the intermediate’s end.
keyType	CertificateKeyType	yes	ECDSA (default) or RSA for devices that take nothing else.

IssuedCertificate

A certificate the authority issued for another device. Its key was handed out once and is not kept.

Field	Type	Required	Description
id	integer (int64)	yes	Its number on the box.
certificate	CertificateInfo	yes	The certificate.
keyType	CertificateKeyType	yes	The key it was made with.
createdAt	string (date-time)	yes	When it was issued.
createdBy	null | string	yes	The administrator who issued it, if the account still had that name.
currentAuthority	boolean	yes	It chains to the current root; false after a new authority replaced the old one.

IssuedCertificateFiles

A newly issued certificate with its files; the private key is in this answer only.

Field	Type	Required	Description
certificate	IssuedCertificate	yes	The entry in the list.
certificatePem	string	yes	The certificate followed by the intermediate, as servers take it.
privateKeyPem	string	yes	The private key (PKCS #8, unencrypted).

Job

A long operation of a user, such as copying files. Also the data of the jobs/{id} topics.

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

JobList

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

Field	Type	Required	Description
jobs	Job[]	yes

JobProgress

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

Field	Type	Required	Description
itemsDone	integer (int64)	yes	Items (for example files) finished so far.
itemsTotal	integer (int64)	yes	Items in the whole job.
bytesDone	integer (int64)	yes	Bytes processed so far.
bytesTotal	integer (int64)	yes	Bytes in the whole job.
currentItem	null | string	yes	What the job works on right now, for example a path.

JobState

Where a job is in its life. The last four are final and never change again.

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

JsonElement

Type: object

LacpRate

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

Type: "slow", "fast"

LogArchiveState

Type: "off", "ready", "unavailable"

LogEntry

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

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

LoginRequest

Field	Type	Required	Description
username	string	yes
password	string	yes

LoginResponse

Field	Type	Required	Description
user	null | UserInfo	yes	The signed-in user.
totpRequired	boolean	yes	True when a TOTP or recovery code must follow.
challenge	null | string	yes	Pass to /api/auth/login/totp within five minutes.

LogLevelName

Type: "debug", "info", "warn", "error"

LogPage

A page of entries, newest first.

Field	Type	Required	Description
entries	LogEntry[]	yes	At most the requested limit.
nextCursor	null | string	yes	Pass as cursor for the next, older page; null when there is none.

LogSettings

Retention of the current logs on the system disk and of the optional archive on a pool.

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

LogStatus

The settings with what they hold now.

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

MarkNotificationsReadRequest

Body of POST /api/notifications/read.

Field	Type	Required	Description
ids	null | integer (int64)[]	no	The notifications to mark as read; null or missing marks every unread one.

NetworkChangeOrigin

Where a change of the network came from.

Type: "web", "console"

NetworkCheck

What a change would do, before it is applied.

Field	Type	Required	Description
config	NetworkConfig	yes	The settings as they would be stored (canonical form).
interfaces	string[]	yes	The interfaces whose configuration changes.
hostNameChanged	boolean	yes	Whether the host name changes.
connectionAffected	boolean	yes	Whether the interface this browser’s connection comes in on changes; the page warns.
addresses	string[]	yes	Static addresses (without prefix) of the changed interfaces, to open after the change.

NetworkConfig

Everything Pithyx configures in the network. Cards that are not listed get their address by DHCP.

Field	Type	Required	Description
interfaces	InterfaceConfig[]	yes	Cards with their own settings, bonds and VLANs.
global	GlobalNetworkConfig	yes	Host name, name servers, search domains, default route.

NetworkLink

An interface as the system has it now.

Field	Type	Required	Description
name	string	yes	The kernel’s name, for example enp1s0.
kind	InterfaceKind	yes	Card, bond or VLAN.
macAddress	null | string	yes	The hardware address.
up	boolean	yes	Whether the interface is up and its link works.
carrier	boolean	yes	Whether a cable (or the other end) is connected.
speedMbps	null (int32) | integer (int32)	yes	The link speed in Mbit/s, when the driver reports it.
duplex	null | string	yes	full or half, when the driver reports it.
mtu	integer (int32)	yes	The MTU in bytes.
addresses	string[]	yes	IPv4 and global IPv6 addresses with prefix length.
gateways	string[]	yes	The default gateways reached through this interface.
dnsServers	string[]	yes	The name servers this interface announced or was given.
defaultRoute	boolean	yes	Whether this interface carries the default route (the lowest metric).
master	null | string	yes	The bond this card belongs to.
vlanParent	null | string	yes	For a VLAN: the interface that carries it.
vlanId	null (int32) | integer (int32)	yes	For a VLAN: its id.
method	string	yes	dhcp, static, off or unknown: how its IPv4 address comes.
configured	boolean	yes	Whether Pithyx keeps settings for it (otherwise a card gets DHCP).
changeable	boolean	yes	Whether Pithyx may change it here; on a development machine only the interfaces in /etc/pithyx/test-nics.

NetworkState

The network of the box. Administrators only.

Field	Type	Required	Description
config	NetworkConfig	yes	What Pithyx configured.
links	NetworkLink[]	yes	Every card, bond and VLAN; container bridges and virtual cables are left out.
hostName	string	yes	The host name the system has now.
globalChangeable	boolean	yes	Whether Pithyx may change host name, name servers and the default route here; not on a development machine.
pending	null | PendingNetworkChange	yes	A change of the network waiting for its confirmation.
confirmSeconds	integer (int32)	yes	How long a change waits for its confirmation before it is rolled back.
connectionInterface	null | string	yes	The interface this browser’s connection comes in on, if known; empty in the live topic.

NetworkTestInterface

One interface after a connection test of the installer.

Field	Type	Required	Description
name	string	yes	The interface.
up	boolean	yes	Whether its link came up.
addresses	string[]	yes	The addresses it got.
gateways	string[]	yes	Its gateways.
gatewayReachable	null | boolean	yes	Whether the first gateway answered a ping; null without a gateway.

NetworkTestStatus

The connection test of the installer: the settings are applied, checked and rolled back.

Field	Type	Required	Description
running	boolean	yes	Whether the test still runs; the page may lose its connection meanwhile.
interfaces	NetworkTestInterface[]	yes	What each tested interface got.
errorCode	null | string	yes	Why the test could not run.
errorParams	object	yes	Values for its text.

NewDesktopItem

Field	Type	Required	Description
kind	DesktopItemKind	yes	What to create.
column	integer (int32)	yes	Grid column.
row	integer (int32)	yes	Grid row.
app	null | string	no	Shortcuts: the id of the app to open. Required for shortcuts, not allowed for notes.
name	null | string	no	Shortcuts: an own label, or null for the app’s name.
text	null | string	no	Notes: the text, at most 4000 characters. Required for notes, not allowed for shortcuts.

NewFolderRequest

Field	Type	Required	Description
path	string	yes	The new folder, relative to the share. Its parent must exist.

NewGroup

Field	Type	Required	Description
name	string	yes	Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name.
description	null | string	no	Optional, at most 200 characters.
memberIds	null | integer (int64)[]	no	The ids of the first members.

NewShare

Field	Type	Required	Description
name	string	yes	Letters, digits, spaces, dots, dashes and underscores, 1 to 64 characters, not starting with a dot.
path	string	yes	An existing folder on the host: absolute, without symlinks, outside the system directories and not overlapping another share.

NewUser

Field	Type	Required	Description
username	string	yes	Lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, at most 32 characters; not a system name.
password	string	yes	At least 8 characters and not one of the most common passwords.
displayName	null | string	no	Optional, at most 64 characters.
groupIds	null | integer (int64)[]	no	The groups the user joins, besides the built-in group users.
grants	null | GrantEntry[]	no	The user’s own grants; when left out, the desktop login, SMB and the apps org.pithyx.files, org.pithyx.viewer and org.pithyx.demo.

Notification

An entry of a user’s notification history. The text is not part of it: the desktop translates code with params from the notifications namespace (<code>.title, .body).

Field	Type	Required	Description
id	integer (int64)	yes	Stable id; never reused.
code	string	yes	Message code, for example jobs.job.failed, storage.alert.poolDegraded, storage.alert.resolved or app.message (an app’s own plain text in params.title and params.body).
params	object	yes	Message parameters: strings and numbers, plus nested objects where a code says so.
tone	NotificationTone	yes	How the desktop shows it.
app	null | string	yes	Id of the app that sent it; null for the system.
createdAt	string (date-time)	yes	When it was created (UTC).
readAt	null (date-time) | string (date-time)	yes	When the user read it (UTC); null while unread.

NotificationEvent

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

Field	Type	Required	Description
change	"created", "read", "deleted"	yes	What changed in a user’s notifications.
notification	null | object	yes	An entry of a user’s notification history. The text is not part of it: the desktop translates code with params from the notifications namespace (<code>.title, .body).
ids	integer (int64)[]	yes	The notifications read or deleted; for created the ones dropped.
readAt	null (date-time) | string (date-time)	yes	When the notifications of a read event were read (UTC).

NotificationList

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

Field	Type	Required	Description
items	Notification[]	yes	The signed-in user’s notifications, newest first; at most 200, none older than 30 days.

NotificationTone

How a notification looks: the color of its card and toast.

Type: "info", "success", "warning", "critical"

Partition

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

PasswordReset

Field	Type	Required	Description
password	string	yes	The new password, with the same rules as everywhere.

PendingNetworkChange

A change of the network waiting for its confirmation.

Field	Type	Required	Description
id	string (uuid)	yes	Pass to confirm or revert it.
deadline	string (date-time)	yes	When it is rolled back unless confirmed, UTC.
interfaces	string[]	yes	The interfaces it changed.
addresses	string[]	yes	Static addresses (without prefix) it set; open one of them when the old address went away.
hostName	null | string	yes	The new host name, when it changed.
origin	NetworkChangeOrigin	yes	Settings in a browser or the menu on the console.

PermissionCatalog

Every resource besides shared folders a grant can name, in the order the editors show them.

Field	Type	Required	Description
rights	string[]	yes	The special rights.
protocols	string[]	yes	The file protocols.
apps	string[]	yes	The app ids given to users; the administration apps come with the administrator right.

PlannedCommand

Field	Type	Required	Description
program	string	yes	Program name.
arguments	string[]	yes	Arguments, passed without a shell.

Pool

Field	Type	Required	Description
name	string	yes	Pool name.
poolGuid	string	yes	Pool GUID as decimal text (it does not fit a JSON number).
state	string	yes	ZFS state: ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, REMOVED or SUSPENDED; degraded further when disks are gone that ZFS has not noticed yet.
sizeBytes	integer (int64)	yes	Raw size of all vdevs, parity included.
allocatedBytes	integer (int64)	yes	Raw space in use.
freeBytes	integer (int64)	yes	Raw space free.
capacityPercent	integer (int32)	yes	Share of the raw space in use.
fragmentationPercent	null (int32) | integer (int32)	yes	Free space fragmentation, if known.
readOnly	boolean	yes	True when the pool was imported read-only.
dataErrors	integer (int64)	yes	Number of files with permanent errors.
scan	null | PoolScan	yes	The last or running scrub or resilver, if any.
vdevs	Vdev[]	yes	Top-level vdevs, including log, cache, special and spare devices.
expansion	null | PoolExpansion	no	A RAID-Z expansion (OpenZFS 2.3): a disk attached to a raidz vdev, onto which ZFS spreads the existing data.

PoolExpansion

A RAID-Z expansion (OpenZFS 2.3): a disk attached to a raidz vdev, onto which ZFS spreads the existing data.

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

PoolList

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

Field	Type	Required	Description
pools	Pool[]	yes
datasets	Dataset[]	yes

PoolScan

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

PowerAction

What the power button does.

Type: "restart", "shutdown"

PowerRequest

Field	Type	Required	Description
action	PowerAction	yes	restart or shutdown.

ProcessList

Snapshot and event of system/processes.

Field	Type	Required	Description
at	string (date-time)	yes	When the list was read (UTC).
processes	object[]	yes	Every process except kernel threads.

ProxyBasicAuthUser

A user of the host’s Basic Auth.

Field	Type	Required	Description
username	string	yes	1 to 64 characters without a colon.
password	null | string	no	The password; leave it out to keep the stored one of an existing user.

ProxyCertificateSource

Which certificate a host presents on 443.

Type: "box", "custom"

ProxyHeader

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

Field	Type	Required	Description
name	string	yes	The header’s name, letters, digits and -; never one the proxy controls itself.
value	string	yes	Its value, at most 4096 characters, without line breaks.

ProxyHost

A proxy host as Settings shows it.

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

ProxyHostRequest

A proxy host as an administrator saves it.

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

ProxyOptionsRequest

The settings that apply to every host.

Field	Type	Required	Description
unknownHosts	UnknownHostAction	yes	What a name no enabled host has gets.
signInAddress	null | string	no	An https:// or http:// origin the box’s sign-in answers at, such as a proxy host in front of 7484; none for the requested name on 7484.

ProxyRedirect

A redirect host as Settings shows it.

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

ProxyRedirectRequest

A redirect host as an administrator saves it.

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

ProxySettings

Settings > Reverse proxy.

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

ProxySignInRule

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

Field	Type	Required	Description
required	boolean	yes	Visitors sign in with their account on the box first.
users	string[]	yes	User names allowed besides the groups; administrators always are.
groups	string[]	yes	Group names whose members are allowed. With no users and no groups, everybody who may sign in is.

ProxyStream

A stream as Settings shows it.

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

ProxyStreamRequest

A stream as an administrator saves it.

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

ProxyTarget

Where a proxy host forwards to.

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

ProxyTargetStatus

Whether a proxy host’s target answers.

Field	Type	Required	Description
reachable	boolean	yes	The target answered with any HTTP status.
status	null (int32) | integer (int32)	yes	Its status code, if it answered.
error	null | string	yes	Why not: timeout, refused, dns, tls or other.
milliseconds	integer (int64)	yes	How long the check took.

ProxyTargetTls

How the proxy checks the certificate of an HTTPS target.

Type: "system", "box", "none"

ProxyTicket

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

Field	Type	Required	Description
url	string	yes	The address to open.

ProxyTicketRequest

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

Field	Type	Required	Description
url	string	yes	The address it asked for.

RecoverRequest

Field	Type	Required	Description
username	string	yes
recoveryKey	string	yes
newPassword	string	yes

RecoverResponse

Field	Type	Required	Description
recoveryKey	string	yes	The new recovery key. The old one no longer works.

RecoveryCodes

Field	Type	Required	Description
codes	string[]	yes	Shown exactly once. Each code replaces a TOTP code for one login.

RenameRequest

Field	Type	Required	Description
path	string	yes	The file or folder to rename.
name	string	yes	The new name in the same folder.

ResourceSample

One second of the box, the event of system/resources. Rates are per second since the previous sample.

Field	Type	Required	Description
at	string (date-time)	yes	When it was measured (UTC).
uptimeSeconds	number (double)	yes	Seconds since boot.
loadAverage	number (double)[]	yes	Over 1, 5 and 15 minutes.
cpu	object	yes
memory	object	yes	Physical memory split the way the monitor draws it. On Linux the ZFS ARC is not part of the page cache, so the kernel counts it as used; UsedBytes leaves it out and ArcBytes shows it.
network	object[]	yes	Every interface except the loopback and container links.
disks	object[]	yes	Every whole disk (no partitions, zvols or loop devices).
temperatures	object[]	yes	Every sensor found; empty where the hardware or a virtual machine has none.

ResourceSnapshot

Snapshot of system/resources: what the box is and the last hour, as far as someone watched it.

Field	Type	Required	Description
cpuCount	integer (int32)	yes	Cores the kernel lists.
memoryTotalBytes	integer (int64)	yes	Installed memory the kernel manages.
history	object	yes	The ring buffer of the last hour, averaged into buckets so the snapshot stays small. Every series has one entry per time; a device that did not exist at a time has null there.
latest	null | object	yes	One second of the box, the event of system/resources. Rates are per second since the previous sample.

RestoreBackupRequest

Field	Type	Required	Description
restoreId	string	yes	From the summary of the checked backup.
categories	BackupCategory[]	yes	The parts to restore; each replaces the current one completely.

RestorePointsRequest

Field	Type	Required	Description
enabled	boolean	yes	Daily restore points, kept 7 days, on or off.

RestoreProblem

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

Field	Type	Required	Description
category	BackupCategory	yes	The part it belongs to.
step	string	yes	accounts (Linux accounts and groups), linuxPasswords, sambaPasswords, time, tls or sshKeys.

RestoreResult

Field	Type	Required	Description
restored	BackupCategory[]	yes	The parts that were restored.
problems	RestoreProblem[]	yes	Steps that failed; details are in the Log Center.
restarting	boolean	yes	The daemon restarts in a few seconds to load the restored configuration.

RollbackRequest

Field	Type	Required	Description
snapshot	string	yes	The snapshot to restore.
version	string	yes	Its version, typed by the administrator as the confirmation.

SavedLayout

Field	Type	Required	Description
layout	JsonElement	yes	The layout now saved for this device.
version	integer (int64)	yes	Its version, for If-Match on the next save.

ServerMessage

Type: 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.

Field	Type	Required	Description
admin	boolean	yes	Administrators may do everything.
rights	string[]	yes	The special rights: right:admin, right:desktopLogin, right:sshLogin, right:power.
protocols	string[]	yes	The file protocols: protocol:smb, protocol:sftp, protocol:webdav, protocol:ftp.
apps	string[]	yes	The ids of the apps of IReadOnlyList<string> PermissionCatalog.Apps the user may open.

SetupRequest

Field	Type	Required	Description
username	string	yes
password	string	yes
displayName	null | string	no

SetupResponse

Field	Type	Required	Description
user	UserInfo	yes	The administrator, already signed in.
recoveryKey	string	yes	Shown exactly once. It is the only way to reset the administrator password.

SetupStatus

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

ShareAccess

Type: "none", "read", "readWrite"

ShareDataChoice

Type: "keep", "destroy", null

ShareDetails

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

Field	Type	Required	Description
id	integer (int64)	yes	Stable id.
name	string	yes	Name shown to users.
description	string	yes	Free text for administrators and users, may be empty.
path	string	yes	The share root on the host.
pool	null | string	yes	The pool of the share’s dataset; null for a folder share.
dataset	null | string	yes	Full name of the share’s dataset, for example tank/pithyx/shares/media; null for a folder share (development only).
usedBytes	null (int64) | integer (int64)	yes	Space the dataset uses with its snapshots; null for a folder share or while the dataset is not there (pool missing).
availableBytes	null (int64) | integer (int64)	yes	Space still available to the dataset; null like UsedBytes.
quotaBytes	null (int64) | integer (int64)	yes	The dataset’s quota, or null for none.
readUsers	integer (int32)	yes	Active users other than administrators who may read, through their own grants or their groups.
readWriteUsers	integer (int32)	yes	Active users other than administrators who may read and write, through their own grants or their groups.
restorePoints	null | boolean	yes	Whether daily restore points (snapshots kept 7 days) are on; null for a folder share.
smb	boolean	yes	Whether SMB offers the shared folder (dataset shares only).
sftp	boolean	yes	Whether SFTP shows the shared folder (dataset shares only).
smbEncrypt	boolean	yes	Whether SMB clients must encrypt.
webDav	boolean	yes	Whether WebDAV offers the shared folder.
ftp	boolean	yes	Whether FTP offers the shared folder.

ShareGrants

Who may use a shared folder. Administrators only.

Field	Type	Required	Description
grants	SubjectGrant[]	yes	The grants of users and groups on it; the editor changes these.
users	ShareUserAccess[]	yes	Every user with the access it ends up with, administrators and deactivated users included.

ShareGrantsRequest

Field	Type	Required	Description
grants	SubjectGrant[]	yes	Every grant the shared folder should have; the others go.

ShareInfo

A share the user can use.

Field	Type	Required	Description
id	integer (int64)	yes	Stable id; file paths are relative to the share.
name	string	yes	Name shown to users: the shared folder’s name, home for the caller’s home, the folder name for another user’s home.
access	ShareAccess	yes	The user’s access: read or read and write.
path	null | string	yes	The share root on the host. Only administrators get it.
unavailable	null | string	no	Why its files cannot be reached now (ShareAvailability), or null when they can.
kind	ShareKind	no	A shared folder, the caller’s home or another user’s home.

ShareKind

What a share is.

Type: "share", "home", "userHome"

ShareListRevision

Snapshot and event of shares/list.

Field	Type	Required	Description
revision	integer (int64)	yes	Changes whenever a user’s list of usable shares may have changed; compare it, do not count on it.

SharePlanRequest

A shared folder action to plan. share.create needs Name and Pool (Description is optional); share.delete needs ShareId, ConfirmName and Data.

Field	Type	Required	Description
action	string	yes	share.create or share.delete.
name	null | string	no	Name of the new shared folder; its dataset name is derived from it and shown in the plan.
pool	null | string	no	Pool of the new shared folder; it needs the Pithyx layout (<pool>/pithyx/shares).
description	null | string	no	Description of the new shared folder.
shareId	null (int64) | integer (int64)	no	The shared folder to delete.
confirmName	null | string	no	The shared folder’s name, typed by the user to delete it.
data	null | ShareDataChoice	no	keep leaves the dataset or folder with its files, destroy destroys the dataset and its snapshots (dataset shares only).

ShareUpdate

Changes of a share; fields left out stay. The dataset is never renamed by this.

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

ShareUserAccess

One user’s effective access to a shared folder.

Field	Type	Required	Description
userId	integer (int64)	yes	The user’s id.
username	string	yes	Login name.
displayName	null | string	yes	Name shown, if set.
administrator	boolean	yes	Administrators use every shared folder with read and write.
disabled	boolean	yes	Deactivated users use none.
access	ShareAccess	yes	What the user ends up with: none, read or readWrite.

SmartReport

SMART health of one disk as last read. The API serves it from memory; reading it never runs a command.

Field	Type	Required	Description
diskId	string	yes	The disk’s id.
state	string	yes	passed, warning (reallocated, pending or uncorrectable sectors, media errors or a failed self-test), failed (the drive predicts its failure), unsupported (no SMART, see Reason) or unknown (not read yet, asleep since the daemon started, or the read failed).
reason	null | string	yes	For unsupported: virtual (a disk of a virtual machine) or not_available. For unknown: asleep, not_read or read_failed. Otherwise null.
asleep	boolean	yes	True when the last check found the disk asleep; the values are then from ReadAt.
temperatureCelsius	null (int32) | integer (int32)	yes	Current temperature, if reported.
powerOnHours	null (int64) | integer (int64)	yes	Power-on time, if reported.
reallocatedSectors	null (int64) | integer (int64)	yes	ATA attribute 5, raw value.
pendingSectors	null (int64) | integer (int64)	yes	ATA attribute 197, raw value.
uncorrectableSectors	null (int64) | integer (int64)	yes	ATA attribute 198, raw value.
mediaErrors	null (int64) | integer (int64)	yes	NVMe media and data integrity errors.
criticalWarning	null (int32) | integer (int32)	yes	NVMe critical warning bits; not 0 means the drive reports a critical condition.
lastSelfTest	null | string	yes	Result of the newest self-test: passed, failed, aborted or running; null without one.
readAt	null (date-time) | string (date-time)	yes	When SMART data was last read (UTC); null if never.
checkedAt	string (date-time)	yes	When the disk was last checked (UTC), including checks that found it asleep.

Snapshot

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

SnapshotCreateRequest

Field	Type	Required	Description
dataset	string	yes	The dataset to snapshot.

SnapshotInfo

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

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

SnapshotList

Response of GET /api/storage/snapshots.

Field	Type	Required	Description
dataset	string	yes	The dataset.
snapshots	Snapshot[]	yes	Its snapshots, oldest first.

SnapshotMessage

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

Field	Type	Required	Description
id	string	yes
topic	string	yes
data	object	yes
type	"snap"	yes
requestId	string	yes

SnapshotRequest

Field	Type	Required	Description
dataset	string	yes	The dataset.
name	string	yes	The exact snapshot name after @.

SnapshotSchedule

Field	Type	Required	Description
kind	string	yes	hourly, daily, weekly or monthly.
enabled	boolean	yes	Whether the schedule takes snapshots.
keep	integer (int32)	yes	How many of its snapshots it keeps (1 to 1000).

SnapshotScheduleList

Schedules of a dataset: all four kinds, in the order hourly, daily, weekly, monthly.

Field	Type	Required	Description
dataset	string	yes	The dataset.
schedules	SnapshotSchedule[]	yes	One entry per kind; kinds left out of a PUT stay as they are.

StagedUpdate

An uploaded update file that passed every check and waits for “Install”. TrustedSignature: False only for a development file on a development box.

Field	Type	Required	Description
version	string	yes
channel	string	yes
minimumVersion	string	yes
changelog	string	yes
size	integer (int64)	yes
trustedSignature	boolean	yes
packages	integer (int32)	yes
kernel	string	yes
publishedAt	string (date-time)	yes

StorageAlert

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

Field	Type	Required	Description
key	string	yes	Stable key of the cause, for example pool.degraded:tank or disk.smart_failed:wwn-0x5000c500a1b2c3d4.
severity	string	yes	warning or critical.
code	string	yes	Message code in the notifications namespace (<code>.title, .body, .action).
params	object	yes	Message parameters: strings and numbers.
since	string (date-time)	yes	When the daemon first saw the cause (UTC); a restart starts it again.
muted	boolean	yes	True when the user muted this alert at this severity or higher.

StorageDisk

A disk with the guard’s verdict, for the Storage settings page.

Field	Type	Required	Description
disk	Disk	yes
guard	GuardVerdict	yes

StorageDiskList

Response of GET /api/storage/disks.

Field	Type	Required	Description
disks	StorageDisk[]	yes	Every disk with its verdict.
environment	string	yes	dev or prod; on dev only the declared test disks can be used.

StorageHealth

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

Field	Type	Required	Description
alerts	StorageAlert[]	yes	Current alerts, critical first, with the user’s mute flags.
smart	SmartReport[]	yes	SMART state of every disk.

StoragePlanPreview

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

Field	Type	Required	Description
planId	null | string	yes	Runs the plan exactly as shown with POST /api/storage/plans/{planId}/run; null while a disk is not allowed, and while RequiresConfirmName is true and the name was not typed yet.
disks	GuardVerdict[]	yes	The guard’s verdict for every chosen disk, after probing them again.
commands	null | PlannedCommand[]	yes	The exact commands, or null while a disk is not allowed.
datasets	string[]	yes	For destroying or exporting a pool: every dataset that goes or becomes unavailable; for pool.import: the datasets it mounts. For destroying a dataset: the dataset, its children and every snapshot of them (dataset@snapshot), each dataset followed by its snapshots. For renaming a dataset: the dataset and its children, whose names change. For destroying a snapshot: the snapshot (dataset@snapshot); for rolling back: every newer snapshot, which goes too.
expiresAt	string (date-time)	yes	Until when the plan may run.
warnings	string[]	yes	Stable codes for what the user must know before running it: lowers_redundancy, replication_mismatch, irreversible and no_redundancy (adding a vdev: it tolerates fewer failed disks than the pool, it has a layout ZFS calls a replication mismatch, it can never be removed, it has no redundancy), irreversible (RAID-Z expansion), other_system (an import forced over another system’s claim), degraded (the pool is imported with devices missing), unmounted_datasets (Unmounted stay unmounted) and datasets_unavailable (exporting a pool with datasets in use); for a rollback changes_lost (every change since the snapshot is lost) and newer_snapshots (the listed newer snapshots are destroyed).
requiresConfirmName	boolean	yes	True when the plan runs only with the pool’s name (for a rollback the dataset’s full name) typed in confirmName.
unmounted	UnmountedDataset[]	yes	For pool.import: datasets that stay unmounted, and why; those that would hide part of the system also get canmount=noauto.

StoragePlanRequest

A destructive storage action to plan. Which fields an action needs: pool.create Pool, Layout, DiskIds, Encryption (and Confirmations for disks that are not empty); pool.destroy Pool and ConfirmName; pool.replace Pool, Vdev and one disk in DiskIds with its serial in Confirmations; pool.spare.add Pool and one disk; pool.spare.remove, pool.offline and pool.online Pool and Vdev; pool.import.readonly PoolGuid from the import scan, NewName when the name is taken, and Force with the pool name in ConfirmName when the scan says needsForce; pool.import Pool (imported read-only), and Force with ConfirmName to force it; pool.export Pool; pool.vdev.add Pool, Layout (single, mirror, raidz1 to raidz3), DiskIds, Confirmations, and ConfirmName when the preview says so; pool.raidz.expand Pool, Vdev (the raidz vdev), one disk and ConfirmName; dataset.rename Pool, Dataset and NewName; dataset.set Pool, Dataset and at least one of QuotaBytes, ReservationBytes, Compression and RecordSizeBytes; dataset.destroy Pool, Dataset and ConfirmName; volume.create Pool, Name, SizeBytes and Sparse; snapshot.destroy Pool, Dataset and the snapshot’s Name; snapshot.rollback Pool, Dataset, the snapshot’s Name and the dataset’s full name in ConfirmName.

Field	Type	Required	Description
action	string	yes	pool.create, pool.destroy, pool.replace, pool.spare.add, pool.spare.remove, pool.offline, pool.online, pool.import.readonly, pool.import, pool.export, pool.vdev.add, pool.raidz.expand, dataset.rename, dataset.set, dataset.destroy, volume.create, snapshot.destroy or snapshot.rollback.
pool	string	yes	The pool, or the new pool’s name; for pool.import.readonly the scanned name (the GUID decides).
layout	null | string	no	single, stripe, mirror, mirrors (pairs), raidz1, raidz2 or raidz3.
diskIds	null | string[]	no	The disks to use, by id.
name	null | string	no	Name of a new volume (one path component), or the snapshot after @ for the snapshot actions. Shared folders are created with POST /api/shares/plans.
vdev	null | string	no	GUID of the device to replace, take offline, bring online or remove, or of the raidz vdev to expand.
encryption	null | string	no	The answer to the encryption question of a new pool: none, or key once the key vault exists.
confirmName	null | string	no	The pool’s name, or the dataset’s full name, typed by the user where the preview says requiresConfirmName and to destroy.
confirmations	null | map of string	no	Serial numbers the user typed, by disk id.
dataset	null | string	no	Full name of the dataset or volume to rename, change or destroy, on Pool.
newName	null | string	no	The new last component of a renamed dataset (it stays below the same parent), or for pool.import.readonly the name to import the pool under when its own is taken.
quotaBytes	null (int64) | integer (int64)	no	New quota in bytes (dataset, children and snapshots), 0 for none; null leaves it.
reservationBytes	null (int64) | integer (int64)	no	New reservation in bytes (dataset, children and snapshots), 0 for none; null leaves it.
compression	null | string	no	New compression: off, lz4, zle, zstd, zstd-1 to zstd-19, gzip, gzip-1 to gzip-9; null leaves it.
recordSizeBytes	null (int64) | integer (int64)	no	New record size of a file system, a power of two from 4 KiB to 1 MiB; null leaves it.
sizeBytes	null (int64) | integer (int64)	no	Size of a new volume, at least 1 MiB; rounded up to whole 16 KiB blocks.
sparse	null | boolean	no	True for a volume that reserves no space up front.
poolGuid	null | string	no	For pool.import.readonly: the pool’s numeric identifier from the import scan.
force	null | boolean	no	For imports: import a pool that was last used by another system; needs ConfirmName.

StorageSchedule

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

StorageScheduleList

Response of GET /api/storage/schedules.

Field	Type	Required	Description
schedules	StorageSchedule[]	yes

StorageScheduleUpdate

Body of PUT /api/storage/schedules.

Field	Type	Required	Description
kind	string	yes	scrub, shortSelfTest or longSelfTest.
target	string	yes	The pool name for scrubs; empty for self-tests.
frequency	string	yes	off, weekly or monthly.

StoreApp

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

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

StoreAppDetails

The detail page of a catalog app.

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

StoreAppList

Apps of the enabled catalogs, sorted by name.

Field	Type	Required	Description
apps	StoreApp[]	yes

StoreAppVersion

A published version of a catalog app.

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

StoreChannel

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

Type: "stable", "beta"

StoreSettings

The Store’s settings.

Field	Type	Required	Description
policy	UpdatePolicy	yes	What a check does with newer versions; each app may override it.
time	string	yes	The daily check time as HH:mm in the box’s time zone; the box adds its own delay of up to an hour.
channel	StoreChannel	yes	The branch every catalog is read from.
nextCheckAt	string (date-time)	yes	When the next check runs (UTC), the box’s delay included.
lastCheckAt	null (date-time) | string (date-time)	yes	When the last check ran (UTC), if one did.

StoreSettingsRequest

Field	Type	Required	Description
policy	UpdatePolicy	yes	What a check does with newer versions.
time	string	yes	HH:mm in the box’s time zone.
channel	StoreChannel	yes	stable or beta.

StoreState

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

Field	Type	Required	Description
settings	StoreSettings	yes	The settings with the next check.
catalogs	CatalogInfo[]	yes	Every catalog, the project’s first.
updates	AppUpdate[]	yes	Newer versions of installed apps, by app id.

SubjectGrant

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

Field	Type	Required	Description
subjectKind	SubjectKind	yes	user or group.
subjectId	integer (int64)	yes	The user’s or the group’s id.
level	GrantLevel	yes	read or readWrite.

SubjectKind

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

Type: "user", "group", "app"

SystemInfo

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

SystemOverview

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

SystemRegion

The regional settings of the box.

Field	Type	Required	Description
language	string	yes	The system language: the sign-in page and every user on “Automatic” whose browser asks for a language Pithyx does not have get it, and so do messages the box sends on its own. One of IReadOnlyList<string> SystemRegion.Languages.
region	null | string	yes	ISO 3166 country code such as DE or US whose date, time and number formats every user sees, or null to follow each user’s language.

ThumbnailRequest

Body of POST /api/files/{shareId}/thumbnails.

Field	Type	Required	Description
folder	null | string	yes	The folder shown, relative to the share.
names	string[]	yes	Entries of that folder on screen, at most 200.
size	ThumbnailSize	yes	small (64 px, list rows) or large (256 px, grid tiles).

ThumbnailSize

The two thumbnail sizes: rows of the list, tiles of the grid (both twice their CSS size for sharp screens).

Type: "small", "large"

ThumbnailsReady

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

Field	Type	Required	Description
items	object[]	yes	Each with ready and its version, or none.
size	"small", "large"	yes	The two thumbnail sizes: rows of the list, tiles of the grid (both twice their CSS size for sharp screens).

ThumbnailState

Field	Type	Required	Description
name	string	yes	The entry.
status	ThumbnailStatus	yes	Whether it has a thumbnail.
version	null | string	yes	For ready: changes whenever the file changes; pass it as v so a new version is loaded.

ThumbnailStates

Response of POST /api/files/{shareId}/thumbnails. Nothing was rendered while answering.

Field	Type	Required	Description
topic	string	yes	Subscribe to it for the thumbnails that are still pending.
items	ThumbnailState[]	yes	One state per distinct name asked for.

ThumbnailStatus

Whether a thumbnail can be shown now.

Type: "ready", "pending", "none"

ThumbnailWatch

Snapshot of a thumbnail topic; the events carry everything.

Field	Type	Required	Description
watching	boolean	yes	Always true.

TimeSettings

Field	Type	Required	Description
timeZone	string	yes	IANA name of the system time zone.
synchronized	boolean	yes	Whether the clock is synchronized with a time server.
ntpServers	string[]	yes	Time servers Pithyx configured; empty means the distribution’s defaults.
timeZones	string[]	yes	Every time zone the system knows.

TimeSettingsRequest

Field	Type	Required	Description
timeZone	string	yes	IANA name of the new time zone.
ntpServers	string[]	yes	At most eight host names or addresses; empty for the distribution’s defaults.

TlsNamesRequest

Names the box’s own certificate covers besides its host name and addresses.

Field	Type	Required	Description
extraNames	string[]	yes	DNS names or addresses inside the authority’s scope, at most 20.

TlsSettings

Settings > Certificates.

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

TopicEvents

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

TopicSnapshots

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

TotpConfirmRequest

Field	Type	Required	Description
code	string	yes

TotpDisableRequest

Field	Type	Required	Description
password	string	yes

TotpEnrollment

Field	Type	Required	Description
secret	string	yes	Base32 secret for manual entry.
uri	string	yes	otpauth:// URI for the QR code.

TotpLoginRequest

Field	Type	Required	Description
challenge	string	yes	From the login response.
code	null | string	no	Six-digit code from the authenticator app.
recoveryCode	null | string	no	One of the recovery codes shown when TOTP was enabled, instead of a code.

TrashItem

One item in a share’s recycle bin.

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

TrashItemsRequest

Field	Type	Required	Description
ids	integer (int64)[]	yes	Items of the share’s recycle bin, at most 1000.
onConflict	null | ConflictPolicy	no	For restoring: what happens when the original place is taken; rename when left out.

TrashPage

Field	Type	Required	Description
items	TrashItem[]	yes	Newest first.
nextCursor	null | string	yes	Pass as cursor for the next page; null on the last page.
retentionDays	integer (int32)	yes	Days the share keeps deleted items; 0 keeps them until the bin is emptied.

TrashSettingsRequest

Field	Type	Required	Description
retentionDays	integer (int32)	yes	0 to 3650; 0 keeps deleted items until the bin is emptied.

UnknownHostAction

What 443 and 80 do with a name no enabled host has.

Type: "redirect", "notFound"

UnmountedDataset

Field	Type	Required	Description
name	string	yes	The dataset.
mountPoint	string	yes	Its mount point.
reason	string	yes	Why it stays unmounted: system_path (/ or at or below a system directory), shadows_mount (it would hide something mounted there or below), duplicate_mountpoint (another dataset of the pool mounts there first) or key_unavailable (encrypted and locked).

UpdateAppRequest

Field	Type	Required	Description
enabled	boolean	yes	False hides the app from everybody and stops serving its frontend; its data and grants stay.

UpdateCatalogRequest

Field	Type	Required	Description
enabled	null | boolean	no	Switches the catalog on or off; null leaves it.
registryToken	null | string	no	user:token to pull the catalog’s private images; empty removes it, null leaves it.

UpdateHistoryEntry

One update or rollback of the system. Kind: update or rollback. Source: online (from the channel), file (uploaded), recovery (the console menu) or manual (a rollback from Settings). Snapshot: The snapshot taken before an update, or the one a rollback restored. State: running, restarting, succeeded, failed (nothing changed) or rolled_back.

Field	Type	Required	Description
id	integer (int64)	yes
kind	string	yes
source	string	yes
fromVersion	string	yes
toVersion	string	yes
snapshot	null | string	yes
state	string	yes
errorCode	null | string	yes
errorParams	null | object	yes
startedAt	string (date-time)	yes
finishedAt	null (date-time) | string (date-time)	yes

UpdatePolicy

Type: "automatic", "notify", "none", null

UpdateProblem

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

Field	Type	Required	Description
code	string	yes
params	object	yes

UpdateSettingsRequest

Field	Type	Required	Description
checkEnabled	boolean	yes	The daily check (on by default; it only notifies).
channel	string	yes	stable or beta.

UpdateSourceCandidate

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

Field	Type	Required	Description
name	string	yes
url	string	yes
keys	UpdateSourceKey[]	yes
savedBy	string	yes
savedAt	string (date-time)	yes

UpdateSourceInfo

The update source the box follows. Official: True for the Pithyx project’s keys; false after a switch to another source in the recovery menu.

Field	Type	Required	Description
name	string	yes
url	string	yes
official	boolean	yes
keys	UpdateSourceKey[]	yes

UpdateSourceKey

A key of an update source as Settings shows it.

Field	Type	Required	Description
keyId	string	yes
publicKey	string	yes
channels	string[]	yes

UpdateStatus

Settings > Updates for administrators (topic system/updates). Supported: Whether updates and rollbacks apply here; false on a machine not laid out by the installer. UnsupportedReason: not_btrfs, not_subvolume, not_array or findmnt. RunningJobId: The job of an update or rollback that runs now. Snapshots: The kept snapshots, newest first; each can be restored. Source: The update source the box follows; only the recovery menu switches it. SourceCandidate: A source file saved in Settings for the recovery menu, or null.

Field	Type	Required	Description
installedVersion	string	yes
channel	string	yes
checkEnabled	boolean	yes
lastCheckAt	null (date-time) | string (date-time)	yes
nextCheckAt	null (date-time) | string (date-time)	yes
checking	boolean	yes
available	null | AvailableUpdate	yes	The newest version of the box’s channel when it is newer than the installed one. Installable: False when the box is older than MinimumVersion and needs a version in between first.
debian	null | DebianUpdates	yes	The Debian updates apt offers; the kernel and ZFS never come from Debian.
problem	null | UpdateProblem	yes	Why the last check could not read the channel, as an error code with its params.
supported	boolean	yes
unsupportedReason	null | string	yes
staged	null | StagedUpdate	yes	An uploaded update file that passed every check and waits for “Install”. TrustedSignature: False only for a development file on a development box.
runningJobId	null (int64) | integer (int64)	yes
history	UpdateHistoryEntry[]	yes
snapshots	SnapshotInfo[]	yes
source	UpdateSourceInfo	yes
sourceCandidate	null | UpdateSourceCandidate	yes	A source file an administrator saved in Settings for the recovery menu, which alone can switch to it.

UserDeletion

The result of deleting a user.

Field	Type	Required	Description
job	null | Job	yes	A long operation of a user, such as copying files. Also the data of the jobs/{id} topics.

UserGrants

The rights of a user for the editor. Administrators only.

Field	Type	Required	Description
grants	GrantEntry[]	yes	The user’s own grants; the editor changes these.
inherited	InheritedGrant[]	yes	What its groups give it; changed on the group.
effective	SessionPermissions	yes	What the user may do: the union of both, or everything for an administrator.

UserInfo

The signed-in user.

Field	Type	Required	Description
id	integer (int64)	yes	Stable id.
username	string	yes	Login name.
displayName	null | string	yes	Name shown, if set.
isAdmin	boolean	yes	Whether the user has the administrator right, its own or through a group.
totpEnabled	boolean	yes	Whether the user signs in with a second factor.
permissions	SessionPermissions	yes	What the user may do; the topic session/permissions sends changes.
groups	GroupRef[]	yes	The user’s groups by name, without the built-in group every user is in; apps get them in their context.

UserSummary

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

Field	Type	Required	Description
id	integer (int64)	yes	Stable id.
username	string	yes	The Linux user name, lower case.
displayName	null | string	yes	Shown instead of the user name, if set.
isAdmin	boolean	yes	Whether the user has the administrator right, its own or through a group; administrators have every right.
uid	null (int64) | integer (int64)	yes	The Linux uid from the Pithyx range (20000 to 29999), never reused.
totpEnabled	boolean	yes	Whether the user signs in with a second factor.
createdAt	string (date-time)	yes	When the user was created, UTC.
home	null | string	yes	The user’s home folder on a pool, or null when there is no pool yet.
disabled	boolean	yes	Deactivated: cannot sign in, and the Linux account is expired.
rights	string[]	yes	The special rights the user has (right:admin, right:desktopLogin, right:sshLogin, right:power), its own and through its groups; a deactivated user gets them back when activated.
protocols	string[]	yes	The file protocols the user may use (protocol:smb, protocol:sftp, protocol:webdav, protocol:ftp), the same way.
fileServicePassword	boolean	yes	Whether SMB and SFTP know the user’s password. They learn it when the user signs in on the web or an administrator sets it; until then the user cannot use them.
groupIds	integer (int64)[]	yes	The groups the user is a member of; the built-in group users, which has everybody, is left out.

UserUpdate

Fields left out stay as they are.

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

Vdev

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

VlanSettings

Field	Type	Required	Description
parent	string	yes	The network card or bond that carries the VLAN’s tagged frames.
id	integer (int32)	yes	The 802.1Q VLAN id, 1 to 4094.

WebSocketCloseCode

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

WindowPreference

Field	Type	Required	Description
appId	string	yes	The app the preference belongs to.
width	integer (int32)	yes	Last free width of the app’s windows in CSS pixels.
height	integer (int32)	yes	Last free height in CSS pixels.

WindowPreferenceRequest

Field	Type	Required	Description
width	integer (int32)	yes
height	integer (int32)	yes