Skip to main content
Matrix42 Self-Service Help Center

Rest API – Event Definitions

How to create, update, query and delete Event Definitions using the FireScope REST API.


The REST API allows you to work with Event Definitions (EDs) in FireScope SPM using a REST client in lieu of the SPM user interface. 

  • Retrieve
  • Search
  • Create or Update
  • Delete


To retrieve the current information about an ED as a JSON document, send a GET request with the following URL format:


Note: Don’t forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Query Parameter Descriptions

Property Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the Edge Device. String Yes
ci Name of the CI. String Yes
name Name of the ED. String Yes


Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.


Note: Don’t forget to change the domain name (localhost) and query parameter values (account, edge_device, ci, name, page and size) to match your environment and data.

Search Parameter Descriptions

Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
edge_device Filter the results by an Edge Device’s exact name. String   No
ci Filter the results by a ConfigurationItem’s exact name. String   No
   "account_id": "firescope",
   "entity": "eventdef",
   "page": 0,
   "size": 2,
  "results": [
         "account_id": "firescope",
         "criteria": "(@A > 3)",
         "description": "Verify Ping",
         "evaluations": [{
            "builder_symbol": "@A",
            "attributeid": "ping",
            "evaluation": "count_of",
            "parameter": "120,0"
         "eventdefs_cis": [{ "edge_device": "edge2", "ci": "" }]
      }, {
         "account_id": "firescope",
         "criteria": "(@A > 3)",
         "description": "Verify Ping",
         "evaluations": [{
            "builder_symbol": "@A",
            "attributeid": "ping",
            "evaluation": "count_of",
            "parameter": "120,0"
         "eventdefs_cis": [{ "edge_device": "edge1", "ci": "VMware" }]

 Create or Update

To create or update an ED, POST a JSON document with the specific information for that ED to the following URL::


Note: Don’t forget to change the domain name (localhost

Use the following example as a guide, but note that it may not include all optional properties.

  "account_id" : "firescope",
  "criteria" : "(@A > 3)",
  "description" : "Verify Ping",
  "evaluations" : [{
    "builder_symbol" : "@A",
    "attributeid" : "ping",
    "evaluation" : "count_of",
    "parameter" : "120,0"}],
  "eventdefs_cis" : [{"edge_device" : "edge1", "ci" : "VMware"}],
  "fs_eventdef_type" : {
    "perf" : 1
  "modetype" : 0,
  "priority" : 3,
  "status" : 0

Property Descriptions

Property Description Type Default Value Required
account_id Name of the SPM account. String   Yes
comments   String   No
createdate Timestamp the ED was created. Read only. Number 0 No
criteria Expression used to evaluate this event definition. Examples:@A>5or(@A+@B-@C)=0 String   No
custom_1 Use these custom fields to store and assign additional information that willbe associated with any generated events. The custom fields are accessible for notifications as macros {EVENT.CUSTOM_1} … {EVENT.CUSTOM_5}. String   No
custom_2 String   No
custom_3 String   No
custom_4 String   No
custom_5 String   No
description Unique name of the ED. String   Yes
evaluations One or more attributes and the function applied to it that make up this event definition.
PropertyDescriptionTypeDefault ValueRequiredattributeidName of the attribute.String Yesbuilder_symbolReplacement variable use inside the criteria. Must start with an ampersand followed by a character. Example: @AString YesevaluationFunction to apply to the attribute. The following is a list of function names along with its description and a numbered list of parameters to supply in the parameters field. Expand for list of possible valuesString YesparameterA comma-separated list of parameter values for the specific evaluation. See the evaluation field above to determine the appropriate parameters (if any) to supply.String0Yes 
Object[]   Yes
eventdefs_cis  The parent CI that this event definition is a part of. Example:[{“edge_device” : “Edge1”, “ci” : “VMware”}] Object[]   Yes
eventdef_depends  Dependent event definitions Object[] [ ] No
fs_eventdef_type Classify how identified events will impact IT operations. At least one of the following flags mustbe enabled: avail, bus, perf, or sec.
PropertyDescriptionTypeDefault ValueRequiredavailAvailability: Indicates that either this asset is offline or users will not be able to perform tasks.BooleanFALSEYesbusBusiness flag: Indicates this event directly impacts key business processes or the business will lose money if the event occurs.BooleanFALSEYesperfPerformance flag: Indicates end users will experience slowness or degraded service as a result of this event.BooleanFALSEYessecSecurity flag: Indicates sensitive data may be compromised or unauthorized actions have been identified.BooleanFALSEYes
Object   Yes
modetype 0 = Simple1 = Advanced Number 0 No
priority The severity for events generated by this definition. Severity is used in dashboards, reports and notifications.The severity level of events can determine if a notification is create and/or sent to users or not.0 = Not Classified1 = Information2 = Average3 = Warning4 = High5 = Major Number 0 Yes
resetinterval Time in seconds until the eventdef should be automatically reset to passed. Number   No
status 0 = Enabled1 = Disabled Number 0 Yes
url Link to a useful KB article or process document that should be followed if this event occurs. String   No
value The read only result of the last calculation of the event definition0 = OK1 = Failed Number   No


To delete an ED, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

  • Was this article helpful?