Skip to main content

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