title: "Servers API" description: "Manage monitored servers — list, create, update, delete, fetch metrics history, and compare across hosts." last_updated: "2026-05-24"

Servers API

Endpoints under /servers manage the servers monitored by the BoxWatch agent. For conceptual docs see Servers overview.

All routes below require a bearer token.

List servers

GET/servers

Auth: bearer

Returns every server on your account, plus latest metrics, 30-day uptime, and plan-limit metadata. Sorted by active DESC, then group_name ASC, then newest first.

Response — 200 OK

{
  "servers": [
    {
      "id": 12,
      "name": "web-01",
      "hostname": "web-01.prod",
      "ip": "10.0.1.5",
      "os": "Ubuntu 22.04",
      "status": "online",
      "active": true,
      "last_seen": "2026-05-24T18:42:11Z",
      "enabled_metrics": { "cpu": true, "memory": true, "disk": true },
      "created_at": "2026-04-01T10:00:00Z",
      "group_id": 3,
      "group_name": "Production",
      "uptime_30d": 99.8,
      "metrics": {
        "cpu_usage": 17.4,
        "memory_usage": 62.1,
        "disk_usage": 41.0,
        "disk_mnt_usage": 88.3
      }
    }
  ],
  "plan": "pro",
  "serverLimit": 7,
  "basePlanLimit": 7,
  "bonusServers": 0,
  "activeCount": 1,
  "timestamp": "2026-05-24T18:42:11Z"
}

Servers beyond your plan limit appear in the list but have active: false and stop receiving metrics. disk_mnt_usage is only included when a second mount point exists and differs from disk_usage.

Create server

POST/servers

Auth: bearer

Registers a new server slot and returns the agent key the installer needs.

Request body

Field	Type	Required	Description
`hostname`	string	yes	Hostname for the server (display + matching).
`enabled_metrics`	object	no	Per-metric enable flags. Defaults to `{}` (all on).

{ "hostname": "db-02.prod", "enabled_metrics": { "network": false } }

Response — 201 Created

{
  "server": {
    "id": 47,
    "hostname": "db-02.prod",
    "agent_key": "bw_agent_8c1f4...",
    "enabled_metrics": { "network": false },
    "created_at": "2026-05-24T18:42:11Z"
  },
  "timestamp": "2026-05-24T18:42:11Z"
}

Pass agent_key to the agent installer on the target box.

Errors

400 — Hostname required.
403 — Plan server limit reached. Upgrade or delete unused servers.

Compare servers

GET/servers/compare

Auth: bearer

Returns time-series data for a single metric across up to 50 servers, for trend comparisons.

Query parameters

Param	Type	Required	Description
`metric`	string	yes	One of `cpu`, `memory`, `disk`, `load_1m`, `network_in`, `network_out`.
`server_ids`	string	one-of	Comma-separated server IDs.
`group_id`	integer	one-of	Compare every server in this group instead of listing IDs.
`hours`	integer	no	Lookback window. Default `24`.

Response — 200 OK

{
  "metric": "cpu",
  "hours": 24,
  "servers": [
    {
      "id": 12,
      "hostname": "web-01",
      "data": [
        { "timestamp": "2026-05-23T18:45:00Z", "value": 14.2 },
        { "timestamp": "2026-05-23T18:50:00Z", "value": 18.7 }
      ]
    }
  ],
  "timestamp": "2026-05-24T18:42:11Z"
}

Errors

400 — Invalid metric, missing both server_ids/group_id, or more than 50 servers requested.

Get server

GET/servers/:id

Auth: bearer

Returns one server with full metrics snapshot, disk-fill projection, and 24h/7d/30d/90d uptime percentages.

Response — 200 OK

{
  "server": {
    "id": 12,
    "name": "web-01",
    "hostname": "web-01.prod",
    "ip": "10.0.1.5",
    "os": "Ubuntu 22.04",
    "status": "online",
    "last_seen": "2026-05-24T18:42:11Z",
    "enabled_metrics": { "cpu": true },
    "created_at": "2026-04-01T10:00:00Z",
    "metrics": {
      "cpu": 17.4,
      "memory": 62.1,
      "disk": 41.0,
      "disk_mnt": 88.3,
      "load_1m": 0.42,
      "load_5m": 0.61,
      "load_15m": 0.55,
      "uptime": 2419200
    },
    "disk_projection": {
      "days_until_full": 47,
      "trend_per_day_pct": 0.83
    },
    "uptime": { "h24": 100, "d7": 99.9, "d30": 99.8, "d90": 99.6 }
  },
  "timestamp": "2026-05-24T18:42:11Z"
}

Errors

404 — Server not found or not owned by your account.

Update server

PATCH/servers/:id

Auth: bearer

Patch one or more fields. At least one of name, enabled_metrics, or group_id must be present.

Request body

Field	Type	Notes
`name`	string	Display name. Trimmed and truncated at 100 chars.
`enabled_metrics`	object	Replaces the existing flags.
`group_id`	integer or `null`	Group to move into, or `null` to ungroup. Must belong to your account.

Response — 200 OK

{ "message": "Server updated", "timestamp": "2026-05-24T18:42:11Z" }

Errors

400 — No updatable fields provided, or group_id doesn't belong to your account.
404 — Server not found.

Delete server

DELETE/servers/:id

Auth: bearer

Permanently deletes the server and its metric history. Cron checks, processes, and uptime probes linked to the server are cascaded by the DB.

Response — 200 OK

{ "message": "Server deleted", "timestamp": "2026-05-24T18:42:11Z" }

Errors

404 — Server not found.

Metric history

GET/servers/:id/history

Auth: bearer

Returns time-series metrics for one server, downsampled to ~200 points.

Query parameters

Param	Type	Default	Notes
`hours`	integer	`24`	Capped at `168` (7 days).

Response — 200 OK

{
  "history": [
    {
      "cpu": 17.4,
      "memory": 62.1,
      "disk": 41.0,
      "disk_mnt": null,
      "load": 0.42,
      "network_in": 134217,
      "network_out": 98214,
      "timestamp": "2026-05-23T18:45:00Z"
    }
  ],
  "hours": 24,
  "count": 200,
  "timestamp": "2026-05-24T18:42:11Z"
}

Errors

404 — Server not found.

ℹ

Watched processes for a server are managed under /servers/:id/processes/*. See Processes API.