API Reference

Verify API key, retrieve org metadata

Returns the organization owning the supplied API key. Use this as a health-check call before submitting voyage requests.

curl https://api.vesselfront.com/v1/organization \
  -H "X-API-Key: vf_live_your_key"

{
  "id":   "7a510548-aec2-49b3-…",
  "name": "Acme Shipping Ltd"
}

Need the full request/response schema? Request the OpenAPI spec.

List vessels in your organization

Returns all vessel profiles. Supports pagination and search.

Create a vessel profile

Vessel particulars are the performance baseline every routing call inherits. DWT, LBP, pitch, and service speed drive the FOC model directly.

{
  "name":            "MV Atlantic Star",
  "dwt":             75000,
  "loa":             229,
  "lbp":             220,
  "breadth":         32.2,
  "depth":           20.1,
  "draftDesign":     14.5,
  "draftScant":      15.0,
  "serviceSpeed":    14.5,
  "pitch":           5.2,
  "dateConstructed": "2015-06-01"
}

Get a single vessel by ID

Returns the full vessel profile, including stored performance curves and historical baseline references.

Update a vessel profile

Partial update. Send only the fields you want to change.

Delete a vessel profile

Deletes the vessel and detaches it from historical chartings. Historical voyage records remain queryable for audit.

Vessel-level voyage statistics

Aggregate stats for a vessel: voyages completed, distance covered, fuel-saving averages, CII trajectory.

List route optimizations

Returns chartings for your organization, newest first.

Create a new charting (route optimization)

A single POST triggers the VesselFront multi-agent engine. Weather forecasts, ECA zones, war-zone avoidance, vessel performance curves, and your custom constraints are applied simultaneously. Typically returns within a minute.

{
  "vesselId":         "66b72ad4-…",
  "portFromName":     "AABENRAA",
  "latFrom":          55.03,
  "lngFrom":          9.46,
  "portToName":       "AAHEIM",
  "latTo":            62.06,
  "lngTo":            5.51,
  "startDate":        "2026-06-01T00:00:00.000Z",
  "speedRangeMin":    11,
  "speedRangeMax":    13,
  "draft":            14,
  "trim":             2,
  "rpm":              55,
  "dwt":              68439,
  "lbp":              220,
  "pitch":            5.435,
  "optimizationType": "1",
  "routeType":        "1",
  "avoidWarZones":    true,
  "avoidEca":         false
}

List ongoing voyages

Returns chartings whose voyages are currently in progress (startDate ≤ now ≤ ETA).

Need the full request/response schema? Request the OpenAPI spec.

Get a single charting by ID

Returns the optimized route, waypoint sequence, FOC estimate, and links to RTZ/CSV exports.

Update a charting

Partial update — for example, attaching metadata or marking a voyage as completed.

Re-compute voyage segments

Re-runs the segment-level computations against the latest weather window — useful after a long delay between charting creation and departure.

Key waypoints with weather state

Returns segment-level critical waypoints — wave height peaks, wind shifts, ECA transitions. Useful for operator briefings.

Fuel-oil consumption estimate

Returns the FOC baseline (mt/day) for the voyage, computed from the vessel's stored performance curve and the optimized track.

Download signed CSV

Returns the route as a CSV with a SHA-256 integrity hash in the X-Content-Hash response header. Required for P&I claims documentation.

Download RTZ 1.1 XML

Returns the route in RTZ 1.1 XML format — accepted by all major ECDIS systems.

LLM-generated routing rationale

Returns a plain-English explanation for the route — why waypoints were chosen, hazards avoided, trade-offs made. Rate-limited to 10 requests per hour per organization.

List constraints

Returns active constraints visible to your organization.

Create a no-go polygon

Block routes through any geographic area via a GeoJSON polygon. Set start_date and end_date to activate time-limited zones.

{
  "name":       "Black Sea Exclusion Zone",
  "type":       "HIGH_RISK",
  "level":      "ORGANIZATION",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [31.5,46.5], [34.0,46.5],
      [34.0,44.0], [31.5,44.0],
      [31.5,46.5]
    ]]
  },
  "is_active":  true,
  "start_date": "2026-06-01",
  "end_date":   "2026-12-31"
}

Delete a constraint

Removes the constraint from future chartings. Historical chartings retain a reference for audit.

List per-customer routing rules

Returns rule sets attached to client identities within your organization.

Need the full request/response schema? Request the OpenAPI spec.

Create a per-customer rule set

Define routing preferences scoped to a downstream client — wave limits, mode defaults, no-go regions.

Need the full request/response schema? Request the OpenAPI spec.

Replace a client rule set

Full replacement of the rule set. Use PATCH semantics by submitting the merged document.

Delete a client rule set

Detaches the rule set. Subsequent chartings for that client revert to organization defaults.

Query historical telemetry

Returns telemetry records for a vessel in a time window. Paginated by timestamp.

Push a telemetry record

Submit an AIS-derived telemetry record for a vessel. Feeds voyage deviation tracking, fuel performance analytics, and CII reporting.

{
  "timestamp":       "2026-06-01T14:23:00.000Z",
  "latitude":        57.41,
  "longitude":       8.12,
  "heading":         342,
  "speed":           12.4,
  "rpm":             55,
  "engineLoad":      72,
  "fuelConsumption": 24.6,
  "draft":           14.0,
  "windSpeed":       8.2,
  "seaState":        3
}