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

# Versioning and deprecation

> What /v1 promises, what counts as a breaking change, and how much notice a removal gets.

## What `/v1` promises

Every endpoint is under `/v1`, and `/v1` is stable. We change it only in ways that keep a working integration
working, and we do not bump the version for them:

* a new endpoint, an optional request field or query parameter, a new field in a response or webhook event
* a new value of an enum, a new error `code`, a new webhook topic, a larger limit

So a client must **ignore response and event fields it does not know**, and treat an unknown status, topic or
error `code` as "something else", not as a failure.

## What breaks, and what happens then

A breaking change is one that can fail a working integration: removing or renaming an endpoint, field or
topic, changing a field's type or meaning, making an optional field required, or rejecting input that was
accepted. It does not go into `/v1`. It ships under `/v2`, and `/v1` keeps working beside it.

A `/v1` endpoint is removed only after at least **90 days' notice**, from the day it is deprecated to its
sunset date. The notice is in the endpoint itself:

| Where | What |
| - | - |
| `openapi.json` | the operation is marked `deprecated: true` |
| `Deprecation` response header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) | the day it was deprecated, as `@<unix seconds>` |
| `Sunset` response header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) | the day it stops answering, as an HTTP date |

The headers are on the endpoint's successful responses. Log them in your client, and alert on them.

## Clients

We do not ship SDKs. The OpenAPI document is the contract: [`/openapi.json`](https://docs.parser-app.com/openapi.json), also served by the API at
`https://api.parser-app.com/openapi.json`. Generate a client from it, and generate it again when a
new field appears:

```bash theme={null}
# TypeScript types
npx openapi-typescript https://api.parser-app.com/openapi.json -o parser.d.ts

# any other language
openapi-generator-cli generate -i https://api.parser-app.com/openapi.json -g python -o parser-client
```


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