.. _arbitrator-API-resources-alerts:

alerts 
---------

The alerts resource supports the following operations. 

.. tabularcolumns:: |p{1.5cm}|p{5cm}|p{8.5cm}|

+--------+------------------------+-----------------------------------+
| Method | URL                    | Description                       |
+========+========================+===================================+
| GET    | ``alerts``             | Get a list of all alerts.         |
+--------+------------------------+-----------------------------------+
| GET    | ``alerts/{alert_id}``  | Get a single alert by alert id.   |
+--------+------------------------+-----------------------------------+
| POST   | ``alerts/disposition`` | Disposition an Alert through API. |
+--------+------------------------+-----------------------------------+



GET 
....

``/alerts``

``/alerts/{alert_id}``

* GET Parameters 

  ``alert_id`` - Optional input parameter specifying alert by ``alert_id``. 

  Example 

  ``/alerts/104``

* GET Query Parameters 

  Query parameters are only used with GET requests and can be appended to the URL with
  a ``?`` sign:
 
  ``?reference_id`` - Optional query parameter specifying the alert by ``reference_id``. 

  Example 

  ``/alerts?reference_id=20000-55000002-00-01-2784-2``

* Response Codes 

	
  .. tabularcolumns:: |p{5cm}|p{5cm}|

  +------------------+---------+
  | HTTP Status Code | Reason  |
  +==================+=========+
  | 200              | Success |
  +------------------+---------+




* Response Body 

  AlertResult 
    
* Example Curl Request 

  Command with ``alert_id``: 

  ::


     curl -k -w '\nRESP_CODE: %{response_code}\n' 
          -X GET https://10.13.37.12/api/alerts/807 


  Output: 
 
  ::

     {"alerts":[{
          "ALERTLOG_ID":"807",
          "ALERT_MESSAGE":"Node: tarb(127.0.0.1) - Alert 1 : User (admin) : Device (tarb)",
          "STATMON_ID":"1",
          "STATMON_LIFE_ID":"1",
          "CYCLE_NUM":"0",
          "LOG_DATE":"1485531000",
          "LAST_ESC_DATE":"1485534603",
          "ACK_DATE":"1486064927",
          "LAST_UPDATED":"0",
          "ACK_LEVEL":-1,
          "PCOUNTER":1,
          "ASC_ID":11,
          "IRP_ID":"1",
          "IRS_ID":"107",
          "AD_ID":2,
          "REFERENCE_ID":"20000- 55000002-00-01-2785-4",
          "USER_NAME":"admin",
          "NODE":"tarb",
          "SHORT_MESSAGE":"Alert 1 : User (admin) : Device (tarb)",
          "RULE_NAME":"Alert  1",
          "POLICY_NAME":"Kenny",
          "DISPOSITION_SCRIPT":".\/scripts\/disptest.php",
          "DISPOSITION_CONFIG":""}]
      }


  RESP_CODE: ``200``


  Command with ``reference_id``:

  :: 

     curl -k -w '\nRESP_CODE: %{response_code}\n' 
          -X GET https://10.13.37.12/api/alerts?
                   reference_id=20000-55000002-00-01-2785-4 

  Output:

  ::

     {"alerts":[{
          "ALERTLOG_ID":"807",
          "ALERT_MESSAGE":"Node: tarb(127.0.0.1) - Alert 1 : User (admin) : Device (tarb)",
          "STATMON_ID":"1",
          "STATMON_LIFE_ID":"1",
          "CYCLE_NUM":"0",
          "LOG_DATE":"1485531000",  
          "LAST_ESC_DATE":"1485534603",
          "ACK_DATE":"1486064927",
          "LAST_UPDATED":"0",
          "ACK_LEVEL":-1,  
          "PCOUNTER":1,
          "ASC_ID":11,
          "IRP_ID":"1",
          "IRS_ID":"107",
          "AD_ID":2,
          "REFERENCE_ID":"20000- 55000002-00-01-2785-4",
          "USER_NAME":"admin",
          "NODE":"tarb",
          "SHORT_MESSAGE":"Alert 1 : User (admin) : Device (tarb)",
          "RULE_NAME":"Alert  1",
          "POLICY_NAME":"Kenny",
          "DISPOSITION_SCRIPT":".\/scripts\/disptest.php",
          "DISPOSITION_C  ONFIG":""}]
     } 

 RESP_CODE: ``200``

POST 
......

* POST Parameters 
    
  The alerts POST API only accepts parameters form. The request ``application/x-www-form-urlencode``
  body should be in the following format: 

  ``reference_id=value&disposition=14&username=value``

  The required fields are the following: 

  .. tabularcolumns:: |p{2.5cm}|p{2cm}|p{9.5cm}|
  
  +------------------+--------+--------------------------------------------------------------------------------------------+
  | Field name       | Type   | Description                                                                                |
  +==================+========+============================================================================================+
  | ``reference_id`` | Text   | The reference id of the alert that needs to be dispositioned.                              |
  +------------------+--------+--------------------------------------------------------------------------------------------+
  | ``disposition``  | Number | The valid values are 0, 1, 2, 3, 4, 14, 15. Please see disposition table for  description. |
  +------------------+--------+--------------------------------------------------------------------------------------------+
  | ``username``     | Text   | The username making the request. Used only for tracking and logging.                       |
  +------------------+--------+--------------------------------------------------------------------------------------------+



* Disposition Description 

  .. tabularcolumns:: |p{2.5cm}|p{10.5cm}|
  
  +-------+--------------------------------------------------------+
  | Value | Description                                            |
  +=======+========================================================+
  | 0     | Open.                                                  |
  +-------+--------------------------------------------------------+
  | 1     | Under Review.                                          |
  +-------+--------------------------------------------------------+
  | 2     | Acknowledged.                                          |
  +-------+--------------------------------------------------------+
  | 3     | Release.                                               |
  +-------+--------------------------------------------------------+
  | 4     | Disregarded. This will delete Alert from system.       |
  +-------+--------------------------------------------------------+
  | 14    | Closed.                                                |
  +-------+--------------------------------------------------------+
  | 15    | Closed and Locked. This will delete Alert from system. |
  +-------+--------------------------------------------------------+

    
* Example Curl Request

  ::


    curl -k -w '\nRESP_CODE: %{response_code}\n' 
         -X POST https://10.13.37.14/api/alerts/disposition 
         -d 'reference_id=10000-01000009-00-01-4607- 4&disposition=2&username=testuser' 

  Output: 

  ::

     {"alerts":{
         "ok":true,
         "data":{
            "ALERTLOG_ID":117760,
            "ALERT_MESSAGE":"Node: tarb50.14(10.13.37.14) - Tcritical : Severity  (critical)",
            "STATMON_ID":1,
            "STATMON_LIFE_ID":1,
            "CYCLE_NUM":0,
            "LOG_DATE":1571839153,
            "LAST_ESC_DATE":1571842756,
            "ACK_DATE":1571856666,
            "LAST_UPDATED":0,
            "ACK_LEVEL":-1,
            "PCOUNTER" :1,
            "ASC_ID":11,
            "IRP_ID":2,
            "IRS_ID":5,
            "AD_ID":"2",
            "REFERENCE_ID":"10000-01000009-00-01- 4607-4",
            "USER_NAME":null,
            "NODE":"tarb50.14",
            "SHORT_MESSAGE":"Tcritical : Severity  (critical)",
            "RULE_NAME":"Tcritical",
            "POLICY_NAME":"Touy",
            "DISPOSITION_SCRIPT":"",
            "DISPO  SITION_CONFIG":""},
         "query":""}} 

  RESP_CODE: ``200``