# Super API versioning and deprecation policy

The Super API versions breaking contracts in the request path. The current stable surface is `v1` at `https://app.getsupers.com/v1`. No sunset is currently scheduled for v1.

## Versioning

Breaking request or response changes use a new major path such as `/v2`. Compatible additions may ship within v1, including new optional request fields, new response fields, new model identifiers, new OAuth scopes that are not required by existing operations, and new endpoints. Clients should ignore response fields they do not understand and should discover models rather than hard-code a model list.

## Deprecation notice

When a resource is scheduled for deprecation, SuperPowers AI will document the affected operation, replacement, migration steps, deprecation date, and planned sunset date. Responses will use the [RFC 9745](https://www.rfc-editor.org/info/rfc9745/) `Deprecation` header with a Structured Field date and a `Link` relation of `deprecation` pointing to this policy or operation-specific guidance.

## Sunset notice

If a deprecated resource will stop responding, responses will also use the [RFC 8594](https://www.rfc-editor.org/info/rfc8594/) `Sunset` header with the retirement date. Except for urgent security, legal, abuse-prevention, or provider shutdown conditions outside our reasonable control, the planned sunset will be announced at least 90 days before retirement. A replacement path and migration guidance will be published whenever a replacement exists.

## Current status

The v1 models, chat-completions, and legacy completions endpoints are active and are not deprecated. The legacy completions operation remains supported, while new integrations should prefer `/v1/chat/completions`. That preference is guidance, not a scheduled sunset.

## Current machine-readable contract

- OpenAPI 3.1: https://getsupers.com/openapi.json
- Developer portal: https://getsupers.com/developers/
- OAuth Protected Resource Metadata: https://app.getsupers.com/.well-known/oauth-protected-resource/v1
- Contact: https://getsupers.com/contact