API versioning policy

Last updated: 2026-05-24

This policy describes the contract between Qcrawl and any application that integrates with the Qcrawl API. The goal is simple: code you write against Qcrawl today should keep working without changes for the lifetime of the major version it targets.

Versioning scheme

The API is versioned in the URL path. The current version is v1, served at https://api.qcrawl.com/v1/. There is exactly one supported major version at a time.

What does not count as a breaking change

The following are additive and can ship in any release without warning. Your code must tolerate them.

New endpoints under the same major version.
New optional request parameters with safe defaults.
New fields in response objects.
New response headers.
New enum values for fields documented as extensible.
New error codes for failure conditions that previously returned the closest existing 4xx or 5xx code.
Performance improvements that change latency characteristics.
Bug fixes that bring observed behaviour in line with the documented behaviour.

What counts as a breaking change

Anything in this list is treated as breaking. Breaking changes never ship inside v1. They land in v2 with the timeline below.

Removing an endpoint, parameter, response field, or header.
Renaming any of the above.
Changing the type of a field (string to int, scalar to array, etc.).
Making a previously optional parameter required.
Changing the meaning of an existing enum value.
Changing HTTP status codes for documented success paths.
Changing authentication or rate-limit semantics in a way that requires client code to change.
Changing webhook payload shape in a way that breaks existing receivers.

Deprecation timeline

When we eventually release v2, the following timeline applies. v1 does not shut off the day v2 ships.

Day 0: v2 ships. v1 keeps working with no behaviour change. The changelog and this page list every breaking difference.
Months 0–12: Both versions are fully supported. Every v1 response carries a Deprecation: true header and a Sunset header pointing at the planned end-of-life date (per RFC 9745).
Months 12–18: v1 remains available. The Sunset date is reaffirmed in every response and the customer dashboard surfaces a migration banner. We email account owners at month 12 and month 15.
Month 18: v1 returns 410 Gone. Migration window ends.

Minimum total notice from v2 ship date to v1 shutdown: 18 months. We will not shorten this for any reason short of a critical security defect that cannot be patched in v1.

Individual endpoint deprecation

Occasionally a single endpoint inside the current major version may be deprecated — for example, because a better-shaped successor exists. In that case:

The endpoint continues to function and returns the same shape.
Every response from the deprecated endpoint carries Deprecation: true and Sunset: <date> headers.
Minimum window from first Deprecation header to removal: 6 months.
The endpoint's docs page links to the recommended replacement.

Security exceptions

If a vulnerability requires changing API behaviour to fix it, we will change the behaviour without the 6 or 18 month notice. We will document the change in the changelog within 24 hours and notify affected customers by email. Defects that affect billing or data confidentiality are treated this way; cosmetic or performance defects are not.

SDKs and tooling

Postman collection and OpenAPI specification are regenerated from the same source as the API itself. When new endpoints or fields ship, both update on the next deploy. The collection URL is stable: /qcrawl.postman_collection.json.

Reading deprecation headers

Both deprecation headers follow RFC 9745. In your client, treat them as advisory: log them, surface them to your engineering team, but do not interpret Deprecation: true as a failure signal — the endpoint still works until the Sunset date passes.

Deprecation: true
Sunset: Sat, 24 Nov 2027 00:00:00 GMT
Link: <https://qcrawl.com/legal/api-versioning/>; rel="deprecation"

Changelog

Every API change — additive or breaking — is recorded in the changelog with date, scope, and migration notes where applicable.

Questions

Engineering teams considering Qcrawl for a long-lived integration are welcome to ask for written confirmation of this policy on company letterhead. Email [email protected].