Tools

Private API

Every call is authenticated with the same bearer token as the sync — the datahoster-config-apiToken from your local client config, sent as Authorization: Bearer <token>. These routes are read-only and identical across every hoster (they live in the shared common/server/logs-stats.js). As with the sync, without a valid token every reply — a bad token or an unknown route — is an identical 404 wall; with a valid token a read returns 200, and an authenticated request on a different API version's path answers 426. The routes are versioned under /api/v3/, pinned to the local client's own shared/version.js version. Files are exposed by timestamp (logs) or exact validated name (stats) only, so no filename ever crosses the wire and there is no path-traversal surface.

GET /api/v3/logs

Lists the Caddy access logs so the local client can mirror them. The active log is reported by size only; each rotated file is keyed by its rotation timestamp, never its name — so the server can't influence where the local client writes, and a newly-appeared timestamp is how the local client detects that the active log rotated.

{
  "active": { "size": 12345 },
  "rotated": [
    { "ts": 1784370489663, "size": 67108864 },
    { "ts": 1784514159284, "size": 41943040 }
  ]
}

GET /api/v3/logs/file

Streams the bytes of one access-log file. A Range header is honoured so the local client fetches only the tail appended since last time; an immutable rotated file is fetched once, whole. See pull-logs.js.

GET /api/v3/logs/file?which=active
Authorization: Bearer <token>
Range: bytes=12345-

GET /api/v3/stats

Lists the server-health day-files and the sampling interval, so the local client can mirror them. Files are named <type>-YYYY-MM-DD.log; a past day is frozen and mirrored once, today's file grows.

{
  "interval": 15000,
  "files": [
    { "name": "cpu-2026-07-20.log",    "type": "cpu",    "date": "2026-07-20", "size": 82944 },
    { "name": "memory-2026-07-20.log", "type": "memory", "date": "2026-07-20", "size": 61200 }
  ]
}

GET /api/v3/stats/file

Streams one stat day-file by its exact name, which is validated against <type>-YYYY-MM-DD.log — the only thing that reaches the filesystem, so there is no path-traversal surface. A Range fetches only the growing tail of the current day. See pull-stats.js.

GET /api/v3/stats/file?name=cpu-2026-07-20.log
Authorization: Bearer <token>
Range: bytes=61200-

GET /api/v3/stats/now

Returns a single live health snapshot for debugging — the same shape the recorder samples on its interval, but taken on demand and never stored. Counter fields (CPU core times, disk/network bytes) are cumulative; a consumer diffs two snapshots to get a rate. Metrics a host can't report (e.g. disk/network IO off Linux) are null rather than an error. Built by shared/stats.js.

{
  "ts": 1784514159,
  "uptime": 864000,
  "hostname": "vps-1",
  "load": [0.12, 0.09, 0.05],
  "cpu":    { "model": "…", "cores": [ { "user": 0, "nice": 0, "sys": 0, "idle": 0, "irq": 0 } ] },
  "memory": { "total": 0, "used": 0, "available": 0, "free": 0 },
  "disk":   { "path": "/", "total": 0, "used": 0, "free": 0 },
  "diskIo": { "readBytes": 0, "writeBytes": 0 },
  "netIo":  { "rxBytes": 0, "txBytes": 0 }
}

Mirroring Process

The local client mirrors both sources the same way, statelessly, deriving everything from what it already has on disk — the counterpart of how the sync mirrors the data files. It uses the same version-pinned /api/v<N> prefix as the sync, then:

The download itself lives in the shared toolkit (common/browse/pull-logs.js and common/browse/pull-stats.js), so every hoster mirrors the same way. The mirrored files then feed the static Web Logs and Server Logs browsers. Datahoster's own Data Logs browser is built separately, from the columnar files the sync mirrors down (_data/<host>/datahoster-data/…), read back through the storage engine (shared/store.js) as a read-only loader, not from this API.