API Documentation

Integrate AlertG with your devices and systems.

Authentication

Include your API key in the X-API-Key header with every request.

HTTP Header

X-API-Key: your_api_key_here

Create API keys from the API Keys page in your dashboard. Each key can be scoped to ingest-only, read-only, or read-write permissions.

Webhook Integration

Send device telemetry data via HTTP POST.

POST/api/ingest

Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

JSON

{
  "device_id": "dev_abc123",
  "payload": {
    "temperature": 82.5,
    "humidity": 45,
    "pressure": 1013.25,
    "battery": 87,
    "status": "normal"
  }
}

Response

JSON

{
  "ok": true,
  "device_id": "dev_abc123",
  "alerts_fired": 1,
  "timestamp": "2026-02-24T10:30:00Z"
}

MQTT Integration

Connect your MQTT broker to AlertG.

Topic Format

MQTT Topic

alertgate/{user_id}/{device_id}/data

Connection Details

Broker: mqtt.alertg.xyz
Port: 8883 (TLS) / 1883 (plain)
Username: Your user ID
Password: Your API key
Protocol: MQTT v3.1.1 / v5.0

Publish JSON payloads to the topic. The payload format is the same as the webhook request body (the payload field).

Code Examples

cURL

bash

curl -X POST https://alertg.xyz/api/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "device_id": "sensor-01",
    "payload": {
      "temperature": 82.5,
      "humidity": 45
    }
  }'

Python

python

import requests

response = requests.post(
    "https://alertg.xyz/api/ingest",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "device_id": "sensor-01",
        "payload": {
            "temperature": 82.5,
            "humidity": 45,
        },
    },
)

print(response.json())

Node.js

javascript

const response = await fetch("https://alertg.xyz/api/ingest", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    device_id: "sensor-01",
    payload: {
      temperature: 82.5,
      humidity: 45,
    },
  }),
});

const data = await response.json();
console.log(data);

Arduino / ESP32

cpp

#include <WiFi.h>
#include <HTTPClient.h>

void sendData(float temperature, float humidity) {
  HTTPClient http;
  http.begin("https://alertg.xyz/api/ingest");
  http.addHeader("Content-Type", "application/json");
  http.addHeader("X-API-Key", "YOUR_API_KEY");

  String payload = "{\"device_id\":\"esp32-01\",";
  payload += "\"payload\":{\"temperature\":" + String(temperature);
  payload += ",\"humidity\":" + String(humidity) + "}}";

  int code = http.POST(payload);
  if (code > 0) {
    Serial.println(http.getString());
  }
  http.end();
}

Raspberry Pi (Python)

python

import requests
import Adafruit_DHT

sensor = Adafruit_DHT.DHT22
pin = 4

humidity, temperature = Adafruit_DHT.read_retry(sensor, pin)

if temperature is not None:
    requests.post(
        "https://alertg.xyz/api/ingest",
        headers={
            "X-API-Key": "YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        json={
            "device_id": "rpi-dht22",
            "payload": {
                "temperature": round(temperature, 1),
                "humidity": round(humidity, 1),
            },
        },
    )

Rate Limits

API requests are rate-limited based on your plan.

Plan	Ingest (req/min)	API (req/min)
Free	60	30
Hobby	300	120
Pro	1,000	600
Business	5,000	3,000
Enterprise	Custom	Custom

Error Codes

400Bad Request - Invalid payload or parameters.

401Unauthorized - Missing or invalid API key.

403Forbidden - Insufficient permissions.

404Not Found - Resource does not exist.

429Too Many Requests - Rate limit exceeded.

500Internal Server Error - Please try again later.