Testing and mock servers | Pole Star APIs

Two ways to exercise these APIs from this documentation: against a mock server, or against production with your own key.

There is no separate customer test environment. Calls with a real key go to production, so build against the mock until you are confident in the shape of what you are sending.

Mock server

Every endpoint has a mock. On any reference page, open the environment menu above the request URL, which shows Production, and choose Cloud Mock. Try it then sends the request to the mock instead. Your browser remembers the choice, so switch back to Production when you want real data.

The mock needs no credentials. Leave the authentication field(s) empty. We build its responses from the contract, so they carry the right fields and structure without touching production or consuming quota. It stores nothing: a POST returns a success response, but the subscription it describes does not exist afterwards.

Use it to:

Check the response shape before you write a parser

Build a client while commercial arrangements are still in progress

Reproduce an integration bug without disturbing live data

Develop against endpoints your account does not yet have access to

Mock values are random, only the shape is real

The mock fills each field with a generated value of the right type. An imo can come back as a string of placeholder words and a draught as a negative number. Use it to validate structure and integration logic, never to assess data quality, coverage or a specific vessel, and do not demo it as real data.

Try it, with your own key

Endpoint pages have a Try it button that sends a real request from your browser.

Have a key ready

You create keys in the account service at account.polestarglobal.com, not here. See Authentication.

Check the environment and paste the key

Make sure the environment menu shows Production, then supply your credentials as that endpoint requires (see Authentication). The portal does not carry the key between endpoints, so you paste it again on each endpoint you try. That keeps it from leaking into pages you did not mean to call.

Send the request

The call goes to production under your own credentials, with your own permissions and against your own quota.

Read-only first

Try it sends genuine requests. A GET is harmless. A POST creates a real subscription, and a DELETE removes one. Start with reads, and use the mock for anything that writes until you mean it.

Choosing between them

	Mock	Try it
Needs a key	No	Yes
Data	Generated from the contract	Real
Hits production	No	Yes
Consumes quota	No	Yes
Good for	Shape, structure, integration logic	Confirming real behaviour and your own access
Not good for	Judging coverage or data quality	Exploratory calls that write

Work through the mock first, then confirm against production with a read. Integration problems are cheapest to fix in that order.

Before you go live

Test your webhook receiver

Point a subscription at a request-capture service, confirm the payload and your handling, then switch the callback URL to your own endpoint. Check callback_url_status reaches ok. See Notifications & Webhooks.

Handle the errors you have not seen yet

A 429 and a 500 both arrive eventually. Retry with backoff on those two, and never on a 400 or a 422. See Errors & Status Codes.

Log identifiers from the start

Store the request_id and X-Correlation-Id from every response, not just failures. Support can trace a request from either one.

Use a separate key per integration

Revoking one then leaves the others running.

Getting help

Talk to our team with the request_id from the response body and the X-Correlation-Id header. With those two values support can look your request up directly.

Testing & Sandbox

Mock server#

Try it, with your own key#

Choosing between them#

Before you go live#

Getting help#

Mock server

Try it, with your own key

Choosing between them

Before you go live

Getting help