> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning and Deprecation

> WorldMonitor REST compatibility guarantees, deprecation notices, and sunset signals for agents and long-lived integrations.

WorldMonitor versions public REST APIs in the URL:

```
https://api.worldmonitor.app/api/<domain>/v<major>/<operation>
```

For example, `/api/market/v1/list-market-quotes` is a version 1 operation.
Different domains may advance independently, so clients should use the version
present in each path rather than assuming one global API version.

One domain currently deviates from that shape: shipping v2 puts the version
before the domain — `/api/v2/shipping/<operation>` (e.g.
`/api/v2/shipping/route-intelligence`). Every other domain is at v1 with the
standard `/api/<domain>/v1/` prefix.

## Compatibility within a major version

Within a published major version, WorldMonitor may add optional request fields,
response fields, operations, and enum values. Existing fields keep their
meaning and type. We do not remove or rename operations or fields, make an
optional field required, or otherwise introduce an intentionally breaking
change without publishing a new major-version path.

Clients should ignore response fields and enum values they do not recognize.
The bundled [OpenAPI specification](https://www.worldmonitor.app/openapi.yaml)
is the source of truth for the currently published contract.

## Protobuf compatibility check

The public API is JSON over HTTP. On pull requests that touch proto paths, CI
runs `make breaking` against `origin/main` with Buf's `FILE`, `PACKAGE`, and
`WIRE_JSON` rules. That job fails the `proto-breaking` check-run when the
baseline is missing or a rule is violated; it is not yet one of the deploy-gate
required contexts that branch protection aggregates for merge. `WIRE_JSON` is
intentional: generated JSON field names and shapes are part of the versioned
REST contract. The repository does not currently ship binary-protobuf
consumers, so the binary `WIRE` rule is intentionally not enabled. The CI
workflow fetches full Git history so a missing `origin/main` baseline fails the
check instead of allowing a vacuous pass.

## Deprecation timeline

When WorldMonitor replaces or retires a public REST version or operation:

1. We publish the replacement and migration guidance in the API documentation
   and [changelog](/docs/changelog).
2. The deprecated surface remains available for at least **six months** after
   the public deprecation announcement.
3. We publish a specific shutdown date at least **90 days** before that date.
4. Until shutdown, requests to the deprecated surface will carry the HTTP
   signals below. (This is forward-looking policy: nothing is deprecated
   today, so no endpoint currently emits them.)

Security, privacy, legal, or upstream-provider emergencies may require a faster
change. When that happens, we publish notice and migration guidance as soon as
practical.

## Machine-readable signals

### Policy discovery on current (non-deprecated) responses

[RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) allows a `Link` with
`rel="deprecation"` without a `Deprecation` header, so agents can find this
policy before any surface is retired. Current WorldMonitor API and homepage
responses may include:

```http theme={null}
Link: <https://www.worldmonitor.app/api-versioning.md>; rel="deprecation"; type="text/markdown"
```

That header is **not** a deprecation notice. It points at the static
[markdown policy](https://www.worldmonitor.app/api-versioning.md) (this HTML
page is the human twin).

### Signals on a deprecated operation or version

Responses from a deprecated operation or version also include:

```http theme={null}
Deprecation: @1782864000
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://www.worldmonitor.app/api-versioning.md>; rel="deprecation"; type="text/markdown"
```

* [`Deprecation`](https://www.rfc-editor.org/rfc/rfc9745.html) is the date the
  surface became deprecated, expressed as an HTTP Structured Field date.
* [`Sunset`](https://www.rfc-editor.org/rfc/rfc8594.html) is the final
  availability date in HTTP-date format.
* `Link` with `rel="deprecation"` points to this policy or to migration
  guidance. On current surfaces it is policy discovery only.

The OpenAPI operation is also marked `deprecated: true`. Agents should treat
`Deprecation` as a migration warning and stop scheduling calls beyond the
`Sunset` date.

No currently supported endpoint sends these headers merely because its path
contains `v1`. A version number identifies a compatibility boundary; it does
not by itself mean the version is deprecated.

## Client guidance

* Pin the complete versioned path from the OpenAPI document.
* Regenerate or update clients when a replacement major version is published.
* Monitor `Deprecation`, `Sunset`, and `Link` on successful and error responses.
* Subscribe to the [changelog](/docs/changelog) for human-readable release notices.