Predictions

Retrieve machine health scores, estimated time to maintenance or failure, and anomaly summaries. All endpoints are authenticated with a Bearer JWT (see Authentication).

Endpoints

Method	Path	Description
GET	/api/v1/machines/predictions/fleet	Health predictions for every machine
GET	/api/v1/machines/{machine_id}/prediction	Health prediction for one machine
GET	/api/v1/machines/{machine_id}/prediction/narrative	Plain-language summary of a machine's prediction
GET	/api/v1/machines/{machine_id}/prediction/history	Health-score history for a machine
GET	/api/v1/machines/{machine_id}/anomalies/summary	Anomaly summary for a machine

Fleet predictions

GET /api/v1/machines/predictions/fleet

{
  "predictions": [
    {
      "machine_id": "...",
      "machine_name": "CNC Mill #1",
      "health_score": 82,
      "risk_level": "watch",
      "days_to_maintenance": 21,
      "contributing_factors": ["Rising vibration on X-axis", "Elevated spindle temperature"],
      "ai_narrative": null,
      "last_analyzed_at": "2026-08-05T10:30:00Z",
      "estimated_days_to_failure": 45,
      "degradation_rate_per_day": 0.4
    }
  ],
  "total": 1
}

• health_score ranges from 0 to 100. It blends the machine's alerts over the last 7 and 30 days with the share of its readings that were anomalous over the last 7 days (5% or more scores worst), so a machine that reports often is judged by its rate of anomalies, not their number.
• risk_level is one of healthy, watch, warning, or critical.
• days_to_maintenance and estimated_days_to_failure are null when none is predicted.

Machine prediction

GET /api/v1/machines/{machine_id}/prediction

Parameter	Type	Default	Description
language	string	en	Language for text fields

Returns a single MachinePrediction object with the same fields shown above.

Prediction narrative

GET /api/v1/machines/{machine_id}/prediction/narrative

Returns only the generated plain-language narrative, so scores can be displayed immediately while the narrative is produced separately.

Parameter	Type	Default	Description
language	string	en	Language for the narrative
refresh	boolean	false	Write a new narrative instead of returning the one kept for this situation

{
  "machine_id": "...",
  "ai_narrative": "CNC Mill #1 shows early signs of bearing wear. Vibration has trended up over the past two weeks; plan a bearing inspection within the next 30–45 days."
}

A narrative is generated only for machines at warning or critical risk; for any other machine ai_narrative is null. It is also null when the AI provider cannot be reached.

Generated narratives are kept on the server for up to 24 hours under the situation they describe: the machine, the language, and the risk level, health score, days to maintenance and contributing factors. A request for the same situation returns the kept narrative without calling the AI again. When any of those change, the next request writes a new one. Pass refresh=true to write a new one anyway.

This endpoint counts against a small additional per-account rate limit (see Rate Limiting).

Prediction history

GET /api/v1/machines/{machine_id}/prediction/history

Parameter	Type	Default	Range	Description
days	int	30	1–365	Lookback window

{
  "machine_id": "...",
  "points": [
    { "health_score": 88, "risk_level": "healthy", "recorded_at": "2026-07-06T00:00:00Z" },
    { "health_score": 82, "risk_level": "watch", "recorded_at": "2026-08-05T00:00:00Z" }
  ]
}

Anomaly summary

GET /api/v1/machines/{machine_id}/anomalies/summary

Summarizes anomaly events for the machine over the recent window, broken down by metric.

{
  "machine_id": "...",
  "total_anomaly_events": 15,
  "metrics": [
    {
      "metric_name": "vibration",
      "total_events": 12,
      "latest_sigma": 3.8,
      "latest_at": "2026-08-05T09:15:00Z"
    }
  ],
  "baseline_drift": [
    { "metric_name": "temperature", "baseline_mean": 68.0, "current_mean": 72.5, "drift_sigma": 2.1 }
  ]
}