# API deprecation

URL: /products/api/deprecation · Id: `capability:api-deprecation`

> API deprecation retires an API version no Tenant needs: it posts a sunset date, sends `Deprecation` and `Sunset` headers, and lists each Tenant still pinned.

API deprecation retires an API [Version](/business/nouns/version) no [Tenant](/business/nouns/tenant) needs: it posts a sunset date, sends `Deprecation` and `Sunset` headers, and lists each Tenant still pinned.

## Contract
Status `planned`, as `Interface.deprecate` and `Interface.sunset`. Deprecating `v1` posts its sunset date to the [Changelog](/code/systems/changelog) and adds both headers to every `v1` response. The pin report lists each Tenant whose `apiVersion` is `v1`, with its last call.

Sunset stops a version only when no Tenant pins it. Until then, every version a Tenant pins keeps serving, and nothing retires it.

To see who still calls a version today, list the Tenants pinned to it:

```bash
curl "https://api.sb/leaseline.app/tenants?where=apiVersion%20%3D%20v1" \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

[Versioning your API](/products/api/versions) covers pins and gates.

## Verbs
None.

## Interfaces
None.

## Example
Leaseline ships `v2` in month 6. Three months later Harbor Residential has moved its pin and no Tenant calls `v1`, so the pin report is empty and `v1` can be retired.