API Integration Guide

Make real-time predictions with your deployed machine learning models using our REST API.

Overview

Once your model is trained and deployed, you can make real-time predictions using our API endpoint. This allows you to integrate machine learning predictions directly into your applications, websites, or data pipelines.

API Endpoint

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

Request Headers

• x-api-key - API key that is issued when the endpoint is configured
• x-username - Username associated with your account
• x-model-id - Unique identifier associated with the model

Getting Your Credentials

Follow the steps in our Deployment guide to:

1. Save your model to your Model Inventory
2. Navigate to your model page
3. Generate your API key at the top of the model page
4. Find your Model ID in the API Integration tab

Request Body

• features - Nested dictionary of features. The keys are the names of the columns or features from your data and the values are the new values for those columns.

tip

Below is a high-level structure of the nested features dictionary features : { features : { {name: value}}}

Response Object

The response structure depends on your model type:

Classification Models

{
  "prediction": "spam",
  "confidence": 0.95
}

Regression Models

{
  "prediction": 125000.50
}

Real Estate Data Example

Let's walk through the real estate dataset from our Modeling guide and see how each row would look when making API calls:

MSSubClass	MSZoning	LotFrontage	LotArea	Street	SalePrice
60	RL	65	8450	Pave	181500
60	RL	68	11250	Pave	223500
60	RL	70	9550	Pave	140000

API Request for Row 1

{
  "features": {
    "features": {
      "MSSubClass": 60,
      "MSZoning": "RL",
      "LotFrontage": 65,
      "LotArea": 8450,
      "Street": "Pave"
    }
  }
}

API Request for Row 2

{
  "features": {
    "features": {
      "MSSubClass": 60,
      "MSZoning": "RL",
      "LotFrontage": 68,
      "LotArea": 11250,
      "Street": "Pave"
    }
  }
}

API Request for Row 3

{
  "features": {
    "features": {
      "MSSubClass": 60,
      "MSZoning": "RL",
      "LotFrontage": 70,
      "LotArea": 9550,
      "Street": "Pave"
    }
  }
}

Sample Request

Here's a complete example using the first row of data:

import requests

url = 'https://predict.heimdallapp.org/predict/'
headers = {
    'X-api-key': 'YOUR-API-KEY',
    'X-username': 'YOUR-USERNAME',
    'x-model-id': 'YOUR-MODEL-ID'
}

# Sample features for a real estate price prediction model
data = {
    "features": {
        "features": {
            "MSSubClass": 60,
            "MSZoning": "RL",
            "LotFrontage": 65,
            "LotArea": 8450,
            "Street": "Pave"
        }
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    prediction = result['prediction']
    
    # Check if it's a classification model (has confidence)
    if 'confidence' in result:
        print(f"Prediction: {prediction} (Confidence: {result['confidence']:.2%})")
    else:
        print(f"Predicted Sale Price: ${prediction:,.2f}")
else:
    print(f"Error: {response.status_code}")

Understanding the Response

Classification Models

When you have a classification model (predicting categories like "spam" vs "not spam"), the response includes:

• prediction: The predicted class (e.g., "spam", "not spam")
• confidence: A score between 0 and 1 indicating how confident the model is in its prediction

The confidence score helps you understand the reliability of the prediction. A confidence of 0.95 means the model is 95% confident in its prediction.

Regression Models

When you have a regression model (predicting numerical values like house prices), the response includes:

• prediction: The predicted numerical value (e.g., $181,500)

Regression models don't include confidence scores because they predict continuous numerical values rather than discrete categories.

Real Estate Data Example

In the context of our real estate example, the model has learned patterns from historical property sales data. When you send a request with features like:

• MSSubClass (60): Building class type
• MSZoning ("RL"): Residential Low density zoning
• LotFrontage (65): 65 feet of street frontage
• LotArea (8450): 8,450 square foot lot
• Street ("Pave"): Paved road access

The model analyzes these features and predicts a sale price based on similar properties it has seen during training. For example, it might recognize that:

• Properties with larger lot areas tend to sell for more
• Paved street access increases value
• Certain zoning types correlate with higher prices

The model essentially finds the best combination of these factors to predict what a property with these characteristics would likely sell for in the current market.

Error Handling

Common Error Codes

• 400 Bad Request - Invalid request format
• 401 Unauthorized - Invalid API key or username
• 422 Unprocessable Entity - Invalid request body structure
• 500 Internal Server Error - Server-side error

Best Practices

• Always check response status codes
• Implement retry logic for transient errors
• Cache API keys securely
• Monitor API usage and rate limits