Generate an API client from the contract

There is no hand-written Pole Star SDK, and that is deliberate. Every endpoint here comes from an OpenAPI 3.1 contract generated from the running service; each category has its own contract, so you can generate a typed client per category and regenerate it when that contract moves.

Regenerating keeps your client in step with the contract.

Generating a client

Get the contract

The OpenAPI contract behind these pages is downloadable from this site. Save it, or reference it by URL directly in your build.

Run a generator

Any OpenAPI 3.1 generator works. openapi-generator covers most languages:

Swap -g for java, python, go, csharp or whichever target you need.

Wire up authentication

Generated clients expose the security scheme as configuration. Configure it once on the client rather than per call: an api-key header for Insights, or the equivalent scheme for other products, read from the environment.

Regenerate on a schedule

Pin the contract version you generated from and check for a newer one deliberately. Regenerating during an incident adds risk to a problem you are already handling.

3.1, not 3.0

The contracts are OpenAPI 3.1. Most generators support it, but a few still default to 3.0 and will either fail or mangle schemas without warning. Check your generator's 3.1 support first.

What you get for free

Because we generate the contract from the service instead of maintaining it by hand, a generated client inherits some things worth relying on:


Types that match production	Response models come from the code that serves the response
One envelope	Every list endpoint returns the same `meta` and `data` shape, so pagination is written once
One error model	A single error type covers the suite
Enum values	Vessel types, zone types and event types arrive as real enums, not loose strings

Things to handle yourself

Code generation gives you transport and types. The rest is yours.

Pagination. Generators produce a call, not a loop. Write the walk once against the meta block. See Pagination & Filtering.

Retries. Retry 429 and 5xx with backoff. Do not retry 4xx, because the request will keep being wrong.

Correlation. Log the request_id from the body and the X-Correlation-Id header on every call. Without them a support conversation starts with reproducing the problem.

Additive change. Ignore fields you do not recognise. New fields and enum values ship without a version bump, and a strict deserialiser will break on them. Versioning & Deprecation sets out the contract.

Generate per category, not per endpoint

Scope the generated client to the categories you hold. A narrower client is faster to review, and it fails loudly when someone reaches for surface you have not bought.

Letting an assistant do it

If you would rather not run a generator, an assistant connected over MCP can read these contracts directly and write the client for you, including the pagination loop and retry policy above, which generators leave out. AI Assistants & Agents covers the setup.

Quick Start

From API key to a working call, then on to a generated client.

Pagination & Filtering

The walk your generated client will not write for you.

Errors & Status Codes

What to retry, and what not to.

SDKs & Code Generation

Generating a client#

What you get for free#

Things to handle yourself#

Letting an assistant do it#

Related#

Generating a client

What you get for free

Things to handle yourself

Letting an assistant do it

Related