{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Change Policy — kwery Docs","siteUrl":"https://docs.kwery.co","description":"What kwery considers a breaking vs. non-breaking API change, and how changes are announced."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-change-policy","__idx":0},"children":["API change policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"non-breaking","level":2,"__idx":1},"children":["Non-breaking changes — may happen at any time "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["backwards compatible"]}," and can ship without notice. Your integration"," ","must tolerate them (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/robustness"},"children":["Robustness"]},"):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding new endpoints,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding new ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," request parameters,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding new fields to responses (at any nesting level),"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding new sources, countries, keys, or topics,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding new ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/change-events"},"children":["change-event"]}," types,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["relaxing a validation rule (accepting input that was previously rejected)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The practical rule for your client code: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["read the fields you need and ignore the rest."]}," ","Never fail on unknown fields, and never depend on field order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"breaking","level":2,"__idx":2},"children":["Breaking changes — versioned and announced "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We consider all of the following ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incompatible"]},", and none of them ship silently:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["removing or renaming an endpoint, request parameter, or response field,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["changing a field's type, meaning, or default value,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["making an optional parameter required,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["changing or removing existing values of enumerated fields — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", per-result"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," strings, event types,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["tightening a validation rule (rejecting input that was previously accepted)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an incompatible change is necessary, it is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"pricing-changes","level":2,"__idx":3},"children":["Pricing and credit changes "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Per-source ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/pricing#source-weights"},"children":["credit weights"]}," may change if a source's delivery"," ","cost structurally changes. Any change is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["announced in advance and never applies"," ","retroactively"]}," to a running billing period."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"scope","level":2,"__idx":4},"children":["What this policy does not cover "]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/trust#components"},"children":["trust ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completeness"]}]}," tells you when content is thin."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Undocumented behavior."]}," Anything not described in this documentation or the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference"},"children":["API Reference"]}," may change without notice. If you depend on something"," ","undocumented, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://kwery.co/contact"},"children":["tell us"]}," — we'd rather document it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/robustness"},"children":["Robustness"]}," — how to build an integration that rides through"," ","non-breaking changes and bad days."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors-and-limits"},"children":["Errors & limits"]}," — the response envelope and status codes."]}]}]},"headings":[{"value":"API change policy","id":"api-change-policy","depth":1},{"value":"Non-breaking changes — may happen at any time","id":"non-breaking","depth":2},{"value":"Breaking changes — versioned and announced","id":"breaking","depth":2},{"value":"Pricing and credit changes","id":"pricing-changes","depth":2},{"value":"What this policy does not cover","id":"scope","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"API Change Policy — kwery Docs","description":"What kwery considers a breaking vs. non-breaking API change, and how changes are announced."}},"lastModified":"2026-09-14T12:09:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/api-change-policy","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}