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.
• 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

{
  "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."
}

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 }
  ]
}