API Version 2

Overview

API Version 2 is the modern replacement for Version 1. It utilizes OAuth2 (JWT) for authentication and provides “high-signal” endpoints designed to handle environments with thousands of monitors efficiently.

Interactive documentation (Swagger UI) is available at: https://api.knowledgefront.com/v2/docs

Authentication (OAuth2)

Version 2 uses the OAuth2 Client Credentials grant type. Instead of providing your username and password for every request, you use a client_id and client_secret to obtain a JSON Web Token (JWT).

1. Creating an OAuth Client

To use API v2, you must first create an OAuth client in the Knowledge Front web interface.

Navigate to Account > API Settings (Placeholder for real path).
Click Create New API Client.
Provide a label for your client (e.g., “Grafana Integration”).
Copy your Client ID and Client Secret.

Important: The client_secret is only shown once. Store it securely.

Create OAuth Client Placeholder

2. Obtaining an Access Token

Use your credentials to request an access token from the token endpoint. Standard OAuth2 client authentication is supported via HTTP Basic Auth.

Endpoint: POST /v2/token

Sample Request (cURL):

curl -X POST https://api.knowledgefront.com/v2/token \
     -u "your-client-id:your-client-secret" \
     -d "grant_type=client_credentials"

Sample Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Using the Token

Once you have an access_token, include it in the Authorization header of your subsequent API requests.

curl -H "Authorization: Bearer <your-access-token>" 
     https://api.knowledgefront.com/v2/status

Status Monitoring (High-Signal)

The v2 Status endpoint is designed for large-scale environments. By default, it follows a “high-signal” philosophy: it only returns monitors that currently have an active alert.

Get Alert Status Summary

URL: GET /v2/status

Description: Returns a summary of active alerts for your account.

Query Parameters:

Parameter	Type	Description
`all`	boolean	If `true`, returns all active monitors regardless of their alert status.

Sample Response (Healthy)

{
  "global_alert_active": false,
  "monitors": []
}

Sample Response (Alert Active)

{
  "global_alert_active": true,
  "monitors": [
    {
      "id": "7c69ea44af255acddd821b",
      "label": "Primary SMTP MX",
      "type": "smtp",
      "alert_active": true
    }
  ]
}

System Endpoints

API Version

URL: GET /v2/version Public: No (Requires Auth) Description: Returns the major/minor version and release date of the current API instance.

Integration Example (Python)

The following example demonstrates how to handle the OAuth2 handshake and make an authenticated request.

import time
import requests

class KFv2Client:
    def __init__(self, client_id, client_secret, base_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url.rstrip('/')
        self._token = None
        self._expires_at = 0

    def _get_token(self):
        if self._token and time.time() < self._expires_at - 60:
            return self._token
        
        # Standard OAuth2: Basic Auth for credentials, form-encoded grant_type
        resp = requests.post(
            f"{self.base_url}/v2/token", 
            data={"grant_type": "client_credentials"},
            auth=(self.client_id, self.client_secret)
        )
        resp.raise_for_status()
        data = resp.json()
        self._token = data["access_token"]
        self._expires_at = time.time() + data.get("expires_in", 3600)
        return self._token

    def get_status(self, all_monitors=False):
        headers = {"Authorization": f"Bearer {self._get_token()}"}
        params = {"all": "true"} if all_monitors else {}
        resp = requests.get(f"{self.base_url}/v2/status", headers=headers, params=params)
        resp.raise_for_status()
        return resp.json()

# Usage
client = KFv2Client("your-id", "your-secret", "https://api.knowledgefront.com")
status = client.get_status()
if status['global_alert_active']:
    print(f"Alerts active on {len(status['monitors'])} monitors!")
else:
    print("All systems operational.")