worldmonitor/docs/api-versioning.mdx

---
title: "API Versioning and Deprecation"
description: "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.

## 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.

## 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](/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 carry the HTTP signals
   below.

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

Responses from a deprecated operation or version include:

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

- [`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 migration guidance or this policy.

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](/changelog) for human-readable release notices.