Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Ariel Endpoints

 

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

GET /ariel/databases

Retrieves a list of available Ariel database names.

Table 1: GET /ariel/databases Resource Details

MIME Type

application/json

Table 2: 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 3: 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}

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

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

MIME Type

application/json

Table 5: 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.

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.

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 6: 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" } ] }

GET /ariel/event_saved_search_groups

Retrieves a list the event Ariel saved search groups.

Table 7: GET /ariel/event_saved_search_groups Resource Details

MIME Type

application/json

Table 8: 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.

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 9: 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

[ { "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 /ariel/event_saved_search_groups/{group_id}

Retrieves an event Ariel saved search group.

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

MIME Type

application/json

Table 11: 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 12: 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

{ "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 /ariel/event_saved_search_groups/{group_id}

Updates the owner of an event Ariel saved search group.

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

MIME Type

application/json

Table 14: 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 15: 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 16: 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

{ "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>" }

DELETE /ariel/event_saved_search_groups/{group_id}

Deletes an event Ariel saved search group.

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

MIME Type

text/plain

Table 18: 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 19: 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 20: GET /ariel/flow_saved_search_groups Resource Details

MIME Type

application/json

Table 21: 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.

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 22: 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

[ { "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 /ariel/flow_saved_search_groups/{group_id}

Retrieves a flow Ariel saved search group.

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

MIME Type

application/json

Table 24: 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 25: 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

{ "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 /ariel/flow_saved_search_groups/{group_id}

Updates the owner of a flow Ariel saved search group.

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

MIME Type

application/json

Table 27: 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 28: 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 29: 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

{ "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>" }

DELETE /ariel/flow_saved_search_groups/{group_id}

Deletes a flow Ariel saved search group.

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

MIME Type

text/plain

Table 31: 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 32: 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/parser_keywords

Retrieves keywords applicable to AQL Parser.

Table 33: GET /ariel/parser_keywords Resource Details

MIME Type

application/json

Table 34: 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 35: 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 36: POST /ariel/processors/aql_metadata Resource Details

MIME Type

application/json

Table 37: 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 38: 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

{ "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/saved_search_delete_tasks/{task_id}

Retrieves the delete the Ariel saved search task status.

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

MIME Type

application/json

Table 40: 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 41: 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

{ "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 /ariel/saved_search_dependent_tasks/{task_id}

Retrieves the dependent the Ariel saved search task status.

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

MIME Type

application/json

Table 43: 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 44: 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

{ "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_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

POST /ariel/saved_search_dependent_tasks/{task_id}

Cancels the dependent Ariel saved search task.

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

MIME Type

application/json

Table 46: 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 47: 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 48: 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

{ "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_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /ariel/saved_search_dependent_tasks/{task_id}/results

Retrieves the Ariel saved search dependent task results.

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

MIME Type

application/json

Table 50: 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 51: 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

[ { "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: 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_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, 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_TYPE>", "user_has_edit_permissions": true } ]

GET /ariel/saved_searches

Retrieves a list of Ariel saved searches.

Table 52: GET /ariel/saved_searches Resource Details

MIME Type

application/json

Table 53: 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.

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 54: 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.

Response Sample

[ { "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" } ]

GET /ariel/saved_searches/{id}

Retrieves an Ariel saved search.

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

MIME Type

application/json

Table 56: GET /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 57: 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.

Response Sample

{ "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

POST /ariel/saved_searches/{id}

Updates the Ariel saved search owner only.

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

MIME Type

application/json

Table 59: POST /ariel/saved_searches/{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 60: POST /ariel/saved_searches/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

saved_search

Object

application/json

null

{ "id": "1", "name": "String", "database": "String", "is_shared": true, "owner": "String" }

Table 61: 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.

404

1002

The Ariel saved search does not exist.

409

1004

The provided user does not have the required capabilities to own the Ariel saved search.

422

1005

A request parameter is not valid.

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 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.

Response Sample

{ "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

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 62: DELETE /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 63: 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 64: 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

{ "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 /ariel/saved_searches/{id}/dependents

Retrieves the objects that depend on the Ariel saved search.

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

MIME Type

application/json

Table 66: 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 67: 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

{ "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_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /ariel/searches

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

Table 68: GET /ariel/searches Resource Details

MIME Type

application/json

Table 69: 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 70: 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

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 71: POST /ariel/searches Resource Details

MIME Type

application/json

Table 72: POST /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_expression

query

Required

String

text/plain

Required - The AQL query to execute.

Table 73: POST /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new Ariel search was successfully created.

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

{ "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" }

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 74: DELETE /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 75: 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 76: 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 77: GET /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 78: 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 79: 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

{ "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}/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 80: GET /ariel/searches/{search_id}/metadata Resource Details

MIME Type

application/json

Table 81: 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

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.

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 82: 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

{ "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" } ] }

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 83: POST /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 84: 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 85: 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

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 86: GET /ariel/searches/{search_id}/results Resource Details

MIME Type

application/json application/csv text/table application/xml

Table 87: 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 88: 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": "1.1.1.1", "destinationIP": "127.0.0.1" }, { "sourceIP": "1.1.1.1", "destinationIP": "127.0.0.1" } ] }

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 89: POST /ariel/validators/aql Resource Details

MIME Type

application/json

Table 90: 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 91: 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>" } ] }