Watchers

Create Watcher

POST /_alerting/watchers/

Description Use this API to create new Watcher by supplying all necessary information. Please note, only one Watcher can be created per IoT Gateway.

HTTP Method POST

Endpoint: /_alerting/watchers/

Request Header Authorization Basic Token

Request Parameters

Query Parameters

  • pipeline_id (string, optional): ID of the Pipeline/Gateway for which we need a Watcher

  • is_hidden (integer, optional): Indicates whether the watcher is system created

Body Parameters

  • watcher_name (string, required): Name of the Watcher.

  • function_id (string, required): ID of the Function.

  • plant_id (string, required): ID of the Plant.

  • site_id (string, required): ID of the Site.

  • gateway_id (string, required): ID of the IoT Gateway.

  • is_enabled (integer, required): Indicates whether the Watcher is enabled (1 or 0).

  • triggers (list of objects, required): List of triggers, each with the following:

    • condition (list of objects, optional): List of conditions, each with:

      • comparison (string, required): Comparison symbol (e.g., ‘<=’).

      • monitor_id (string, required): ID of the monitor.

      • tag_id (string, required): ID of the tag

      • threshold (string, required): Threshold value of the tag.

    • id (string, required): ID of trigger

    • minimum_duration (string, required): Minimum duration for the trigger (alert marked if condition is true for more than this duration).

    • name (string, required): Name of the trigger.

    • notifyTo (list of objects, required): Notification preferences:

      • email (boolean, required): Send notifications via email.

      • sms (boolean, required): Send notifications via SMS.

      • users (list of string, required): List of user IDs to notify.

      • whatsapp (boolean, required): Send notifications via WhatsApp.

    • severity (integer, required): Severity level of the trigger (lower number implies higher importance).

    • trigger_relation (string, required): Relation between multiple condtion

Sample Request

curl -X POST 'https://app.4pointx.com/_alerting/watchers/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <token>' \
-d '{
    "created_at_time": 1696827561516,
    "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
    "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
    "is_enabled": 1,
    "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
    "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
    "triggers": [
        {
            "condition": [
                {
                    "comparison": ">=",
                    "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                    "tag_id": "I_RM3201_RTD_09",
                    "threshold": "60"
                }
            ],
            "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
            "minimum_duration": "0s",
            "name": "I_RM3201_RTD_09 >= 60",
            "notifyTo": {
                "email": true,
                "sms": false,
                "users": [
                  user1@email.com,
                  user2@email.com
                ],
                "whatsapp": false
            },
            "severity": 1,
            "trigger_relation": "AND"
        },
        {
            "condition": [
                {
                    "comparison": "<=",
                    "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                    "tag_id": "I_RM3201_RTD_09",
                    "threshold": "30"
                }
            ],
            "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
            "minimum_duration": "2s",
            "name": "I_RM3201_RTD_09 <= 30",
            "notifyTo": {
                "email": true,
                "sms": false,
                "users": [
                  user3@email.com
                ],
                "whatsapp": true
            },
            "severity": 2,
            "trigger_relation": "AND"
        }
    ],
    "watcher_name": "Example_watcher"
}'

Note: Used when a “condition” Gateway is created

curl -X POST 'https://app.4pointx.com/_alerting/watchers?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af' \
             -H 'Authorization: Basic <token>'

Sample Response

Success

{
    "id": "8c254283-19f3-4bdb-996a-e748a617bea3"
}

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

{
  "error": {
    "status": 400,
    "message": "Invalid content type"
  }
}

{
  "error": {
    "status": 400,
    "message": "Insufficient inputs"
  }
}

{
  "error": {
    "status": 400,
    "message": "Watcher already exists for a given Gateway"
  }
}

{
  "error": {
    "status": 400,
    "message": "Please provide at least one notification medium (SMS, Email, or WhatsApp) for the selected user(s)."
  }
}

{
  "error": {
    "status": 400,
    "message": "Select at least one user to notify"
  }
}

Delete Watcher

DELETE /_alerting/watchers/<watcher_id>

Description Deletes an existing Watcher.

