Docs · telemetry integration

Telemetry integration — wire your aircraft or alert source to the Volgarde agent plane.

Three copy-ready payloads cover your integrations: the full aircraft telemetry shape, the Volgarde alert shape, and the back-compat radar envelope. All three are versioned, pinned at the integrator side, and feed the same agent reasoning pipeline that delivers the alert webhooks documented on /docs/api.

Payload formats

Every payload is delivered as UTF-8 JSON, encoded in snake_case at depth 2. Timestamps are ISO 8601 UTC (Z suffix), positions are WGS84 (lat/lon in decimal degrees), physical units are explicit in the unit key. Integrators MUST pin the contract version; Volgarde rejects a payload at an unpinned major.

Aircraft telemetry (POST /v1/telemetry/ingest)

Covers callsign + ICAO hex, position lat/lon, altitude, EGT/N1 engine parameters and an ISO8601 timestamp — the minimum envelope accepted by POST /v1/telemetry/ingest.

Sample aircraft telemetry payload

application/json

{
  "contract": {
    "name": "fleet.telemetry",
    "version": "1.5.0"
  },
  "aircraft": {
    "callsign": "TVF81LP",
    "hex_icao": "394C9F",
    "fleet_id": "af-klm-long-haul",
    "aircraft_family": "A350-900"
  },
  "position": {
    "lat": 43.4393,
    "lon": 5.2214,
    "altitude_ft": 36000
  },
  "engine": {
    "egt_c": 482.7,
    "n1_pct": 71.4,
    "n2_pct": 84.2,
    "fuel_flow_kgps": 0.93
  },
  "timestamp": "2026-08-19T14:02:11.422Z",
  "source": "acars"
}

Volgarde alert (POST /v1/alerts/webhook)

Severity low/medium/high, a catalogued Volgarde anomaly_type, aircraft_id, recommended_action, and confidence ∈ [0, 1] — this is the envelope accepted by POST /v1/alerts/webhook.

Sample Volgarde alert payload

application/json

{
  "contract": {
    "name": "fleet.alert",
    "version": "1.2.0"
  },
  "severity": "high",
  "anomaly_type": "engine.egt.excursion",
  "aircraft_id": "394C9F",
  "recommended_action": "ground_EGT_check_within_24h",
  "confidence": 0.86,
  "occurred_at": "2026-08-19T14:02:11.422Z",
  "context": {
    "tail": "F-HNAV",
    "fleet_id": "af-klm-long-haul",
    "source": "acars"
  }
}

Radar envelope (back-compat)

Keeps the historical radar envelope (station, sweep window, ADS-B / Mode-S / SSR plots) for in-place integrators — equivalent to the legacy /v1/ingest/radar/stream surface.

Sample radar envelope

application/json

{
  "contract": {
    "name": "radar",
    "version": "1.2.0"
  },
  "station": {
    "id": "LFML-SSR-01",
    "site": "Marseille-Marignane",
    "kind": "ssr-mode-s"
  },
  "window": {
    "from": "2026-08-19T14:00:00.000Z",
    "to": "2026-08-19T14:01:00.000Z"
  },
  "plots": [
    {
      "at": "2026-08-19T14:00:42.118Z",
      "callsign": "TVF81LP",
      "altitude": {
        "value": 36000,
        "unit": "ft"
      },
      "groundSpeed": {
        "value": 471,
        "unit": "kt"
      },
      "lat": 43.4393,
      "lon": 5.2214
    }
  ]
}

Onboarding checklist

Step-by-step path from first contract review to a Volgarde-signed incident in production. Steps 1-3 are integrator-side; steps 4-6 are the Volgarde mission-architect handoff.

1
Pin the contract version you target (current major: fleet.telemetry=v1, fleet.alert=v1) and freeze it on your side.
2
Mint a Bearer JWT in the Volgarde console, scoped for the right audience (volgarde.api) and the required scope (fleet:read, fleet:write, alerts:write or incidents:read).
3
Post an aircraft telemetry payload to POST /v1/telemetry/ingest or an alert payload to POST /v1/alerts/webhook, then verify the 202 + request_id returned.
4
Pair with a Volgarde mission architect to confirm the alert-webhook endpoint and the HMAC verification path.
5
Run the first alert end-to-end (a synthetic anomaly) and capture the Volgarde-Event-Id + signature on your side.
6
Promote to production: enable dual-active token rotation and the alert.fired / alert.escalated handler.

Versioning and pinning

Contracts follow semver at the envelope level. Volgarde accepts the integrator's pinned major and the next higher minor; raises beyond that require a contract migration. The integrator console exposes a deprecation timeline 90 days ahead of a major bump, and a structured migration note lands in the same payload channel used for alert webhooks.