Skip to main content

Fleet

Get a fleet-wide view of machine status, roll up KPIs by site, and manage edge-agent heartbeats. Unless noted, endpoints are authenticated with a Bearer JWT (see Authentication); the agent heartbeat endpoints use an API key.

Endpoints​

MethodPathDescription
GET/api/v1/fleet/statusStatus of every active machine in your fleet
GET/api/v1/fleet/sitesList sites with rolled-up KPIs
GET/api/v1/fleet/sites/comparisonCross-site KPI comparison
GET/api/v1/fleet/sites/{site_id}/kpisDetailed KPI rollup for one site
GET/api/v1/agent/heartbeatEdge-agent heartbeat (API key)
POST/api/v1/agent/heartbeatEdge-agent heartbeat with telemetry (API key)
GET/api/v1/agent/fleetStatus of your reporting edge agents (Admin)

Endpoints marked Admin require an account administrator role.

Fleet status​

GET /api/v1/fleet/status

Returns each active machine with its status, count of unacknowledged alerts, and most recent reading time.

curl https://api.haltless.io/api/v1/fleet/status \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "total_machines": 45,
  "machines": [
    {
      "machine_id": "...",
      "machine_name": "CNC Mill #1",
      "machine_identifier": "CNC-001",
      "status": "healthy",
      "active_alert_count": 0,
      "last_reading_at": "2026-08-05T10:30:00Z"
    }
  ]
}

Sites​

A site groups machines so KPIs can be rolled up per location.

List sites​

GET /api/v1/fleet/sites

Returns each site with its aggregated KPIs.

Cross-site comparison​

GET /api/v1/fleet/sites/comparison

Returns a comparison table of key KPIs across all sites in one response.

Site detail​

GET /api/v1/fleet/sites/{site_id}/kpis

Returns the detailed KPI rollup for a single site. Responds 404 if the site does not exist.

Edge-agent heartbeat​

The edge agent calls these endpoints with an API key (see API Keys and the Edge Agent overview).

Heartbeat​

GET /api/v1/agent/heartbeat

Returns 200 while the account's subscription is active, or 402 when payment is required. The success body tells the agent when to check in again and whether an update is available.

{
  "status": "active",
  "next_check_seconds": 3600,
  "latest_agent_version": "1.4.0",
  "min_supported_version": "1.0.0",
  "update_available": false,
  "unsupported": false
}

Heartbeat with telemetry​

POST /api/v1/agent/heartbeat

Posts a telemetry snapshot with the heartbeat. Same authentication and 200/402 behavior as the GET.

{
  "agent_id": "edge-plant-1-abc123",
  "agent_version": "1.4.0",
  "uptime_seconds": 86400,
  "buffer_count": 0,
  "buffer_age_hours": 0.0,
  "collectors": { "modbus-line-1": "ok", "opcua-line-2": "ok" },
  "hostname": "edge-plant-1"
}

Agent fleet view​

GET /api/v1/agent/fleet

Lists your currently reporting edge agents. Requires an account administrator role.

{
  "agents": [
    {
      "agent_id": "edge-plant-1-abc123",
      "agent_version": "1.4.0",
      "hostname": "edge-plant-1",
      "uptime_seconds": 86400,
      "buffer_count": 0,
      "buffer_age_hours": 0.0,
      "collectors": { "modbus-line-1": "ok" },
      "last_seen": "2026-08-05T10:30:00Z",
      "online": true,
      "update_available": false,
      "unsupported": false
    }
  ],
  "total": 1
}