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

Stated plainly, because a policy that implies nothing ever moves is one we would break in a week — and because two of these are customer protections rather than exemptions from one.
  • 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.
  • 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, routinely read as synonyms. Only one of them stops working.

How you are told

Which endpoints are governed by an executable contract

17 of 90 published endpoints are descriptor-backed: the server imports the same descriptor this documentation, the OpenAPI spec and the MCP tool schema are generated from, and validates your request against it at request time. Their published contract cannot drift from their behaviour, and they answer 400 UNKNOWN_PARAM — with a suggested spelling — for a parameter they do not declare. The remaining endpoints are live and supported; their published shape is hand-maintained, and a parameter they do not recognise is reported in applied_filters.ignored rather than refused. Check applied_filters.ignored on every response. It is the difference between a filter that narrowed your result and one that was dropped. GET /api/v2/meta/endpoints reports the current split, per endpoint, in its coverage key.

Currently deprecated parameters

Still supported and still applied. Migrate at your convenience; you will get the notice above before any of them stops working.

Retired parameters

Accepted, never rejected, and no longer affecting results. Each is named in applied_filters.retired on any response where you send it, with this sentence.

Removed paths

These answer 410 Gone. Each names its own successor in the response body and in a Link: <…>; rel="successor-version" header, so you do not need this page to migrate — call the path and read the answer.
  • /api/media-events
  • /api/public/entity-geg
  • /api/public/entity-geg/baseball-card
  • /api/public/entity-geg/source-mix
  • /api/public/entity-geg/theme-abnormality
  • /api/public/media-events
  • /api/public/media-events/{cluster_id}
  • /api/public/media-events/{cluster_id}/conflict
  • /api/public/media-events/{cluster_id}/events
  • /api/public/media-events/{cluster_id}/meta
  • /api/v1/cameoplus-events
  • /api/v1/conflict-events
  • /api/v1/conflict-events/summary
  • /api/v1/entity-geg
  • /api/v1/media-events
  • /api/v2/markets

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.