API versioning and deprecation policy

The policyCopy Anchor Link

An integration built against a released DALP API version keeps working when you upgrade the platform. DALP never removes an operation from a released version, and never changes one incompatibly, inside that version. A breaking change ships only on a new version, such as /api/v3, next to the version you already call. An operation or a whole version is removed only after a deprecation announcement that gives at least 90 days' notice.

Each version path is a separate contract:

Before a version is released, it can still change between development builds, and every such change is listed in the release notes. From its first release onward, the rule on this page holds for as long as the version is served.

What counts as a breaking changeCopy Anchor Link

A change is breaking when a client that worked against the previous release can fail against the new one without changing its own code. On a released version, DALP refuses these changes in its build:

• Removing a path, or a method on a path.
• Adding a required input: a path, query, or header parameter, or a request body field.
• Removing or narrowing an accepted input, such as dropping an enum value or tightening a format.
• Removing a field from a success response, or changing its type.

These changes are not breaking, and ship inside a released version:

• A new operation, or a new optional input on an existing one.
• A new field in a success response. Ignore response fields your client does not know; a strict decoder that rejects unknown fields breaks on a change DALP treats as compatible.
• A new error on an existing operation, for example a new rejection when a request conflicts with platform state. Handle errors by their class and the retryable flag, as Errors describes, so a new error code reaches a branch your client already has.
• Changes to descriptions, examples, summaries, and operation tags in the OpenAPI document.

How a deprecation is announcedCopy Anchor Link

A deprecated operation keeps working until its sunset date, and tells you on every response that it is going away. DALP announces a deprecation in two places at the same time: on the wire, and in the OpenAPI contract.

On the wire, every response from a deprecated operation carries three headers. That includes error responses, such as a rate-limit refusal, so a client sees the notice whatever the request outcome.

A full set of headers on one response looks like this:

Deprecation: @1779321600
Sunset: Wed, 19 Aug 2026 00:00:00 GMT
Link: <https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation>; rel="deprecation"; type="text/html", </api/v2/platform-status/data-freshness>; rel="successor-version"

Sunset is omitted while no sunset date is set. The API exposes all three headers to browser clients through cross-origin resource sharing (CORS), so a web application can read them as well as a server integration.

In the OpenAPI contract, the operation carries deprecated: true, documents the three headers on its success responses, and holds the announcement in the x-dalp-deprecation extension:

{
  "deprecated": true,
  "x-dalp-deprecation": {
    "deprecatedAt": "2026-05-21",
    "sunsetAt": "2026-08-19",
    "successors": ["/api/v2/platform-status/data-freshness"]
  }
}

A generated client marks the operation as deprecated, so your build warns where you call it. DALP's build refuses an operation marked deprecated without this announcement, which means a deprecation in the contract always comes with the headers and a notice window.

The notice windowCopy Anchor Link

The sunset date is at least 90 days after the deprecation date. DALP enforces this where the deprecation is declared: an announcement with a shorter window does not build, so no release can ship one.

The 90-day window is a minimum. DALP can keep a deprecated operation past its sunset date, and a later release can move the sunset further out. It never moves it closer than 90 days after the announcement.

The same window applies to a whole version. When a version is deprecated, every operation it serves answers with the headers, and the version path is removed only after its own sunset date.

What your integration should doCopy Anchor Link

Watch for the Deprecation header in the client you use against DALP, and treat it as a work item rather than an error. Log the method, path, and Sunset value once per operation, so the notice reaches a person before the sunset date.

When you see the headers:

1. Read the successor-version links for the replacement path.
2. Check the release notes for the release that announced the deprecation; its compatibility section names the operation and the change.
3. Move your calls to the successor before the sunset date, and test against a DALP build that still serves both.

After the sunset date, a release can remove the operation. A call to a removed path fails as a route that does not exist.

Current deprecationsCopy Anchor Link

How releases record API changesCopy Anchor Link

Every release entry has a compatibility section. It names each deprecation the release announces, with its sunset date and replacement, and each operation or version the release removes after its sunset. A new version is announced in the release that makes it stable. See the changelog for each release.

Next stepsCopy Anchor Link

• Errors for the error class and retryable flag that keep a client working when an operation gains a new error.
• V2 API reference and V1 API reference for each operation's contract, including its deprecation status.