Inbound API

POST JSON to your project endpoint and TotalKPI captures it as a data source. No polling required - your backend pushes data whenever it has something new.

Endpoint

POST /api/inbound/YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with a key from Settings → Security. Each key is scoped to your project.

Payload format

Any flat or nested JSON object works. Include a timestamp field (ISO 8601) to record when each data point occurred - otherwise the server's receive time is used.

{ "cpu_usage": 72.4, "timestamp": "2025-01-15T10:00:00Z" }

Send multiple fields in one payload to track them all from the same request:

{
  "cpu_usage": 72.4,
  "memory_usage": 85.1,
  "disk_usage": 43.0,
  "timestamp": "2025-01-15T10:00:00Z"
}

Nested objects are supported - you'll select the exact path when mapping:

{
  "server": "web-01",
  "metrics": { "cpu_usage": 72.4, "memory_usage": 85.1 },
  "timestamp": "2025-01-15T10:00:00Z"
}

To send multiple data points in one request, use an array:

[
  { "cpu_usage": 72.4, "timestamp": "2025-01-15T10:00:00Z" },
  { "cpu_usage": 68.1, "timestamp": "2025-01-15T11:00:00Z" }
]

Code examples

curl -X POST https://totalkpi.com/api/inbound/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"cpu_usage": 72.4, "memory_usage": 85.1, "timestamp": "2025-01-15T10:00:00Z"}'

await fetch("https://totalkpi.com/api/inbound/YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    cpu_usage: 72.4,
    memory_usage: 85.1,
    timestamp: "2025-01-15T10:00:00Z"
  })
});

import requests

requests.post("https://totalkpi.com/api/inbound/YOUR_API_KEY", json={
    "cpu_usage": 72.4,
    "memory_usage": 85.1,
    "timestamp": "2025-01-15T10:00:00Z"
})

file_get_contents("https://totalkpi.com/api/inbound/YOUR_API_KEY", false,
  stream_context_create([
    "http" => [
      "method" => "POST",
      "header" => "Content-Type: application/json",
      "content" => json_encode([
        "cpu_usage" => 72.4,
        "memory_usage" => 85.1,
        "timestamp" => "2025-01-15T10:00:00Z"
      ])
    ]
  ])
);

Mapping payloads to data sources

The first time your endpoint receives a new payload structure, it appears in Settings → Inbound under Unmapped Payloads. Click it to open the mapping modal:

1. Pick which numeric field(s) to track.
2. Set a name, unit, and target page for each field.
3. Save - a template is created for this payload structure.

Every subsequent payload with the same structure is processed automatically using that template.

Templates

Templates are listed in Settings → Inbound → Saved Payload Templates. You can:

• Pause a template to stop storing new data without deleting it.
• Add paths to an existing template by clicking "View payload" and selecting an unmapped field.
• Delete a template, optionally deleting the linked data source too.