Getting started with the Pole Star APIs

What you need before your first call, and what every response looks like once you make one.

Get an account and credentials

Credentials are issued per organisation and scoped to the products you have bought. Your account manager provisions them. If you do not have a contact yet, talk to our team.

Create an API key

Log in to account.polestarglobal.com, open the API Keys tab on your profile, and click Add new key. The key is shown once, so copy it straight away.

Create a separate key for each project or integration. Revoking one then leaves the others working. Full detail in Authentication.

Call an endpoint

Insights endpoints live under https://api.polestar-production.com. Send your Insights key in the api-key header, over HTTPS. Other products authenticate differently; see Authentication.

Read the envelope

Every list response uses the same shape, so one integration pattern works across the suite. See below.

Every list response has the same shape

List endpoints return a meta block alongside data. Use meta to paginate, and to trace a request when you contact support.

{
  "meta": {
    "limit": 100,
    "offset": 0,
    "total_count": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_timestamp": "2026-08-12T10:20:00Z"
  },
  "data": [ ]
}

Field	Meaning
`limit`	Page size. Defaults to 100
`offset`	Number of records skipped. Defaults to 0
`total_count`	Total matching records, so you know when to stop
`request_id`	Quote this when raising a support ticket
`request_timestamp`	When the request was served

Paginating

Pass limit and offset as query parameters and walk forward until offset + limit reaches total_count.

Start small

Leave limit at its default while you are exploring. Raising it makes responses slower to inspect and harder to read.

When something goes wrong

Errors return a consistent body, so one handler covers every endpoint.

{
  "status": 400,
  "title": "Bad Request",
  "detail": "timestamp_start must be an ISO 8601 timestamp",
  "field": "timestamp_start",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-08-12T10:20:00Z"
}

detail says what to fix and field says where, which together are usually enough to resolve a 400 without opening a ticket.

Status	Meaning	What to do
`400`	Malformed request	Read `detail` and `field`
`401`	Credentials missing, invalid or expired	Check Authentication
`403`	Your account lacks the permission for this operation	Talk to your account manager
`404`	Nothing matches the identifier you passed	Verify the ID
`409`	An equivalent record already exists	Reuse it instead of creating another
`422`	Well-formed but semantically invalid	Read `detail`
`500`	Fault on our side	Retry with backoff, then send us the `request_id`

Errors & Status Codes → covers every code and body in full.

Tracing a request

Every response carries an X-Correlation-Id header. Log it. When you report a problem, that value plus the request_id from the body lets support find your exact request without asking you to reproduce it.

Then what

Quick Start

A working call and a generated client, in three steps.

Concepts & Terminology

Vessels, voyages, zones, ports and fleets, and how they relate.

Testing & Sandbox

Where to try calls safely before you point at production.

Getting Started

Every list response has the same shape#

Paginating#

When something goes wrong#

Tracing a request#

Then what#

Every list response has the same shape

Paginating

When something goes wrong

Tracing a request

Then what