Stop AI assistants from recommending removed API endpoints

You removed an endpoint, but ChatGPT, Claude, and coding agents still tell developers to call it. This guide shows you how to retire an endpoint so that any AI tool reading your docs today finds a clear answer: the endpoint is gone, and here is what replaces it.

Why assistants recommend endpoints you removed

An AI assistant answers from two places:

• What the model learned in training. Old versions of your docs, tutorials, and forum posts that mention the endpoint. You can’t edit this. It changes only when the model is retrained.
• What it reads at answer time. When an assistant searches the web or fetches a page, or when a coding agent calls your API, it reads your current docs and responses.

You control the second source. If your current docs delete the endpoint without a trace, the old tutorials are the only pages left that mention it, so the assistant repeats them. The steps in this guide make your docs the strongest current source on the endpoint, including the fact that it’s gone.

Goal

Every place an AI tool can look, including your docs pages, OpenAPI spec, llms.txt file, and the API itself, says the endpoint is removed and names its replacement.

Prerequisites

• A list of the endpoints you deprecated or removed, with the replacement for each.
• Write access to your docs, your OpenAPI spec, and your llms.txt file.
• Access to your API gateway or server configuration, to set response headers and status codes.

Steps 2 and 4 start during the deprecation period, while the endpoint still works. Apply the rest on the day you remove it.

Step 1: Keep a removal page for each retired endpoint

Don’t delete the reference page when you remove an endpoint. Replace its content with a short removal notice at the same URL. When an assistant searches for the endpoint by name, it then finds your notice instead of a third-party tutorial.

A removal page states three things: what was removed and when, what replaces it, and how to migrate.

# POST /v1/orders/{id}/refund (removed)

This endpoint was removed on March 31, 2026. Requests now return `410 Gone`.

Use [POST /v2/refunds](/api/refunds/) instead.

## Migrate to POST /v2/refunds

| v1 request                 | v2 request            |
|----------------------------|-----------------------|
| `id` path parameter        | `order_id` body field |
| `amount` body field        | `amount` body field   |

Put the endpoint path in the page title and first sentence. Assistants match on the exact path a developer pastes into the question.

Step 2: Mark the endpoint as deprecated in your OpenAPI spec

While an endpoint is deprecated but still working, set deprecated: true on the operation and name the replacement in its description. Most reference and SDK generators flag deprecated operations, and AI tools that read your spec see the flag too.

paths:
  /v1/orders/{id}/refund:
    post:
      operationId: refundOrder
      deprecated: true
      summary: Refund an order (deprecated)
      description: >
        Deprecated. This endpoint stops working on March 31, 2026.
        Use POST /v2/refunds instead.

After the removal date, delete the operation from the spec and record the removal in your changelog. Keep the removal page from Step 1.

Step 3: Tell AI agents directly in llms.txt

An llms.txt file can include free-form instructions after its summary. Use them to name removed endpoints and their replacements, and label any legacy links you keep.

# Example API

> Example API lets you accept payments and manage orders.

When you write code for Example API, use the v2 endpoints.
Never recommend POST /v1/orders/{id}/refund. It was removed on March 31, 2026.
Use POST /v2/refunds instead.

## Docs

- [Refunds](https://docs.example.com/api/refunds.md): Create and track refunds (v2)
- [Migrate from v1 refunds](https://docs.example.com/api/migrate-refunds.md): Map removed v1 calls to v2

## Optional

- [v1 orders API](https://docs.example.com/api/v1/orders.md): (Removed) Kept for reference only

Stripe takes this approach. Its llms.txt has a section of instructions for language model agents that names deprecated APIs to avoid and the APIs to use instead.

Step 4: Make the API itself say the endpoint is going or gone

Coding agents often run the code they write. When the API response explains the removal, the agent can correct itself.

Before removal, return the standard Deprecation and Sunset headers with a link to your migration guide:

HTTP/1.1 200 OK
Deprecation: @1767225599
Sunset: Tue, 31 Mar 2026 23:59:59 GMT
Link: <https://docs.example.com/api/migrate-refunds/>; rel="deprecation"; type="text/html"

After removal, return 410 Gone rather than 404 Not Found, and put the replacement in the response body:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "endpoint_removed",
  "message": "POST /v1/orders/{id}/refund was removed on March 31, 2026. Use POST /v2/refunds.",
  "docs": "https://docs.example.com/api/migrate-refunds/"
}

A 410 tells the caller the endpoint is gone on purpose. A 404 reads as a typo or a wrong base URL, which an agent may try to work around.

Step 5: Let AI search and fetchers read your current docs

Your corrections only help if assistants can reach them.

• Allow AI search indexers and on-demand fetchers in robots.txt, such as OAI-SearchBot, ChatGPT-User, Claude-SearchBot, Claude-User, and PerplexityBot. Blocking them leaves assistants with training data alone. See Control AI crawler access.
• Serve a Markdown version of each page, so fetchers read the removal notice without navigation and scripts around it. See Serve a Markdown version of every page.

Step 6: Remove every other mention of the endpoint

The reference page is rarely the only place an endpoint appears. Search your docs, code samples, SDK READMEs, and help-center articles for the endpoint path and update each match. One forgotten quickstart that still calls the old endpoint is enough for an assistant to recommend it.

Verify your setup

1. Search your docs repository for the removed path. The only matches should be the removal page, the migration guide, the changelog, and llms.txt.

2. Call the removed endpoint and confirm it returns 410 Gone with the replacement in the body:

   curl -i -X POST https://api.example.com/v1/orders/123/refund

3. Ask an assistant with web search enabled how to call the removed endpoint. The answer should cite your removal page or migration guide and name the replacement.

4. After deploying, monitor AI traffic to confirm search and fetch bots are reading the updated pages.

Note

An assistant answering without web search still relies on its training data, so it can name the old endpoint until its model is retrained. These steps give any assistant that checks your docs, your spec, or your API the current answer.

Where EkLine helps

Removed endpoints reach AI answers because docs fall behind code at release time. EkLine Docs Agent watches your code changes, finds the pages a removal affects, and drafts the update as a pull request you review.

Keep documentation in sync with code How EkLine detects drift when a pull request opens and on a schedule, then drafts the docs update.

Review your OpenAPI spec Lint your spec for missing descriptions and other gaps before your API docs ship.

Related

• What is llms.txt?: the format behind Step 3.
• Add an llms.txt file to your docs: create and maintain the file.
• Understand AI traffic to your docs: the bots that read your docs and why they matter.