We just raised $142 million in our Series D Round! Read About Our Plans for the Future

Rules API Rules API

Last Updated: May. 31, 2022

This guide will help you use our Rules CRUD-API to create, read, update or delete rules and rule groups using an API.

In order to send an external request, the request headers should contain the following:

  1. Content-Type: application/JSON
  2. Authorization: Bearer {{Alerts, Rules and Tags API key}}. This API key can be found under Data Flow –> API Keys.

** Note that only admin users have access to the Rules API, So the Alerts, Rules and Tags API key will be visible only for admin users.

First, make sure to select the correct API endpoint for your Account region

Cluster RegionBase API Endpoint
Europe (.com)https://api.coralogix.com/api/v1/external/
US (.us)https://api.coralogix.us/api/v1/external/
India (.in)https://api.app.coralogix.in/api/v1/external/
Sweden (.eu2.)https://api.eu2.coralogix.com/api/v1/external/
Singapore (sg.com)https://api.coralogixsg.com/api/v1/external/

Groups API

Request typeURLBody
CreatePOSThttps://api.coralogix.com/api/v1/external/group“name”: (string)(mandatory) – the name of the rules group,
“Description”: (string)(optional – default is an empty string) – the description for the rules group,
“enabled”: (boolean)(optional) – indicates rather the group is active or not when created – if fields is missing or value is empty – default is True,
“creator”: (string)(optional – default is “Coralogix external API”) – the name of the group creator,
“ruleMatchers”:(array of objects)(mandatory) – the conditions which the group of rules work on – application/subsystem/severity of logs.
Each object in the array should:

“field”: (string) can be any of the following – applicationName/ subsystemName/ severity,
“constraint”: (string)-  the value for the chosen field (if the field is severity, the value should be one: debug, verbose, info, warning, error, critical)

Example:
{

"name":"group name",
"description":"group description",
"enabled":true,
"creator":"<email of creator>",
 "ruleMatchers": [
{"field": "applicationName",
"constraint": "<application name>"},
{"field": "subsystemName",
"constraint": "<subsystem name>"},
{"field": "severity",
"constraint": "<severity>"},
{"field": "severity",
"constraint": "<severity>"},
{"field": "severity",
"constraint": "<severity>"}
]
}
ReadGEThttps://api.coralogix.com/api/v1/external/group/GROUPID
UpdatePUThttps://api.coralogix.com/api/v1/external/group/GROUPID“name”: (string)(mandatory) – the name of the rules group,
“Description”: (string)(optional – default is an empty string) – the description for the rules group,
“enabled”: (boolean)(optional) – indicates rather the group will be set to active or not when updating,
“ruleMatchers”:(array of objects)(mandatory) – the conditions which the group of rules work on – application/subsystem/severity of logs.
Each object in the array should:

“field”: (string) can be any of the following – applicationName/ subsystemName/ severity,
“constraint”: (string)-  the value for the chosen field (if the field is severity, the value should be one: debug, verbose, info, warning, error, critical)

Example:
{

"name":"group name",
"description":"group description",
"enabled":true,
 "ruleMatchers": [
{"field": "applicationName",
"constraint": "<application name>"},
{"field": "subsystemName",
"constraint": "<subsystem name>"},
{"field": "severity",
"constraint": "<severity>"},
{"field": "severity",
"constraint": "<severity>"},
{"field": "severity",
"constraint": "<severity>"}
]
}
DeleteDELETEhttps://api.coralogix.com/api/v1/external/group/GROUPID

Rules API

Request typeURLBody
CreatePOSThttps://api.coralogix.com/api/v1/external/rule/GROUPID“type”: (string)(mandatory) – type of the rule(block, extract, parse, jsonextract, replace, timestampextract, removefields),
“description”: (string)(optional – default is an empty string) – the description for the rule,
“enabled”: (boolean)(optional) – indicates rather the rule is active or not when created – if fields is missing or value is empty – default is True,
“name”: (string)(mandatory) – the name of the rules group,
Rule”: (string)(mandatory – except in “removefields” and “timestampextract” – for more info look at restrictions) – the regex of the rule (must be a regex that can be compiled),
“SourceField”: (string)(optional) – If not stated in the body then the default source field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2
“DestinationField”:(string)(optional) – If not stated in the body then the default destination field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2…


Restrictions:

Rule types: ‘Block’ or ‘Extract’:
API request body cannot have: “ReplaceNewVal” OR “DestinationField”

Rule type: ‘Parse’:
API request body cannot have: “ReplaceNewVal”

