naxos-docs/docs/development/api-reference.md

NaxOS Management Daemon REST & WebSocket API Reference

The NaxOS daemon listens on internal port 8088 (reverse-proxied via Nginx on port 80/443 at /api/).

---

1. System & Engine

GET /api/v1/system/status

Returns high-level appliance status, health metrics, and active generation.

Response Example:

{
  "status": {
    "hostname": "naxos",
    "uptimeSeconds": 864200,
    "cpuUsagePercent": 12.4,
    "memoryTotalBytes": 33554432000,
    "memoryUsedBytes": 14200000000,
    "arcSizeBytes": 4294967296,
    "arcHitRatioPercent": 98.6,
    "zfsPoolsCount": 1,
    "activeSharesCount": 3,
    "runningAppsCount": 2,
    "osVersion": "NaxOS 26.05 (NixOS)",
    "nixosGeneration": 42
  }
}

POST /api/v1/system/rebuild

Triggers nixos-rebuild-safe and streams stdout/stderr output in real-time as Server-Sent Events (SSE) (text/event-stream).

---

2. OpenZFS Storage

GET /api/v1/storage/pools

Lists all active OpenZFS pools, capacity, fragmentation, and health.

POST /api/v1/storage/pools

Creates a new OpenZFS pool. Payload:

{
  "name": "tank",
  "layout": "mirror",
  "devices": ["/dev/sda", "/dev/sdb"],
  "ashift": 12
}

GET /api/v1/storage/unimported

Scans connected disks for foreign pools (TrueNAS / legacy NixOS) available for zero-data-loss import.

POST /api/v1/storage/import

Safely imports a pool. Payload:

{
  "poolName": "tank",
  "force": true,
  "noMount": true
}

GET /api/v1/storage/datasets

Lists datasets, compression, mountpoint, and quotas.

---

3. GitOps Synchronization

GET /api/v1/gitops/status

Returns current branch, head commit SHA, and remote sync state.

GET /api/v1/gitops/commits

Returns generation commit history log.

POST /api/v1/gitops/rollback

Instantly rolls back the declarative appliance configuration to the specified Git commit hash. Payload:

{
  "commitSha": "5da58ae0912f1"
}

---

4. Real-Time Logs

GET /api/v1/logs/stream

SSE stream delivering journald logs in real time. Supports optional ?unit=<service> query parameter.