Introduction

When you change an agent's configuration through the API (add a data source, add variables, add a VNC server, and more), the change is staged in IXON Cloud. It only reaches the device once you push the configuration.

On this page, you will learn about the API equivalent of the Push config to device action in Fleet Manager.

The AgentListConfigurationPush endpoint

Pushing is done with AgentListConfigurationPush:

curl --request POST \
     --url https://portal.ixon.cloud:443/api/agents/configuration/push \
     --header 'Api-Application: <your_application_id>' \
     --header 'Api-Company: <your_company_id>' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_bearer_token>' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "publicId": "<your_agent_id>"
  }
]
'

A successful call returns:

{
  "type": "Null",
  "data": null,
  "status": "success"
}

"Success" does not mean "done"

The push call returns success immediately, but the gateway applies the configuration in the background. In Fleet Manager, this is the moment the config button turns blue ("Synchronizing..."). When the device has finished applying and reported back, the button turns white again ("Device config in sync").

This background gap can cause problems, so the safest option is to push, then wait until the device reports back before doing anything else.

When can a configuration be pushed?

Two different conditions matter before a push:

1. mdrServer is not null.
2. The device must not be mid-apply from a previous push.

Keep in mind that an agent can be online while a push still fails. The Agent not online push error can appear when:

• The config button is blue: a previous push is still being applied (config not yet in sync). Pushing again during this window fails and may generate an Agent not online error. Pushing once the button is white succeeds.
• mdrServer is null: without the MDR/MQTT connection, a push cannot be delivered even if the VPN connection is active.

How to read the sync state

To know whether a configuration is in sync, the developer can perform a check on two different conditions:

1. config.differentConfigs (boolean)

This field can be found in the agent's config, and the values can be read as such:

• false: in sync. The "Device config in sync" white button is visible in the Fleet Manager.
• true: not in sync. The configuration still needs to be pushed. The blue "Push device config" button is visible in the Fleet Manager.

curl --request GET \
  --url 'https://portal.ixon.cloud/api/agents/<agent_id>?fields=config.differentConfigs' \
  --header 'Api-Version: 2' \
  --header 'Api-Application: <application_id>' \
  --header 'Api-Company: <company_id>' \
  --header 'Authorization: Bearer <bearer_token>'

Example: differentConfigs is false, so the device is in sync:

{
  "status": "success",
  "type": "Agent",
  "data": {
    "publicId": "ay403xfX4zGi",
    "config": {
      "differentConfigs": false
    }
  }
}

2. config.configPushedOn & config.configReportedOn (timestamps)

Two timestamps on the agent's config:

• configPushedOn: when the portal last sent config to the device.
• configReportedOn: when the device last reported back which configuration it has.

Whichever timestamp is more recent tells you the state:

• If configPushedOn is the more recent one: the device hasn't reported back since that push, so it's not in sync (blue button).
• If configReportedOn is the more recent one: it has already sent back the latest config, so it is in sync (white button).

Written as a check, that's simply configReportedOn >= configPushedOn for "in sync".

curl --request GET \
  --url 'https://portal.ixon.cloud/api/agents/<agent_id>?fields=config(configPushedOn,configReportedOn)' \
  --header 'Api-Version: 2' \
  --header 'Api-Application: <application_id>' \
  --header 'Api-Company: <company_id>' \
  --header 'Authorization: Bearer <bearer_token>'

Example: the config was sent at 12:18:56 and the device reported at 12:19:04. The report is more recent, so the device is in sync:

{
  "status": "success",
  "type": "Agent",
  "data": {
    "publicId": "ay403xfX4zGi",
    "config": {
      "configPushedOn": "2026-07-22T12:18:56Z",
      "configReportedOn": "2026-07-22T12:19:04Z"
    }
  }
}

Which one should you use?

Pick either option by the question you are answering:

• Are there changes waiting to be pushed? (including changes staged but not yet pushed): As this resembles a general check, differentConfigs is the easiest, simplest option to display a current synced/not synced state.
• Did my push apply / is the device back in sync?: differentConfigs works too, but prefer using the configReportedOn >= configPushedOn condition when confirmation is critical. It proves that the device reported back after your push.

Recommended flow for integrations

1. Stage the change with the relevant API call (e.g. create a variable on a data source).
2. Confirm the change was staged (e.g. the create call returned a publicId).
3. Wait until the agent is in sync (differentConfigs == false, or configReportedOn >= configPushedOn) so you are not pushing on top of an in-flight push.
4. Push the configuration.
5. Wait until in sync again to confirm the device applied your push (button white) before reporting success or issuing the next push.

Python tutorial:

The tutorial below creates a new variable, verifies it, checks the device is reachable, pushes, and polls until the device reports back in sync.

Notes

• Reconnects during setup. Changing anything WAN-related (Ethernet, Wi-Fi, cellular) can cause the device to reconnect, briefly dropping activeVpnSession/mdrServer. Handle this by waiting for the connection to return before pushing again, rather than treating the momentary drop as a hard failure.
• Repeated pushes. Do not fire a second push while the first is still applying (blue button "Synchronizing..."). Always wait for in sync between pushes.
• Do you even need to push? If your only change is a value on an agent's custom field, a PATCH to the Agent is usually enough and no push is required. Pushing is needed when you change the device configuration itself (data sources, variables, network configurations and more).

Related

• AgentListConfigurationPush endpoint reference