Migration of APIv1 to APIv2

It is IXON’s mission to help industrial machine manufacturers create value with the IoT. In order to encompass more advanced features that help industrial machine manufacturers, IXON redesigned it’s API. If you want to develop with the IXON API, IXON recommends usage of the APIv2 since this is the most advanced and most frequently updated version of the IXON API. Take a look at our guide on how to use the APIv2 if you currently aren’t using the APIv1.

If you are currently using the APIv1 and want to migrate to the APIv2, don’t worry. The APIv2 looks pretty similar to the APIv1, so you will still recognise the API. Some changes have been made however. The biggest changes are discussed below. If you want to look at specific changes for certain endpoints, we recommend you to take a look at our reference guide with a up-to-date list of all APIv2 endpoints.


Migration to the IXON Cloud

To use the APIv2 you first need to migrate your company in the IXON Cloud. You can use the IXON Migration Wizard for this.

Consolidation and change of url

The APIv1 consists of 3 separate API’s, for the APIv2 the General API and the LSI have been integrated into one. This way you only have to make requests to one url for both general requests and Cloud Logging requests: https://portal.ixon.cloud:443/api/. You can now also use the same headers and authentication tokens for general API requests and Cloud Logging requests. Take a look at our guide on how to use historical and real-time Cloud Logging data. IXON’s VPN Client API remains unchanged.

Discovery and headers

The APIv2 discovery is now a resource and therefore not returned as a link. The example below shows how the discovery request returns endpoints:

    "type": "Discovery",
    "data": [
            "rel": "AccessRecoverList",
            "href": "<<url>>:443/api/access-recover"
            "rel": "AccessTokenList",
            "href": "<<url>>:443/api/access-tokens"
    "moreAfter": null,
    "status": "success"

Headers that had an IX-prefix have this prefix removed. The example below shows how some of these common headers look without this prefix:

curl --request GET \
     --url '<<url>>:443/api/' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id"

Rate limit

The APIv2 has a rate limit of 50 requests per second or 3000 requests per minute. When this limit is exceeded, requests will be buffered up to 250 requests per second. Any additional requests will be dropped. Therefore, we recommend implementing a handler for a HTTP 429 too many requests response. By dynamically lowering the amount of requests, after a 429, the client should be able to keep communicating with our APIs.


Filters were formely added as operators, they are now implemented as functions. The example below shows an applied filter in the APIv2. Please look specifically at the function structure of filters.

curl --request GET \
     --url '<<url>>:443/api/agents/{agentId}?filters=eq(publicId,"{value}")' \
     --header 'Accept: application/json' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id"

User Management

The APIv2 uses a more extensive user management system than the APIv1. Where the APIv1 uses the /categories endpoint, this has been replaced by three elements: roles, groups and access-categories. These new attributes have to be taken into account with API implementations that register users and/or IXrouter/IXagent. This also applies to API implementations that change user rights of IXrouter or IXagent groups (formerly categories).