Deprecating an Endpoint

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.

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:

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, 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:

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:

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.

Getting Started

API Studio

API Consumers

API Gateway

Account

Deprecate an endpoint

From an OpenAPI document

Before you delete it

​Deprecate an endpoint

​From an OpenAPI document

​Before you delete it

Deprecate an endpoint

From an OpenAPI document

Before you delete it