Servers API

Read your servers over the Servor API with a servers:read token — list every server in your team and fetch a single server's details.

Read the servers in your team over the API. Use these endpoints to build an inventory, feed your own dashboards, or look up a server's id before reading its command history. Everything here is read-only — adding and editing servers stays in the dashboard: add a server in Servor.

These endpoints require the servers:read scope.

get/v1/serversScope: servers:read

List servers

Example request

curl https://api.servor.app/v1/servers \
  -H "Authorization: Bearer sv_live_..."

Example response

[
  {
    "id": "uuid",
    "name": "web-01",
    "host": "203.0.113.10",
    "os": "debian",
    "tags": [
      "prod"
    ],
    "lastSeenAt": "2026-08-20T10:00:00.000Z",
    "createdAt": "2026-08-01T00:00:00.000Z"
  }
]

get/v1/servers/{id}Scope: servers:read

Get a server

Parameters

iduuidpath · required
The server id.

Example request

curl https://api.servor.app/v1/servers/:id \
  -H "Authorization: Bearer sv_live_..."

Example response

{
  "id": "uuid",
  "name": "web-01",
  "host": "203.0.113.10",
  "os": "debian",
  "tags": [
    "prod"
  ],
  "lastSeenAt": "2026-08-20T10:00:00.000Z",
  "createdAt": "2026-08-01T00:00:00.000Z"
}

get/v1/server-groupsScope: servers:read

List server groups

Example request

curl https://api.servor.app/v1/server-groups \
  -H "Authorization: Bearer sv_live_..."

Example response

[
  {
    "id": "uuid",
    "name": "production",
    "color": "emerald",
    "position": 1024
  }
]

get/v1/servers/{id}/metricsScope: metrics:read

Read a server metric series

Parameters

idstringpath · required
Server id.
rangestringquery · optional
One of 1h, 24h, 7d, 30d (default 24h). Past 24h the series is served from hourly rollups.

Example request

curl https://api.servor.app/v1/servers/:id/metrics \
  -H "Authorization: Bearer sv_live_..."

Example response

{
  "resolution": "raw",
  "range": "24h",
  "points": [
    {
      "at": "2026-08-20T10:00:00.000Z",
      "cpuPercent": 12.4,
      "ramUsedMb": 2048,
      "ramTotalMb": 8192,
      "diskUsedGb": 31,
      "diskTotalGb": 80
    }
  ]
}

get/v1/servers/{id}/scheduled-commandsScope: scheduled-commands:read

List scheduled commands for a server

Parameters

idstringpath · required
Server id.

Example request

curl https://api.servor.app/v1/servers/:id/scheduled-commands \
  -H "Authorization: Bearer sv_live_..."

Example response

[
  {
    "id": "uuid",
    "name": "Nightly backup",
    "command": "systemctl start backup",
    "cron": "0 3 * * *",
    "enabled": true,
    "lastRunAt": "2026-08-20T03:00:00.000Z",
    "lastExitCode": 0,
    "consecutiveFailures": 0
  }
]

What you get back

GET /v1/servers — the list of servers in your team.
GET /v1/servers/{id} — the details of a single server.

Example

curl https://api.servor.app/v1/servers \
  -H "Authorization: Bearer sv_live_..."

Take an id from that list to read one server:

curl https://api.servor.app/v1/servers/srv_123 \
  -H "Authorization: Bearer sv_live_..."

Fleet sections

GET /v1/server-groups returns the sections the fleet is arranged in, in the team's order. Each server carries the matching groupId.

Covered by servers:read rather than a scope of its own: a section is part of the shape of the fleet, and a token that could list machines but not the headings they sit under would return an inventory nobody can file.

Server metrics

GET /v1/servers/{id}/metrics returns the CPU, RAM and disk series, to graph in whatever already draws your curves. Scope metrics:read.

curl "https://api.servor.app/v1/servers/$ID/metrics?range=24h" \
  -H "Authorization: Bearer sv_live_..."

range is 1h, 24h, 7d or 30d (default 24h). Past 24 hours the series comes from hourly rollups; the resolution field tells you which of the two you are reading.

Scheduled commands on a server

GET /v1/servers/{id}/scheduled-commands returns each task's cron schedule and its last outcome — enough to answer “did last night's backup run?”. Scope scheduled-commands:read.

Reading a schedule does not let you trigger it

The command text is returned — a schedule you cannot read is not one you can audit — and it grants nothing regardless: no token can execute anything. A run must be signed in a browser with your vault key, which the API never holds.

Notes

Responses never include SSH credentials or encrypted payloads.
To read the command history of a server, see the Commands API.
A 403 means your token is missing the servers:read scope; a 404 means the server id doesn't exist or isn't in your team. See errors.

Servers API

What you get back

Example

Fleet sections

Server metrics

Scheduled commands on a server

Notes

See also