Docs · API reference
API reference — the Volgarde telemetry, alerting and authentication contract.
Four endpoints, an auth matrix and an error model are now published. The surface below is locked — the documentation tracks the contract surfaced by the Volgarde routes listed on this portal.
Authentication
Every request is signed with a Bearer JWT issued from the Volgarde console. Tokens are minted per integrator, scoped to a fleet or an alert channel, and rotated without downtime via a dual-active window. Scopes follow the colon-case convention (fleet:read, alerts:write); a token without the required scope is rejected with a 403, regardless of signature validity.
Algorithm
Bearer JWT (RS256) over HTTPS, mutual TLS for sensitive fleet sources
Header
Authorization: Bearer <jwt>
Audience
volgarde.api · the aud claim must match the targeted environment
Scope
Colon-case concatenation of the required scopes (fleet:read, alerts:write, fleet:write, incidents:read, admin:rotate)
Rotation
Dual-active, 24 h overlap, prior token revoked on first success of the new one
| Scope | Granted on |
|---|---|
| fleet:read | Telemetry and health reads — GET /v1/fleet/{aircraft_id}/health, GET /v1/incidents |
| fleet:write | Telemetry ingestion — POST /v1/telemetry/ingest (advanced operator account) |
| alerts:write | External alert intake — POST /v1/alerts/webhook |
| incidents:read | Incident reads — GET /v1/incidents (sub-scope of fleet:read, dedicated to alert-tier integrators) |
| admin:rotate | Token rotation — cabinet endpoint, signed off by a Volgarde mission architect |
Ingestion and consumption endpoints
Four documented endpoints: telemetry ingestion (POST /v1/telemetry/ingest, scope fleet:write), aircraft health reads (GET /v1/fleet/{aircraft_id}/health, scope fleet:read), external alert intake (POST /v1/alerts/webhook, scope alerts:write) and incident reads (GET /v1/incidents, scope fleet:read). Each endpoint returns a 2xx code and an id correlated to the audit trail.
| Method | Endpoint | Purpose | Rate-limit |
|---|---|---|---|
| POST | /v1/telemetry/ingest | Aircraft telemetry ingestion — JSON payload covering callsign, ICAO hex, position, altitude, engine parameters and timestamp. | 600 events/min · burst 1,200 |
| GET | /v1/fleet/{aircraft_id}/health | Aggregated health for one airframe — last health, detected drifts, open alert events. | 60 req/min · burst 120 |
| POST | /v1/alerts/webhook | External alert intake (Volgarde-tier third party) — severity, anomaly_type, recommended_action and confidence. | 300 events/min · burst 600 |
| GET | /v1/incidents | Paginated incident list — filters by aircraft_id, severity, time window and status. | 60 req/min · burst 120 |
Per-endpoint rate limits
Each endpoint enforces a sliding 1-minute window with a maximum burst. The Volgarde-RateLimit-Limit / -Remaining / -Reset headers ship with every 2xx and 4xx response, and a 429 additionally exposes a Retry-After in seconds.
| Endpoint | Window | Ceiling | Headers |
|---|---|---|---|
| POST /v1/telemetry/ingest | 1 minute | 600 events (burst 1,200) | Volgarde-RateLimit-Limit, -Remaining, -Reset |
| GET /v1/fleet/{aircraft_id}/health | 1 minute | 60 req (burst 120) | Volgarde-RateLimit-Limit, -Remaining, -Reset |
| POST /v1/alerts/webhook | 1 minute | 300 events (burst 600) | Volgarde-RateLimit-Limit, -Remaining, -Reset |
| GET /v1/incidents | 1 minute | 60 req (burst 120) | Volgarde-RateLimit-Limit, -Remaining, -Reset, ETag |
Alert webhooks
Volgarde delivers agent-level alerts as signed webhooks. Each delivery carries a Volgarde-Event-Id, a Volgarde-Timestamp, and a Volgarde-Signature computed as HMAC-SHA256 over the raw body. Integrators must verify the signature and respond with a 2xx within 5 s; missed deliveries are retried with exponential backoff up to 24 h, and the full delivery log is exposed in the Volgarde console.
alert.firedanomaly confirmed, agent reasoning attachedalert.escalatedanomaly retained past the corroboration windowalert.resolvedoperator acknowledged, audit closedfleet.ingest.lagstream lag exceeded the integrator-set thresholdauth.token.rotatednew token confirmed active
Error model
Every error response ships the same envelope { code, message, request_id }; a retry_after (in seconds) accompanies 429s. The request_id mirrors the ingest id when the error comes from an ingestion, and a Volgarde-side correlation id is attached to 5xx for incident follow-up.
| Code | HTTP | Meaning |
|---|---|---|
| payload.invalid | 400 | JSON payload malformed, out of contract or out of range — a field is missing or invalid. |
| auth.missing | 401 | No Bearer JWT on the request — Authorization header absent or empty. |
| scope.insufficient | 403 | Required scope missing from the token — the endpoint requires fleet:read / fleet:write / alerts:write / incidents:read. |
| rate.exceeded | 429 | Per-endpoint rate limit hit — the Retry-After header carries the delay in seconds. |
| internal.unexpected | 5xx | Volgarde-side fault — response correlated by request_id (include in any escalation). |