Predictions

Machine learning-powered drift predictions, pattern analysis, and risk insights.

Base path: /api/predictions

Authentication: Bearer token required on all routes

Get High-Risk Predictions

GET /api/predictions/high-risk

Get predictions flagged as high risk across all repositories.

Response

{
  "success": true,
  "data": [
    {
      "_id": "pred1",
      "resourceType": "aws_iam_role",
      "resourceAddress": "module.auth.aws_iam_role.admin",
      "riskScore": 0.92,
      "predictedDriftType": "policy_change",
      "confidence": 0.87,
      "repositoryConfig": "abc123"
    }
  ]
}

Example

curl -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/predictions/high-risk

Get All Predictions

GET /api/predictions/all

Get all predictions (not just high-risk) for debugging and analysis.

Get ML Insights

GET /api/predictions/insights

Get ML insights for the dashboard including enhanced metrics, anomaly detection, and top risk factors.

Response

{
  "success": true,
  "data": {
    "totalPredictions": 45,
    "highRiskCount": 8,
    "avgConfidence": 0.82,
    "topRiskFactors": [
      { "factor": "manual_iam_changes", "frequency": 12 },
      { "factor": "security_group_edits", "frequency": 8 }
    ],
    "anomalies": [...]
  }
}

Get Learned Patterns

GET /api/predictions/patterns

Get drift patterns learned by the ML model from historical data.

Response

{
  "success": true,
  "data": [
    {
      "pattern": "iam_policy_drift_after_deploy",
      "frequency": 23,
      "avgSeverity": "high",
      "resources": ["aws_iam_role", "aws_iam_policy"]
    }
  ]
}

Get User Model Info

GET /api/predictions/model

Get information about the user's personalized ML model.

Get ML Dashboard

GET /api/predictions/ml-dashboard

Get comprehensive ML dashboard data (predictions, insights, model performance).

Get Metrics

GET /api/predictions/metrics

Get prediction metrics globally.

GET /api/predictions/metrics/:repositoryConfigId

Get prediction metrics for a specific repository.

Path Parameters

Parameter	Type	Description
repositoryConfigId	string	Repository config ID

Trigger Pattern Learning

POST /api/predictions/learn

Trigger ML pattern learning from drift history. This trains the model on new drift data.

Example

curl -X POST -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/predictions/learn

List Predictions for Repository

GET /api/predictions/repository/:repositoryConfigId

List predictions for a specific repository.

Path Parameters

Parameter	Type	Description
repositoryConfigId	string	Repository config ID

Get Prediction

GET /api/predictions/:predictionId

Get details for a specific prediction.

Path Parameters

Parameter	Type	Description
predictionId	string	Prediction ID

Get Prediction Explanation

GET /api/predictions/:predictionId/explanation

Get a detailed SHAP-based explanation for why a prediction was made.

Path Parameters

Parameter	Type	Description
predictionId	string	Prediction ID

Response

{
  "success": true,
  "data": {
    "predictionId": "pred1",
    "shapValues": {
      "resource_age_days": 0.35,
      "recent_manual_changes": 0.28,
      "deploy_frequency": 0.15
    },
    "topFeatures": [
      { "feature": "resource_age_days", "impact": "high", "direction": "increases_risk" }
    ]
  }
}

Mark Prediction as Seen

POST /api/predictions/:predictionId/seen

Mark a prediction as seen/acknowledged.

Path Parameters

Parameter	Type	Description
predictionId	string	Prediction ID

Take Action on Prediction

POST /api/predictions/:predictionId/action

Record an action taken on a prediction.

Path Parameters

Parameter	Type	Description
predictionId	string	Prediction ID

Request Body

Field	Type	Required	Description
action	string	Yes	Action taken (e.g., investigate, ignore, scan)

Submit Feedback

POST /api/predictions/:predictionId/feedback

Submit feedback on prediction accuracy.

Path Parameters

Parameter	Type	Description
predictionId	string	Prediction ID

Request Body

Field	Type	Required	Description
accurate	boolean	Yes	Whether the prediction was accurate
comment	string	No	Optional feedback