Skip to main content

ML API integration

A trained model is one POST. Send one row of feature columns and leave the target out. Put prediction in an application, a website, a data pipeline, or an internal portal. The API Integration tab fills in the column names.

POST https://predict.heimdallapp.org/predict/

Headers​

HeaderValue
X-api-keyKey from the model page. Shown once.
X-usernameYour Heimdall username, the same value in the sample on that page.
x-model-idThe id in /ml/{id}.

A missing or wrong username, model id, or key returns 404 with detail set to Invalid Username, Invalid Model ID, or Invalid API Key.

Body​

features.features is one object. Keys are feature column names. Values are numbers, or strings for categorical columns. Do not send the target column.

{
  "features": {
    "features": {
      "rooms": 3,
      "age": 42
    }
  }
}

Replace rooms and age with the columns from your model. The sample on the model page already does this.

Response​

Classification:

{
  "prediction": "setosa",
  "confidence": 0.91
}

confidence is present when the model exposes class probabilities. Regression returns prediction only, as a string of the number.

import requests

response = requests.post(
    "https://predict.heimdallapp.org/predict/",
    headers={
        "X-api-key": "YOUR-API-KEY",
        "X-username": "YOUR-USERNAME",
        "x-model-id": "YOUR-MODEL-ID",
    },
    json={"features": {"features": {"rooms": 3, "age": 42}}},
)
print(response.json()["prediction"])

Replace rooms and age with the columns from your model. The key is on the model page, shown once. x-model-id is the id in /ml/{id}.

Batch​

POST https://predict.heimdallapp.org/predict/batch/ with the same three headers and a CSV or Excel file in the file field. The file uses the same columns as a single call, including a header row.

{
  "status": "success",
  "total_records": 2,
  "processed_records": 2,
  "failed_records": 0,
  "predictions": [
    {
      "row_index": 0,
      "prediction": "setosa",
      "confidence": 0.91,
      "status": "success",
      "error": null
    }
  ],
  "summary": {
    "model_type": "logistic",
    "processing_time_seconds": 0.4,
    "threshold_used": 0.2
  }
}

Next​