Fleet Management
https://api.polestar-production.com/fleet-management/v2/fleets.What the eight do
| Operation | Does |
|---|---|
POST /fleet-management/v2/fleets | Create a fleet and populate it with vessels, in one call |
GET /fleet-management/v2/fleets | List your active fleets |
GET /fleet-management/v2/fleets/{fleet_id} | Read one fleet, including its current vessel count |
PUT /fleet-management/v2/fleets/{fleet_id} | Rename it, change its description, add or remove vessels |
DELETE /fleet-management/v2/fleets/{fleet_id} | Soft-delete it |
GET /fleet-management/v2/fleets/{fleet_id}/vessels | List its members, enriched with vessel reference data |
GET /fleet-management/v2/fleets/{fleet_id}/composition | Break it down by type, class, flag, build and size, without listing every member |
GET /fleet-management/v2/fleets/{fleet_id}/events | List recent events across all its members |
{fleet_id} is a UUID. A malformed fleet_id returns 422 on the read and update endpoints; Delete Fleet returns 400.Coming from v1
/v1/fleets still runs and is not deprecated, so existing integrations keep working. New work should use /v2, which is what this reference documents.POST /v1/fleets/{id}/vessels call. In v2 that endpoint does not exist: vessels go in the body when you create the fleet, and add_imo and remove_imo are part of the same PUT that changes the name.Creating a fleet
name is required, between 3 and 100 characters. description is optional, up to 200. imo_numbers is required, which is the change most likely to catch a v1 client: there is no way to create an empty fleet.201 Created with the fleet's fleet_id.400 and no fleet is created. If some resolve and some do not, the fleet is created with the ones that worked and the rest come back under vessel_results.rejected, grouped by reason.409, matched case-insensitively across your active fleets. v1 did not enforce this.Changing a fleet
PUT /fleet-management/v2/fleets/{fleet_id} carries all four fields, and any combination of them:name, description, add_imo and remove_imo must be present, or the request is rejected with 422. An omitted field is left unchanged, and no IMO may appear in both lists.Create and update report failures differently
POST returns vessel_results.rejected, an array grouped by reason, each entry carrying reason and the imo_numbers that hit it. The reasons are INVALID_FORMAT and NOT_FOUND.PUT returns vessel_results.failed, an array with one entry per IMO, each carrying imo, reason and the action it was supplied under. The reasons are VESSEL_NOT_FOUND, INVALID_IMO, ALREADY_IN_FLEET and SYSTEM_ERROR.Reading a fleet
GET /v2/fleets/{fleet_id}/vessels returns members enriched from the asset cache with vessel information and last known position, along with when each vessel was added and by whom. That audit trail is the reason to keep membership here rather than in your own table.flag_code as ISO 3166-1 alpha-3, vessel_type, vessel_class and mti_score.GET /v2/fleets/{fleet_id} returns the fleet with its current vessel count. A fleet that has been soft-deleted reads as 409 here rather than 404.The two list endpoints sort on different fields
GET /v2/fleets accepts name and last_modified_at only, defaulting to -last_modified_at. It also takes a name filter, matched case-insensitively on a partial string, so finding a fleet by name no longer means listing everything and matching client-side as it did in v1.GET /v2/fleets/{fleet_id}/vessels sorts on the vessel fields it returns. Either endpoint takes a - prefix for descending, and anything outside the accepted set is rejected with 422.limit and offset. limit defaults to 100 and is capped at 500.mti_score depends on entitlement
mti_score is left out of each vessel entirely unless your account is entitled to MTI tier 1. It is absent rather than null, so treat a missing key as "not entitled" rather than "no score".Profiling a fleet
GET /v2/fleets/{fleet_id}/composition tells you what a fleet is made of, for a chart or a report, without paging through its members.| Section | Holds |
|---|---|
summary | Vessel count after filtering, average age, total deadweight and the number of flag states |
type_and_class | Counts and percentages by vessel type and by vessel class |
registration_and_flag | The most common ports of registry and flag states |
build_and_origin | The most common countries of build and builders, and an age profile |
size_and_dimensions | Distributions of deadweight, gross tonnage, length overall, beam and draught |
label, count and percentage. We count a vessel with no value for an attribute under Unknown. Where a section reports vessels_with_data, that is the number of vessels its figures are based on, so check it before comparing two fleets.flag_code (ISO 3166-1 alpha-3), vessel_type and vessel_class narrow the fleet before we compute the breakdown. Each takes a comma-separated list or a repeated parameter, and values are case-insensitive. The vessels list also filters on mti_score; composition does not.409, as it does on the fleet itself.Recent activity across a fleet
GET /v2/fleets/{fleet_id}/events lists recent events for every vessel in the fleet in one feed.timestamp_start is required, and a call without it returns 400. timestamp_end is optional. Both are UTC in ISO 8601 and both are inclusive; a window that ends before it starts returns 422.event_type narrows the feed, repeated or as a comma-separated list:| Event types | Cover |
|---|---|
ZONE_ENTRY, ZONE_EXIT, PORT_ARRIVAL, PORT_DEPARTURE, PORT_AREA_ARRIVAL, PORT_AREA_DEPARTURE | Zone and port activity |
AIS_GAP | Periods when a vessel stopped transmitting AIS |
STS_PAIRING | Potential ship-to-ship operations |
POSITIONAL_DISCREPANCY | Possible AIS spoofing |
PORT_STATE_CONTROL | Inspections and detentions |
data.events carries event_details, whose fields depend on the event type, and vessel_information for the member it concerns. Zone and port events also carry zone_information. Page with limit (1 to 500, default 100) and offset; meta.total_count says how many events match.Read the feed to look back, subscribe to be told
Ownership and deletion
403, not 404, so the response distinguishes "not yours" from "does not exist".active flag, so the fleet stops appearing in reads and listings without being destroyed. DELETE returns 204 No Content with an empty body.Where fleets get used
fleet_id instead of imo on a vessel notification subscription and every member is covered.Related
Modified at 2026-10-21 14:41:29