Cargoplot APICargoplot API
API docs
OpenAPI spec

Versioning

The version is in the path

Every endpoint lives under /v1. While it stays there, we will not make a change that breaks a client written against it.

What may change without warning

Additive things, which a correctly written client ignores:

  • New fields on existing responses. Do not use a parser that rejects unknown fields — treat anything you do not recognise as ignorable.
  • New endpoints, new query parameters, new optional filters.
  • New enum values. This is the one that catches people: a status you have never seen can appear because we added a state. Handle an unrecognised enum as "something else" rather than crashing or, worse, silently mapping it to a state it is not.

What will not change under you

  • An existing field will not be removed, renamed, or change type.
  • An endpoint will not disappear or change what it accepts.
  • An enum value we have shipped will not change meaning.

If we ever need to break one of these, it goes in a /v2 and /v1 keeps working while we tell you how long for. We do not have a deprecation policy to point at yet — when there is something to deprecate, it will be announced in the changelog before it happens, not after.

What can be written

Inquiries are the first thing the API lets you write: you can raise one, change it, cancel it and delete it — see creating and updating inquiries. A shipment's cargo-ready date followed: it can be moved until the cargo is picked up. Your client references joined it on the same endpoint, and can be changed until the shipment is completed or cancelled — see changing a shipment. Both writes arrived as new endpoints alongside the reads, not as changes to them.

Everything else is read-only. The set of write operations is pinned by a test over the generated spec rather than by anyone remembering, so a new write endpoint fails the build until it is a deliberate decision and gets its entry in the changelog.

So you can build reporting, dashboards, alerting and sync-into-our-system integrations, raise inquiries from your own systems, pass on a cargo-ready date that moved, and keep your own order references on a shipment. You cannot create a shipment; that still happens in the app, from an accepted quote.

Keeping up

  • /openapi.json is generated from the API's own definitions on every deploy, so it always describes what is running. If you generate a client, regenerate it from this rather than pinning a copy.
  • /changelog.md is the plain-text changelog, served from the API itself.
  • The changelog page is the same content, rendered.

There is no version number to poll and no Sunset header to watch. The spec is the contract, and the changelog is the narration.