HTTP Method DELETE

Endpoint /_alerting/watchers/<watcher_id>

Request Header Authorization Basic Token

Request Parameters

URL Parameters

  • watcher_id (string, required) The ID of the Watcher that is to be deleted.

Sample Request

curl -X DELETE 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' -H 'Authorization: Basic <token>'

Sample Response

Success

"Deleted"

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

{
  "error": {
    "status": 400,
    "message": "Invalid Watcher ID"
  }
}

Update Watcher

PUT /_alerting/watchers/<watcher_id>

Description Use this API to update the configuration of an existing Watcher.

HTTP Method PUT

Endpoint /_alerting/watchers/<watcher_id>

Request Header Authorization Basic Token

Request Parameters

Query Parameters

  • pipeline_id (string, optional): ID of the Pipeline/Gateway for which we need a Watcher

  • monitor_id (string, optional): ID of the Monitor

  • is_hidden (integer, optional): Indicates whether the watcher is system created

Body Parameters

  • watcher_name (string, required): Name of the Watcher.

  • function_id (string, required): ID of the Function.

  • plant_id (string, required): ID of the Plant.

  • site_id (string, required): ID of the Site.

  • gateway_id (string, required): ID of the IoT Gateway.

  • is_enabled (integer, required): Indicates whether the Watcher is enabled.

  • triggers (list of objects, required): List of triggers, each with the following:

    • condition (list of objects, optional): List of conditions, each with:

      • comparison (string, required): Comparison symbol (e.g., ‘<=’).

      • monitor_id (string, required): ID of the monitor.

      • tag_id (string, required): ID of the tag

      • threshold (string, required): Threshold value of the tag.

    • id (string, required): ID of trigger

    • minimum_duration (string, required): Minimum duration for the trigger (alert marked if condition is true for more than this duration).

    • name (string, required): Name of the trigger.

    • notifyTo (list of objects, required): Notification preferences:

      • email (boolean, required): Send notifications via email.

      • sms (boolean, required): Send notifications via SMS.

      • users (list of string, required): List of user IDs to notify.

      • whatsapp (boolean, required): Send notifications via WhatsApp.

    • severity (integer, required): Severity level of the trigger (lower number implies higher importance).

    • trigger_relation (string, required): Relation between multiple condtion

URL Parameters

  • watcher_id (string, required) The ID of the Watcher that is to be updated.

Sample Request

curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <token>' \
-d '{
        "created_at_time": 1696827561516,
        "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
        "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
        "gateway_name": "My Gateway 1",
        "is_enabled": 1,
        "is_hidden": 0,
        "last_update_time": 1701172774457,
        "latest_alert_date": 1667260702000,
        "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
        "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
        "total_alerts": 4,
        "triggers": [
            {
                "condition": [
                    {
                        "comparison": ">=",
                        "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                        "tag_id": "I_RM3201_RTD_09",
                        "threshold": "60"
                    },
                    {
                        "comparison": "<=",
                        "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                        "tag_id": "I_RM3201_RTD_09",
                        "threshold": "30"
                    }
                ],
                "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
                "minimum_duration": "0s",
                "name": "I_RM3201_RTD_09 >= 60 OR I_RM3201_RTD_09 <= 30",
                "notifyTo": {
                    "email": true,
                    "sms": false,
                    "users": [
                      user1@email.com,
                      user2@email.com
                    ],
                    "whatsapp": false
                },
                "severity": 1,
                "trigger_relation": "OR"
            },
            {
                "condition": [
                    {
                        "comparison": "<=",
                        "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                        "tag_id": "I_RM3201_RTD_08",
                        "threshold": "90"
                    }
                ],
                "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
                "minimum_duration": "0s",
                "name": "I_RM3201_RTD_08 > 90",
                "notifyTo": {
                    "email": true,
                    "sms": false,
                    "users": [
                      user3@email.com
                    ],
                    "whatsapp": true
                },
                "severity": 2,
                "trigger_relation": "AND"
            }
        ],
        "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
        "watcher_name": "Example_watcher"
    }'

