API Version Information and Changelog

GoodData's public API is versioned. This allows GoodData to release new API without breaking existing clients for the purposes of deprecation and end-of-life of old API. GoodDatae API versioning will not break existing clients without giving you a chance to adapt the newer API. Versioning is straightforward to implement on the client side by using the X-GDC-Version custom header. API version changes are tracked in the API Changelog.


When GoodData makes a change to a resource, the global version will increase and GoodData assigns the new version of the individual updated resource to the new version number. 

The X-GDC-Version header: {version} specifying version of an API is used to return the current version. Please note that it is best practice to use the latest version for any versioned or unversioned resource.

The GoodData server selects the API version based on received X-GDC-Version header. If no header is received, then server returns the oldest (deprecated) API version available. A deprecated API version is any version older than latest.

X-GDC-Version Header

Change your X-GDC-version header via you preferred HTTP client software.

  • If you have set the X-GDC-Version header correctly to the current version, the latest API resource is returned.
  • If the X-GDC-Version has an older version number, the older resource is returned with a deprecation warning and information about the most current version.
  • If the version is not specified and the: 
    • resource is versioned, the oldest, non end-of-life version is served. 
    • resource is not versioned, the only available version is served.

X-GDC-Deprecation Header

The X-GDC-Deprecated header is added to any returned versioned resource and provides information about deprecation and end-of-life.


End-of-life=’RFC1123 DATE-TIME’; valid-version: INT

X-GDC-DEPRECATED: "End-of-life=Sat, X Nov 20XX 12:00:00 GM; valid-version=2"


Deprecation dates are communicated as a part of release notes and within the returned API resource. Please stay subscribed to release notes for information on API deprecation and end-of-life. 

When an existing API call is updated, the global API version is incremented. Deprecation date headers will be added into the original API (into the version to be deprecated). Information about the deprecation will be added into the Release Notes when a new API resource is published. Generally APIs updated have an end-of-life approximately one calendar year after version update (deprecation), in this period both versions of the API (current and deprecated) are supported. Upon the end of the deprecation period (end-of-life), the old version of API is removed and only the new version remains.

API Version Changelog

Version Date released Changelog Resource Changed / Doc LinkEstimated End-of-Life
2September 8 2018

Two additional query parameters for Listing Projects and paging in response.

User projects and rolesSeptember 2019
3November 15 2018Changed filter merging and evaluation logic in executeAfm resource.NANA