API Reference

The NaviSight Route Risk API

A single POST returns 31-member ensemble routing, segment-level risk decomposition, and insurance-grade exposure metrics. Built for fleet operators, P&I clubs, cargo underwriters, and marine telematics platforms.

v1 — stablehttps://api.navisight.io

Authentication

All API requests authenticate with an API key sent in the X-API-Key header. Keys are issued from your account dashboard under Account → API and ship with a per-key revocation switch.

# Header on every request
X-API-Key: nv_live_••••••••••••••••

Never embed live keys in browser bundles or commit them to source control. Use a server-side proxy and rotate via the dashboard on suspicion of leak.

Rate limits

Plan	Limit	Burst
Captain	1,000 req / hour	100 req / minute
Fleet / Enterprise	Custom	Custom

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. On 429s, respect Retry-After and back off exponentially.

POST /api/v1/route-risk

POSThttps://api.navisight.io/api/v1/route-risk

Submit origin, destination, departure time, and a vessel descriptor. Returns the safest / fastest / most-comfortable / fuel-efficient routes plus ensemble percentiles, per-segment risk decomposition, and (when entitled) insurance exposure metrics.

curl -X POST 'https://api.navisight.io/api/v1/route-risk' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: nv_live_••••••••••••••••' \
  -d '{
  "origin": {
    "lat": 25.7617,
    "lon": -80.1918,
    "name": "Miami, FL"
  },
  "destination": {
    "lat": 32.3078,
    "lon": -64.7505,
    "name": "St. George's, Bermuda"
  },
  "departure_time": "2026-06-15T08:00:00Z",
  "vessel": {
    "loa_m": 14,
    "beam_m": 4.2,
    "draft_m": 2.1,
    "displacement_t": 16.5,
    "cruising_speed_kts": 7.5,
    "vessel_type": "sailing_monohull"
  },
  "objective": "safest",
  "ensemble": true,
  "insurance": {
    "include_exposure_hours": true,
    "include_exceedance_counts": true,
    "include_loss_probability": true,
    "thresholds": {
      "wind_kts": 35,
      "wave_m": 4
    }
  }
}'

Request schema (full)+

{
  "origin": {
    "lat": 25.7617,
    "lon": -80.1918,
    "name": "Miami, FL"
  },
  "destination": {
    "lat": 32.3078,
    "lon": -64.7505,
    "name": "St. George's, Bermuda"
  },
  "departure_time": "2026-06-15T08:00:00Z",
  "vessel": {
    "loa_m": 14,
    "beam_m": 4.2,
    "draft_m": 2.1,
    "displacement_t": 16.5,
    "cruising_speed_kts": 7.5,
    "vessel_type": "sailing_monohull"
  },
  "objective": "safest",
  "ensemble": true,
  "insurance": {
    "include_exposure_hours": true,
    "include_exceedance_counts": true,
    "include_loss_probability": true,
    "thresholds": {
      "wind_kts": 35,
      "wave_m": 4
    }
  }
}

Response schema (full)+

{
  "route_id": "rt_01HXY9TQ5J7K3P",
  "composite_risk_score": 27,
  "risk_band": "low",
  "ensemble": {
    "members": 31,
    "p10_eta_hours": 89.2,
    "p50_eta_hours": 96.4,
    "p90_eta_hours": 104.7,
    "cone_polygon": "[[lat,lon], ...]"
  },
  "weather_exposure_hours": {
    "wind_gt_25_kts": 8.5,
    "wind_gt_35_kts": 1.2,
    "wave_gt_3m": 14,
    "wave_gt_4m": 3.5
  },
  "exceedance_counts": {
    "wind_threshold_breaches": 3,
    "wave_threshold_breaches": 2,
    "combined_breaches": 1
  },
  "loss_probability": {
    "minor_damage": 0.043,
    "major_damage": 0.0061,
    "total_loss": 0.00018,
    "methodology": "Per-segment Weibull fit, NTSB+MAIB+USCG corpus (n=56,197)"
  },
  "segments": [],
  "generated_at": "2026-05-28T14:22:01Z"
}

Insurance-grade fields

Set insurance.include_* on the request to opt in to the underwriting payload. These fields are gated to API keys with the insurance scope.

Field	Type	Description
weather_exposure_hours	object	Hours of in-transit exposure above named thresholds (wind > 25/35 kts, wave > 3/4 m). Drives premium loading and operational risk assessment.
exceedance_counts	object	Discrete count of threshold breaches per voyage. Used for binomial/Poisson loss frequency models.
loss_probability	object	Per-voyage probability of minor damage / major damage / total loss, fit from the NTSB + MAIB + USCG combined incident corpus (n=56,197). Includes 95% CIs on request.
ensemble.p10_eta_hours	number	10th-percentile (best-case) transit time across the 31-member GEFS ensemble. Pairs with p50 / p90 for arrival-window underwriting.
ensemble.cone_polygon	Polygon	GeoJSON-style polygon enclosing the 80% spatial spread of ensemble routes. Useful for cargo-in-transit zone-of-risk calculations.

Error codes

Code	Name	Meaning
400	Bad Request	Malformed JSON, missing required field, or invalid coordinate range.
401	Unauthorized	Missing or invalid X-API-Key header.
402	Payment Required	Subscription required to access this endpoint or feature.
403	Forbidden	API key does not have permission for this endpoint or insurance fields.
404	Not Found	Route ID or webhook ID does not exist.
422	Unprocessable Entity	Route is infeasible — origin/destination on land, or no path within vessel limits.
429	Too Many Requests	Rate limit exceeded. See X-RateLimit-* headers.
500	Internal Server Error	Routing engine failure. Retry with exponential backoff.
503	Service Unavailable	Upstream weather provider degraded. Retry after the value in Retry-After.

All error bodies follow { "error": { "code": "...", "message": "...", "request_id": "..." } }. Include request_id in any support ticket.

Webhooks

Register a webhook URL to receive push notifications when a long-running ensemble analysis completes, when a monitored voyage crosses a risk threshold, or when an ATBA / NTM advisory changes within your fleet's active routes.

// Example webhook payload — POST'd to your URL
{
  "event": "voyage.risk_threshold_crossed",
  "delivered_at": "2026-05-28T14:22:01Z",
  "voyage_id": "vy_01HXY9TQ5J7K3P",
  "vessel_id": "vs_01HX8WCBQ4A6Z2",
  "risk_band_was": "low",
  "risk_band_now": "moderate",
  "trigger": {
    "field": "wind_kts",
    "threshold": 35,
    "observed": 38.4,
    "at": { "lat": 28.91, "lon": -73.42 }
  },
  "signature": "v1,t=1740751321,sig=••••••••"
}

Available events

voyage.completed
voyage.risk_threshold_crossed
voyage.advisory_changed
ensemble.ready

Verifying signatures

HMAC-SHA256 over the raw body using your webhook secret. Reject any payload whose signature header doesn't match or whose timestamp drift exceeds 5 minutes.

Ready to integrate?

Captain and Fleet plans include API access. Need volume pricing, dedicated SLAs, or a private deployment? We'll get you set up.

View plans Talk to sales