API Reference

VesselFront's REST API gives you programmatic access to maritime route optimization, vessel management, and telemetry. Embed AI-powered voyage intelligence directly into your fleet management system, ERP, or custom workflows. No installation required..

REST · JSON 27 endpoints Typically < 1 min per route

Organization

1 endpoint

Retrieve the organization record tied to your API key. The returned record confirms key validity and provides the orgId required when creating vessels and chartings.

GET /organization

Get the organization associated with the API key

Responses

200 Organization info returned successfully

401 Invalid or missing API key

Vessel

6 endpoint s

Manage the vessels in your fleet. Physical parameters — DWT, LBP, service speed, and propeller pitch — are stored here and fed directly into the routing engine to produce accurate fuel and ETA predictions.

GET /vessel

List vessels (paginated)

Parameters

Name	In	Type	Required	Description
`page`	query	integer	optional	—
`pageSize`	query	integer	optional	—

Responses

200 List of vessels

401 Unauthorized

POST /vessel

Create a new vessel

Request Body

Field	Type	Required	Notes
`name`	string	optional	nullable
`image`	string	optional	nullable
`dateConstructed`	string	required	—
`captain`	string	optional	nullable
`dwt`	number	required	—
`loa`	number	required	—
`lbp`	number	required	—
`breadth`	number	required	—
`depth`	number	required	—
`draftDesign`	number	required	—
`serviceSpeed`	number	required	—
`draftScant`	number	required	—
`pitch`	number	required	—
`imo`	string	optional	—
`orgId`	string	optional	—
`type`	number	optional	—
`registrarId`	string	optional	—
`owner`	string	optional	—

Responses

201 Vessel created

403 Validation error or forbidden

GET /vessel/{vesselId}

Get a vessel by ID

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—

Responses

200 Vessel details

404 Vessel not found

PATCH /vessel/{vesselId}

Update a vessel

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—

Request Body

Field	Type	Required	Notes
`name`	string	optional	nullable
`image`	string	optional	nullable
`dateConstructed`	string	required	—
`captain`	string	optional	nullable
`dwt`	number	required	—
`loa`	number	required	—
`lbp`	number	required	—
`breadth`	number	required	—
`depth`	number	required	—
`draftDesign`	number	required	—
`serviceSpeed`	number	required	—
`draftScant`	number	required	—
`pitch`	number	required	—
`imo`	string	optional	—
`orgId`	string	optional	—
`type`	number	optional	—
`registrarId`	string	optional	—
`owner`	string	optional	—

Responses

200 Vessel updated

404 Vessel not found

DELETE /vessel/{vesselId}

Delete a vessel

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—

Responses

200 Vessel deleted

404 Vessel not found

GET /vessel/{vesselId}/stats

Get statistics for a vessel

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—

Responses

200 Vessel statistics

404 Vessel not found

Charting

11 endpoint s

The core resource. A charting is a route optimization request between two ports. Once created, the engine applies weather forecasts, ECA zones, piracy avoidance, and your vessel's performance curve, then returns a set of waypoints. Poll the record or use webhooks to detect completion. Export routes as CSV or RTZ for direct ECDIS upload.

GET /charting

List chartings (paginated)

Parameters

Name	In	Type	Required	Description
`page`	query	integer	optional	—
`pageSize`	query	integer	optional	—
`search`	query	string	optional	—

Responses

200 List of chartings

POST /charting

Create a new charting (route optimization request)

Request Body

Field	Type	Required	Notes
`latFrom`	number	required	—
`lngFrom`	number	required	—
`nidFrom`	string	optional	—
`portFromName`	string	required	—
`latTo`	number	required	—
`lngTo`	number	required	—
`nidTo`	string	optional	—
`portToName`	string	required	—
`startDate`	string (date-time)	required	—
`endDate`	string (date-time)	optional	—
`vesselId`	string	required	—
`speedRangeMin`	number	required	—
`speedRangeMax`	number	required	—
`draft`	number	required	—
`trim`	number	required	—
`rpm`	number	required	—
`dwt`	number	required	—
`lbp`	number	required	—
`pitch`	number	required	—
`optimizationType`	string	required	—
`routeType`	string	required	—
`maxWaveHeight`	number	optional	—
`maxWindBf`	number	optional	—
`maxNorthLat`	number	optional	—
`waveUnit`	string	optional	One of: meters, douglas
`windUnit`	string	optional	One of: m/s, bf
`noGoAreas`	array	optional	—
`avoidEca`	boolean	optional	Default: false
`avoidPiracyAreas`	boolean	optional	Default: true
`avoidWarZones`	boolean	optional	Default: true
`importedData`	array	optional	—
`owner`	string	optional	—
`triggeredBy`	string	optional	—
`onboardingUploadedFileKey`	string	optional	—
`isAlterFrom`	boolean	optional	—

