Skip to content

API Reference

Jump to bottom
Markus Langer edited this page Mar 12, 2026 · 24 revisions

API Reference

All endpoints are served under http://<host>:8080. The API returns JSON. Non-2xx responses include an error string field.

Read endpoints

Method Path Description
GET /api/sysinfo Host and process info
GET /api/version OpenZFS version string
GET /api/pools List all pools with usage stats
GET /api/poolstatus Detailed pool status with vdev tree
GET /api/datasets List all datasets and volumes
GET /api/dataset-props/{name} Editable properties for a dataset
GET /api/snapshots List all snapshots
GET /api/iostat Pool I/O statistics (1-second sample)
GET /api/smart S.M.A.R.T. health per disk
GET /api/events Server-Sent Events stream
GET /metrics Prometheus text exposition

Dataset endpoints

Method Path Description
POST /api/datasets Create a dataset or volume
PATCH /api/datasets/{name} Update dataset properties
DELETE /api/datasets/{name} Destroy a dataset or volume

POST /api/datasets

{
  "name": "tank/data",
  "type": "filesystem",
  "compression": "lz4",
  "quota": "50G",
  "mountpoint": "/mnt/data",
  "recordsize": "128K",
  "atime": "off",
  "exec": "on",
  "sync": "standard",
  "dedup": "off",
  "copies": "1",
  "xattr": "sa"
}

For volumes use "type": "volume" and add "volsize": "10G". Optional: "volblocksize", "sparse": true.

PATCH /api/datasets/{name}

Body is a JSON object with any subset of editable properties. An empty string resets a property to inherited; a non-empty value sets it explicitly.

{ "compression": "zstd", "quota": "", "readonly": "on" }

Editable properties: compression, quota, mountpoint, recordsize, atime, exec, sync, dedup, copies, xattr, readonly, acltype, sharenfs, sharesmb.

DELETE /api/datasets/{name}

Append ?recursive=true to also destroy all child datasets and snapshots. Pool roots (e.g. tank) cannot be deleted via this endpoint.

Snapshot endpoints

Method Path Description
POST /api/snapshots Create a snapshot
DELETE /api/snapshots/{name} Destroy a snapshot

POST /api/snapshots

{ "dataset": "tank/data", "snapname": "2024-01-15_backup", "recursive": false }

DELETE /api/snapshots/{dataset}@{snapname}

Append ?recursive=true to also destroy clones.

User & group endpoints

Method Path Description
GET /api/users List local users
POST /api/users Create a local user
PUT /api/users/{name} Edit user (shell, groups, password)
DELETE /api/users/{name} Delete user and home directory
GET /api/groups List local groups
POST /api/groups Create a local group
PUT /api/groups/{name} Edit group (name, GID, members)
DELETE /api/groups/{name} Delete a local group

System accounts (UID/GID < UID_MIN) are protected from deletion at both API and playbook level.

ACL endpoints

Method Path Description
GET /api/acl-status ACL presence map (dataset → bool)
GET /api/acl/{dataset} Get ACL entries for a dataset
POST /api/acl/{dataset} Add or modify an ACL entry
DELETE /api/acl/{dataset} Remove an ACL entry

GET /api/acl/{dataset}

{
  "dataset": "tank/data",
  "mountpoint": "/mnt/data",
  "acl_type": "posix",
  "entries": [
    { "tag": "user",  "qualifier": "alice", "perms": "r-x", "default": false }
  ]
}

acl_type is one of "posix", "nfsv4", or "off".

POST /api/acl/{dataset}

{ "ace": "user:alice:rwx", "recursive": false }

ACE format depends on acltype:

  • POSIX: setfacl -m spec — "user:alice:rwx", "default:group:storage:r-x"
  • NFSv4: full ACE string — "A::alice@localdomain:rwaDxtTnNcCoy"

DELETE /api/acl/{dataset}?entry=<spec>

Entry format:

  • POSIX: removal spec without perms — user:alice, default:group:storage
  • NFSv4: full ACE string to match

Append &recursive=true (POSIX only) to remove recursively.

Mountpoint ownership

Method Path Description
GET /api/chown/{dataset} Get mountpoint owner and group
POST /api/chown/{dataset} Set mountpoint owner and/or group

SMB endpoints

Method Path Description
GET /api/smb-shares List all active Samba usershares
POST /api/smb-share/{dataset} Create or update a Samba usershare
DELETE /api/smb-share/{dataset} Remove a Samba usershare
GET /api/smb-users List users registered in smbpasswd
POST /api/smb-users/{name} Add a user to smbpasswd
DELETE /api/smb-users/{name} Remove a user from smbpasswd
POST /api/smb-config/pam Run Samba setup playbook

Server-Sent Events

GET /api/events?topics=<comma-separated>

Topic Data Cadence
pool.query Same as GET /api/pools Every 10 s on change
dataset.query Same as GET /api/datasets Every 10 s on change
snapshot.query Same as GET /api/snapshots Every 10 s on change
iostat Same as GET /api/iostat Every 10 s always
user.query Same as GET /api/users On write + every 10 s on change
group.query Same as GET /api/groups On write + every 10 s on change 
# Example — watch pool health and I/O live
curl -N 'http://localhost:8080/api/events?topics=pool.query,iostat'

Clone this wiki locally