Skip to main content

Loop API integration

A loop is two POSTs you call from an application or an internal portal. /predict/ returns a value. /train/ is how the model updates, after you know the outcome. A predict call does not update the model.

Create the loop in the app first. Data Intelligence → Loop. The id in /loop/{id} is x-loop-id.

Base URL: https://loop.heimdallapp.org

Headers​

Predict and train both require:

HeaderValue
X-api-keyKey from the loop page. Shown once.
X-usernameYour Heimdall username.
x-loop-idThe id in /loop/{id}.

Missing x-loop-id returns 400.

Predict​

POST /predict/

data is one object, or a list of objects. Each object has every input field and does not include the output field.

{
  "data": {
    "age": 25,
    "subscription_months": 12
  }
}
{
  "status": "success",
  "message": "Successfully predicted 1 sample(s)",
  "predictions": [
    {
      "churn_probability": 0.2,
      "explanation": {
        "top_contributors": []
      }
    }
  ],
  "failed_samples": 0,
  "errors": []
}

The prediction object uses the output field name from the loop schema. explanation.top_contributors lists up to ten feature contributions. If the model cannot explain the row, explanation.message says so. A mix of good and bad rows returns status partial_success.

Train​

POST /train/

data is one object, or a list. Each object has every input field and the output field, with the value you observed.

{
  "data": {
    "age": 25,
    "subscription_months": 12,
    "churn_probability": 0
  }
}
{
  "status": "success",
  "message": "Successfully trained 1 sample(s)",
  "trained_samples": 1,
  "failed_samples": 0,
  "errors": []
}

Rows that fail validation are counted in failed_samples. The messages are in errors.

Next​