REST API V11.0 References

Each API reference provides information about the parameters, mime type, stability, and responses for each endpoint.

Access Endpoints

Use the references for REST API V11.0 access endpoints.

GET /access/login_attempts

Gets the list of login attempts.

For SAAS and single signon authentication modules, failed login attempts will not be tracked. The successful login attempts will be created when the JSA session is created, not necessarily when the user entered their credentials on the single sign on login page. Any users or authorized service can call this endpoint. If the caller has the ADMIN capability, login attempts for all users will be returned. For all other callers, only login attempts for the current caller will be returned.

Table 1: GET /access/login_attempts Resource Details

MIME Type
application/json

Table 2: GET /access/login_attempts Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
sort	query	Optional	String	text/plain	Optional - This parameter is used to sort the elements in a list.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 3: GET /access/login_attempts Response Codes

HTTP Response Code	Unique Code	Description
200		An array of login attempts. The attempt_time is used as the default sort input in descending order.
422	1005	A request parameter is not valid.
422	1010	Invalid filter criteria supplied.
422	1030	The sort field or order is not valid
500	1020	An error occurred while retiriving login attempts.

Response Description

An array of login attempts. The attempt_time is used as the default sort input in descending order.

attempt_time - Long - The time the login attempt happens. This time is in milliseconds since epoch.
user_id - Long - ID of user who tried login attempt. Users are accessible through the /api/config/access/users APIs.
remote_ip - String - The remote IP address that made the login attempt.
attempt_result - Enum - The result of login attempt.
attempt_method - Enum - The method of the login attempt. HTTP_BASIC is for API based HTTP basic, and LOGIN_PAGE is for UI login attempt.

Response Sample

[{"attempt_result": "String <one of: SUCCESS, FAILURE>", "attempt_time": 42, "remote_ip": "String", "user_id": 42, "attempt_method": "String <one of: LOGIN_PAGE, HTTP_BASIC>"}]

Analytics Endpoints

Use the references for REST API V11.0 analytics endpoints.

GET /analytics/ade_rules

Retrieves a list of ADE rules.

Table 4: GET /analytics/ade_rules Resource Details

MIME Type
application/json

Table 5: GET /analytics/ade_rules Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 6: GET /analytics/ade_rules Response Codes

HTTP Response Code	Unique Code	Description
200		The ADE rules were retrieved.
422	1010	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the ADE rules.

Response Description

An array of ADE Rule objects. An ADE Rule object contains the following fields:

id - Long - The sequence ID of the ADE rule.
name - String - The name of the ADE rule.
ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.
enabled - Boolean - True if the ADE rule is enabled.
owner - String - The owner of the ADE rule.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

[ { "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "owner": "String", "type": "String <one of: ANOMALY, BEHAVIORAL, THRESHOLD>" } ]

GET /analytics/ade_rules/{id}

Retrieves an ADE rule.

Table 7: GET /analytics/ade_rules/{id} Resource Details

MIME Type
application/json

Table 8: GET /analytics/ade_rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 9: GET /analytics/ade_rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The ADE rule was retrieved.
404	1002	The ADE rule does not exist.
500	1020	An error occurred during the attempt to retrieve the ADE rule.

Response Description

The ADE rule after it is retrieved. An ADE Rule object contains the following fields:

id - Long - The sequence ID of the ADE rule.
name - String - The name of the ADE rule.
ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.
enabled - Boolean - True if the ADE rule is enabled.
owner - String - The owner of the ADE rule.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "owner": "String", "type": "String <one of: ANOMALY, BEHAVIORAL, THRESHOLD>" }

POST /analytics/ade_rules/{id}

Updates the ADE rule owner or enabled/disabled only.

Table 10: POST /analytics/ade_rules/{id} Resource Details

MIME Type
application/json

Table 11: POST /analytics/ade_rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 12: POST /analytics/ade_rules/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
ade_rule	Object	application/json	null	{ "id": "1", "name": "String", "type": "String", "owner": "String" }

Table 13: POST /analytics/ade_rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The ADE rule was updated.
403	1009	You do not have the required capabilities to update the ADE rule.
404	1002	The ADE rule does not exist.
409	1004	The provided user does not have the required capabilities to own the ADE rule.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the ADE rule.

Response Description

The ADE rule after it is updated. An ADE Rule object contains the following fields:

id - Long - The sequence ID of the ADE rule.
name - String - The name of the ADE rule.
ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.
enabled - Boolean - True if the ADE rule is enabled.
owner - String - The owner of the ADE rule.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

DELETE /analytics/ade_rules/{id}

Deletes an ADE rule. To ensure safe deletion, a dependency check is carried out. The check might take some time. An asynchronous task is started to do this check.

Table 14: DELETE /analytics/ade_rules/{id} Resource Details

MIME Type
application/json

Table 15: DELETE /analytics/ade_rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 16: DELETE /analytics/ade_rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
202		The ADE rule delete command was accepted and is in progress.
403	1009	You do not have the required capabilities to delete the ADE rule.
404	1002	The ADE rule does not exist.
500	1020	An error occurred during the attempt to delete the ADE rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state that the task is in.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/ade_rules/{id}/dependents

Retrieves the objects that depend on the ADE rule.

Table 17: GET /analytics/ade_rules/{id}/dependents Resource Details

MIME Type
application/json

Table 18: GET /analytics/ade_rules/{id}/dependents Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 19: GET /analytics/ade_rules/{id}/dependents Response Codes

HTTP Response Code	Unique Code	Description
202		The ADE rule dependents retrieval was accepted and is in progress.
404	1002	The ADE rule does not exist.
500	1020	An error occurred during the attempt to initiate the ADE rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. the value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task.
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id}

Retrieves the delete the ADE rule task status.

Table 20: GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Resource Details

MIME Type
application/json

Table 21: GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 22: GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status was retrieved.
404	1002	The Delete Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}

Retrieves the dependent the ADE rule task status.

Table 23: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 24: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 25: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status was retrieved.
404	1002	The Delete Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects tha were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task.
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}

Cancels a dependent the ADE rule task.

Table 26: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 27: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 28: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
task	Object	application/json	null	{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 29: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status was retrieved.
404	1002	The Dependent Task Status does not exist.
409	1004	The task is in a completed state.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the Dependent Task Status.

Response Description

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task.
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results

Retrieves the ADE rule dependent task results.

Table 30: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Resource Details

MIME Type
application/json

Table 31: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 32: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The ADE rule dependents were retrieved.
404	1002	The dependent task dtatus does not exist.
500	1020	An error occurred during the attempt to retrieve the ADE rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

dependent_id - String - The ID of the dependent resource.
dependent_name - String - The name of the dependent resource (default resources can have localized names).
dependent_owner - String - The owner of the dependent resource
dependent_type - String - The type of the dependent resource
dependent_database - String - The database of the dependent resource.
dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.
user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: APP, NAMED_SERVICE, ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_REGEX_PROPERTY_DEPENDENCY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_REGEX_PROPERTY_DEPENDENCY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE, EVENT_AQL_PROPERTY, FLOW_AQL_PROPERTY, OFFENSE_TYPE, SECURITY_PROFILE, ARIEL_INDEX, DOMAIN_MAPPING, FORWARDING_PROFILE, REGEX_EXPRESSION, JSON_EXPRESSION, LEEF_EXPRESSION, CEF_EXPRESSION>", "user_has_edit_permissions": true } ]

GET /analytics/building_blocks

Retrieves a list of building block rules.

Table 33: GET /analytics/building_blocks Resource Details

MIME Type
application/json

Table 34: GET /analytics/building_blocks Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 35: GET /analytics/building_blocks Response Codes

HTTP Response Code	Unique Code	Description
200		The building block rules were retrieved.
422	1010	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the building block rules.

Response Description

An array of Building Block Rule objects. An Building Block Rule object contains the following fields:

id - Long - The sequence ID of the building block rule.
name - String - The name of the building block rule.
building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the building block rule is enabled.
owner - String - The owner of the building block rule.
origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the building block rule in events per second.
base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

[ { "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" } ]

GET /analytics/building_blocks/building_block_delete_tasks/{task_id}

Retrieves the delete the building block rule task status.

Table 36: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Resource Details

MIME Type
application/json

Table 37: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 38: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status was retrieved.
404	1002	The Delete Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}

Retrieves the dependent the building block rule task status.

Table 39: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 40: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 41: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status was retrieved.
404	1002	The Delete Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

POST /analytics/building_blocks/building_block_dependent_tasks/{task_id}

Cancels the dependent the building block rule task.

