Vessel API

Version 1 · 28 October 2026

The API gives a vessel's ISM AI Pilot data to other systems — the office's reporting or BI, a management company's fleet system — and takes machinery running hours from the vessel's alarm and monitoring system (AMS). It is JSON over HTTPS, one key per integration, issued by the Master.

Keys

The Master issues a key in the app: Settings → API access. Name it after whoever will use it (“Office BI”, “AMS PC”), and choose whether it may write running hours — by default a key only reads. The key is shown once; the vessel keeps only its fingerprint. A lost key is revoked and a new one issued. Revoking stops a key at once.

Send the key with every request:

Authorization: Bearer ismp_…

X-API-Key: ismp_… works too. Each key may make 60 requests a minute; above that the answer is 429 with Retry-After.

Base address

https://europe-west1-marine-safety-manager.cloudfunctions.net/api

curl -H "Authorization: Bearer ismp_…" \
  https://europe-west1-marine-safety-manager.cloudfunctions.net/api/v1/due?days=90

Every answer carries vessel (the IMO number) and generatedAt. Dates are yyyy-mm-dd; today is the UTC date.

What it never returns

Crew names, crew certificates, hours of rest and the names of whoever signed a record stay aboard. The API answers about the vessel, its equipment and its machinery.

Reading

Request	Gives
`GET /v1/vessel`	IMO, name, flag, call sign
`GET /v1/due?days=90`	Everything falling due within `days` (0–730, default 90), and everything already overdue: equipment inspections and expiries, certificate expiries, survey windows. Sorted by date.
`GET /v1/equipment`	The equipment register (LSA, FFE, lifting and the vessel's own categories) with next inspection, expiry and the status of each.
`GET /v1/certificates`	Vessel and equipment certificates: number, issuer, issue and expiry dates, status, how many items each covers.
`GET /v1/surveys`	Surveys and audits: due date, the window (`opens`–`closes`) and its state.
`GET /v1/defects`	Open defects — from planned maintenance (`source: "pms"`) and from equipment inspections (`source: "inspection"`).
`GET /v1/machines`	Machinery in the maintenance plan: running hours and the date of the last reading, AMS tag, parent machine.

Status

expired — the date has passed; due — within 60 days; ok — later; none — no date. A survey has a state: overdue (its window has closed), open (inside the window), soon (the window opens within 60 days), planned, done (once-only and carried out).

Example — `GET /v1/due?days=60`

{
  "vessel": "1234567",
  "generatedAt": "2026-10-28T16:02:11.402Z",
  "days": 60,
  "today": "2026-10-28",
  "items": [
    { "kind": "equipment", "what": "expiry", "id": "k3…", "category": "fire_extinguishers",
      "title": "12 — CO2 5 kg", "date": "2026-10-02", "status": "expired", "daysLeft": -26 },
    { "kind": "survey", "what": "window", "id": "s1…", "title": "Class annual survey",
      "date": "2026-11-15", "due": "2027-02-15", "closes": "2027-05-15",
      "state": "soon", "status": "due", "daysLeft": 18 },
    { "kind": "certificate", "what": "expiry", "id": "c7…", "scope": "vessel",
      "title": "Safety Equipment Certificate", "date": "2026-12-01", "status": "due", "daysLeft": 34 }
  ]
}

Writing running hours

A key allowed to write can post what the AMS counters show — the same thing the engineer imports from an AMS export file in the app.

POST /v1/machines/hours
Content-Type: application/json

{ "readings": [
    { "tag": "ME_PS.RH", "counter": 12450.5, "date": "2026-10-28" },
    { "machineId": "a8f…", "counter": 3310 }
] }

Name each machine by its AMS tag (as set in the app — matched ignoring case and punctuation) or by machineId from GET /v1/machines. counter is what the counter shows; if the counter was replaced, the app adds the hours the machine ran before it. date is optional (today) and cannot be in the future. Up to 200 readings a request.

A reading goes through the same checks as one typed by hand. One that does not pass is not taken — the engineer enters it on the machine's screen with a reason. Components whose hours follow their parent (a turbocharger on its engine) move with it.

`status`	Meaning
`ok`	Taken.
`same`	The machine already has this figure for that day.
`doubt`	Lower than the last reading, or more hours than the calendar allows since it. Not taken; `why` says which.
`older`	Dated before the machine's last reading. Not taken.
`follows`	Its hours follow its parent's — post the parent.
`nocounter`	The machine has no running-hours counter.
`dup`	The same machine twice in one request; the first is used.
`unmatched`	No machine with that tag or id.
`invalid`	The row itself is wrong; `why` says how.

Add ?dryRun=1 to see the verdicts without writing anything — for setting up an integration against the real register. Every write is recorded, and the Master sees it under Settings → API access.

Errors

Code	When
`400`	The request body is not what the endpoint takes.
`401`	No key, an unknown key, or a revoked one.
`403`	A read-only key tried to write.
`404`	No such endpoint. `GET /v1` lists them.
`429`	More than 60 requests a minute.

The body of an error is {"error": "…"} in plain English.

Questions, or an AMS that cannot run a script? Write to mail@ismpilot.com.