API Version 2
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
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).
To use API v2, you must first create an OAuth client in the Knowledge Front web interface.
- Navigate to Account Name > API Access
- 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_secretis only shown once. Store it securely.
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
}
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
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.
URL: GET /v2/status
Description: Returns a summary of active alerts and metrics for your account.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
all |
boolean | If true, returns all active monitors regardless of their alert status. |
t |
integer | Time window in seconds (default 1800, max 10800). |
{
"error": null,
"monitor_list": [
{
"alert_active": true,
"alert_count": 1,
"fail_count": 6,
"label": "Primary SMTP MX",
"last_alert": {
"alert": "15470f5c668d11b72c69d595e7fe296fa270c7e93b7f5404282d1dfd",
"monitor": "4cb141d5d6f3aa8d56d43b89480317cbb985849bd53cae637e5619dc",
"time": "2026-05-31T13:51:18",
"utc_time": "2026-05-31T18:51:18"
},
"last_failed": {
"error": "failure on finalizing body delivery",
"flag": false,
"time_init": "2026-05-31T13:51:18",
"utc_mktime": 1780254018,
"utc_time_init": "2026-05-31T18:51:18"
},
"last_test": {
"error": "failure on finalizing body delivery",
"flag": false,
"time_init": "2026-05-31T13:51:18",
"utc_mktime": 1780254018,
"utc_time_init": "2026-05-31T18:51:18"
},
"monitor": "4cb141d5d6f3aa8d56d43b89480317cbb985849bd53cae637e5619dc",
"test_count": 6
}
],
"path": "/status",
"t": 1800
}
Configuration retrieval endpoints allow you to read active monitor
configurations. Type-specific fields are nested inside a first-class
config object, and sensitive fields like password and
client_secret are automatically redacted.
URL: GET /v2/config/monitor
Public: No (Requires Auth)
Description: Returns a list of all active monitor configurations.
{
"monitor_list": [
{
"id": "mon1",
"label": "Primary HTTP Monitor",
"description": "Monitors the main public website homepage",
"type": "http",
"timer": 300,
"time_zone": "America/Chicago",
"active": true,
"config": {
"url": "https://example.com",
"password": "********"
}
}
],
"path": "/config/monitor"
}
URL: GET /v2/config/monitor/{id}
Public: No (Requires Auth)
Description: Returns the configuration of a single active monitor.
{
"monitor": {
"id": "mon1",
"label": "Primary HTTP Monitor",
"description": "Monitors the main public website homepage",
"type": "http",
"timer": 300,
"time_zone": "America/Chicago",
"active": true,
"config": {
"url": "https://example.com",
"password": "********"
}
},
"path": "/config/monitor/mon1"
}
URL: GET /v2/version
Public: No (Requires Auth)
Description: Returns the major/minor version and release date of the current API instance.
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()
active_alerts = [m for m in status.get("monitor_list", []) if m.get("alert_active")]
if active_alerts:
print(f"Alerts active on {len(active_alerts)} monitors!")
else:
print("All systems operational.")