Breaking Changes in thingsHub 7.0

This document outlines the changes that users must be aware of when upgrading from thingsHub 6.0 to thingsHub 7.0:

Introduction of Business Objects

With thingsHub 7.0, we are introducing the concept of Business Objects, which represent key data entities that reflect various aspects of your business operations. This allows users to create and manage custom fields.

The Assets business objects are currently supported.

Understanding the breaking changes in thingsHub 7 requires some familiarity with this concept. The documentation for the Business Objects is available at: Business Objects

Replacing v3/assets with v4/assets

With ThingsHub 7.0, we have combined the Assets and Tracked Assets lists to a single Assets Inventory, and removed all support for v3/assets… endpoints, replacing them with the unified v4/assets endpoints.

The new asset endpoints are compatible with the Business Objects, and support Custom fields of various types.

A summary of the API Changes and newly added v4 endpoints are mentioned in the table below:

{
  "description": "A Red Porsche Car",
  "id": "asset-car-2",
  "metadata": {
    "color": "Red",
    "company": "Porsche"
  },
  "name": "319934",
  "created_at": "2025-03-17T15:35:05.243552Z",
  "updated_at": "2025-03-17T15:35:05.243552Z"
}

{
  "color": "Red",
  "company": "Porsche",
  "id": "asset-car-2",
  "name": "319934",
  "created_at": "2025-03-17T15:35:05.243552Z",
  "updated_at": "2025-03-17T15:35:05.243552Z"
}

{
  "collection": [
    {
      "id": "asset-car-2",
      "color": "Red",
      "company": "Porsche"
      "name": "319934",
      "created_at": "2025-03-17T15:35:05.243552Z",
      "updated_at": "2025-03-17T15:35:05.243552Z"
    },
    ...
  ],
  "total_count": 15,
  "total_pages": 2,
  "page": 1,
  "count": 10
}

Replacing v3/assets-import endpoint with v4/assets-import

With ThingsHub 7.0, we have replaced the v3/assets-import with the improved v4/assets-import endpoint, with Business Objects fields support.

This means that users will now be able to import data into custom fields that they have created as Business Objects.

API users of the v3/assets-import APIs will have to make the following changes to ensure proper functioning for asset import:

• Use the POST https://{your_tenant_url}/api/v4/assets-import endpoint instead of the https://{your_tenant_url}/api/v3/assets-import endpoint.

• If you want to use a key other than id, uid as the ID, or you use a key other than name as the Name, you will also need to provide the following query parameters:

  1. id_mapping_field → The JSON key to use as the ID

  2. name_mapping_field → The JSON key to use as the Name

For further details on how Asset Import works in thingsHub 7, and the relevant validations that come with this, please consult our official documentation on this: Asset Import in ThingsHub

Deprecation of the v3/tracked-assets endpoints

As the old Asset Inventory and Tracked Asset inventories have been combined to a single Assets inventory, all the v3/tracked-assets... endpoints have been deprecated with thingsHub 7.0.

This also means that the canonical way to bind and unbind assets has also changed:

Please go through the swagger page of your thingsHub tenant for the request and response formats.

Breaking helm changes:

Only for On-Premise Customers

There are no breaking Helm changes coming with thingsHub 7.0.

✅ Required Actions

Users should take the following actions to adjust to these breaking changes:

• Update any existing API calls to use the v3/assets endpoints to v4/assets as per the above table.

• Use the v4/assets-import endpoint for importing assets into thingsHub instead of the now removed v3/assets-import

• Use the new /v4/assets/{id}/bind and /v4/assets/{id}/unbind endpoints for binding and unbinding assets respectively.