Responses

201 Charting created

403 Validation error

GET /charting/active

Get all active chartings

Responses

200 List of active chartings

GET /charting/{chartingId}

Get a charting by ID

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—
`addCharting`	query	boolean	optional	—

Responses

200 Charting details

404 Charting not found

PATCH /charting/{chartingId}

Update a charting

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Request Body

Field	Type	Required	Notes
`latFrom`	number	required	—
`lngFrom`	number	required	—
`nidFrom`	string	optional	—
`portFromName`	string	required	—
`latTo`	number	required	—
`lngTo`	number	required	—
`nidTo`	string	optional	—
`portToName`	string	required	—
`startDate`	string (date-time)	required	—
`endDate`	string (date-time)	optional	—
`vesselId`	string	required	—
`speedRangeMin`	number	required	—
`speedRangeMax`	number	required	—
`draft`	number	required	—
`trim`	number	required	—
`rpm`	number	required	—
`dwt`	number	required	—
`lbp`	number	required	—
`pitch`	number	required	—
`optimizationType`	string	required	—
`routeType`	string	required	—
`maxWaveHeight`	number	optional	—
`maxWindBf`	number	optional	—
`maxNorthLat`	number	optional	—
`waveUnit`	string	optional	One of: meters, douglas
`windUnit`	string	optional	One of: m/s, bf
`noGoAreas`	array	optional	—
`avoidEca`	boolean	optional	Default: false
`avoidPiracyAreas`	boolean	optional	Default: true
`avoidWarZones`	boolean	optional	Default: true
`importedData`	array	optional	—
`owner`	string	optional	—
`triggeredBy`	string	optional	—
`onboardingUploadedFileKey`	string	optional	—
`isAlterFrom`	boolean	optional	—

Responses

200 Charting updated

404 Charting not found

POST /charting/{chartingId}/segments/compute

Compute route segments for a charting

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Request Body

Field	Type	Required	Notes
`splitIndices`	array	optional	—

Responses

200 Segments computed

404 Charting not found

GET /charting/{chartingId}/critical-points

Get critical points for a charting

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Responses

200 Critical points data

404 Charting not found

GET /charting/{chartingId}/foc

Get fuel oil consumption (FOC) estimation for a charting

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Responses

200 FOC estimation data

404 Charting not found

GET /charting/{chartingId}/csv

Download route as CSV with integrity hash

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Responses

200 CSV file with hash

404 Charting not found

GET /charting/{chartingId}/rtz

Download route in RTZ format

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Responses

200 RTZ route file

404 Charting not found

GET /charting/{chartingId}/explanation

Get a natural-language explanation of the route (rate-limited to 10 requests/hour)

Parameters

Name	In	Type	Required	Description
`chartingId`	path	string	required	—

Responses

200 Route explanation

404 Charting not found

429 Too many requests

Constraints

3 endpoint s

Define geographic polygons the engine must avoid. Constraints can be scoped globally, per organization, or by vessel type. Common use cases: war zones, piracy hotspots, ECA boundaries, and draft-restricted passages.

GET /constraints

List all navigation constraints

Parameters

Name	In	Type	Required	Description
`level`	query	string	optional	Filter by constraint level
`vesselTypeId`	query	string	optional	Filter by vessel type ID

Responses

200 List of constraints

401 Unauthorized

POST /constraints

Create a navigation constraint

Request Body

