Milestone XProtect RESTful Alarms API (1.0.0)

Using the RESTful Alarms API, you can retrieve and trigger alarms in XProtect. You can also get alarm statistics, list alarm messages and work with alarm snapshots. To get started quickly with the Alarms REST API, refer to our comprehensive quickstart quide. For more detailed information about the Alarms REST API and its endpoints, refer to the complete API reference.

⚠️ The Alarms REST API is currently in beta version. Future releases of this API might break backwards compatibility.

An alarm is an alert that requires attention or action from the security operator. Security operators view alarms in the Alarm Manager tab of Smart Client. Alarms have a state, priority and assigned user.

State

The state of an alarm describes how it is being handled. For example, it can be New, In progress, On hold or Closed. Each state is associated to a state level (integer). You can create custom state levels or view existing ones in the Alarms / Alarm Data Settings node in Management Client.

Priority

The priority of an alarm describes its importance or urgency. For example, it can be High, Medium or Low. Each priority is associated to a priority level (integer). You can create custom priority levels or view existing ones in the Alarms / Alarm Data Settings node in Management Client.

Assigned user

The assigned user of an alarm is the owner of the alarm. For example, the security operator that is verifying the alarm.

Alarms can be created in two ways:

• When an event matches an Alarm Definition
• Posting an alarm directly with the API

Alarm Definitions

You can create an Alarm Definition with the Configuration REST API: Alarm definitions for a specific event type.

If you trigger an event with the Events REST API, a new alarm will be created if the event type matches the Alarm definition.

To use the Alarms REST API, you must have:

• A system running XProtect 2023 R2 or later. You are recommended to set up a small separate system for development. If you don't have one, install XProtect following the Get started guide.

• A Basic user or Windows user with access to some devices. If you don't have one, go to Create basic users.

⚠️ User credentials, bearer tokens, and other sensitive data are transmitted in cleartext if you do not set up certificates and use HTTPS. Make sure that your XProtect system is set up with HTTPS in production.

⚠️ To use most of the Alarms REST API you need a license including Alarm Manager. Check your license capabilities in the Product index

Follow this quickstart guide to retrieve alarms with cURL.

0. Verify the requirements

   Check the initial Requirements.

1. Get an auth token

   Replace the hostname test-01.example.com, username myUser, and password myPassword before running the following sample.

   curl --insecure --request POST "https://test-01.example.com/idp/connect/token" \
   --header "Content-Type: application/x-www-form-urlencoded" \
   --data-urlencode "grant_type=password" \
   --data-urlencode "username=myUsername" \
   --data-urlencode "password=myPassword" \
   --data-urlencode "client_id=GrantValidatorClient"
   

   In Windows Command Prompt (CMD), replace the line continuation character \ with ^.

2. Retrieve alarms

   Replace the hostname test-01.example.com and the sample token eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L... ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg before running the following sample.

   curl --insecure --request GET "https://test-01.example.com/api/rest/v1/alarms" \
   --header "Authorization: Bearer eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L... ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg"
   

   In Windows Command Prompt (CMD), replace the line continuation character \ with ^.

   ☑️ If you receive an empty array, make sure that you have some alarm definitions set up and that they are triggered.

Follow this quickstart guide to retrieve alarms with Python.

0. Verify the requirements

   Check the initial Requirements.

1. Install dependencies

   pip install requests

2. Retrieve alarms

   Replace the USERNAME username, PASSWORD password, and SERVER_URL https://test-01.example.com before running the following sample.

   import requests  # pip install requests
   
   USERNAME = 'username'  # replace with your basic user name
   PASSWORD = 'password'  # replace with your basic user password
   SERVER_URL = 'https://test-01.example.com'  # replace with your server URL
   VERIFY_CERTIFICATES = True  # set to False in development if your certificates are self-signed
   
   
   def main():
       session = requests.Session()
   
       # 1. Retrieve a token from IDP
       response = session.request("POST",
                               f"{SERVER_URL}/IDP/connect/token",
                               headers={
                                   'Content-Type': 'application/x-www-form-urlencoded'
                               },
                               data=f"grant_type=password"
                                       f"&username={USERNAME}"
                                       f"&password={PASSWORD}"
                                       f"&client_id=GrantValidatorClient",
                               verify=VERIFY_CERTIFICATES)
       if response.status_code != 200:
           return print(f"Unable to retrieve token: {response.status_code}")
   
       token = response.json()['access_token']
   
       # 2. Retrieve alarms with the token
       response = session.request("GET",
                               f"{SERVER_URL}/api/rest/v1/alarms",
                               headers={
                                   'Authorization': f'Bearer {token}'
                               },
                               verify=VERIFY_CERTIFICATES)
       if response.status_code != 200:
           return print(f"Unable to retrieve alarms: {response.status_code}")
       
       alarms = response.json()
       print(f"GET /alarms response:\n{alarms}\n\n")
   
   
   if __name__ == '__main__':
       main()
   

   ☑️ If you receive an empty array, make sure that you have some alarm definitions set up and that they are triggered.

Follow this quickstart guide to retrieve alarms with Python using a Windows users.

0. Verify the requirements

   Check the initial Requirements.

1. Install dependencies

   pip install requests requests-ntlm

