Trips
Trip / voyage logs.
POST
/tripsCreate a trip log
Requires `vesselId` and `departureTime`. `status: in_progress` with `engineInputs`/`fuelInputs` triggers vessel-vital write-back at trip start.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| vesselId | string (uuid) | required | — |
| departureTime | string (date-time) | required | — |
| departureLocation | object | optional | — |
| arrivalTime | string (date-time) | optional | — |
| arrivalLocation | object | optional | — |
| captain | string | optional | — |
| crew | array<string> | optional | — |
| purpose | string | optional | — |
| distanceNm | number | optional | — |
| fuelConsumed | number | optional | — |
| maxSpeed | number | optional | — |
| avgSpeed | number | optional | — |
| weatherSummary | string | optional | — |
| passengerCount | integer | optional | — |
| notes | string | optional | — |
| status | enum(scheduled | in_progress | completed | paused | cancelled) | optional | — |
| engineInputs | array<object> | optional | New-shape vital inputs — only meaningful with status=in_progress. |
| fuelInputs | array<object> | optional | — |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| data | object | required | — |
| data.id | string (uuid) | optional | — |
| data.vesselId | string (uuid) | optional | — |
| data.tripName | string | null | optional | — |
| data.tripReference | string | null | optional | — |
| data.departureTime | string (date-time) | optional | — |
| data.departureLocation | object | null | optional | — |
| data.arrivalTime | string (date-time) | null | optional | — |
| data.arrivalLocation | object | null | optional | — |
| data.captain | string | null | optional | — |
| data.crew | array<string> | optional | — |
| data.purpose | string | null | optional | — |
| data.distanceNm | number | null | optional | — |
| data.fuelConsumed | number | null | optional | — |
| data.maxSpeed | number | null | optional | — |
| data.avgSpeed | number | null | optional | — |
| data.weatherSummary | string | null | optional | — |
| data.passengerCount | integer | null | optional | — |
| data.notes | string | null | optional | — |
| data.status | enum(scheduled | in_progress | completed | paused | cancelled) | optional | — |
| data.engineHoursStart | object | null | optional | — |
| data.engineHoursEnd | object | null | optional | — |
| data.createdAt | string (date-time) | optional | — |
| data.updatedAt | string (date-time) | optional | — |
GET
/trips/{id}Get a trip log
Lazily backfills geocoded lat/lon on departure/arrival locations that only have a place name, returning the enriched coordinates immediately.
Path parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (uuid) | required | — |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| data | any | required | — |
GET
/trips/vessel/{vesselId}List a vessel's trip logs
Supports `?cursor=` pagination on every sort except `sortBy=duration` (a raw-SQL computed-column sort with no defined cursor ordering — falls back to `?page=` semantics).
Path parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| vesselId | path | string (uuid) | required | — |
Query parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| cursor | query | string | optional | Opaque pagination cursor from a previous response's `pagination.cursor`. Omit this param entirely for the first page of cursor mode; pass `cursor=` (empty) is also accepted as "start from the beginning in cursor mode." Omitting `cursor` altogether (not even as an empty string) falls back to legacy `?page=` semantics on endpoints that still support it. |
| limit | query | integer | optional | — |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| data | array<object> | required | — |
| data[].id | string (uuid) | optional | — |
| data[].vesselId | string (uuid) | optional | — |
| data[].tripName | string | null | optional | — |
| data[].tripReference | string | null | optional | — |
| data[].departureTime | string (date-time) | optional | — |
| data[].departureLocation | object | null | optional | — |
| data[].arrivalTime | string (date-time) | null | optional | — |
| data[].arrivalLocation | object | null | optional | — |
| data[].captain | string | null | optional | — |
| data[].crew | array<string> | optional | — |
| data[].purpose | string | null | optional | — |
| data[].distanceNm | number | null | optional | — |
| data[].fuelConsumed | number | null | optional | — |
| data[].maxSpeed | number | null | optional | — |
| data[].avgSpeed | number | null | optional | — |
| data[].weatherSummary | string | null | optional | — |
| data[].passengerCount | integer | null | optional | — |
| data[].notes | string | null | optional | — |
| data[].status | enum(scheduled | in_progress | completed | paused | cancelled) | optional | — |
| data[].engineHoursStart | object | null | optional | — |
| data[].engineHoursEnd | object | null | optional | — |
| data[].createdAt | string (date-time) | optional | — |
| data[].updatedAt | string (date-time) | optional | — |
| pagination | object | optional | Canonical cursor-pagination block. On endpoints not yet retrofitted for true cursor support, `cursor` is a best-effort display-only value (not decodable, no `?cursor=` branch accepts it back) — see each endpoint's description for whether it has full cursor support. |
| pagination.cursor | string | null | optional | Opaque token for the next page, or `null` when `hasMore` is `false`. |
| pagination.limit | integer | required | — |
| pagination.hasMore | boolean | required | — |
| pagination.total | integer | required | Total row count matching the filter (not just this page). |