Skip to main content
We give at least 30 days’ notice before a breaking change to a published endpoint, and before removing one. A renamed parameter keeps answering under its old spelling for at least 30 days after the rename is announced. These are minimums: a change with a wide blast radius gets longer. A change is breaking if a request that works today stops working, or if a field a caller is already reading changes its meaning, its type, or disappears.

What changes without notice

  • Adding a new endpoint, a new optional parameter, or a new field to a response body. Parse responses permissively — an unrecognised field is not an error and will not be announced.
  • Widening what an existing parameter accepts, or adding a value to an OPEN vocabulary (source registries, form types, language codes). A closed enum gaining a value is announced. On the Events and Stories list and summary endpoints this includes serving a request as the canonical one it can only mean, reported in applied_filters.normalized; such a rewrite is withdrawn only with the breaking-change notice period.
  • Correcting data. A score, a classification or a count that was wrong is fixed as soon as we know, and the changelog says so — waiting 30 days to stop serving a wrong number would be the opposite of a customer protection.
  • Fixing a defect where the current behaviour is itself the hazard: a 200 hiding a wrong answer, a filter that silently does not apply, or a value we publish and then refuse.
Parse responses permissively. A new field is not a breaking change and will keep appearing; a client that rejects unknown fields has opted into breakage we do not announce.

Deprecated, retired, removed

Three different states. Only one of them stops working. Older parameter names lists every older spelling, deprecated parameter, parameter that no longer applies and older list key, with what to send instead.

How you are told

Response fields scheduled for removal

Still returned and still populated until the date below. Each is marked deprecated in its endpoint’s response schema.

If a change breaks you

Email support@gdeltcloud.com with the request that changed behaviour. A breaking change we shipped without the notice above is our defect, not your migration.