2. Retrieve alarms

   Replace the USERNAME username, PASSWORD password, and SERVER_URL https://test-01.example.com before running the following sample.

   import requests  # pip install requests
   from requests_ntlm import HttpNtlmAuth  # pip install requests-ntlm
   
   
   USERNAME = 'domain\\username'  # replace with your windows domain and username
   PASSWORD = 'password'  # replace with your windows user password
   SERVER_URL = 'https://test-01.example.com'  # replace with your server URL
   VERIFY_CERTIFICATES = True  # set to False in development if your certificates are self-signed
   
   
   def main():
       session = requests.Session()
   
       # 1. Retrieve a token from IDP
       response = session.request("POST",
                               f"{SERVER_URL}/IDP/connect/token",
                               headers={
                                   'Content-Type': 'application/x-www-form-urlencoded'
                               },
                               data="grant_type=windows_credentials&client_id=GrantValidatorClient",
                               verify=VERIFY_CERTIFICATES,
                               auth=HttpNtlmAuth(USERNAME, PASSWORD))
       if response.status_code != 200:
           return print(f"Unable to retrieve token: {response.status_code}")
   
       token = response.json()['access_token']
   
       # 2. Retrieve alarms with the token
       response = session.request("GET",
                               f"{SERVER_URL}/api/rest/v1/alarms",
                               headers={
                                   'Authorization': f'Bearer {token}'
                               },
                               verify=VERIFY_CERTIFICATES)
       if response.status_code != 200:
           return print(f"Unable to retrieve alarms: {response.status_code}")
       
       alarms = response.json()
       print(f"GET /alarms response:\n{alarms}\n\n")
   
   
   if __name__ == '__main__':
       main()
   

   ☑️ If you receive an empty array, make sure that you have some alarm definitions set up and that they are triggered.

Follow this quickstart guide to retrieve alarms with Node.js.

0. Verify the requirements

   Check the initial Requirements.

1. Retrieve alarms

   Replace the USERNAME username, PASSWORD password, and SERVER_URL https://test-01.example.com before running the following sample.

   const USERNAME = 'username';  // replace with your basic user name
   const PASSWORD = 'password';  // replace with your basic user password
   const SERVER_URL = 'https://test-01.example.com';  // replace with your server URL
   const VERIFY_CERTIFICATES = true;  // set to False in development if your certificates are self-signed
   
   
   if (!VERIFY_CERTIFICATES) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
   
   
   fetch(`${SERVER_URL}/IDP/connect/token`, {
       method: 'POST',
       headers:{
           'Content-Type': 'application/x-www-form-urlencoded'
       }, 
       body: new URLSearchParams({
           grant_type: 'password',
           username: USERNAME,
           password: PASSWORD,
           client_id: 'GrantValidatorClient'
       })
   })
   .then(response => response.json())
   .then(token_response => {
       const token = token_response['access_token'];
       return fetch(`${SERVER_URL}/api/rest/v1/alarms`, {
           headers:{
               'Authorization': `Bearer ${token}`
           }
       })
   })
   .then(response => response.json())
   .then(alarms => console.log(alarms))
   .catch((err) => {
       console.log(err);
   });
   

   ☑️ If you receive an empty array, make sure that you have some alarm definitions set up and that they are triggered.

Follow this quickstart guide to retrieve alarms with the PowerShell.

0. Verify the requirements

   Check the initial Requirements.

1. Get an auth token

   Replace the hostname test-01.example.com, username myUser, and password myPassword before running the following sample.

   $headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }
   $body = @{grant_type='password'
       username='myUsername'
       password='myPassword'
       client_id='GrantValidatorClient'}
   $response = Invoke-RestMethod 'https://test-01.example.com/idp/connect/token' -Method 'POST' -Headers $headers -Body $body
   $response | ConvertTo-Json
   

2. Retrieve alarms

   Replace the hostname test-01.example.com and the sample token eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L... ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg before running the following sample.

   $headers = @{ "Authorization" = "Bearer eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L...ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg" }
   $response = Invoke-RestMethod 'https://test-01.example.com/api/rest/v1/alarms' -Method 'GET' -Headers $headers
   $response | ConvertTo-Json
   

   ☑️ If you receive an empty array, make sure that you have some alarm definitions set up and that they are triggered.

You can add match filters to a resource URI to limit the amount of data returned.

GET /resource?property=operator:value

string and DateTime values are delimited with single quotation marks ('), but int values are not.

GET /resource?property=lt:'2023-04-14T07:42:49.223Z'
GET /resource?property=contains:'John'
GET /resource?property=gt:123

Array values are required by some operators like oneOf. Arrays are comma-separated list of values delimited by ( and ):

GET /resource?property=oneOf:(1,4,8)
GET /resource?property=oneOf:('string value 1','string value 2')

When filtering by string values, escape any single quote ' as two single quotes ''.

GET /resource?property=contains:'string with ''single'' quotes'
GET /resource?property=oneOf:('with ''quote''', 'more ''quotes''')

When no filter operator is included, the operator defaults to equals.

GET /resource?property=value

GET /resource?property=equals:value

You can use any of the other available operators, like this:

GET /resource?property=notEquals:123

GET /resource?property=gt:123

GET /resource?property=lt:'2023-04-14T07:42:49.223Z'

GET /resource?property=startsWith:'Event'

GET /resource?property=contains:'a substring'

GET /resource?property=oneOf:(1,2,3)

You can combine multiple operators as a comma separated array, like this:

GET /resource?property=lt:'2023-04-14T07:42:49.223Z',gt:'2023-04-12T07:42:49.223Z'

Available filter operators:

• lt less than
• gt greater than
• equals equals
• notEquals not equals
• startsWith string starts with
• contains string that contains
• oneOf equals one of the values in the array

You can use the orderBy query parameter to order the result of some resource collections.

GET /resource?orderBy=asc:'fieldName'

GET /resource?orderBy=desc:'fieldName'

You can fine tune the ordering combining multiple statements as a comma separated array, like this:

GET /resource?orderBy=asc:'field1',desc:'field2',asc:'field3'

Available ordering operators:

• asc ascending
• desc descending