Docs / HTTP API

HTTP API

Base URL https://api.srvpulse.net/v1. Bearer tokens, JSON in and out.

Authentication

curl https://api.srvpulse.net/v1/hosts \
  -H "Authorization: Bearer spt_live_4Kd91x..."

Tokens are workspace-scoped with roles read, write or admin. 600 requests per minute; X-RateLimit-Remaining is authoritative.

Endpoints

Method	Path	Description
GET	/hosts	Hosts with agent version and last seen
GET	/hosts/{id}/metrics	Time series for a window
GET	/collectors	Collectors, region, upstream state
GET	/checks	List probes
POST	/checks	Create a probe
PATCH	/checks/{id}	Update interval or expectations
GET	/alerts	Open and recent alerts
POST	/exports	Request a bulk export job

Read metrics

GET /v1/hosts/h_8831/metrics?metric=cpu.busy&from=2026-10-18T00:00:00Z&step=60s

{
  "host": "h_8831",
  "metric": "cpu.busy",
  "unit": "percent",
  "points": [
    { "t": "2026-10-18T00:00:00Z", "v": 11.4 },
    { "t": "2026-10-18T00:01:00Z", "v": 13.9 }
  ]
}

Collector state

GET /v1/collectors

{
  "collectors": [
    { "id": "col_ruc1", "region": "ru-central", "upstream": "eu-west",
      "agents": 212, "spool_bytes": 0, "state": "connected" },
    { "id": "col_euw1", "region": "eu-west", "upstream": null,
      "agents": 0, "state": "aggregation" }
  ]
}

Errors

Code	Error	Meaning
400	invalid_window	Range longer than retention
402	quota_exceeded	Host limit reached
403	not_agent_facing	Endpoint accepts collectors only
409	duplicate_id	Check ID already in use
429	rate_limited	Retry after `Retry-After`