Skip to content

Upcoming changes to the ambientCG API

A major update to the ambientCG website is scheduled to release at some point in late 2024 or early 2025. It can already be tested on beta.ambientCG.com and introduces new features and a more interactive user experience.

As a part of these updates, some changes to the underlying data model were necessary which will lead to a new API (v3) which will be announced at a later time. The existing APIs (v1/v2) will continue to work mostly as usual. However, some differences will be noticeable once the update is deployed:

Both v1 and v2 currently offer two separate download links, one using a HTTP redirect and one linking to the CDN directly. When the API was introduced this feature was implemented to accommodate certain CLI-based downloading tools which had trouble following HTTP redirects. Now, several years later, I have decided to retire this "split" and only offer the redirect-based links in the interest of more accurate statistics. For compatibility reasons, both fields will still be offered, but they will contain the same link. The vast majority of HTTP-libraries and tools should have absolutely no trouble with this change.

Removal of the thumbnailAssetId field in /v2/categories_json

Currently, the list of asset categories displays a thumbnailAssetId that is used as a "representative asset" for this category. The new version of the site displays categories in a different way and no longer stores such a "thumbnail asset". The value is therefore permanently set to null.

Changes to the creationMethod field

Both API versions contain a field describing the creationMethod of an asset. The new version of the site stores this information in a different way which is not easily representable as a single string. Therefore, many assets will have their creationMethod changed to UnknownOrOther.

Changes to data inclusion in /v2/full_json endpoint

The /v2/full_json endpoint allows clients to tailor the response data to their needs and to improve query performance using the include=X,Y,Z,... HTTP parameter. The list of possible values for this parameter will change to the following values:

  • statisticsData
  • labelData
  • relationshipData
  • fileData
  • previewData
  • technicalData

Queries using the OLD parameters will (mostly) be converted into the new format, but adjustments to this parameter may still be necessary.

Testing the changes

All upcoming changes can already be tested on beta.ambientCG.com. Please get in touch if you encounter any unexpected bugs, performance issues, inconsistencies or other problems.