Note: Used when a “condition” Gateway is updated

curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af' \
             -H 'Authorization: Basic <token>'

Note: Used when a “condition” Monitor is updated

curl -X PUT 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3?is_hidden=1&pipeline_id=c8d0949d-acdb-410a-af3d-16ec097740af&monitor_id=ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37' \
             -H 'Authorization: Basic <token>'

Sample Response

Success

"Updated"

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

{
  "error": {
    "status": 400,
    "message": "Invalid content type"
  }
}

{
  "error": {
    "status": 400,
    "message": "Insufficient inputs"
  }
}

{
  "error": {
    "status": 400,
    "message": "Watcher already exists for given IoT Gateway"
  }
}

{
  "error": {
    "status": 400,
    "message": "Please provide at least one notification medium (SMS, Email, or WhatsApp) for the selected user(s)."
  }
}

{
  "error": {
    "status": 400,
    "message": "Please select at least one user to notify"
  }
}

Fetch Watcher

GET /_alerting/watchers/<watcher_id>

Description Returns detailed information of a specific Watcher.

HTTP Method GET

Endpoint: /_alerting/watchers/<watcher_id>

Request Header Authorization Basic Token

Request Parameters

URL Parameters

  • watcher_id (string, required): The ID of the Watcher.

Sample Request

curl -X GET 'https://app.4pointx.com/_alerting/watchers/8c254283-19f3-4bdb-996a-e748a617bea3' -H 'Authorization: Basic <token>'

Sample Response

Success

{
    "created_at_time": 1696827561516,
    "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
    "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
    "gateway_name": "My Gateway 1",
    "is_enabled": 1,
    "is_hidden": 0,
    "last_update_time": 1701172774457,
    "latest_alert_date": 1667260702000,
    "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
    "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
    "total_alerts": 4,
    "triggers": [
        {
            "condition": [
                {
                    "comparison": ">=",
                    "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                    "tag_id": "I_RM3201_RTD_09",
                    "threshold": "60"
                }
            ],
            "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
            "minimum_duration": "0s",
            "name": "I_RM3201_RTD_09 >= 60",
            "notifyTo": {
                "email": true,
                "sms": false,
                "users": [
                  user1@email.com,
                  user2@email.com
                ],
                "whatsapp": false
            },
            "severity": 1,
            "trigger_relation": "AND"
        },
        {
            "condition": [
                {
                    "comparison": "<=",
                    "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                    "tag_id": "I_RM3201_RTD_09",
                    "threshold": "30"
                }
            ],
            "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
            "minimum_duration": "2s",
            "name": "I_RM3201_RTD_09 <= 30",
            "notifyTo": {
                "email": true,
                "sms": false,
                "users": [
                  user3@email.com
                ],
                "whatsapp": true
            },
            "severity": 2,
            "trigger_relation": "AND"
        }
    ],
    "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
    "watcher_name": "Example_watcher"
}

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

Fetch List of Watchers

GET /_alerting/watchers/_list

Description Returns a list of configured Watchers along with their details for a specified Function.

HTTP Method GET

Endpoint: /_alerting/watchers/_list

Request Header Authorization Basic Token

Request Parameters

Query Parameters

  • function_id (string, required): The ID of the Function.

Sample Request

curl -X GET 'https://app.4pointx.com/_alerting/watchers/_list?function_id=f14600e7-cf2c-4f7f-af99-784b07b73a99' -H 'Authorization: Basic <token>'

Sample Response

Success

