Lumra API and integrations for developers

Quickstart

Two ways in, both authenticated.

1. The events API

Post an event and get the full result back in one call. Authenticate with your partner key in the Authorization header.

2. Signed webhooks

Point your platform's webhook at Lumra and sign each delivery with your webhook secret. Retries are safe: a repeated event is recognized, not duplicated.

Getting credentials. During a pilot we issue you a partner key (sent once) and a webhook secret. The key travels as Authorization: Bearer <key>. The secret signs your webhook bodies. The host shown in the samples below is illustrative: your base URL is provided with your pilot environment.

Events API

POST an event, get a signed result.

# Send an event. The adapter field selects how it is normalized.
curl -X POST https://api.privinet.net/v1/events \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
        "adapter": "metalert",
        "payload": {
          "external_event_id": "evt-2026-07-03-0001",
          "device_id": "sole-9",
          "event_type": "geofence_exit",
          "lat": 33.9425, "lng": -118.4081,
          "timestamp": "2026-07-03T02:14:09Z"
        }
      }'

# Response (trimmed): a signed, chained record you can read back by id.
{
  "event_id": "164b999f-...",
  "urgency": "critical",
  "escalation_required": true,
  "proof": { "verification_status": "cloud_signed", "key_id": "sw-..." }
}

Endpoint	Does	Auth
POST /v1/events	Ingest one event through the full pipeline, return the signed result	Bearer key
GET /v1/events/{id}	Read an event back	Bearer key
GET /v1/events/{id}/analysis	Risk score, escalation decision, explanation factors	Bearer key
GET /v1/events/{id}/proof	The signed proof record	Bearer key
POST /v1/events/{id}/verify	Recompute the hashes and re-check the signature	Bearer key
GET /v1/events/{id}/proofpack	The court-ready ProofPack export for that incident	Bearer key
POST /v1/webhooks/{partner}	Signed inbound receiver (see below)	HMAC signature

Webhooks

Sign the body. We check every byte.

Compute an HMAC-SHA256 of the exact request body using your webhook secret, and send it as X-Signature: sha256=<hex>. A missing or wrong signature is rejected. A repeated external_event_id returns the original result, so retries never double-record.

# Sign and deliver, in a few lines.
BODY='{"adapter":"metalert","payload":{"external_event_id":"evt-1", ...}}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')"

curl -X POST https://api.privinet.net/v1/webhooks/metalert \
  -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

# First delivery -> creates the record. Retried delivery ->
{ "deduped": true, "event_id": "164b999f-..." }

Adapters

Five inputs, one common record.

The adapter field selects how your raw payload is normalized into the common event shape. More adapters are added per partner need.

metalert · GPS wearables generic_iot · sensor anomalies fleet_dashcam · impacts crop_image · field imagery media · multimodal incidents

Verify

Anyone can check a record, with no PriviNet servers.

Every record can be re-checked independently: recompute the hashes from the data, then check the signature against the published key. The endpoint below does it server-side; a ProofPack does it in a portable file with instructions and an FRE 902(13)/(14) certification template for a qualified person to sign. Verification is always free; the ProofPack export is the paid, court-ready artifact.

# Re-check a record. Any altered byte returns tamper_detected.
curl -X POST https://api.privinet.net/v1/events/{id}/verify \
  -H "Authorization: Bearer pk_live_your_key"

{ "verification_status": "cloud_signed", "detail": "hashes recomputed, signature valid" }

Send an event. Get back a record anyone can verify.