API Stability

We keep aliases around. We don't pull paths out from under you.

If we rename an endpoint, the old path keeps working. There is no fixed calendar date for removal — the only signal you'll ever see is a rolling sunset in the response headers that tells you the earliest we could remove it. As long as your traffic keeps arriving, that floor rolls forward.

This page documents the policy, the headers, the live deprecations endpoint, and the internal scorecard we grade ourselves against release-by-release.

Our deprecation promise

1. Aliases are cheap. When we rename a path, we add the old name to a rewrite table and leave it there. Removal is a deliberate human decision, never a calendar trigger.
2. No fixed sunset dates. The Sunset: header publishes a rolling floor — the earliest we could remove this path. It never points backward and rolls forward as your traffic continues.
3. One global policy. Every alias follows the same window (/api/v1/deprecations shows the current values). Special cases — a path we genuinely need to remove on a tighter timeline for security reasons — are filed as separate policy decisions, not per-entry knobs.
4. Human-in-the-loop removal. Even when our internal cron flags an alias as removal-eligible, the default action is to leave it alone.

How the rolling window works

Three policy constants live in apps/web/lib/api-stability/policy.ts:

The Sunset: header on a deprecated response is computed as:

floor       = addedAt    + minimumGraceDays
activityEnd = lastHitAt  + (inactivityDays + noticeWindowDays)
sunset      = max(floor, activityEnd, now + noticeWindowDays)

So:

• Path just deprecated, still seeing traffic → Sunset = max(floor, lastHit + 120d). Honest about "earliest possible" and rolls forward every time you hit it.
• Path quiet for many weeks → tightens, but never closer than 60 days from now.

Response headers on deprecated paths

Every response from an aliased path carries:

Deprecation: true                                                  RFC 9745
Link: </api/v1/numbers/buy>; rel="successor-version",              RFC 8288
      <https://x402.dial.wtf/docs/api-reference/stability>; rel="deprecation",
      <https://x402.dial.wtf/docs/api-reference/stability>; rel="deprecation-policy"
Sunset: Sun, 16 Nov 2026 00:00:00 GMT                              RFC 8594 (rolling floor)
Warning: 299 - "deprecated; rolling sunset — see Link rel=deprecation-policy"

GET / HEAD requests get 308 Permanent Redirect with these headers. Body-bearing methods (POST / PUT / PATCH / DELETE) are rewritten transparently on the same request — the body reaches the successor handler intact, and the headers are stamped on the response.

Programmatic check — GET /api/v1/deprecations

curl https://x402.dial.wtf/api/v1/deprecations

{
  "policy": {
    "minimumGraceDays": 180,
    "inactivityDays": 60,
    "noticeWindowDays": 60,
    "docs": "https://x402.dial.wtf/docs/api-reference/stability"
  },
  "entries": [
    {
      "from": "/api/v1/lines/buy",
      "successor": "/api/v1/numbers/buy",
      "reason": "renamed numbers/buy",
      "addedAt": "2026-05-20",
      "minimumSunset": "2026-11-16",
      "estimatedSunset": "2026-11-16",
      "lastHitAt": null,
      "uniqueCallersLast30d": null
    }
  ]
}

Cached 5 minutes. No auth.

In @dial/api:

import { DialClient } from "@dial/api";
const client = new DialClient({ baseUrl: "https://x402.dial.wtf" });
const { policy, entries } = await client.apiStability.deprecations();

The SDK also emits a one-time console.warn per deprecated (path → successor) pair seen in your process — so a renamed path shows up the first time you hit it without you having to wire anything up.

How notifications reach you

Today, in-band: the headers above + the SDK warning + the /api/v1/deprecations endpoint. A daily cron (legacy-rewrite-review) aggregates the structured api.legacy_path_hit events that every alias emits, and is wired to email + dashboard banner pipelines as they land (tracked at #119). Org-level Slack / Discord delivery lands with #46.

Stability scorecard

Every row is a question we want to answer "yes" to before we tell a paying customer "the API is stable." We grade ourselves honestly so the gap turns into a roadmap.

Versioning & naming

Deprecation signalling (HTTP)

Rolling sunset window

Telemetry

Contract testing & breaking-change detection

Idempotency, retries, and write safety

Errors

Rate limiting & quotas

Webhooks & async surfaces

Documentation & change communication

Authentication & key lifecycle

SDK lifecycle