Rule type: ‘Jsonextract’:
API request body cannot have: “ReplaceNewVal”
API request body must have: “DestinationField”:(string) – need to be one of: “category”, “className”, “methodName”, “severity”, “threadId”.

Rule type: ‘Replace’:
API request body must have: “ReplaceNewVal”

Rule type: ‘Removefields’:
API request body must have: “Rule”:(string) – comma-separated list of json fields you would like to remove

Rule type: ‘timestampextract’:
API request body cannot have: “Rule” OR “DestinationField” fields
API request body Must have:
“timeFormat”(string) – you can see our suggestion for each type of standard, normally you will need to change the format to match your time field string pattern with the while comply to the standard
“formatStandard”:(string) = need to be one of: “javasdf”, “golang”, “strftime”, “secondsts”, “millits”, “microts”, “nanots”)
API request body should contain a meaningful value for “SourceField”: (string) – should a value is not specified the default source files will be the text field and the rule will not work.
You should set the value as Text.<json_key_with_time_field>)
ReadGEThttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID
UpdatePUThttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID “type”: (string)(mandatory) – type of the rule(block, extract, parse, jsonextract, replace, timestampextract, removefields),
“description”: (string)(optional – default is an empty string) – the description for the rule,
“enabled”: (boolean)(optional) – indicates rather the rule will be set to active or not when updated – if fields is missing or value is empty – default is True,
“name”: (string)(mandatory) – the name of the rules group,
Rule”: (string)(mandatory – except in “removefields” and “timestampextract” – for more info look at restrictions) – the regex of the rule (must be a regex that can be compiled),
“SourceField”: (string)(optional) – If not stated in the body then the default source field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2
“DestinationField”:(string)(optional) – If not stated in the body then the default destination field will be the log text. If you want to run the rule against any internal log JSON field use text.field_name.field_name2…


Restrictions:

Rule types: ‘Block’ or ‘Extract’:
API request body cannot have: “ReplaceNewVal” OR “DestinationField”

Rule type: ‘Parse’:
API request body cannot have: “ReplaceNewVal”

Rule type: ‘Jsonextract’:
API request body cannot have: “ReplaceNewVal”
API request body must have: “DestinationField”:(string) – need to be one of: “category”, “className”, “methodName”, “severity”, “threadId”.

Rule type: ‘Replace’:
API request body must have: “ReplaceNewVal”

Rule type: ‘Removefields’:
API request body must have: “Rule”:(string) – comma-separated list of json fields you would like to remove

Rule type: ‘timestampextract’:
API request body cannot have: “Rule” OR “DestinationField” fields
API request body Must have:
“timeFormat”(string) – you can see our suggestion for each type of standard, normally you will need to change the format to match your time field string pattern with the while comply to the standard
“formatStandard”:(string) = need to be one of: “javasdf”, “golang”, “strftime”, “secondsts”, “millits”, “microts”, “nanots”)
API request body should contain a meaningful value for “SourceField”: (string) – should a value is not specified the default source files will be the text field and the rule will not work.
You should set the value as Text.<json_key_with_time_field>)
DeleteDELETEhttps://api.coralogix.com/api/v1/external/rule/RULEID/group/GROUPID

Exporting multiple rules and groups

Request typeURLHeaders
Get all RulesGEThttps://api.coralogix.com/api/v1/external/rulesContent-Type: application/json
Authorization: Bearer {<API key of team A>}
The result will be a JSON object containing all the company Rules and Groups information
Transfer rulesPOSThttps://api.coralogix.com/api/v1/external/rules/exportContent-Type: application/json
Authorization: Bearer {<API key of team B>}
The body should contain the JSON object you got from executing the GET request (copy and paste the output of the GET request to the body of the POST request without changing anything)
A message stating “Group and Rules transformed successfully” will be prompt once the transfer completed.

NOTE
When moving rules from one account to another keep in mind that the rules groups you imported are concatenated after the existing rules groups, we do not override existing groups by default. If you want to override the existing groups you should first remove them entirely and then import

Getting GroupID or RuleID

To get the GROUPID to use with the API requests URLs go to the rule group that you would like to edit and look at the URL.
To get there – Data Flow –> Parsing Rules. Click on the group you need and the browser URL will show the groupId.

RuleID can only be retrieved when executing a GET request to get a certain rule/group or when getting all the rules of the account.

To learn more about log parsing in Coralogix, read the tutorial.

Read our Regular Expressions 101 guide if you need some pointers on RegEx.

On this page