Field	Type	Required	Notes
`name`	string	required	—
`geometry`	object	required	—
`type`	string	required	One of: USER_DEFINED, PREDEFINED, MILITARY, HIGH_RISK
`level`	string	required	One of: GLOBAL, ORGANIZATION, VESSEL_TYPE
`start_date`	string (date)	optional	—
`end_date`	string (date)	optional	—
`is_active`	boolean	optional	Default: true
`description`	string	optional	—
`orgIds`	array	optional	Required when level is ORGANIZATION
`vesselTypeIds`	array	optional	Required when level is VESSEL_TYPE

Responses

201 Constraint created

403 Validation error

DELETE /constraints/{constraintId}

Delete a navigation constraint

Parameters

Name	In	Type	Required	Description
`constraintId`	path	string	required	—

Responses

200 Constraint deleted

404 Constraint not found

Client Data

4 endpoint s

Store and manage client-specific configuration data linked to constraints. Useful when running a multi-tenant integration and needing per-customer routing rules.

GET /client-data

Get client-specific data

Parameters

Name	In	Type	Required	Description
`vesselTypeId`	query	string	optional	Filter by vessel type ID

Responses

200 Client data returned

401 Unauthorized

POST /client-data

Create a client data entry

Request Body

Field	Type	Required	Notes
`name`	string	required	—
`geometry`	object	required	—
`type`	string	required	One of: USER_DEFINED, PREDEFINED, MILITARY, HIGH_RISK
`level`	string	required	One of: GLOBAL, ORGANIZATION, VESSEL_TYPE
`start_date`	string (date)	optional	—
`end_date`	string (date)	optional	—
`is_active`	boolean	optional	Default: true
`description`	string	optional	—
`orgIds`	array	optional	Required when level is ORGANIZATION
`vesselTypeIds`	array	optional	Required when level is VESSEL_TYPE

Responses

201 Client data created

403 Validation error

PUT /client-data/{constraintId}

Update a client data entry

Parameters

Name	In	Type	Required	Description
`constraintId`	path	string	required	—

Request Body

Field	Type	Required	Notes
`name`	string	required	—
`geometry`	object	required	—
`type`	string	required	One of: USER_DEFINED, PREDEFINED, MILITARY, HIGH_RISK
`level`	string	required	One of: GLOBAL, ORGANIZATION, VESSEL_TYPE
`start_date`	string (date)	optional	—
`end_date`	string (date)	optional	—
`is_active`	boolean	optional	Default: true
`description`	string	optional	—
`orgIds`	array	optional	Required when level is ORGANIZATION
`vesselTypeIds`	array	optional	Required when level is VESSEL_TYPE

Responses

200 Client data updated

404 Not found

DELETE /client-data/{constraintId}

Delete a client data entry

Parameters

Name	In	Type	Required	Description
`constraintId`	path	string	required	—

Responses

200 Client data deleted

404 Not found

Telemetry

2 endpoint s

Push real-time vessel position and engine performance data to VesselFront. Telemetry feeds the voyage analytics dashboard, improves fuel consumption models, and enables live deviation tracking against the planned route.

GET /telemetry/{vesselId}

Get telemetry records for a vessel

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—
`from`	query	string	optional	Start of time range (inclusive)
`to`	query	string	optional	End of time range (inclusive)
`page`	query	integer	optional	Page number (used with pageSize for pagination)
`pageSize`	query	integer	optional	Number of records per page

Responses

200 Telemetry records (array or paginated object)

404 Vessel not found

POST /telemetry/{vesselId}

Create a telemetry record for a vessel

Parameters

Name	In	Type	Required	Description
`vesselId`	path	string	required	—

Request Body

Field	Type	Required	Notes
`timestamp`	string (date-time)	required	—
`latitude`	number	required	Min: -90 · Max: 90
`longitude`	number	required	Min: -180 · Max: 180
`speed`	number	required	Min: 0
`heading`	number	required	Min: 0 · Max: 360
`rpm`	number	required	Min: 0
`fuelConsumption`	number	required	Min: 0
`draft`	number	required	Min: 0
`engineLoad`	number	required	Min: 0 · Max: 100
`windSpeed`	number	optional	Min: 0
`windDirection`	number	optional	Min: 0 · Max: 360
`seaState`	number	optional	Min: 0 · Max: 9
`waterDepth`	number	optional	Min: 0
`trimFore`	number	optional	—
`trimAft`	number	optional	—
`mePower`	number	optional	Min: 0

Responses

201 Telemetry record created

403 Validation error