4. Realm and Platform
4.1 About
Endpoint Summary
| Path | Summary | Method |
|---|---|---|
/api/v1/about |
About | GET |
GET /api/v1/about
About
Return service name, version, and PanFS version.
Nothing sits between the route and its two sources: there is no store to adapt and no invariant to guard. The version file is read per request, so the endpoint follows the realm software without a restart.
Authentication: not required.
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | AboutResponse |
Response Body (200, AboutResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
name |
string | yes | n/a | PanAPI |
Service name |
panfs_version |
string, nullable | no | null |
freebsd_142_amd64/release 2026.18.0-pioneer_swift.1885669 |
PanFS realm software version read from the local filesystem; null when unavailable |
version |
string | yes | n/a | 1.2.3 |
Service version, derived from the package metadata at build time |
4.2 Realm
Endpoint Summary
| Path | Summary | Method |
|---|---|---|
/api/v1/realm |
Get realm | GET |
/api/v1/realm/actions |
Perform realm action | POST |
GET /api/v1/realm
Get realm
Returns the current realm.
Authentication: required (PasswordLogin or BearerJWT).
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response containing the realm | RealmResponse |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 500 | Internal server error. | - |
Response Body (200, RealmResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
realm |
Realm object |
yes | n/a | Realm details | |
server_tzone |
string | yes | n/a | America/Los_Angeles, UTC |
IANA timezone name of the API server’s host (e.g. ‘America/Los_Angeles’). |
Example
{
"realm" : {
"boot_epoch_seconds" : 0,
"clientmode_current" : "balanced",
"clientmode_next" : "balanced",
"data_generation" : 6,
"heartbeat_failure_grace_seconds" : 30,
"heartbeat_period_seconds" : 30,
"id" : "a538deadbeef0001889abcdef1234567",
"locked" : false,
"log_sizing" : "12g",
"mem_sizing_current" : 1,
"mem_sizing_next" : 1,
"mia_timer" : 360,
"name" : "exp-aic-97-5",
"panfs_mounted" : true,
"president_flags" : [
"settled_storage",
"settled_mgr"
],
"state" : "online",
"state_flags" : [],
"volume_layout_type_default" : "raid6+",
"volume_max_vols_realm" : 1200,
"volume_recovery_priority_default" : 50
},
"server_tzone" : "America/Los_Angeles"
}POST /api/v1/realm/actions
Perform realm action
Performs a realm-scoped action. Supported actions: “rehome_root” - reassign the realm root volume to a different StorageSet; “reboot” - reboot the realm; “online” - bring the realm online; “offline” - take the realm offline (mode: “paused” for graceful drain, “unavailable” to make volumes inaccessible without draining); “lock” - prevent new nodes from joining via PanDHCP; “unlock” - re-enable PanDHCP joins. Lock and unlock are idempotent; “move_service” - relocate a service (volume service, PM, CIFS master, …) to a target director node (service_type “primary” performs a live failover, “backup” moves the standby).
Authentication: required (PasswordLogin or BearerJWT).
Request Body (application/json, required)
One of the following, selected by action:
action: lock - RealmLockActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal lock |
yes | n/a | The action to perform on the realm. | |
params |
null (not used) | no | n/a |
action: move_service - RealmMoveServiceActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal move_service |
yes | n/a | The action to perform on the realm. | |
params |
RealmMoveServiceActionParams object |
yes | n/a | Parameters identifying the service to move and its destination node. |
action: offline - RealmOfflineActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal offline |
yes | n/a | The action to perform on the realm. | |
params |
RealmOfflineActionParams object |
no | n/a | Parameters for taking the realm offline. |
action: online - RealmOnlineActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal online |
yes | n/a | The action to perform on the realm. | |
params |
null (not used) | no | n/a |
action: reboot - RealmRebootActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal reboot |
yes | n/a | The action to perform on the realm. | |
params |
null (not used) | no | n/a |
action: rehome_root - RealmRehomeRootActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal rehome_root |
yes | n/a | The action to perform on the realm. | |
params |
RealmRehomeRootActionParams object |
yes | n/a | Parameters required to reassign the realm root volume to a different StorageSet. |
action: unlock - RealmUnlockActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal unlock |
yes | n/a | The action to perform on the realm. | |
params |
null (not used) | no | n/a |
Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Action performed successfully on the realm. No content is returned. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 409 | Conflict. Action conflicts with current system state. | - |
| 422 | Validation error. | - |
| 500 | Internal server error. | - |