API change policy

You should be able to build against the kwery API without worrying that an update on our side breaks your integration overnight. This page is the commitment that makes that safe.

The following are backwards compatible and can ship without notice. Your integration must tolerate them (see Robustness):

• adding new endpoints,
• adding new optional request parameters,
• adding new fields to responses (at any nesting level),
• adding new sources, countries, keys, or topics,
• adding new change-event types,
• relaxing a validation rule (accepting input that was previously rejected).

The practical rule for your client code: read the fields you need and ignore the rest. Never fail on unknown fields, and never depend on field order.

We consider all of the following incompatible, and none of them ship silently:

• removing or renaming an endpoint, request parameter, or response field,
• changing a field's type, meaning, or default value,
• making an optional parameter required,
• changing or removing existing values of enumerated fields — status, per-result reason strings, event types,
• tightening a validation rule (rejecting input that was previously accepted).

When an incompatible change is necessary, it is documented and communicated in advance with enough lead time to adapt your client code, and where feasible shipped as a new API version with a reasonably long sunset period for the previous one.

Per-source credit weights may change if a source's delivery cost structurally changes. Any change is announced in advance and never applies retroactively to a running billing period.

• The data itself. Marketplaces change their pages; fields a source stopped exposing can become empty. That's a data reality, not an API change — the field stays in the schema, and trust completeness tells you when content is thin.
• Undocumented behavior. Anything not described in this documentation or the API Reference may change without notice. If you depend on something undocumented, tell us — we'd rather document it.

• Robustness — how to build an integration that rides through non-breaking changes and bad days.
• Errors & limits — the response envelope and status codes.