Voyage assessments

Score one voyage

Synchronously scores one voyage and retains the assessment for 30 days.

Required scope: voyage:score.

post/api/v1/voyage-assessments

Request

  • Base URL: https://arcnautical.com
  • URL: https://arcnautical.com/api/v1/voyage-assessments
  • Auth: one of:
    • HTTP bearer
    • API key in header X-ArcNautical-Key

Headers

Idempotency-Keystring required

Required for resource-creating POST requests. The same key and identical body replay the original response for 24 hours; a different body returns idempotency_conflict.

Request body

customer_referencestring
include_geometryboolean

Set false to omit route.geometry from the response. The polyline is typically ~87% of an assessment body (measured: 65,053 of 74,265 bytes, 1,885 coordinate pairs on SGSIN-NLRTM), so a caller scoring a book of voyages who wants the score and drivers rather than the line on a map should turn it off. Default true so existing integrations are unchanged.

Example request

{
  "customer_reference": "resilience-model-run-42",
  "route": {
    "origin": {
      "locode": "SGSIN"
    },
    "destination": {
      "locode": "NLRTM"
    },
    "vessel_type": "container",
    "load_condition": "laden",
    "speed_knots": 16,
    "dwt_tonnes": 150000,
    "fuel_type": "vlsfo",
    "bunker_price_usd_per_tonne": 625
  }
}

Response

Assessment created.

idstring required
customer_referencestring
scorenumber required
risk_level'low' | 'moderate' | 'elevated' | 'high' | 'critical' required
confidencenumber required
missing_sourcesstring[] required
source_statusobject required

DEPRECATED — use sources, which carries the same status plus checked_at. Keeps working until 2026-10-31 under the 90-day policy at /developers/stability/; removal ships as v2, never in place.

methodology_versionstring required
assessed_atstring date-time required

When the SCORE was computed — not when this record was written. Scores are cached for four hours by scoring version, date and route hash, so an identical request inside that window returns the ORIGINAL computation time and cached: true. Use this as the "when did we know this" field in an audit trail.

cachedboolean

True when this response came from the score cache rather than being computed for this request. assessed_at then predates your request.

expires_atstring date-time required

When this RECORD is deleted (retention), not how long the verdict is valid.

disclaimerstring required

Changes

No recorded changes to this operation across all 1 revision of this API.