How do you keep agent-facing links working after a site migration?

A site migration can leave an assistant with a perfectly reasonable link to yesterday's documentation. The homepage opens, but an old setup page now lands on a generic welcome screen. The HTTP request succeeds while the original question goes unanswered.

Plan the migration around individual destinations. Preserve a route to the information a reader expected, and test the public redirect chain after deployment. Treat action endpoints separately from ordinary document links.

Start with a URL map

Collect old URLs from your content system, navigation and recent request logs. Include public documentation, downloadable references and regional pages. Save the set before changing the routing rules so you can compare old destinations with new ones.

Google's migration guide recommends building a mapping of old URLs to new URLs, updating internal links and annotations, and implementing server redirects. Those are its recommendations for site moves in Search; they are also useful inputs to your own link acceptance test. Google site move guidance.

Give each mapping a reason. An old installation guide should lead to the current installation guide or a page that explains the relevant replacement. Sending unrelated removed pages to the homepage leaves a reader to restart the search.

For pages with no replacement, decide how to communicate removal. Do not manufacture an equivalent destination just to make every request look successful. Make the resulting behavior part of the content review.

Inspect the chain a client actually follows

Start with the public hostname, including common old forms such as an HTTP URL or a previous subdomain. A local origin test can miss redirects added by the CDN or hosting platform.

For a document, save the redirect headers and final response:

curl -sS -L --max-redirs 8 \
  -D /tmp/move.headers \
  https://old.example.com/docs/setup \
  -o /tmp/moved-setup.html

The limit of eight is a guard for this diagnostic command, not an agent compatibility threshold. Review each Location, the final status and the content. An HTML page saying "not found" inside a successful response still fails the reader's task.

Keep the chain short enough to inspect. Prefer a direct mapping to the final destination over a trail through earlier migrations. Check loops and missing path segments explicitly. If a meaningful query parameter identifies a document version, decide whether the redirect must preserve or translate it.

Separate document moves from API moves

A permanent document redirect and a redirected write request have different consequences. MDN documents 308 Permanent Redirect as preserving the request method and body. Other redirect behavior can vary by code and client, so test the supported SDK rather than applying a document rule to all routes. MDN 308 reference.

For authenticated APIs, publish the current base URL and migration instructions. Check whether your client follows a redirect, resends credentials or stops. Never recommend blindly forwarding credentials to a new host. Use a sandbox and a harmless operation to validate the supported route before trying a write.

A client that cannot read a redirected write response may leave its caller uncertain about the outcome. Provide a lookup path for the operation and check it before another submission. A URL migration should not become a reason to create duplicate records.

Repair the links you control

Update the docs index, site navigation and published reference examples to point directly to current destinations. Redirects help old references; your current pages should not depend on them unnecessarily.

Check internal links in Markdown exports as well as HTML. If a site publishes an llms.txt index, inspect its destinations as part of the same inventory. The existence of that file does not establish that any particular assistant reads it.

For Google's migration signals, update canonical and regional annotations to the new URLs as its guide describes. Keep the distinction clear: correct search metadata does not guarantee that an assistant follows every link or prefers the new domain.

Define a migration result a reviewer can reproduce

Choose a sample covering a deep documentation page, a regional page and a removed route. For each, record the old URL, expected destination and observed final content. Ask the supported client to answer the same factual question before and after the move using your saved source.

Dedica's free scan can add public website readiness findings after the deployment. It is not a complete inventory of old links. Keep your URL map and redirect evidence as the migration's acceptance record.

Monitor requests to old destinations after release. A frequently used obsolete path deserves a specific review even when the homepage and your initial sample work.

Sources

• Site moves with URL changes, Google Search Central.
• 308 Permanent Redirect, MDN.