> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jojapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deprecating an Endpoint

> Mark an endpoint deprecated when another one replaces it: it keeps working, consumers see the replacement, and its responses carry the standard Deprecation headers.

When a new endpoint replaces an old one, deprecate the old one instead of deleting it. A deprecated endpoint keeps working exactly as before, including its billing. What changes is what consumers see:

* **On your API page**, a **Deprecated** badge in the endpoint list and, on the endpoint itself, a notice with the date, the endpoint to use instead and the planned removal date.
* **In the playground**, a warning above **Send Request**. Sending still works.
* **In the OpenAPI document and the MCP server**, the operation is marked `deprecated: true`, and the MCP tool's description sends agents to the replacement's tool.
* **On every response** of the endpoint, the standard headers described in [Response Headers](https://docs.jojapi.com/consumers/response-headers.md#deprecated-endpoints).

Nothing happens on the removal date. An endpoint is removed only when you delete it.

## Deprecate an endpoint

In **Studio**, open the endpoint and choose **Deprecate…** under **Deprecation**:

| Field | What it does |
| - | - |
| **Deprecated as of** | Today by default. A date up to a year ahead announces the deprecation; the headers carry that date from now on. |
| **Replaced by** | Another endpoint of the same API. Consumers see it as the endpoint to use instead. |
| **Planned removal** | Optional. Announced in the `Sunset` header; it cannot be before the deprecation date. |

**Edit** changes these later, and **Undo deprecation** takes the endpoint back to normal.

With the [CLI](https://docs.jojapi.com/studio/cli.md):

```bash theme={null}
jojapi endpoints deprecate GET /v1/users --successor "GET /v2/users" --sunset 2027-02-01
jojapi endpoints undeprecate GET /v1/users
```

Flags you leave out keep their stored values. `--successor none` and `--sunset none` remove them.

Through the [Management API](https://docs.jojapi.com/studio/management-api.md), `POST v2/provider/update-endpoint-deprecation` sets the whole deprecation at once (`endpoints:write`).

### From an OpenAPI document

An import reads OpenAPI's `deprecated` flag. Our extension `x-jojapi-deprecation` carries the date, the removal date and the replacement, and `jojapi export` writes it, so the deprecation travels with your document:

```yaml theme={null}
paths:
  /v1/users:
    get:
      summary: List users
      deprecated: true
      x-jojapi-deprecation:
        date: "2026-11-01T00:00:00Z"
        sunset: "2027-02-01T00:00:00Z"
        successor: "GET /v2/users"
```

The document decides: an operation without `deprecated: true` is not deprecated, so importing a document without the flag undoes a deprecation set in Studio. The preview shows it as a **deprecation** change, and `--keep-changed` keeps your endpoints as they are. Postman Collections say nothing about deprecation and leave it as it is.

## Before you delete it

The deprecation panel in Studio shows who still calls the endpoint: the subscribers whose requests reached it in the last 30 days, with their request counts and their latest call. The same list is available from the CLI:

```bash theme={null}
jojapi endpoints callers GET /v1/users --days 30
```

When nobody calls it any more, or the removal date you announced has passed, delete the endpoint. Consumers who still call it then get `404 Endpoint Not Found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.