Give callers an announcement window

A paid endpoint shouldn’t disappear between two registry refreshes. Publish a stop date while the old route still works, then give agents at least 30 days to move.

The notice needs four facts: the endpoint name, its final service date, the successor URL, and any request differences. Put them at the start of the old registry description. Don’t bury the date in an article that a routing model may never read.

A machine-readable record could look like this: 

{
  "name": "link-unshortener",
  "status": "deprecated",
  "sunset": "2026-09-09T00:00:00Z",
  "successor_url": "https://api.agentutility.ai/url-expander"
}

If your registry schema can’t hold those fields, write the same facts into the description. During the announcement window, successful responses should also include Sunset and Link headers.

Why be this explicit? Agentutility currently lists 799 paid endpoints across 17 clusters, priced from 0.001 to 0.5 USDC per call. A router will keep choosing an old entry if it still reads like an active tool.

Use 410 Gone for a retired paid route

A 301 Moved Permanently response looks convenient. It’s risky for an x402 POST.

Some clients may turn the redirected request into a GET. Others won’t forward the body or payment headers. And a payment authorization created for the old resource shouldn’t be treated as authorization for a different URL.

410 Gone makes the state unambiguous. Return it before issuing an x402 payment challenge, so the caller isn’t asked to pay for a tombstone. 

HTTP/1.1 410 Gone
Content-Type: application/problem+json
Sunset: Wed, 09 Sep 2026 00:00:00 GMT
Link: <https://api.agentutility.ai/url-expander>; rel="successor-version"

{
  "error": "endpoint_retired",
  "endpoint": "link-unshortener",
  "successor": "url-expander",
  "successor_url": "https://api.agentutility.ai/url-expander"
}

The agent can read successor_url, update its route cache, and start a fresh x402 exchange against the replacement.

Keep 301 for GET routes where the move preserves the query contract, response shape, price, and settlement terms. If a POST move is strictly transport-level, 308 Permanent Redirect preserves the method and body. Client support still varies, so a paid API should prefer an explicit migration over redirect magic.

Replace the registry entry at cutoff

The registry change should land before the old route stops accepting paid calls.

During the announcement window, keep both entries discoverable. Mark the old one as deprecated and cross-link the replacement. The successor’s description should name the jobs it accepts without assuming the caller has read the retirement notice.

At cutoff, remove the old entry from active discovery. Leave its HTTP tombstone online for at least 90 days. That split matters: routing models shouldn’t select a dead tool, but agents with cached manifests still need an answer they can act on.

Also preserve the old input fields when they still make sense. If the successor changes a field name or output type, say exactly what changed and show the new request. Silent schema drift is harder to recover from than a dead URL.

A real catalog pair shows the handoff

Take two existing WebProbe routes: link-unshortener and url-expander. Both accept a URL, follow its redirect chain, and return the final destination with hop details. Each costs 0.02 USDC per call.

This isn’t a retirement notice. It’s a concrete migration example using live catalog names.

A caller using the first route sends: 

POST /link-unshortener HTTP/1.1
Host: api.agentutility.ai
Content-Type: application/json

{"url":"https://httpbin.org/redirect/2","max_hops":10}

After a deprecation window, the replacement call changes only the path: 

POST /url-expander HTTP/1.1
Host: api.agentutility.ai
Content-Type: application/json

{"url":"https://httpbin.org/redirect/2","max_hops":10}

The routing instruction is short: use url-expander for short links or redirect-chain inspection. If link-unshortener returns 410, read successor_url and retry there through a new x402 payment flow.

Dead silence teaches an agent nothing. A dated 410 tells it exactly what to do next.