Table 42: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 43: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 44: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
task	Object	application/json	null	{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 45: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Delete Task Status has been retrieved.
404	1002	The Dependent Task Status does not exist.
409	1004	The task is in a completed state
422	1005	A request parameter is not valid
500	1020	An error occurred during the attempt to update the Dependent Task Status.

Response Description

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested the cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields
- message - String - The localized sub-task status message.
- status - String - The current state of the the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results

Retrieves the building block rule dependent task results.

Table 46: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Resource Details

MIME Type
application/json

Table 47: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 48: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The building block rule dependents were retrieved.
404	1002	The Dependent Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the building block rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

dependent_id - String - The ID of the dependent resource.
dependent_name - String - The name of the dependent resource (default resources can have localized names).
dependent_owner - String - The owner of the dependent resource.
dependent_type - String - The type of the dependent resource.
dependent_database - String - The database of the dependent resource.
dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.
user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

GET /analytics/building_blocks/{id}

Retrieves a building block rule.

Table 49: GET /analytics/building_blocks/{id} Resource Details

MIME Type
application/json

Table 50: GET /analytics/building_blocks/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 51: GET /analytics/building_blocks/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The building block rule was retrieved.
404	1002	The building block rule does not exist.
500	1020	An error occurred during the attempt to retrieve the building block rule.

Response Description

The building block rule after it is retrieved. An Building Block Rule object contains the following fields:

id - Long - The sequence ID of the building block rule.
name - String - The name of the building block rule.
building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the building block rule is enabled.
owner - String - The owner of the building block rule.
origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the building block rule in events per second.
base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

POST /analytics/building_blocks/{id}

Updates the building block rule owner or enabled/disabled only.

Table 52: POST /analytics/building_blocks/{id} Resource Details

MIME Type
application/json

Table 53: POST /analytics/building_blocks/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 54: POST /analytics/building_blocks/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
building_block	Object	application/json	null	{ "id": "1", "name": "String", "type": "String", "owner": "String" }

Table 55: POST /analytics/building_blocks/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The building block rule was updated.
403	1009	You do not have the required capabilities to update the building block rule.
404	1002	The building block rule does not exist.
409	1004	The provided user does not have the required capabilities to own the building block rule.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the building block rule.

Response Description

The building block rule after it is updated. A building block rule object contains the following fields:

id - Long - The sequence ID of the building block rule.
name - String - The name of the building block rule.
building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the building block rule is enabled.
owner - String - The owner of the building block rule.
origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the building block rule in events per second.
base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

DELETE /analytics/building_blocks/{id}

Deletes the building block rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 56: DELETE /analytics/building_blocks/{id} Resource Details

MIME Type
application/json

Table 57: DELETE /analytics/building_blocks/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 58: DELETE /analytics/building_blocks/{id} Response Codes

HTTP Response Code	Unique Code	Description
202		The building block rule delete command was accepted and is in progress.
403	1009	You do not have the required capabilities to delete the building block rule.
404	1002	The building block rule does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete the building block rule.

Response Description

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state that the task is in.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/building_blocks/{id}/dependents

Retrieves the objects that depend on the building block rule.

Table 59: GET /analytics/building_blocks/{id}/dependents Resource Details

MIME Type
application/json

Table 60: GET /analytics/building_blocks/{id}/dependents Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 61: GET /analytics/building_blocks/{id}/dependents Response Codes

HTTP Response Code	Unique Code	Description
202		The building block rule dependents retrieval was accepted and is in progress.
404	1002	The building block rule does not exist.
500	1020	An error occurred during the attempt to initiate the building block rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. the value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /analytics/custom_actions/actions

Retrieves a list of available custom actions.

Table 62: GET /analytics/custom_actions/actions Resource Details

MIME Type
application/json

Table 63: GET /analytics/custom_actions/actions Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 64: GET /analytics/custom_actions/actions Response Codes

HTTP Response Code	Unique Code	Description
200		The requested list of custom actions have been successfully retrieved.
500	1020	An internal server error occurred while retrieving custom actions.

Response Description

Array of available custom actions which in turn contain the following fields:

id - Number - Unique ID of the custom action within the JSA deployment.
name - String - Unique name of the custom action within the JSA deployment.
description - String - Optional description attached to the custom action.
interpreter - Number - Unique ID of the custom action interpreter used by the custom action.
script - Number - Unique ID of the custom action script used by the custom action.
parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:
- name - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - String - Value of the custom action parameter.

Response Sample

[ { "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 } ]

POST /analytics/custom_actions/actions

Creates a new custom action with the supplied fields.

The custom action must contain the following fields:

name - Required - String - Unique name of the custom action within the JSA deployment.
description - Optional - String - Description of the custom action.
interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.
script - Required - Number - Unique ID of the custom action script used by the custom action.
parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:
- name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - Required - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Required - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - Required - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

Table 65: POST /analytics/custom_actions/actions Resource Details

MIME Type
application/json

Table 66: POST /analytics/custom_actions/actions Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 67: POST /analytics/custom_actions/actions Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
custom_action	Object	application/json	Custom action JSON object containing the supplied fields (see above for more details).	{ "description": "String", "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

Table 68: POST /analytics/custom_actions/actions Response Codes

HTTP Response Code	Unique Code	Description
201		A new custom action has been successfully created.
422	1005	One or more parameters are invalid in request.
500	1020	An internal server error occurred while posting custom action.

Response Description

The newly created custom action with the following fields:

id - Number - Unique ID of the custom action within the JSA deployment.
name - String - Unique name of the custom action within the JSA deployment.
description - String - Optional description attached to the custom action.
interpreter - Number - Unique ID of the custom action interpreter used by the custom action.
script - Number - Unique ID of the custom action script used by the custom action.
parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:
- name - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

GET /analytics/custom_actions/actions/{action_id}

Retrieves a custom action based on the supplied action_id.

Table 69: GET /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type
application/json

Table 70: GET /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
action_id	path	Required	Number (Integer)	text/plain	Long id of the custom action to be retrieved.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 71: GET /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The requested custom action has been successfully retrieved.
404	1002	The requested custom action could not be found.
500	1020	An internal server error occurred while retrieving custom action with supplied action_id.

Response Description

A custom action with containing following fields:

id - Number - Unique ID of the custom action within the JSA deployment.
name - String - Unique name of the custom action within the JSA deployment.
description - String - Optional description attached to the custom action.
interpreter - Number - Unique ID of the custom action interpreter used by the custom action.
script - Number - Unique ID of the custom action script used by the custom action.
parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:
- name - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

POST /analytics/custom_actions/actions/{action_id}

Updates an existing custom action.

The custom action should contain the following fields:

id - Required - Number - Unique ID of the custom action within the JSA deployment.
name - Optional - String - Unique name of the custom action within the JSA deployment.
description - Optional - String - Description of the custom action.
interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.
script - Required - Number - Unique ID of the custom action script used by the custom action.
parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:
- name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - Optional - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Optional - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - Optional - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

Table 72: POST /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type
application/json

Table 73: POST /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
action_id	path	Required	Number (Integer)	text/plain	Number id of the custom action to be updated.
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 74: POST /analytics/custom_actions/actions/{action_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
custom_action	Object	application/json	Custom action JSON object which can contain the supplied fields (see above for more details).	{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

Table 75: POST /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The custom action has been updated.
404	1002	The requested custom action could not be found.
422	1005	One or more parameters are invalid in request.
500	1020	An internal server error occurred while updating custom action with supplied action_id.

Response Description

The updated custom action with the following fields:

id - Number - Unique ID of the custom action within the JSA deployment.
name - String - Unique name of the custom action within the JSA deployment.
description - String - Optional description attached to the custom action.
interpreter - Number - Unique ID of the custom action interpreter used by the custom action.
script - Number - Unique ID of the custom action script used by the custom action.
parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:
- name - String - Name of the custom action parameter. Unique in the context of the parent custom action.
- parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.
- encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.
- value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

DELETE /analytics/custom_actions/actions/{action_id}

Deletes an existing custom action.

Table 76: DELETE /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type
text/plain

Table 77: DELETE /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
action_id	path	Required	Number (Integer)	text/plain	Number id of the custom action you wish to delete.

Table 78: DELETE /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The custom action has been deleted.
404	1002	The requested custom action could not be found.
500	1020	An internal server error occurred while deleting custom action with supplied action_id.

Response Description

Empty response with 204 successful response code.

Response Sample

GET /analytics/custom_actions/interpreters

Retrieves a list of available custom action interpreters.

Table 79: GET /analytics/custom_actions/interpreters Resource Details

MIME Type
application/json

Table 80: GET /analytics/custom_actions/interpreters Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 81: GET /analytics/custom_actions/interpreters Response Codes

HTTP Response Code	Unique Code	Description
200		The requested list of custom action interpreters have been retrieved.
500	1020	An internal server error occurred while retrieving available custom action interpreters.

Response Description

Array of available custom action interpreters, each with the following fields:

id - Number - Unique ID of the custom action interpreter within the JSA deployment.
name - String - Name of the custom action interpreter.

Response Sample

[ { "id": 42, "name": "String" } ]

GET /analytics/custom_actions/interpreters/{interpreter_id}

Retrieves a custom action interpreter based on supplied interpreter_id.

Table 82: GET /analytics/custom_actions/interpreters/{interpreter_id} Resource Details

MIME Type
application/json

Table 83: GET /analytics/custom_actions/interpreters/{interpreter_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
interpreter_id	path	Required	Number (Integer)	text/plain	Number id of custom action interpreter to be retrieved.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 84: GET /analytics/custom_actions/interpreters/{interpreter_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The requested custom action interpreter has been retrieved.
404	1002	The requested custom action interpreter could not be found.
500	1020	An internal server error occurred while retrieving custom action interpreter with supplied interpreter_id.

Response Description

A custom action interpreter with the following fields:

id - Number - Unique ID of the custom action interpreter within the JSA deployment.
name - String - Name of the custom action interpreter.

Response Sample

{ "id": 42, "name": "String" }

GET /analytics/custom_actions/scripts

Retrieves a list of meta-data for available custom action script files.

Table 85: GET /analytics/custom_actions/scripts Resource Details

MIME Type
application/json

Table 86: GET /analytics/custom_actions/scripts Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 87: GET /analytics/custom_actions/scripts Response Codes

HTTP Response Code	Unique Code	Description
200		The requested custom action script file has been retrieved.
500	1020	An internal server error occurred while retrieving available custom action script file meta-data.

Response Description

Array of available custom action script file meta-data, each with the following fields:

id - Number - Unique ID of the custom action script file within the JSA deployment.
name - String - Name of the custom action script file.

Response Sample

[ { "file_name": "String", "id": 42 } ]

POST /analytics/custom_actions/scripts

Creates a new custom action script file. Newly created custom action script files require a deployment before using.

Users can include an optional HTTP header file_name containing the custom action script file name. If not specified this is defaulted to the script id of the uploaded file.

Table 88: POST /analytics/custom_actions/scripts Resource Details

MIME Type
application/json

Table 89: POST /analytics/custom_actions/scripts Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 90: POST /analytics/custom_actions/scripts Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
file	File	application/octet-stream	Required. The custom action script file. Must be supplied with MIME type application/octet-stream.	File

Table 91: POST /analytics/custom_actions/scripts Response Codes

HTTP Response Code	Unique Code	Description
201		A custom action script file has been created.
500	1020	An internal server error occurred while posting custom action script file.

Response Description

Custom action script file meta-data with the following fields:

id - Number - Unique ID of the custom action script within the JSA deployment.
name - String - Name of the custom action script.

Response Sample

{ "file_name": "String", "id": 42 }

GET /analytics/custom_actions/scripts/{script_id}

Retrieves meta-data of a custom action script file based on supplied script_id.

Table 92: GET /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type
application/json

Table 93: GET /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
script_id	path	Required	Number (Integer)	text/plain	Number id of the custom action script file.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 94: GET /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The requested custom action script file has been retrieved.
404	1002	The requested custom action script file could not be found.
500	1020	An internal server error occurred while retrieving custom action script file meta-data with supplied script_id.

Response Description

Custom action script file meta-data with the following fields:

id - Number - Unique ID of the custom action script file within the JSA deployment.
name - String - Name of the custom action script file.

Response Sample

{ "file_name": "String", "id": 42 }

POST /analytics/custom_actions/scripts/{script_id}

Updates an existing custom action script file. Updated custom action script files require a deployment before using.

Users can include an optional HTTP header file_name containing the custom action script file name. If not specified this is defaulted to the script id of the uploaded file.

Table 95: POST /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type
application/json

Table 96: POST /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
script_id	path	Required	Number (Integer)	text/plain	Number id of the custom action script file to be updated.
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 97: POST /analytics/custom_actions/scripts/{script_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
file	File	application/octet-stream	Required. The custom action script file. Must be supplied with MIME type application/octet-stream.	File

Table 98: POST /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The custom action script file has been updated.
404	1002	The requested custom action script file could not be found.
500	1020	An internal server error occurred while updating custom action script file with supplied script_id.

Response Description

Custom action script file meta-data with the following fields:

id - Number - Unique ID of the custom action script file within the JSA deployment.
name - String - Name of the custom action script file.

Response Sample

{ "file_name": "String", "id": 42 }

DELETE /analytics/custom_actions/scripts/{script_id}

Deletes an existing custom action script file.

Table 99: DELETE /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type
text/plain

Table 100: DELETE /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
script_id	path	Required	Number (Integer)	text/plain	Number id of the custom action script file to be deleted.

Table 101: DELETE /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The custom action script file has been deleted.
404	1002	The requested custom action script file could not be found.
422	1005	The requested custom action script file is tied to an existing custom action.
500	1020	An internal server error occurred while deleting custom action script file with supplied script_id.

Response Description

Empty response with a 204 successful response code.

Response Sample

GET /analytics/rule_groups

Retrieves a list of the rule groups.

Table 102: GET /analytics/rule_groups Resource Details

MIME Type
application/json

Table 103: GET /analytics/rule_groups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 104: GET /analytics/rule_groups Response Codes

HTTP Response Code	Unique Code	Description
200		The rule rroups were returned.
500	1020	An error occurred during the attempt to retrieve the rule groups.

Response Description

List of the Group objects. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

[ { "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" } ]

GET /analytics/rule_groups/{group_id}

Retrieves a rule group.

Table 105: GET /analytics/rule_groups/{group_id} Resource Details

MIME Type
application/json

Table 106: GET /analytics/rule_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 107: GET /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The rule group was retrieved.
404	1002	The rule group does not exist.
500	1020	An error occurred during the attempt to retrieve the rule group.

Response Description

A single Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

POST /analytics/rule_groups/{group_id}

Updates the owner of a rule group.

Table 108: POST /analytics/rule_groups/{group_id} Resource Details

MIME Type
application/json

Table 109: POST /analytics/rule_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 110: POST /analytics/rule_groups/{group_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
group	Object	application/json	Required - Group object with the owner set to a valid deployed user.	{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH _GROUP, FLOW_SAVED_SEARCH _GROUP, OFFENSE_SAVED_SEARCH _GROUP, QRM_SAVED_SEARCH _GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH _GROUP, SIMULATION_SAVED_SEARCH _GROUP, TOPOLOGY_SAVED_SEARCH _GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 111: POST /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The rule group was updated.
404	1002	The rule group does not exist.
409	1004	The provided user does not have the required capabilities to own the rule group.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the rule group.

Response Description

The updated Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

DELETE /analytics/rule_groups/{group_id}

Deletes a rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 112: DELETE /analytics/rule_groups/{group_id} Resource Details

MIME Type
text/plain

Table 113: DELETE /analytics/rule_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null

Table 114: DELETE /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
202		The rule delete command was accepted and is in progress.
404	1002	The rule does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete the rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/rules

Retrieves a list of rules.

Table 115: GET /analytics/rules Resource Details

MIME Type
application/json

Table 116: GET /analytics/rules Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 117: GET /analytics/rules Response Codes

HTTP Response Code	Unique Code	Description
200		The rules were retrieved.
422	1010	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the rules.

Response Description

An array of rule objects. A rule object contains the following fields:

id - Long - The sequence ID of the rule.
name - String - The name of the rule.
type - String - The type of rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the rule is enabled.
owner - String - The owner of the rule.
origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the rule in events per second.
base_host_id - Long - The ID of the host from which the rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

GET /analytics/rules/rule_delete_tasks/{task_id}

Retrieves the delete the rule task status.

Table 118: GET /analytics/rules/rule_delete_tasks/{task_id} Resource Details

MIME Type
application/json

Table 119: GET /analytics/rules/rule_delete_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 120: GET /analytics/rules/rule_delete_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The delete task status was retrieved.
404	1002	The delete task status does not exist.
500	1020	An error occurred during the attempt to retrieve the delete task status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/rules/rule_dependent_tasks/{task_id}

Retrieves the dependent rule task status.

Table 121: GET /analytics/rules/rule_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 122: GET /analytics/rules/rule_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 123: GET /analytics/rules/rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The delete task status was retrieved.
404	1002	The delete task status does not exist.
500	1020	An error occurred during the attempt to retrieve the delete task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested the cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. the value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

POST /analytics/rules/rule_dependent_tasks/{task_id}

Cancels the dependent the rule task.

Table 124: POST /analytics/rules/rule_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 125: POST /analytics/rules/rule_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 126: POST /analytics/rules/rule_dependent_tasks/{task_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
task	Object	application/json	null	{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 127: POST /analytics/rules/rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The dependent task status was retrieved.
404	1002	The dependent task status does not exist.
409	1004	The task is in a completed state.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /analytics/rules/rule_dependent_tasks/{task_id}/results

Retrieves the rule dependent task results.

Table 128: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Resource Details

MIME Type
application/json

Table 129: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 130: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The rule dependents were retrieved.
404	1002	The dependent task status does not exist.
500	1020	An error occurred during the attempt to retrieve the rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

dependent_id - String - The ID of the dependent resource.
dependent_name - String - The name of the dependent resource (default resources can have localized names).
dependent_owner - String - The owner of the dependent resource.
dependent_type - String - The type of the dependent resource.
dependent_database - String - The database of the dependent resource.
dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.
user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

GET /analytics/rules/{id}

Retrieves a rule.

Table 131: GET /analytics/rules/{id} Resource Details

MIME Type
application/json

Table 132: GET /analytics/rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 133: GET /analytics/rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The rule was retrieved.
404	1002	The rule does not exist.
500	1020	An error occurred during the attempt to retrieve the rule.

Response Description

The rule after it is retrieved. A rule object contains the following fields:

id - Long - The sequence ID of the rule.
name - String - The name of the rule.
type - String - The type of rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the rule is enabled.
owner - String - The owner of the rule.
origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the rule in events per second.
base_host_id - Long - The ID of the host from which the rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

POST /analytics/rules/{id}

Updates the rule owner or enabled/disabled only.

Table 134: POST /analytics/rules/{id} Resource Details

MIME Type
application/json

Table 135: POST /analytics/rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 136: POST /analytics/rules/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
rule	Object	application/json	Required - Rule object.	{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

Table 137: POST /analytics/rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The rule was updated.
403	1009	You do not have the required capabilities to update the rule.
404	1002	The rule does not exist.
409	1004	The provided user does not have the required capabilities to own the rule.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the rule.

Response Description

The rule after it is updated. An Rule object contains the following fields:

id - Long - The sequence ID of the rule.
name - String - The name of the rule.
type - String - The type of rule: EVENT, FLOW, COMMON, USER.
enabled - Boolean - True if the rule is enabled.
owner - String - The owner of the rule.
origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.
base_capacity - Long - The base capacity of the rule in events per second.
base_host_id - Long - The ID of the host from which the rule's base capacity was determined
average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.
capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.
identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.
linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:
- SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.
- OVERRIDE - The identifier value of the system rule being overridden.
- USER - The value will be null.
creation_date - Long - The number of milliseconds since epoch when the rule was created.
modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

DELETE /analytics/rules/{id}

Delete the rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 138: DELETE /analytics/rules/{id} Resource Details

MIME Type
application/json

Table 139: DELETE /analytics/rules/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 140: DELETE /analytics/rules/{id} Response Codes

HTTP Response Code	Unique Code	Description
202		The rule delete command was accepted and is in progress.
403	1009	You do not have the required capabilities to delete the rule.
404	1002	The rule does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete the rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/rules/{id}/dependents

Retrieves the objects that depend on the rule.

Table 141: GET /analytics/rules/{id}/dependents Resource Details

MIME Type
application/json

Table 142: GET /analytics/rules/{id}/dependents Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 143: GET /analytics/rules/{id}/dependents Response Codes

HTTP Response Code	Unique Code	Description
202		The rule dependents retrieval was accepted and is in progress.
403	1009	null
404	1002	The rule does not exist.
500	1020	An error occurred during the attempt to initiate the rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested the cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. the value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of Task Component objects. A Task Component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

Ariel Endpoints

Use the references for REST API V11.0 Ariel endpoints.

GET /ariel/databases

Retrieves a list of available Ariel database names

Table 144: GET /ariel/databases Resource Details

MIME Type
application/json

Table 145: GET /ariel/databases Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 146: GET /ariel/databases Response Codes

HTTP Response Code	Unique Code	Description
200		The database list was retrieved.

Response Description

The names of the available Ariel databases.

Response Sample

[ "String" ]

GET /ariel/databases/{database_name}

Retrieve the columns that are defined for a specific Ariel database.

This is the set of columns that can be explicitly named in the column list of a SELECT query.

Table 147: GET /ariel/databases/{database_name} Resource Details

MIME Type
application/json

Table 148: GET /ariel/databases/{database_name} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
database_name	path	Required	String	text/plain	Required. The name of the Ariel database that contains the columns that you want to retrieve.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 149: GET /ariel/databases/{database_name} Response Codes

HTTP Response Code	Unique Code	Description
200		The database columns were retrieved.
404	1002	The database does not exist.

Response Description

A list of columns that are defined for the specified database. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

GET /ariel/event_saved_search_groups

Retrieves a list the event Ariel saved search groups.

Table 150: GET /ariel/event_saved_search_groups Resource Details

MIME Type
application/json

Table 151: GET /ariel/event_saved_search_groups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 152: GET /ariel/event_saved_search_groups Response Codes

HTTP Response Code	Unique Code	Description
200		The event Ariel saved search groups were returned.
500	1020	An error occurred during the attempt to retrieve the event Ariel saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default groups can have localized names).
description - String - The description of the group (default groups can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group ids.

Response Sample

GET /ariel/event_saved_search_groups/{group_id}

Retrieves an event Ariel saved search group.

Table 153: GET /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 154: GET /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 155: GET /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The event Ariel saved search group was retrieved.
404	1002	The vent Ariel saved search group does not exist.
500	1020	An error occurred during the attempt to retrieve the event Ariel saved search groups.

Response Description

A single Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

POST /ariel/event_saved_search_groups/{group_id}

Updates the owner of an event Ariel saved search group.

Table 156: POST /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 157: POST /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 158: POST /ariel/event_saved_search_groups/{group_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
group	Object	application/json	Required - Group object with the owner set to a valid deployed user.	{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH _GROUP, FLOW_SAVED_SEARCH _GROUP, OFFENSE_SAVED_SEARCH _GROUP, QRM_SAVED_SEARCH _GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH _GROUP, SIMULATION_SAVED_SEARCH _GROUP, TOPOLOGY_SAVED_SEARCH _GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 159: POST /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The event Ariel saved search group was updated.
404	1002	The event Ariel saved search group does not exist.
409	1004	The provided user does not have the required capabilities to own the Eevent Ariel saved search group.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the event Ariel saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The id of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group ids.

Response Sample

DELETE /ariel/event_saved_search_groups/{group_id}

Deletes an event Ariel saved search group.

Table 160: DELETE /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type
text/plain

Table 161: DELETE /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null

Table 162: DELETE /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The event Ariel saved search group was deleted.
404	1002	The event Ariel saved search group does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete theevent Ariel saved search group.

Response Description

Response Sample

GET /ariel/flow_saved_search_groups

Retrieves a list of flow Ariel saved search groups.

Table 163: GET /ariel/flow_saved_search_groups Resource Details

MIME Type
application/json

Table 164: GET /ariel/flow_saved_search_groups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 165: GET /ariel/flow_saved_search_groups Response Codes

HTTP Response Code	Unique Code	Description
200		The Retrieves a list of flow Ariel saved search groups were returned.
500	1020	An error occurred during the attempt to retrieve the flow Ariel saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

GET /ariel/flow_saved_search_groups/{group_id}

Retrieves a flow Ariel saved search group.

Table 166: GET /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 167: GET /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 168: GET /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The flow Ariel saved search group was retrieved.
404	1002	The flow Ariel saved search group does not exist.
500	1020	An error occurred during the attempt to retrieve the flow Ariel saved search group.

Response Description

A single Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

POST /ariel/flow_saved_search_groups/{group_id}

Updates the owner of a flow Ariel saved search group.

Table 169: POST /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 170: POST /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 171: POST /ariel/flow_saved_search_groups/{group_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
group	Object	application/json	Required - Group object with the owner set to a valid deployed user.	{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH _GROUP, FLOW_SAVED_SEARCH _GROUP, OFFENSE_SAVED_SEARCH _GROUP, QRM_SAVED_SEARCH _GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH _GROUP, SIMULATION_SAVED_SEARCH _GROUP, TOPOLOGY_SAVED_SEARCH _GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 172: POST /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The flow Ariel saved search group was updated.
404	1002	The flow Ariel saved search group does not exist.
409	1004	The provided user does not have the required capabilities to own the flow Ariel saved search group.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the flow Ariel saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

DELETE /ariel/flow_saved_search_groups/{group_id}

Deletes a flow Ariel saved search group.

Table 173: DELETE /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type
text/plain

Table 174: DELETE /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null

Table 175: DELETE /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The flow Ariel saved search group was deleted.
404	1002	The flow Ariel saved search group does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete the flow Ariel saved search group.

Response Description

Response Sample

GET /ariel/flow_vlans

Retrieves a list of available flow VLAN IDs in the Ariel database.

Table 176: GET /ariel/flow_vlans Resource Details

MIME Type
application/json

Table 177: GET /ariel/flow_vlans Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 178: GET /ariel/flow_vlans Response Codes

HTTP Response Code	Unique Code	Description
200		The flow VLAN ID list was retrieved.
500	1000	An error occurred while the flow VLAN ID list was being retrieved.

Response Description

An array of flow VLAN ID objects. A flow VLAN ID object contains the following fields:

id - Long - The ID of the flow VLAN field.
enterprise_vlan_id - Short - The enterprise VLAN ID.
customer_vlan_id - Short - The customer VLAN ID.

Response Sample

[ { "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 } ]

DELETE /ariel/flow_vlans/{id}

Deletes a flow VLAN ID with specified enterprise and customer VLAN ID's and removes any associated domain mappings.

Table 179: DELETE /ariel/flow_vlans/{id} Resource Details

MIME Type
text/plain

Table 180: DELETE /ariel/flow_vlans/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	Required - The ID of the flow VLAN ID object to be deleted. Note that this is also the concatenation of the customer VLAN ID to the enterprise VLAN ID.

Table 181: DELETE /ariel/flow_vlans/{id} Response Codes

HTTP Response Code	Unique Code	Description
204		The flow VLAN ID has been successfully deleted.
404	1031	The flow VLAN ID specified could not be found.
500	1030	An error occurred while the flow VLAN ID was being deleted.

Response Description

The deleted flow VLAN ID object. A flow VLAN ID object contains the following fields:

id - Long - The ID of the flow VLAN field.
enterprise_vlan_id - Short - The enterprise VLAN ID.
customer_vlan_id - Short - The customer VLAN ID.

Response Sample

GET /ariel/flow_vlans/{id}

Retrieves a flow VLAN ID object by VLAN ID.

Table 182: GET /ariel/flow_vlans/{id} Resource Details

MIME Type
application/json

Table 183: GET /ariel/flow_vlans/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	Required - The ID of the flow VLAN to retrieve.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 184: GET /ariel/flow_vlans/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The flow VLAN id object was retrieved.
404	1010	No flow VLAN was found for the provided flow VLAN ID.
500	1011	An error occurred while the flow VLAN field was being retrieved.

Response Description

The flow VLAN ID after it is retrieved. A flow VLAN ID object contains the following fields:

id - Long - The ID of the flow VLAN field.
enterprise_vlan_id - Short - The enterprise VLAN ID.
customer_vlan_id - Short - The customer VLAN ID.

Response Sample

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

POST /ariel/flow_vlans

Creates a new flow VLAN field as specified by input parameters.

Table 185: POST /ariel/flow_vlans Resource Details

MIME Type
application/json

Table 186: POST /ariel/flow_vlans Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 187: POST /ariel/flow_vlans Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

body

Object

application/json

Only the enterprise VLAN ID and customer VLAN ID can be set when creating a new flow VLAN field. All other fields are ignored.

id - Int - The ID of the flow VLAN field. Cannot be updated by POST.
enterprise_vlan_id - Short - The enterprise VLAN ID for the flow VLAN domain configuration field. The value must be in the range 0 - 4095, where 0 indicates the enterprise VLAN field is non-existent.
customer_vlan_id - Short - The customer VLAN ID for the flow VLAN domain configuration field. The value must be in the range 1 - 4095.

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

Table 188: POST /ariel/flow_vlans Response Codes

HTTP Response Code	Unique Code	Description
201		The flow VLAN field has been successfully created.
409	1020	A flow VLAN ID object parameter already exists and belongs to a domain.
422	1022	The VLAN provided was invalid. Customer VLAN ID must be between 1 and 4095.
422	1023	The VLAN provided was invalid. Enterprise VLAN ID must be between 0 and 4095 and customer VLAN ID must be between 1 and 4095.
422	1024	The VLAN provided was invalid. Enterprise VLAN ID must be between 0 and 4095.
500	1025	An error occurred while the flow VLAN field was being created.

Response Description

New flow VLAN ID object. A flow VLAN ID object contains the following fields:

id - Int - The ID of the flow VLAN field.
enterprise_vlan_id - Short - The enterprise VLAN ID.
customer_vlan_id - Short - The customer VLAN ID.

Response Sample

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

GET /ariel/functions/{function_name}

Retrieves AQL Function with given name for a given database.

Table 189: GET /ariel/functions/{function_name} Resource Details

MIME Type
application/json

Table 190: GET /ariel/functions/{function_name} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
database	query	Required	String	text/plain	Required - Name of DB to retrieve functions for.
function_name	path	Required	String	text/plain	Required - The name of function to retrieve.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 191: GET /ariel/functions/{function_name} Response Codes

HTTP Response Code	Unique Code	Description
200		Function is retrieved

Response Description

List of AQL Functions.

Response Sample

{ "args_types": [ "String" ], "catalog": "String", "class_name": "String", "info": "String", "name": "String", "required_args": 42, "required_capabilities": "String", "return_type": "String", "var_args": true }

GET /ariel/functions

Retrieves AQL Functions for given database.

Table 192: GET /ariel/functions Resource Details

MIME Type
application/json

Table 193: GET /ariel/functions Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
database	query	Required	String	text/plain	Name of DB to retrieve functions for.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 194: GET /ariel/functions Response Codes

HTTP Response Code	Unique Code	Description
200		Functions are retrieved

Response Description

List of AQL Functions.

Response Sample

[ { "args_types": [ "String" ], "catalog": "String", "class_name": "String", "info": "String", "name": "String", "required_args": 42, "required_capabilities": "String", "return_type": "String", "var_args": true } ]

GET /ariel/lookups

Retrieves a list of all tagged field lookups

Table 195: GET /ariel/lookups Resource Details

MIME Type
application/json

Table 196: GET /ariel/lookups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 197: GET /ariel/lookups Response Codes

HTTP Response Code	Unique Code	Description
200		The lookup list was retrieved.
500	1020	Internal server error

Response Description

The list of available tagged field lookups.

Response Sample

[ { "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" } ]

DELETE /ariel/lookups/{name}

Deletes a tagged field lookup with particular name

Table 198: DELETE /ariel/lookups/{name} Resource Details

MIME Type
application/json

Table 199: DELETE /ariel/lookups/{name} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
name	path	Required	String	text/plain	The name of this lookup entry
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 200: DELETE /ariel/lookups/{name} Response Codes

HTTP Response Code	Unique Code	Description
202		The lookup was deleted.
404	1002	Lookup doesn't exist
500	1020	Internal server error

Response Description

The deleted field lookup.

Response Sample

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

GET /ariel/lookups/{name}

Retrieves a tagged field lookup by name.

Table 201: GET /ariel/lookups/{name} Resource Details

MIME Type
application/json

Table 202: GET /ariel/lookups/{name} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
name	path	Required	String	text/plain	The name of lookup entry to be retrieved.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 203: GET /ariel/lookups/{name} Response Codes

HTTP Response Code	Unique Code	Description
200		The lookup was retrieved.
404	1002	Lookup with this name does not exist
500	1020	Internal server error

Response Description

The lookup associated with particular name.

Response Sample

POST /ariel/lookups/{name}

Updates a tagged field lookup with particular name

Table 204: POST /ariel/lookups/{name} Resource Details

MIME Type
application/json

Table 205: POST /ariel/lookups/{name} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
name	path	Required	String	text/plain	The name of this lookup entry
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 206: POST /ariel/lookups/{name} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
data	Object	application/json	Json structure representing all changeable fields for this lookup entry	{ "default_value": "String", "map": { "String": "String" } }

Table 207: POST /ariel/lookups/{name} Response Codes

HTTP Response Code	Unique Code	Description
200		The lookup was created.
404	1002	Lookup doesn't exist
500	1020	Internal server error

Response Description

The updated field lookup.

Response Sample

POST /ariel/lookups

Creates a new tagged field lookup

Table 208: POST /ariel/lookups Resource Details

MIME Type
application/json

Table 209: POST /ariel/lookups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 210: POST /ariel/lookups Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
data	Object	application/json	Json structure representing all fields for new lookup entry	{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

Table 211: POST /ariel/lookups Response Codes

HTTP Response Code	Unique Code	Description
201		The lookup was created.
500	1020	Internal server error

Response Description

The newly created field lookup.

Response Sample

GET /ariel/parser_keywords

Retrieves keywords applicable to AQL Parser.

Retrieves AQL Parser set of keywords

Table 212: GET /ariel/parser_keywords Resource Details

MIME Type
application/json

Table 213: GET /ariel/parser_keywords Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 214: GET /ariel/parser_keywords Response Codes

HTTP Response Code	Unique Code	Description
200		AQL Parser information retrieved

Response Description

Information about the AQL Parser.

Response Sample

{ "keywords": [ "String" ], "where_clause_keywords": [ "String" ] }

POST /ariel/processors/aql_metadata

Parses the Ariel Query Language (AQL) query expression and returns expected metadata without execution of the query.

This endpoint only accepts SELECT query expressions.

Table 215: POST /ariel/processors/aql_metadata Resource Details

MIME Type
application/json

Table 216: POST /ariel/processors/aql_metadata Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
query_ expression	query	Required	String	text/plain	Required - The AQL query for metadata.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 217: POST /ariel/processors/aql_metadata Response Codes

HTTP Response Code	Unique Code	Description
200		An AQL query expression was successfully validated.
422	2000	The query_expression contains invalid AQL syntax.
500	1020	An error occurred during the attempt to validate AQL.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of columns that are defined for the specified AQL query. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

GET /ariel/saved_search_delete_tasks/{task_id}

Retrieves the delete the Ariel saved search task status.

Table 218: GET /ariel/saved_search_delete_tasks/{task_id} Resource Details

MIME Type
application/json

Table 219: GET /ariel/saved_search_delete_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 220: GET /ariel/saved_search_delete_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The delete task status was retrieved.
404	1002	The delete task status was exist.
500	1020	An error occurred during the attempt to retrieve the delete task status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/ariel/saved_search_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /ariel/saved_search_dependent_tasks/{task_id}

Retrieves the dependent Ariel saved search task status.

Table 221: GET /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 222: GET /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 223: GET /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The dependent task status was retrieved.
404	1002	The dependent task status does not exist.
500	1020	An error occurred during the attempt to retrieve the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task.
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

POST /ariel/saved_search_dependent_tasks/{task_id}

Cancels the dependent Ariel saved search task.

Table 224: POST /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type
application/json

Table 225: POST /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 226: POST /ariel/saved_search_dependent_tasks/{task_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
task	Object	application/json	null	{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 227: POST /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The delete task status was retrieved.
404	1002	The dependent task status does not exist.
409	1004	The task is in a completed state.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state that the task is in.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested cancellation of the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. the vaalue is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /ariel/saved_search_dependent_tasks/{task_id}/results

Retrieves the Ariel saved search dependent task results.

Table 228: GET /ariel/saved_search_dependent_tasks/{task_id}/results Resource Details

MIME Type
application/json

Table 229: GET /ariel/saved_search_dependent_tasks/{task_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
task_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 230: GET /ariel/saved_search_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The Ariel saved search dependents were retrieved.
404	1002	The Dependent Task Status does not exist.
500	1020	An error occurred during the attempt to retrieve the Ariel saved searches.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

dependent_id - String - The ID of the dependent resource.
dependent_name - String - The name of the dependent resource. ( Default resources can have localized names )
dependent_owner - String - The owner of the dependent resource.
dependent_type - String - The type of the dependent resource.
dependent_database - String - The database of the dependent resource.
dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.
user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

GET /ariel/saved_searches

Retrieves a list of Ariel saved searches.

Table 231: GET /ariel/saved_searches Resource Details

MIME Type
application/json

Table 232: GET /ariel/saved_searches Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 233: GET /ariel/saved_searches Response Codes

HTTP Response Code	Unique Code	Description
200		The Ariel saved searches were retrieved.
422	1010	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the Ariel Saved Searches.

Response Description

An array of Ariel Saved Search objects. An Ariel Saved Search object contains the following fields:

id - Long - The ID of the Ariel saved search.
uuid - String - The uuid of the Ariel saved search.
name - String - The name of the Ariel saved search.
database - String - The database of the Ariel saved search, events or flows.
isShared - Boolean - True if the Ariel saved search is shared with other users.
owner - String - The owner of the Ariel saved search.
aql - String - The AQL query.
description - String - The description of the Ariel saved search.
isAggregate - Boolean - True if the Ariel saved search is an aggregate search.
isDashboard - Boolean - True if the Ariel saved search is in the dashboard.
isDefault - Boolean - True if the Ariel saved search is default search.
isQuickSearch - Boolean - True if the Ariel saved search is default search.

Response Sample

[ { "aql": "String", "database": "String <one of: EVENTS, FLOWS>", "description": "String", "id": 42, "is_aggregate": true, "is_dashboard": true, "is_default": true, "is_quick_search": true, "is_shared": true, "name": "String", "owner": "String", "uid": "String" } ]

GET /ariel/saved_searches/{id}

Retrieves an Ariel saved search.

Table 234: GET /ariel/saved_searches/{id} Resource Details

MIME Type
application/json

Table 235: GET /ariel/saved_searches/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	Required - The ID of the Ariel Saved Search to retrieve.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 236: GET /ariel/saved_searches/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Ariel saved search was retrieved.
404	1002	The Ariel saved search does not exist.
500	1020	An error occurred during the attempt to retrieve the Ariel Saved Search.

Response Description

The Ariel saved search after it is retrieved. An Ariel Saved Search object contains the following fields:

id - Long - The ID of the Ariel saved search.
uuid - String - The uuid of the Ariel saved search.
name - String - The name of the Ariel saved search.
database - String - The database of the Ariel saved search, events or flows.
isShared - Boolean - True if the Ariel saved search is shared with other users.
owner - String - The owner of the Ariel saved search.
aql - String - The AQL query.
description - String - The description of the Ariel saved search.
isAggregate - Boolean - True if the Ariel saved search is an aggregate search.
isDashboard - Boolean - True if the Ariel saved search is in the dashboard.
isDefault - Boolean - True if the Ariel saved search is default search.
isQuickSearch - Boolean - True if the Ariel saved search is default search.

Response Sample

{ "aql": "String", "database": "String <one of: EVENTS, FLOWS>", "description": "String", "id": 42, "is_aggregate": true, "is_dashboard": true, "is_default": true, "is_quick_search": true, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

POST /ariel/saved_searches/{id}

Updates the Ariel saved search.

Table 237: POST /ariel/saved_searches/{id} Resource Details

MIME Type
application/json

Table 238: POST /ariel/saved_searches/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	Required - The ID of the Ariel saved search to edit.
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 239: POST /ariel/saved_searches/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
saved_search	Object	application/json	Required - Ariel Saved Search object.	{ "is_shared": true, "owner": "String", "is_quick_search": true, "is_default": true, "is_dashboard": true, }

Table 240: POST /ariel/saved_searches/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The Ariel saved search was updated.
403	1009	You do not have the required capabilities to update the Ariel Saved Search.
403	1012	You are not allowed to update the owner field
404	1002	The Ariel saved search does not exist.
409	1007	The provided user does not have the required capabilities to own the Ariel saved search.
422	2000	null
422	1006	Non group by searches cannot be added to the dashboard.
422	1011	The provided new owner is not an existing user
500	1020	An error occurred during the attempt to update the Ariel Saved Search.

Response Description

The Ariel saved search after it has been updated. An Ariel Saved Search object contains the following fields:

id - Long - The Id of the saved search.
uuid - String - The uid string of the saved search. There are two formats of uid strings: one is rfc4122 pseudo randomly generated UUID format; the other is a string-digit format, e.g. SEARCH-250.
name - String - The name of the Ariel saved search.
database - String - The database of the Ariel saved search, events or flows.
isShared - Boolean - True if the saved search is shared with everyone.
owner - String - Owner of the saved search. Only the admin user can change the owner from one to another. Even the owner itself cannot reassign it to another user.
aql - String - The AQL string or a null value. If it is an AQL string, the saved search is an AQL based search. If it is a null value, the saved search is a baisc search that is based on query parameters instead of an AQL.
description - String - The description of the Ariel saved search.
isAggregate - Boolean - True if the saved search is aggregated, so it could be in dashboard.
isDashboard - Boolean - True if the Ariel saved search is in the dashboard.
isDefault - Boolean - True if this saved search is the default saved search to the user who calls this endpoint. A user can have only one default saved search.
isQuickSearch - Boolean - True if the saved search should be in quick search.

Response Sample

DELETE /ariel/saved_searches/{id}

Deletes an Ariel saved search. To ensure safe deletion, a dependency check is carried out. The check might take some time. An asynchronous task is started to do this check.

Table 241: DELETE /ariel/saved_searches/{id} Resource Details

MIME Type
application/json

Table 242: DELETE /ariel/saved_searches/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 243: DELETE /ariel/saved_searches/{id} Response Codes

HTTP Response Code	Unique Code	Description
202		The Ariel saved search delete command was accepted and is in progress.
403	1009	You do not have the required capabilities to delete the Ariel saved search.
404	1002	The Ariel saved search does not exist.
500	1020	An error occurred during the attempt to delete the Ariel Saved Search.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/ariel/saved_search_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /ariel/saved_searches/{id}/dependents

Retrieves the objects that depend on the Ariel saved search.

Table 244: GET /ariel/saved_searches/{id}/dependents Resource Details

MIME Type
application/json

Table 245: GET /ariel/saved_searches/{id}/dependents Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 246: GET /ariel/saved_searches/{id}/dependents Response Codes

HTTP Response Code	Unique Code	Description
202		The Ariel saved search dependents retrieval was accepted and is in progress
404	1002	The Ariel saved search does not exist
500	1020	An error occurred during the attempt to initiate the Ariel Saved Search dependents retrieval task

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

id - Long - The ID of the task.
message - String - The localized task message.
status - String - The current state of the task.
name - String - The name of the task.
created_by - String - The name of the user who started the task.
cancelled_by - String - The name of the user who requested to cancel the task.
created - Long - The time in milliseconds since epoch since the task was created.
started - Long - The time in milliseconds since epoch since the task was started.
modified - Long - The time in milliseconds since epoch since the task was modified.
completed - Long - The time in milliseconds since epoch since the task was completed.
number_of_dependents - Long - The number of dependents found. The value is null until the task completes.
maximum - Long - The maximum number of objects to check for dependency.
progress - Long - The number of objects that were checked for dependency.
task_components - Array - An array of task component objects. A task component object contains the following fields:
- message - String - The localized sub-task status message.
- status - String - The current state of the sub-task.
- sub_task_type - String - The type of the sub-task
- maximum - Long - The maximum number of objects to check for dependency.
- progress - Long - The number of objects that were checked for dependency.
- created - Long - The time in milliseconds since epoch since the sub-task was created.
- started - Long - The time in milliseconds since epoch since the sub-task was started.
- modified - Long - The time in milliseconds since epoch since the sub-task was modified.
- completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

GET /ariel/searches

Retrieves the list of Ariel searches. Search IDs for completed and active searches are returned.

Table 247: GET /ariel/searches Resource Details

MIME Type
application/json

Table 248: GET /ariel/searches Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
db_name	query	Optional	String	text/plain	Optional - The name of the Ariel database to retrieve the list of Ariel searches.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 249: GET /ariel/searches Response Codes

HTTP Response Code	Unique Code	Description
200		The search list was retrieved.
500	1020	An error occurred during the attempt to retrieve the list of searches.
503	1010	The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of search IDs.

Response Sample

[ "String" ]

POST /ariel/searches

Create a new asynchronous Ariel search.

Creates a new Ariel search as specified by the Ariel Query Language (AQL) query expression. Searches are executed asynchronously. A reference to the search ID is returned and should be used in subsequent API calls to determine the status of the search and retrieve the results once it is complete.

This endpoint only accepts SELECT query expressions.

Queries are applied to the range of data in a certain time interval. By default this time interval is the last 60 seconds. An alternative time interval can be specified by specifying them as part of the query expression. For further information, see the AQL reference guide.

Table 250: POST /ariel/searches Resource Details

MIME Type
application/json

Table 251: POST /ariel/searches Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
query_expression	query	Optional	String	text/plain	Optional - The AQL query to execute. Mutually exclusive with saved_search_id
saved_search_id	query	Optional	Number (Integer)	text/plain	Optional - Saved search ID to execute. Mutually exclusive with queryExpression

Table 252: POST /ariel/searches Response Codes

HTTP Response Code	Unique Code	Description
201		A new Ariel search was successfully created.
404	1002	The Ariel saved search does not exist.
409	1004	The search cannot be created. The requested search ID that was provided in the query expression is already in use. Please use a unique search ID (or allow one to be generated).
422	2000	The query_expression contains invalid AQL syntax.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to create a new search.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search ID. Use the search ID to access or manipulate the search with the other API endpoints.

If the exact search being created was already recently created, the response message will return a reference to the original search ID rather than creating a new search.

Response Sample

SearchStatus { "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

DELETE /ariel/searches/{search_id}

Deletes an Ariel search. This discards any results that were collected and stops the search if it is in progress. This search is deleted regardless of whether the results were saved.

Table 253: DELETE /ariel/searches/{search_id} Resource Details

MIME Type
application/json

Table 254: DELETE /ariel/searches/{search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
search_id	path	Required	String	text/plain	Required - The search ID of the search to delete.

Table 255: DELETE /ariel/searches/{search_id} Response Codes

HTTP Response Code	Unique Code	Description
202		The delete request has been accepted.
404	1002	The search does not exist.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to delete the search.
503	1010	The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the deleted search.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}

Retrieve status information for a search, based on the search ID parameter. The same informational fields are returned regardless of whether the search is in progress or is complete.

Table 256: GET /ariel/searches/{search_id} Resource Details

MIME Type
application/json

Table 257: GET /ariel/searches/{search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
search_id	path	Required	String	text/plain	Required. The identifier for an Ariel search.
Prefer	header	Optional	String	text/plain	Optional. Specify 'wait=N' where N is number of seconds to wait for COMPLETED status of the search.

Table 258: GET /ariel/searches/{search_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The search information was retrieved.
206		The search information was retrieved with 'Prefer: wait=N' timeout(sec) expired before the search is completed
404	1002	The search does not exist.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the search information.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search status.

Response Sample

GET /ariel/searches/{search_id}/metadata

Retrieve the columns that are defined for the specified Ariel search id. This is the set of columns that can be explicitly named in the column list of a SELECT query.

Table 259: GET /ariel/searches/{search_id}/metadata Resource Details

MIME Type
application/json

Table 260: GET /ariel/searches/{search_id}/metadata Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
search_id	path	Required	String	text/plain	null
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 261: GET /ariel/searches/{search_id}/metadata Response Codes

HTTP Response Code	Unique Code	Description
200		Columns were successfully retrieved.
404	1002	The search does not exist.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of columns that are defined for the specified database. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

POST /ariel/searches/{search_id}

Updates details for an Ariel search. You can update searches in the following ways:

To cancel an active search, set the status parameter to CANCELED. This stops the search and keeps any search results that were collected before the search was canceled.
The results for a completed search can be saved by setting the save_results parameter to true. This ensures that the search is not automatically removed when it expires in accordance with the retention policy.

The Ariel server uses an internal retention policy to manage available disk space. Searches might be deleted automatically, according to the settings of the retention policy. Searches with saved results are not automatically reclaimed by the server and are therefore retained. A search can be explicitly deleted by using the DELETE /searches/{search_id} endpoint.

Note

Saving too many search results might result in insufficient disk space to process new searches.

Table 262: POST /ariel/searches/{search_id} Resource Details

MIME Type
application/json

Table 263: POST /ariel/searches/{search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
search_id	path	Required	String	text/plain	Required. The ID of the search to update.
status	query	Optional	String	text/plain	Optional. The only accepted value is CANCELED. If this value is provided, the search is canceled.
save_results	query	Optional	String	text/plain	Optional. The only accepted value is true. If this value is provided, the search results are not deleted by the search expiration removal process. If status parameter was provided, this parameter is not checked and silently ignored.

Table 264: POST /ariel/searches/{search_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The search was updated.
404	1002	The search does not exist.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the search.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search that was updated.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "EXECUTE", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": "1467049610018" }, { "sourceip": "10.100.100.121", "starttime": "1467049610019" } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}/results

Retrieves search results in the requested format.

Retrieve the results of the Ariel search that is identified by the search ID. The Accepts request header indicates the format of the result. The formats are RFC compliant and can be JSON, CSV, XML, or tabular text.

By default, all query result records are returned. To restrict the results to a contiguous subset of the records, you can supply a Range header to specify the inclusive range of records to be returned.

This end-point works with query results that are generated by AQL query expressions. This endpoint might not work as expected for results that are generated by other means. Search results might not be retrievable for searches that are created on the Console.

The response samples are for the following query: Select sourceIP, destinationIP from events.

Table 265: GET /ariel/searches/{search_id}/results Resource Details

MIME Type
application/json application/csv text/table application/xml

Table 266: GET /ariel/searches/{search_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
search_id	path	Required	String	text/plain	The ID of the search criteria for the returned results.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 267: GET /ariel/searches/{search_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The search results were retrieved.
404	1002	The search does not exist.
404	1003	Search results not found. The search is still in progress.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the search results.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

The search results for the specified search ID. The format that is used to encapsulate the data depends on the format specified in the Accept header for this request.

Response Sample

{ "events": [ { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" }, { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" } ] }

GET /ariel/taggedfields

Retrieves a list of available tagged fields for Ariel catalog.

Table 268: GET /ariel/taggedfields Resource Details

MIME Type
application/json

Table 269: GET /ariel/taggedfields Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
catalog	query	Optional	String	text/plain	Optional. The name of the Ariel database that contains the tagged fields that you want to retrieve.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 270: GET /ariel/taggedfields Response Codes

HTTP Response Code	Unique Code	Description
200		The tagged field list was retrieved.
404	1002	The catalog does not exist
500	1020	Internal server error

Response Description

The list of available tagged fields.

Response Sample

[ { "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" } ]

POST /ariel/taggedfields

Creates a new Tagged field as specified by input parameters.

Table 271: POST /ariel/taggedfields Resource Details

MIME Type
application/json

Table 272: POST /ariel/taggedfields Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
tag	query	Required	String	text/plain	The number to be assigned to this tagged property
name	query	Required	String	text/plain	The name of this tagged property
catalog	query	Required	String	text/plain	The name of the Ariel database that will contain the new tagged field.
type	query	Required	String	text/plain	The type of this tagged field
array	query	Required	Boolean	text/plain	Is this field an array?
format_class_name	query	Optional	String	text/plain	Fully qualified name of formatter class
format_params	query	Optional	String	text/plain	Optional parameter for formatter
description	query	Optional	String	text/plain	Optional description of tagged property
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 273: POST /ariel/taggedfields Response Codes

HTTP Response Code	Unique Code	Description
201		A new tagged field was successfully created.
404	1002	null
500	1020	null

Response Description

New Tagged field

Response Sample

{ "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

DELETE /ariel/taggedfields/{tag}

Deletes a Tagged field with specified tag.

Table 274: DELETE /ariel/taggedfields/{tag} Resource Details

MIME Type
application/json

Table 275: DELETE /ariel/taggedfields/{tag} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
tag	path	Required	String	text/plain	The number to be assigned to this tagged property
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 276: DELETE /ariel/taggedfields/{tag} Response Codes

HTTP Response Code	Unique Code	Description
202		Tagged field was successfully deleted.
404	1002	null
500	1020	null

Response Description

Deleted tagged field

Response Sample

GET /ariel/taggedfields/{tag}

Retrieves a tagged field with specified tag number.

Table 277: GET /ariel/taggedfields/{tag} Resource Details

MIME Type
application/json

Table 278: GET /ariel/taggedfields/{tag} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
tag	path	Required	String	text/plain	number, associated with this particular tag property
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 279: GET /ariel/taggedfields/{tag} Response Codes

HTTP Response Code	Unique Code	Description
200		The tagged field list was retrieved.
404	1002	The catalog does not exist
500	1020	Internal server error

Response Description

Tagged field, associated with this tag number

Response Sample

POST /ariel/taggedfields/{tag}

Updates a tagged field with specified tag number.

Table 280: POST /ariel/taggedfields/{tag} Resource Details

MIME Type
application/json

Table 281: POST /ariel/taggedfields/{tag} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
tag	path	Required	String	text/plain	The number to be assigned to this tagged property
format_class_name	query	Optional	String	text/plain	Fully qualified name of formatter class
format_params	query	Optional	String	text/plain	Optional parameter for formatter
description	query	Optional	String	text/plain	Optional description of tagged property
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 282: POST /ariel/taggedfields/{tag} Response Codes

HTTP Response Code	Unique Code	Description
200		Tagged field was successfully updated.
404	1002	The catalog does not exist
500	1020	Internal server error

Response Description

Updated tagged field

Response Sample

POST /ariel/validators/aql

Validates the Ariel search as specified by the Ariel Query Language (AQL) query expression.

This endpoint only accepts SELECT query expressions.

Table 283: POST /ariel/validators/aql Resource Details

MIME Type
application/json

Table 284: POST /ariel/validators/aql Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
query_ expression	query	Required	String	text/plain	Required - The AQL query to validate.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 285: POST /ariel/validators/aql Response Codes

HTTP Response Code	Unique Code	Description
200		An AQL query expression was successfully validated.
500	1020	An error occurred during the attempt to validate AQL.
503	1010	The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Array of errors/warnings encountered during AQL validation or null if validation was successful.

Response Sample

{ "error_messages": [ { "code": 42, "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ] }

Asset Model Endpoints

Use the references for REST API V11.0 Asset Model endpoints.

GET /asset_model/assets

List all assets found in the model.

Table 286: GET /asset_model/assets Resource Details

MIME Type
application/json

Table 287: GET /asset_model/assets Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 288: GET /asset_model/assets Response Codes

HTTP Response Code	Unique Code	Description
200		The request to retrieve assets completed successfully.
500	1020	The server encountered an error while trying to retrieve the assets.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[{"interfaces": [{"mac_address": "String", "last_seen_profiler": 42, "created": 42, "first_seen_scanner": 42, "last_seen_scanner": 42, "ip_addresses": [{"last_seen_profiler": 42, "created": 42, "first_seen_scanner": 42, "last_seen_scanner": 42, "network_id": 42, "id": 42, "type": "String", "first_seen_profiler": 42, "value": "String"}], "id": 42, "first_seen_profiler": 42}], "id": 42, "domain_id": 42, "properties": [{"last_reported": 42, "name": "String", "type_id": 42, "id": 42, "last_reported_by": "String", "value": "String"}]}]

POST /asset_model/assets/{asset_id}

Update an asset with several pertinent pieces of information.

The asset_id tag is mandatory, and is the unique identifier for an asset. This field is available through the /asset_model/assets or /asset_model/saved_searches/{saved_search_id}/results query. To update properties, the property type ID which is available through the /asset_model/properties query must be provided along with the new value. See the sample provided demonstrating an example asset update.

Table 289: POST /asset_model/assets/{asset_id} Resource Details

MIME Type
text/plain

Table 290: POST /asset_model/assets/{asset_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
asset_id	path	Required	String	text/plain	Unique identifier of the asset to update.

Table 291: POST /asset_model/assets/{asset_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
asset	JSON	application/json	JSON representation of an asset.	{ "properties": [ { "type_id": 1001, "value": "given name value" }, { "type_id": 1002, "value": "unified name value" } ] }

Table 292: POST /asset_model/assets/{asset_id} Response Codes

HTTP Response Code	Unique Code	Description
202		The request to update the asset was successful. The update will take place when the asset profile application receives the request.
422	1005	One or more of the requested property updates were invalid.
500	1020	The server encountered an error registering the update with the asset profile application.

Response Description

Information about the asset that was updated.

Response Sample

String

GET /asset_model/properties

Get a list of available asset property types that can be used or applied against the /asset_model/assets endpoint.

Table 293: GET /asset_model/properties Resource Details

MIME Type
application/json

Table 294: GET /asset_model/properties Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 295: GET /asset_model/properties Response Codes

HTTP Response Code	Unique Code	Description
200		The request to retrieve the list of asset property types completed successfully.
500	1020	An error occurred while trying to retrieve the list of asset property types.

Response Description

List of asset properties. Per asset property type: id and name that make up this asset property type.

Response Sample

[ { "custom": true, "data_type": "String", "display": true, "id": 42, "name": "String", "state": 42 } ]

GET /asset_model/saved_search_groups

Retrieves a list the asset saved search groups.

Table 296: GET /asset_model/saved_search_groups Resource Details

MIME Type
application/json

Table 297: GET /asset_model/saved_search_groups Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 298: GET /asset_model/saved_search_groups Response Codes

HTTP Response Code	Unique Code	Description
200		The asset saved search groups were returned.
500	1020	An error occurred during the attempt to retrieve the asset saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

GET /asset_model/saved_search_groups/{group_id}

Retrieves an asset saved search group.

Table 299: GET /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 300: GET /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 301: GET /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The asset saved search group was retrieved.
404	1002	The asset saved search group does not exist.
500	1020	An error occurred during the attempt to retrieve the asset saved search group.

Response Description

A single Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The id of the parent group. ( Default resources can have localized names )
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group. ( Default groups can have localized names )
description - String - The description of the group. ( Default groups can have localized names )
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

POST /asset_model/saved_search_groups/{group_id}

Updates the owner of an asset saved search group.

Table 302: POST /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type
application/json

Table 303: POST /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 304: POST /asset_model/saved_search_groups/{group_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
group	Object	application/json	Required - Group object with the owner set to a valid deployed user.	{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

Table 305: POST /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The asset saved search group has been updated.
404	1002	The asset saved search group does not exist.
409	1004	The provided user does not have the required capabilities to own the asset saved search group.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the asset saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

id - Long - The ID of the group.
parent_id - Long - The ID of the parent group (default resources can have localized names).
type - String - The type of the group.
level - Long - The depth of the group in the group hierarchy.
name - String - The name of the group (default resources can have localized names).
description - String - The description of the group (default resources can have localized names).
owner - String - The owner of the group.
modified_time - Long - The time in milliseconds since epoch since the group was last modified.
child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

DELETE /asset_model/saved_search_groups/{group_id}

Deletes an asset saved search group.

Table 306: DELETE /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type
text/plain

Table 307: DELETE /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
group_id	path	Required	Number (Integer)	text/plain	null

Table 308: DELETE /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The asset saved search group was deleted.
404	1002	The asset saved search group does not exist.
409	1004	null
500	1020	An error occurred during the attempt to delete the asset saved search group.

Response Description

Response Sample

GET /asset_model/saved_searches

Retrieves a list of saved searches that can be used or applied against the /asset_model/saved_searches/{saved_search_id}/results query.

Table 309: GET /asset_model/saved_searches Resource Details

MIME Type
application/json

Table 310: GET /asset_model/saved_searches Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 311: GET /asset_model/saved_searches Response Codes

HTTP Response Code	Unique Code	Description
200		The request to retrieve the list of saved searches completed successfully.
500	1020	The server encountered an error during the attempt to retrieve the list of saved searches.

Response Description

A list of saved searches. Each saved search contains an ID, name, and list of filters.

Response Sample

[ { "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" } ]

GET /asset_model/saved_searches/{saved_search_id}

Retrieves an asset saved search.

Table 312: GET /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type
application/json

Table 313: GET /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
saved_search_id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 314: GET /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The asset saved search was retrieved,
404	1002	The asset saved search does not exist,
500	1020	An error occurred during the attempt to retrieve the asset saved search,

Response Description

The asset saved search after it is retrieved. An Asset Saved Search object contains the following fields:

id - Long - The ID of the asset saved search.
name - String - The name of the asset saved search.
owner - String - The owner of the asset saved search.
isShared - Boolean - True if the asset saved search is shared with other users.
description - String - The description of the asset saved search.
filters - List of Strings - The asset saved search filters.
columns - List of Strings - The asset saved search columns.

Response Sample

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

POST /asset_model/saved_searches/{saved_search_id}

Updates the asset saved search owner only.

Table 315: POST /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type
application/json

Table 316: POST /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
saved_search_id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 317: POST /asset_model/saved_searches/{saved_search_id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
saved_search	Object	application/json	null	{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

Table 318: POST /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code	Unique Code	Description
200		The asset saved search was updated.
403	1009	You do not have the required capabilities to update the asset saved search.
404	1002	The asset saved search does not exist.
409	1004	The provided user does not have the required capabilities to own the asset saved search.
422	1005	A request parameter is not valid.
500	1020	An error occurred during the attempt to update the asset saved search.

Response Description

The asset saved search after it is updated. An Asset Saved Search object contains the following fields:

id - Long - The ID of the asset saved search.
name - String - The name of the asset saved search.
owner - String - The owner of the asset saved search.
isShared - Boolean - True if the asset saved search is shared with other users.
description - String - The description of the asset saved search.
filters - List of Strings - The asset saved search filters.
columns - List of Strings - The asset saved search columns.

Response Sample

DELETE /asset_model/saved_searches/{saved_search_id}

Deletes an asset saved search.

Table 319: DELETE /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type
text/plain

Table 320: DELETE /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
saved_search_id	path	Required	Number (Integer)	text/plain	null

Table 321: DELETE /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code	Unique Code	Description
204		The asset saved searchh was deleted.
403	1009	You do not have the required capabilities to delete the asset saved search.
404	1002	The asset saved search does not exist.
500	1020	An error occurred during the attempt to delete the asset saved search.

Response Description

Response Sample

GET /asset_model/saved_searches/{saved_search_id}/results

Retrieves a list of assets based on the results of an asset saved search.

Table 322: GET /asset_model/saved_searches/{saved_search_id}/results Resource Details

MIME Type
application/json

Table 323: GET /asset_model/saved_searches/{saved_search_id}/results Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
saved_search_id	path	Required	String	text/plain	Unique identifier of the saved search used to retrieve assets.
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 324: GET /asset_model/saved_searches/{saved_search_id}/results Response Codes

HTTP Response Code	Unique Code	Description
200		The request to retrieve assets completed successfully.
404	1002	null
422	1005	The unique identifier of the saved search provided was invalid.
500	1003	The server encountered an error executing the saved search.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[ { "domain_id": 42, "id": 42, "interfaces": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "ip_addresses": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "last_seen_profiler": 42, "last_seen_scanner": 42, "network_id": 42, "type": "String", "value": "String" } ], "last_seen_profiler": 42, "last_seen_scanner": 42, "mac_address": "String" } ], "properties": [ { "id": 42, "last_reported": 42, "last_reported_by": "String", "name": "String", "type_id": 42, "value": "String" } ] } ]

Authentication Endpoints

Use the references for REST API V11.0 authentication endpoints.

POST /auth/logout

Invoke this method as an authorized user and your session will be invalidated.

Table 325: POST /auth/logout Resource Details

MIME Type
text/plain

There are no parameters for this endpoint.

Table 326: POST /auth/logout Response Codes

HTTP Response Code	Unique Code	Description
200		The session was invalidated.

Response Description

Returns true. Throws exception upon failure.

Response Sample

true

Bandwidth Manager Endpoints

Use the references for REST API V11.0 bandwidth manager endpoints.

GET /bandwidth_manager/configurations

Retrieves a list of configurations

Table 327: GET /bandwidth_manager/configurations Resource Details

MIME Type
application/json

Table 328: GET /bandwidth_manager/configurations Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
sort	query	Optional	String	text/plain	Optional - This parameter is used to sort the elements in a list.

Table 329: GET /bandwidth_manager/configurations Response Codes

HTTP Response Code	Unique Code	Description
200		The configurations were retrieved.
422	1010	A filter parameter is not valid.
422	1030	A sort parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the configurations.

Response Description

An array of configuration objects. A configuration object contains the following fields:

Id - Long - The ID that is automatically generated for the configuration. The ID is unique for each configuration that is created.
name - String - The name of the configuration.
host_id - Long - The ID of the managed host for the configuration. If the ID is null, the configuration applies to all hosts in the deployment.
device_name - String - The network device for the configuration.If the name is null, the configuration applies to all devices.
kb_limit - Long - The bandwidth limit for the configuration in kilobytes/sec.
created_by - String - The created_by field is automatically populated with USER, JSA-SAF, JSA-SF or JSA-AQS-PRIO.

Response Sample

[ { "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" } ]

DELETE /bandwidth_manager/configurations/{id}

Delete a bandwidth manager configuration by ID.

Delete a configuration by sequence id.

Table 330: DELETE /bandwidth_manager/configurations/{id} Resource Details

MIME Type
text/plain

Table 331: DELETE /bandwidth_manager/configurations/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null

Table 332: DELETE /bandwidth_manager/configurations/{id} Response Codes

HTTP Response Code	Unique Code	Description
204		The configuration has been deleted.
404	1001	The configuration id does not exist
409	1002	The configuration has filters or a child configuration.
420	1023	null
500	1020	An error occurred attempting to retrieve the configuration.

Response Description

Response Sample

GET /bandwidth_manager/configurations/{id}

Retrieves a configuration.

Table 333: GET /bandwidth_manager/configurations/{id} Resource Details

MIME Type
application/json

Table 334: GET /bandwidth_manager/configurations/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 335: GET /bandwidth_manager/configurations/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The configuration was retrieved.
404	1002	The configuration does not exist.
500	1020	An error occurred during the attempt to retrieve the configuration.

Response Description

The configuration after it is retrieved. A configuration object contains the following fields:

Id - Long - The ID that is automatically generated for the configuration. The ID is unique for each configuration that is created.
name - String - The name of the configuration.
host_id - Long - The ID of the managed host for the configuration. If the ID is null, the configuration applies to all hosts in the deployment.
device_name - String - The network device for the configuration.If the name is null, the configuration applies to all devices.
kb_limit - Long - The bandwidth limit for the configuration in kilobytes/sec.
created_by - String - The created_by field is automatically populated with USER, JSA-SAF, JSA-SF or JSA-AQS-PRIO.

Response Sample

{ "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" }

POST /bandwidth_manager/configurations/{id}

Update a bandwidth manager configuration by ID.

Update a configuration by sequence id.

Table 336: POST /bandwidth_manager/configurations/{id} Resource Details

MIME Type
application/json

Table 337: POST /bandwidth_manager/configurations/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 338: POST /bandwidth_manager/configurations/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
configuration	Object	application/json	null	{ "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" }

Table 339: POST /bandwidth_manager/configurations/{id} Response Codes

HTTP Response Code	Unique Code	Description
204		The configuration has been deleted.
404	1002	The configuration does not exist.
420	1023	null
422	1005	The kb_limit parameter value must be a positive integer.
422	1008	The name parameter value must be less than 100 characters.
422	1009	The name parameter must not contain the $ character.
500	1020	An error occurred attempting to retrieve the configuration.

Response Description

Response Sample

{ "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" }

POST /bandwidth_manager/configurations

Creates a bandwidth manager configuration.

Table 340: POST /bandwidth_manager/configurations Resource Details

MIME Type
application/json

Table 341: POST /bandwidth_manager/configurations Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 342: POST /bandwidth_manager/configurations Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
configuration	Object	application/json	null	{ "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" }

Table 343: POST /bandwidth_manager/configurations Response Codes

HTTP Response Code	Unique Code	Description
202		The configuration was created successfully.
422	1000	The managed host id does not exist.
422	1001	A parameter was passed incorrectly.
422	1002	The host_id parameter must be a positive integer or -1.
422	1005	The kb_limit parameter value must be a positive integer.
422	1008	The name parameter value must be less than 100 characters.
422	1009	The hostname parameter value must be less than 100 characters.
422	1010	The name parameter must not contain the $ character.
500	1020	An error occurred attempting to retrieve the configuration.

Response Description

Response Sample

{ "created_by": "String", "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "kb_limit": 42, "name": "String" }

GET /bandwidth_manager/filters

Retrieves a list of egress filters

Table 344: GET /bandwidth_manager/filters Resource Details

MIME Type
application/json

Table 345: GET /bandwidth_manager/filters Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
Range	header	Optional	String	text/plain	Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.
filter	query	Optional	String	text/plain	Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
sort	query	Optional	String	text/plain	Optional - This parameter is used to sort the elements in a list.

Table 346: GET /bandwidth_manager/filters Response Codes

HTTP Response Code	Unique Code	Description
200		The rules were retrieved.
422	1010	A request parameter is not valid.
422	1030	A sort parameter is not valid.
500	1020	An error occurred during the attempt to retrieve the filters.

Response Description

An array of filter objects. A filter object contains the following fields:

id - Long - The ID that is automatically generated for the filter. The ID is unique for each filter that is created.
name - String - The name of the filter that is supplied by the user.
host_id - Long - The ID of the managed host for the filter. If the ID is null, the filter applies to all hosts in the deployment.
device_name - String - The network device for the filter. If the name is null, the filter applies to all devices.
source_port - Integer - The source port for the filter.
source_port_mask - Integer - The source port mask for the filter.
source_cidr - String - The source CIDR for the filter.
destination_port - Integer - The destination port for the filter.
destination_port_mask - Integer - The destination port mask for the filter.
destination_cidr - String - The destination CIDR for the filter.
match_all - Boolean - Indicates whether the filter matches all incoming packets by priority level. The default is false, and can be set to true.
created_by - String - The created_by field is automatically populated with USER, JSA-SAF, JSA-SF or JSA-AQS-PRIO.

Response Sample

[ { "configuration_id": 42, "created_by": "String", "destination_cidr": "String", "destination_port": 42, "destination_port_mask": 42, "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "match_all": true, "name": "String", "partner_id": 42, "source_cidr": "String", "source_port": 42, "source_port_mask": 42 } ]

DELETE /bandwidth_manager/filters/{id}

Update a filter by ID.

Table 347: DELETE /bandwidth_manager/filters/{id} Resource Details

MIME Type
text/plain

Table 348: DELETE /bandwidth_manager/filters/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null

Table 349: DELETE /bandwidth_manager/filters/{id} Response Codes

HTTP Response Code	Unique Code	Description
204		The filter has been deleted.
404	1020	The filter does not exist.
420	1023	null
500	1021	An error occurred attempting to retrieve the filter.

Response Description

Response Sample

GET /bandwidth_manager/filters/{id}

Retrieves a filter.

Table 350: GET /bandwidth_manager/filters/{id} Resource Details

MIME Type
application/json

Table 351: GET /bandwidth_manager/filters/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	query	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 352: GET /bandwidth_manager/filters/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The filter was retrieved.
404	1000	The filter does not exist.
500	1020	An error occurred during the attempt to retrieve the filter.

Response Description

The filter after it is retrieved. A filter object contains the following fields:

id - Long - The ID that is automatically generated for the filter. The ID is unique for each filter that is created.
name - String - The name of the filter that is supplied by the user.
host_id - Long - The ID of the managed host for the filter. If the ID is null, the filter applies to all hosts in the deployment.
device_name - String - The network device for the filter. If the name is null, the filter applies to all devices.
source_port - Integer - The source port for the filter.
source_port_mask - Integer - The source port mask for the filter.
source_cidr - String - The source CIDR for the filter.
destination_port - Integer - The destination port for the filter.
destination_port_mask - Integer - The destination port mask for the filter.
destination_cidr - String - The destination CIDR for the filter.
match_all - Boolean - Indicates whether the filter matches all incoming packets by priority level. The default is false, and can be set to true.
created_by - String - The created_by field is automatically populated with USER, JSA-SAF, JSA-SF or JSA-AQS-PRIO.

Response Sample

{ "configuration_id": 42, "created_by": "String", "destination_cidr": "String", "destination_port": 42, "destination_port_mask": 42, "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "match_all": true, "name": "String", "partner_id": 42, "source_cidr": "String", "source_port": 42, "source_port_mask": 42 }

POST /bandwidth_manager/filters/{id}

Delete a filter by sequence ID.

Update a filter by sequence ID.

Table 353: POST /bandwidth_manager/filters/{id} Resource Details

MIME Type
application/json

Table 354: POST /bandwidth_manager/filters/{id} Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
id	path	Required	Number (Integer)	text/plain	null
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 355: POST /bandwidth_manager/filters/{id} Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
filter	Object	application/json	null	{ "configuration_id": 42, "created_by": "String", "destination_cidr": "String", "destination_port": 42, "destination_port_mask": 42, "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "match_all": true, "name": "String", "partner_id": 42, "source_cidr": "String", "source_port": 42, "source_port_mask": 42 }

Table 356: POST /bandwidth_manager/filters/{id} Response Codes

HTTP Response Code	Unique Code	Description
200		The filter has been updated.
404	1002	Bandwidth manager filter not found.
422	1005	null
422	1011	The source_port parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1012	The source_port_mask parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1013	The destination_port parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1014	The destination_port_mask parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1016	The name parameter value must not exceed 100 characters.
422	1018	The source_cidr parameter value must be a valid CIDR.
422	1019	The destination_cidr parameter value must be a valid CIDR.
422	1020	The name parameter must not contain the $ character.
500	1030	An error occurred attempting to retrieve the filter.

Response Description

Response Sample

POST /bandwidth_manager/filters

Creates a bandwidth manager filter

Table 357: POST /bandwidth_manager/filters Resource Details

MIME Type
application/json

Table 358: POST /bandwidth_manager/filters Request Parameter Details

Parameter	Type	Optionality	Data Type	MIME Type	Description
fields	header	Optional	String	text/plain	Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 359: POST /bandwidth_manager/filters Request Body Details

Parameter	Data Type	MIME Type	Description	Sample
class	Object	application/json	null	{ "configuration_id": 42, "created_by": "String", "destination_cidr": "String", "destination_port": 42, "destination_port_mask": 42, "device_name": "String", "host_id": 42, "hostname": "String", "id": 42, "match_all": true, "name": "String", "partner_id": 42, "source_cidr": "String", "source_port": 42, "source_port_mask": 42 }

Table 360: POST /bandwidth_manager/filters Response Codes

HTTP Response Code	Unique Code	Description
202		The configuration was created successfully.
404	1002	Unable to find the managed host by using the host_id.
422	1005	A parameter was passed incorrectly.
422	1004	The host_id parameter value must be a positive integer or null.
422	1010	null
422	1011	The source_port parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1012	The source_port_mask parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1013	The destination_port parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1014	The destination_port_mask parameter value must be a positive integer. The value must be in the range 1 - 65534.
422	1016	The name parameter value must not exceed 100 characters.
422	1017	The device_name parameter value must not exceed 100 characters.
422	1018	The source_cidr parameter value must be a valid CIDR.
422	1019	The destination_cidr parameter value must be a valid CIDR.
422	1020	The hostname parameter value must not exceed 100 characters.
422	1021	The configuration was not found.
422	1022	The name parameter must not contain the $ character.
500	1030	An error occurred trying to create the filter.

Response Description

Response Sample

Configuration Endpoints

Use the references for REST API V11.0 configuration endpoints.

GET /config/access/security_profiles

Get the list of deployed security profiles available in the system.

Get the list of deployed security profiles available in the system. The ADMIN or SAASADMIN capabilities are required to call this endpoint.

Table 361: GET /config/access/security_profiles Resource Details

MIME Type
application/json

Table 362: GET /config/access/security_profiles Request Parameter Details

Parameter	Type