# Versioning and deprecation

> v1 is stable. New endpoints, fields and values can arrive at any time, so ignore what you do not know. Anything we remove or change is announced at least six months ahead.

Source: https://getlaunchlist.com/help/docs/api/versioning

---

The API lives at `/v1`, and **v1 is stable**. This page says what that means: what can change
without warning, what never changes inside v1, and how much notice you get when something has to go.

## Changes that can land at any time

These are additive. They can ship in v1 on any day, with no notice:

- new endpoints
- new fields in a response
- new optional parameters on a request
- new values in a field that lists a fixed set of values, such as a status or a stage

Write your client to cope with them. **Ignore fields you do not know**, and treat an enum value you
do not recognize as "something new" rather than as an error. A client that rejects an unknown field
will break the day we add one.

## Changes that need a new version

A breaking change never ships in v1. It ships in a new version, at `/v2`, and v1 keeps working beside
it. Breaking means a call that worked before now fails or means something else, for example:

- removing or renaming an endpoint, a parameter or a response field
- changing the type or the meaning of a field
- making an optional parameter required

## Notice before anything is removed

If something in v1 will be removed or changed, we tell you **at least 6 months ahead**, in two places:

1. **The changelog**, in these docs. The entry names what is changing, the date and what to
   use instead.
2. **Response headers on the affected endpoint.** Each response carries a `Deprecation` header
   ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) from the day the notice starts, and a `Sunset`
   header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the date it stops working.

The headers look like this. The values are an example, not a live notice:

```http
Deprecation: @1798761600
Sunset: Fri, 01 Jan 2027 00:00:00 GMT
```

A client that logs these two headers will hear about a removal without anyone reading the changelog.

## Today

Nothing in v1 is deprecated, so no response carries either header. The
[OpenAPI document](/help/docs/api/openapi) always describes the API as it is now.

## Common questions

### Will the LaunchList API change under my integration?

v1 will not change in a way that breaks a working client without notice. New endpoints, new response fields and new enum values can appear at any time. Anything removed or changed is announced at least six months ahead.

### How will I know an endpoint is being removed?

We post it in the changelog, and the affected responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the removal date, at least six months before it.

### Is anything in the LaunchList API deprecated today?

No. Nothing in v1 is scheduled for removal.