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 edge-agent API key that holds the agent scope (see API Keys and the Edge Agent overview). A key without that scope gets 403.

Heartbeat​

GET /api/v1/agent/heartbeat

Returns 200 while your company's account is active. The success body tells the agent when to check in again (every 5 minutes) and whether an update is available:

{
  "status": "active",
  "next_check_seconds": 300,
  "latest_agent_version": "0.5.0",
  "min_supported_version": "0.1.0",
  "update_available": false,
  "unsupported": false
}

While your company's account is suspended, it returns 402 Payment Required instead, telling the agent to pause and check again later:

{
  "detail": {
    "error_code": "TENANT_SUSPENDED",
    "message": "This company account has been suspended. Contact your administrator for help.",
    "next_check_seconds": 3600
  }
}

Heartbeat with telemetry​

POST /api/v1/agent/heartbeat

Posts a telemetry snapshot with the heartbeat. Same authentication and 200/402 behavior as the GET; update_available and unsupported are worked out from the agent_version you send. The agent shows up in the fleet view for 15 minutes after its last heartbeat.

{
  "agent_id": "edge-plant-1-abc123",
  "agent_version": "0.5.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": "0.5.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
}