[
   {
      "created_at_time": 1696827561516,
      "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
      "gateway_id": "c8d0949d-acdb-410a-af3d-16ec097740af",
      "gateway_name": "My Gateway 1",
      "is_enabled": 1,
      "is_hidden": 0,
      "last_update_time": 1701172774457,
      "latest_alert_date": 1667260702000,
      "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
      "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
      "total_alerts": 4,
      "triggers": [
          {
              "condition": [
                  {
                      "comparison": ">=",
                      "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                      "tag_id": "I_RM3201_RTD_09",
                      "threshold": "60"
                  }
              ],
              "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
              "minimum_duration": "0s",
              "name": "I_RM3201_RTD_09 >= 60",
              "notifyTo": {
                  "email": true,
                  "sms": false,
                  "users": [
                    user1@email.com,
                    user2@email.com
                  ],
                  "whatsapp": false
              },
              "severity": 1,
              "trigger_relation": "AND"
          },
          {
              "condition": [
                  {
                      "comparison": "<=",
                      "monitor_id": "ac41ec7a-0d4b-4e1e-81e2-c09e9c82dd37",
                      "tag_id": "I_RM3201_RTD_09",
                      "threshold": "30"
                  }
              ],
              "id": "defe837f-ee8b-45b9-d04e-64asac3k5346",
              "minimum_duration": "0s",
              "name": "I_RM3201_RTD_09 <= 30",
              "notifyTo": {
                  "email": true,
                  "sms": false,
                  "users": [
                    user3@email.com
                  ],
                  "whatsapp": true
              },
              "severity": 2,
              "trigger_relation": "AND"
          }
      ],
      "watcher_id": "8c254283-19f3-4bdb-996a-e748a617bea3",
      "watcher_name": "Example_watcher"
  },
  {
      "created_at_time": 1696827561718,
      "function_id": "f14600e7-cf2c-4f7f-af99-784b07b73a99",
      "gateway_id": "dc70949d-acdb-410a-af3d-16ec0sd54520af",
      "gateway_name": "My Gateway 2",
      "is_enabled": 1,
      "is_hidden": 0,
      "last_update_time": 1701172774457,
      "latest_alert_date": 1667260702000,
      "plant_id": "7a45d8e5-92d2-46a7-92d3-85aa4bd57bba",
      "site_id": "4230adcb-f349-4780-bf79-4a8c94a3b13b",
      "total_alerts": 0,
      "triggers": [
          {
              "condition": [
                  {
                      "comparison": ">=",
                      "monitor_id": "ac41ffga-0d4b-4e1e-8sde2-c05sd482dd37",
                      "tag_id": "RM_RM3201_RTD_09",
                      "threshold": "60"
                  },
                  {
                      "comparison": ">=",
                      "monitor_id": "ac41ffga-0d4b-4e1e-8sde2-c05sd482dd37",
                      "tag_id": "RM_RM6401_RTD_06",
                      "threshold": "60"
                  }
              ],
              "id": "cefe738f-ae6b-45b9-b08b-60aaac3b5635",
              "minimum_duration": "0s",
              "name": "RM_RM3201_RTD_09 >= 60 AND RM_RM6401_RTD_06 >= 60",
              "notifyTo": {
                  "email": true,
                  "sms": false,
                  "users": [
                    user1@email.com,
                    user2@email.com
                  ],
                  "whatsapp": true
              },
              "severity": 1,
              "trigger_relation": "AND"
          }
      ],
      "watcher_id": "4e2545283-ef45-6f66-6984-7g48aa17bea3",
      "watcher_name": "My Example Watcher"
  }
]

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

{
  "error": {
    "status": 400,
    "message": "Insufficient inputs"
  }
}

{
  "error": {
    "status": 400,
    "message": "Invalid function_id"
  }
}

Fetch Watcher Count

GET /_alerting/watchers/_count

Description Returns the total number of Watchers currently configured for a Function.

HTTP Method GET

Endpoint: /_alerting/watchers/_count

Request Header Authorization Basic Token

Request Parameters

Query Parameters

  • function_id (string, required): The ID of the Function.

Sample Request

curl -X GET 'https://app.4pointx.com/_alerting/watchers/_count?function_id=f14600e7-cf2c-4f7f-af99-784b07b73a99' -H 'Authorization: Basic <token>'

Sample Response

Success

5

Error

{
  "error": {
    "status": 401,
    "message": "Unauthorized access to module by general-user"
  }
}

{
  "error": {
    "status": 400,
    "message": "Insufficient inputs"
  }
}

{
  "error": {
    "status": 400,
    "message": "Invalid function_id"
  }
}