Score your first vessel

MTI scores vessels. You hold an IMO number, you ask for its score, and you decide what to do with the answer. This page covers the first call, the three levels of detail, and the two ways of asking about more than one ship at a time.

Before you start, get your client credentials from your Pole Star representative.

The base URL is being confirmed

Every example on this page reads the host from $MTI_BASE_URL. We are confirming the production host with the MTI team and will publish it here once it is settled. Your representative can give you the host to use in the meantime.

Your first call

Exchange your client credentials for an access token, then ask for one vessel's composite score.

{
    "meta": {
        "requestId": "266ea41d-adf5-4e12-9a11-9c9a6f12b0a1",
        "requestTimestamp": "2026-09-22T09:14:22Z"
    },
    "data": {
        "imoNumber": "9811000",
        "mtiScore": 3.49,
        "mtiVesselClass": "Bulk Carriers",
        "updatedAt": "2026-09-19T02:00:00Z"
    }
}

mtiScore runs from 0 to 5, and higher is better. Understanding MTI Scores explains the scale and the five categories behind it.

Three levels of detail

The same vessel answers three different questions, and the endpoint you choose sets how much comes back.

Call	Returns
`GET /vessels/{imo}/scores/overall`	The composite score, the vessel class, and when we last updated it
`GET /vessels/{imo}/scores`	The composite score plus the five category scores
`GET /vessels/{imo}`	Everything: identity, ownership, management, classification, dimensions, the scores, and the reason text behind each category

Start at the smallest one that answers your question. The full vessel record is a wide response and most integrations do not need it on every lookup.

Screening a portfolio

Post up to 500 IMO numbers and get them all back in one round trip.

The response carries what we hold in data, and lists anything we could not resolve in notFound. One unrecognised IMO number does not fail the request, so check notFound on every batch call.

{
    "meta": {
        "requestId": "266ea41d-adf5-4e12-9a11-9c9a6f12b0a1",
        "requestTimestamp": "2026-09-22T09:14:22Z",
        "requestedCount": 3,
        "returnedCount": 2
    },
    "data": [ ],
    "notFound": ["9183934"]
}

POST /vessels/scores/overall/batch takes the same request body and returns the composite score alone.

Batch beats looping

Five hundred IMO numbers in one request is one round trip. The same five hundred through GET /vessels/{imo}/scores is five hundred, and it will run into rate limiting long before it finishes.

Paging a large result set

GET /vessels filters and pages across the whole scored population.

limit defaults to 100 and offset to 0. meta.totalCount tells you how far you can page. The filters are search, flag_country, vessel_type, vessel_status, score_min and score_max, and sort_by takes a field name with an optional - prefix for descending, for example -mti_score.

Where to go next

Overview

How the API is put together: OAuth 2.0 client credentials, three access shapes, one response envelope.

Authentication

Getting an access token, and what happens when it expires.

Understanding Scores

Understanding MTI scores.

Getting Started with MTI

Your first call#

Three levels of detail#

Screening a portfolio#

Paging a large result set#

Where to go next#

Your first call

Three levels of detail

Screening a portfolio

Paging a large result set

Where to go next