One endpoint, one JSON contract,
one header.

1. Provisioning

Every node needs a device token before it can send data. KINGSHIP issues one per node: request credentials for your integration and we'll provision it. The token is bound to a single nodeId; a payload claiming a different node is rejected with 403.

2. Connectivity check

GET /api/v1/ingest/ping        (no auth)
→ { "ok": true, "serverTime": "2026-08-23T10:15:00.000Z" }

Use during bring-up and after SIM failover to confirm the data path before flushing buffered readings.

3. Telemetry

POST /api/v1/ingest
Content-Type: application/json
X-Device-Token: <deviceToken>

{
  "nodeId": "KS-KLA-0001",
  "firmwareVersion": "1.5.0",
  "network": { "activeSlot": 1, "operator": "MTN-UG", "rssiDbm": -71 },
  "readings": [
    {
      "ts": "2026-08-23T10:15:00Z",
      "tanks": [
        {
          "tank": 1,
          "volumeLiters": 8214.5,
          "fuelHeightMm": 1971.5,
          "waterHeightMm": 4.0,
          "temperatureCelsius": 26.4
        }
      ],
      "dispensers": [
        { "dispenser": 1, "totalizerPulses": 894210, "flowRateLpm": 34.2 }
      ],
      "generator": { "running": false, "runtimeHours": 1204.5 }
    }
  ]
}

Response (200):

{ "ok": true, "nodeId": "KS-KLA-0001", "accepted": 1, "rejected": 0, "serverTime": "…" }

Unknown fields are stripped, out-of-range values fail validation with a 400 and per-field messages. A reading with an unparseable or out-of-window timestamp is skipped and counted in rejected: the rest of the batch still lands.

Cadence: one reading every 60 seconds, one readings entry per POST in normal operation.

4. Offline buffering & backfill

When connectivity is down, keep sampling and store readings locally. On reconnect: ping to confirm the path, flush the buffer oldest-first (up to 500 per POST) with each entry carrying its original ts and "buffered": true, and only erase locally after a 200 with a matching accepted count.

Retry rule: treat only HTTP 200 as delivered. On 5xx/timeout, keep the data and retry with exponential backoff. On 400/401/403, don't retry the same payload in a loop: flag a configuration fault.

5. Heartbeat & offline alerts

The 60-second POST is the heartbeat. If the server hears nothing for the configured window (5 minutes by default), the node is flagged offline and a critical alert is raised on the dashboard: reconnection raises the matching online alert automatically.

6. Transport notes

• HTTPS only in production: standard TLS 1.2+ (OpenSSL via curl / requests / axios, etc.)
• Keep JSON compact; a single-tank reading is ~250 bytes, ~11 MB/month at 60 s cadence
• Set Content-Length correctly; chunked encoding is not required
• On modem/SIM failover, re-run the ping check before resuming POSTs