Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Reference Data Endpoints

 

Use the references for REST API V9.0 reference data endpoints.

GET /reference_data/map_delete_tasks/{task_id}

Retrieves the delete reference data map task status.

Table 1: GET /reference_data/map_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 2: GET /reference_data/map_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 3: GET /reference_data/map_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/reference_data/maps/map_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 /reference_data/map_dependent_tasks/{task_id}

Retrieves the dependent reference data map task status.

Table 4: GET /reference_data/map_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 5: GET /reference_data/map_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 6: GET /reference_data/map_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/reference_data/maps/map_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 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 /reference_data/map_dependent_tasks/{task_id}

Cancels the dependent reference data map task.

Table 7: POST /reference_data/map_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 8: POST /reference_data/map_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 9: POST /reference_data/map_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 10: POST /reference_data/map_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/reference_data/maps/map_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 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 /reference_data/map_dependent_tasks/{task_id}/results

Retrieves the reference data map dependent task results.

Table 11: GET /reference_data/map_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 12: GET /reference_data/map_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 13: GET /reference_data/map_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference data map dependents were retrieved.

404

1002

The dependent task status does not exist.

500

1020

An error occurred during the attempt to retrieve the reference data maps.

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 /reference_data/map_of_sets

Retrieve a list of all reference map of sets.

Table 14: GET /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 15: GET /reference_data/map_of_sets 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 16: GET /reference_data/map_of_sets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference map of sets

Response Description

A list of all of the reference map of sets. This returns information about the map of sets but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" } ]

POST /reference_data/map_of_sets

Create a new reference map of sets.

Table 17: POST /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 18: POST /reference_data/map_of_sets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference map of sets to create

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference map of sets. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

key_label

query

Optional

String

text/plain

Optional - The label to describe the keys

value_label

query

Optional

String

text/plain

Optional - The label to describe the data values

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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: POST /reference_data/map_of_sets Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference map of sets was successfully created

409

1004

The reference map of sets could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference map of sets

Response Description

Information about the newly created reference map of sets.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/map_of_sets/bulk_load/{name}

Adds or updates data in a reference map of sets.

Table 20: POST /reference_data/map_of_sets/bulk_load/{name} Resource Details

MIME Type

application/json

Table 21: POST /reference_data/map_of_sets/bulk_load/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the map of sets to add or update data in.

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 22: POST /reference_data/map_of_sets/bulk_load/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Array

application/json

Required - The JSON-formatted data to add or update in the reference map of sets.

{"key1":["Data11","Data12"], "key2":["Data21","Data22"], "key3":["Data31","Data32"], "key4":["Data41","Data42"], "key5":["Data51","Data52"], "key6":["Data61","Data62"]}

Table 23: POST /reference_data/map_of_sets/bulk_load/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

Data was successfully added or updated in the reference map of sets.

400

1001

An error occurred parsing the JSON-formatted message body.

404

1002

The reference map of sets does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to add or update data in the reference map of sets.

Response Description

Information about the reference map of sets where data was added or updated. This returns information about the reference map of sets but not the data that it contains.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/map_of_sets/{name}

Return the reference map of sets identified by name. If provided, limit specifies the number of records to return starting at the record that is specified by offset. If the number is not specified, then the first 20 records is returned.

Table 24: GET /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 25: GET /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets 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.

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 26: GET /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has been retrieved

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference map of sets

Response Description

The reference map of sets identified by the name specified in the request. The portion of the reference map of sets' data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": [ { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } ] }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/map_of_sets/{name}

Add or update an element in a reference map of sets.

Table 27: POST /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 28: POST /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to add or update an element in

key

query

Required

String

text/plain

Required - The key of the set to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference map of sets. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - This indicates where the data originated. The default value is 'reference data api'

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 29: POST /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has had an element added or updated

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference map of sets

Response Description

Information about the reference map of sets that has had an element added or updated. This returns information about the reference map of sets but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

DELETE /reference_data/map_of_sets/{name}

Remove a map of sets or purge its contents.

Table 30: DELETE /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 31: DELETE /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference map of sets should have its contents purged (true), keeping the reference map of sets structure. If the value is "false" or not specified the reference map of sets will be removed completely.

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: DELETE /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Map of Sets deletion or purge request has been accepted and is in progress

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference map of sets

Response Description

A status_id to retrieve the Reference Data Map of Sets deletion or purge status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

GET /reference_data/map_of_sets/{name}/dependents

Retrieves the dependents of the Map of Sets.

Table 33: GET /reference_data/map_of_sets/{name}/dependents Resource Details

MIME Type

application/json

Table 34: GET /reference_data/map_of_sets/{name}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets retrieve dependents 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 35: GET /reference_data/map_of_sets/{name}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Map of Sets dependent retrieval request has been accepted and is in progress

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to get the dependents for the reference map of sets

Response Description

A status_id to retrieve the Reference Data Map of Sets dependent retrieval status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

DELETE /reference_data/map_of_sets/{name}/{key}

Remove a value from a reference map of sets.

Table 36: DELETE /reference_data/map_of_sets/{name}/{key} Resource Details

MIME Type

application/json

Table 37: DELETE /reference_data/map_of_sets/{name}/{key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to remove a value from

key

path

Required

String

text/plain

Required - The key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference map of sets. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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: DELETE /reference_data/map_of_sets/{name}/{key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has had a value removed

404

1002

The reference map of sets does not exist

404

1003

The record does not exist in the reference map of sets

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the reference map of sets value

Response Description

Information about the reference map of sets that had a value removed. This returns information about the reference map of sets but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

GET /reference_data/map_of_sets_delete_tasks/{task_id}

Retrieves the delete reference data map of sets task status.

Table 39: GET /reference_data/map_of_sets_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 40: GET /reference_data/map_of_sets_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 /reference_data/map_of_sets_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/reference_data/map_of_sets/map_of_sets_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 /reference_data/map_of_sets_dependent_tasks/{task_id}

Retrieves the dependent reference data map of sets task status.

Table 42: GET /reference_data/map_of_sets_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 43: GET /reference_data/map_of_sets_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 /reference_data/map_of_sets_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/reference_data/map_of_sets/map_of_sets_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

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

Cancels the dependent reference data map of sets task.

Table 45: POST /reference_data/map_of_sets_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 46: POST /reference_data/map_of_sets_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 /reference_data/map_of_sets_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 /reference_data/map_of_sets_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/reference_data/map_of_sets/map_of_sets_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

{ "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 /reference_data/map_of_sets_dependent_tasks/{task_id}/results

Retrieves the reference data map of sets dependent task results.

Table 49: GET /reference_data/map_of_sets_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 50: GET /reference_data/map_of_sets_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 /reference_data/map_of_sets_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference data map of sets dependents have been retrieved.

404

1002

The dependent task status does not exist.

500

1020

An error occurred during the attempt to retrieve the reference data map of sets.

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 - 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 /reference_data/maps

Retrieve a list of all reference maps.

Table 52: GET /reference_data/maps Resource Details

MIME Type

application/json

Table 53: GET /reference_data/maps 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 54: GET /reference_data/maps Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference maps

Response Description

A list of all of the reference maps. This returns information about the maps but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" } ]

POST /reference_data/maps

Create a new reference map.

Table 55: POST /reference_data/maps Resource Details

MIME Type

application/json

Table 56: POST /reference_data/maps Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference map to create

key_label

query

Optional

String

text/plain

Optional - The label to describe the keys

value_label

query

Optional

String

text/plain

Optional - The label to describe the data values

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference map. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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: POST /reference_data/maps Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference map was successfully created

409

1004

The reference map could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference map

Response Description

Information about the newly created reference map.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/maps/bulk_load/{name}

Adds or updates data in a reference map.

Table 58: POST /reference_data/maps/bulk_load/{name} Resource Details

MIME Type

application/json

Table 59: POST /reference_data/maps/bulk_load/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of map to add or update data in.

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 /reference_data/maps/bulk_load/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Array

application/json

Required - The JSON-formatted data to add or update in the reference map.

{"key1":"Data1", "key2":"Data2", "key3":"Data3", "key4":"Data4", "key5":"Data5", "key6":"Data6"}

Table 61: POST /reference_data/maps/bulk_load/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

Data was successfully added or updated in the reference map.

400

1001

An error occurred parsing the JSON-formatted message body.

404

1002

The reference map does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to add or update data in the reference map.

Response Description

Information about the reference map where data was added or updated. This returns information about the reference map but not the data that it contains.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/maps/{name}

Retrieve the reference map identified by name. If it is provided, limit specifies the number of records to return starting at record that is specified by offset. If the number is not specified, then the first 20 records are returned.

Table 62: GET /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 63: GET /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map 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.

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 64: GET /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has been retrieved

404

1002

The reference map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference map

Response Description

The reference map identified by the name specified in the request. The portion of the reference map's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/maps/{name}

Add or update an element in a reference map.

Table 65: POST /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 66: POST /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to add or update an element in

key

query

Required

String

text/plain

Required - The key who's value we want to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference map. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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: POST /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had an element added or updated

404

1002

The reference map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference map

Response Description

Information about the reference map that had an element added or updated. This returns information about reference map but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

DELETE /reference_data/maps/{name}

Remove a reference map or purge its contents.

Table 68: DELETE /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 69: DELETE /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference map should have its contents purged (true), keeping the reference map structure. If the value is "false" or not specified the reference map will be removed completely.

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 70: DELETE /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Maps deletion or purge request has been accepted and is in progress

404

1002

The reference map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference map

Response Description

A status_id to retrieve the Reference Data Maps deletion or purge status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

GET /reference_data/maps/{name}/dependents

Retrieves the dependents of the Map.

Table 71: GET /reference_data/maps/{name}/dependents Resource Details

MIME Type

application/json

Table 72: GET /reference_data/maps/{name}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map retrieve dependents 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 73: GET /reference_data/maps/{name}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Maps dependent retrieval request has been accepted and is in progress

404

1002

The reference Map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to get the dependents for the reference map

Response Description

A status_id to retrieve the Reference Data Maps dependent retrieval status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

DELETE /reference_data/maps/{name}/{key}

Remove a value from a reference map.

Table 74: DELETE /reference_data/maps/{name}/{key} Resource Details

MIME Type

application/json

Table 75: DELETE /reference_data/maps/{name}/{key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to remove a value from

key

path

Required

String

text/plain

Required - The key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference map. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 76: DELETE /reference_data/maps/{name}/{key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had a value removed

404

1002

The reference map does not exist

404

1003

The record does not exist in the reference map

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the value from the reference map

Response Description

Information about the reference map that had an element removed. This returns information about map but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

GET /reference_data/set_delete_tasks/{task_id}

Retrieves the delete reference data set task status.

Table 77: GET /reference_data/set_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 78: GET /reference_data/set_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 79: GET /reference_data/set_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/reference_data/sets/set_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 /reference_data/set_dependent_tasks/{task_id}

Retrieves the dependent reference data set task status.

Table 80: GET /reference_data/set_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 81: GET /reference_data/set_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 82: GET /reference_data/set_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/reference_data/sets/set_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 /reference_data/set_dependent_tasks/{task_id}

Cancels the dependent reference data set task.

Table 83: POST /reference_data/set_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 84: POST /reference_data/set_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 85: POST /reference_data/set_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 86: POST /reference_data/set_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/reference_data/sets/set_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>" } ] }

GET /reference_data/set_dependent_tasks/{task_id}/results

Retrieves the reference data set dependent task results.

Table 87: GET /reference_data/set_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 88: GET /reference_data/set_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 89: GET /reference_data/set_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference data set dependents were retrieved.

404

1002

The dependent task status does not exist.

500

1020

An error occurred during the attempt to retrieve the reference data sets.

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 - 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 /reference_data/sets

Retrieve a list of all reference sets.

Table 90: GET /reference_data/sets Resource Details

MIME Type

application/json

Table 91: GET /reference_data/sets 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 92: GET /reference_data/sets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference sets

Response Description

A list of all of the reference sets. This returns information about the sets but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" } ]

POST /reference_data/sets

Create a new reference set.

Table 93: POST /reference_data/sets Resource Details

MIME Type

application/json

Table 94: POST /reference_data/sets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference set being created

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference set. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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 95: POST /reference_data/sets Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference set was successfully created

409

1004

The reference set could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference set

Response Description

Information about the newly created reference set.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/sets/bulk_load/{name}

Add or update data in a reference set.

Table 96: POST /reference_data/sets/bulk_load/{name} Resource Details

MIME Type

application/json

Table 97: POST /reference_data/sets/bulk_load/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of set to add or update data in

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 98: POST /reference_data/sets/bulk_load/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Array

application/json

Required - The JSON formated data to add or update in the reference set

["String", "String", "String", "String", "String", "String", "String", "String", "String", "String", "String"]

Table 99: POST /reference_data/sets/bulk_load/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has had data added or updated

400

1001

An error occurred parsing the JSON formatted message body

404

1002

The reference set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference set

Response Description

Information about the reference set that had data added or updated. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/sets/{name}

Retrieve the reference set that is identified by name. If it is provided, limit specifies the number of records to return starting at the record that is specified by offset. If the number is not specified, then the first 20 records are returned.

Table 100: GET /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 101: GET /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set 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.

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 102: GET /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has been retrieved

404

1002

The reference set does not exist.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference set

Response Description

The reference set identified by the name specified in the request. The portion of the set's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": [ { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } ], "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/sets/{name}

Add or update an element in a reference set.

Table 103: POST /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 104: POST /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set to add or update an element in

value

query

Required

String

text/plain

Required - The value to add or update in the reference set. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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 105: POST /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has had an element added or updated

404

1002

The reference set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update an element in the reference set

Response Description

Information about the reference set that had an element added or updated. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

DELETE /reference_data/sets/{name}

Remove a reference set or purge its contents.

Table 106: DELETE /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 107: DELETE /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the set to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference set should have its contents purged (true), keeping the reference set structure. If the value is "false" or not specified the reference set will be removed completely.

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 108: DELETE /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Sets deletion or purge request has been accepted and is in progress

404

1002

The reference set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference set

Response Description

A status_id to retrieve the Reference Data Sets deletion or purge status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

DELETE /reference_data/sets/{name}/{value}

Remove a value from a reference set.

Table 109: DELETE /reference_data/sets/{name}/{value} Resource Details

MIME Type

application/json

Table 110: DELETE /reference_data/sets/{name}/{value} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set to remove a value from

value

path

Required

String

text/plain

Required - The value to remove from the reference set. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 111: DELETE /reference_data/sets/{name}/{value} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set that had a value removed

404

1002

The reference set does not exist

404

1003

The record does not exist in the reference set

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the value from the reference set.

Response Description

Information about the reference set that had an value removed. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/sets/{name}/dependents

Retrieves the dependents of the set.

Table 112: GET /reference_data/sets/{name}/dependents Resource Details

MIME Type

application/json

Table 113: GET /reference_data/sets/{name}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the Reference Set retrieve dependents 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 114: GET /reference_data/sets/{name}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Sets dependent retrieval request has been accepted and is in progress

404

1002

The Reference Set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to get the dependents for the Reference Set

Response Description

A status_id to retrieve the Reference Data Sets dependent retrieval status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

GET /reference_data/tables_delete_tasks/{task_id}

Retrieve the delete the Reference Data Tables task status.

Table 115: GET /reference_data/tables_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 116: GET /reference_data/tables_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 117: GET /reference_data/tables_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status has been retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred while attempting to retrieve the Delete Task Status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/reference_data/tables/tables_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 of when the task was created.

  • started - Long - The time in milliseconds since epoch of when the task was started.

  • modified - Long - The time in milliseconds since epoch of when the task was modified.

  • completed - Long - The time in milliseconds since epoch of when 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 /reference_data/tables_dependent_tasks/{task_id}

Retrieve the dependent the Reference Data Tables task status.

Table 118: GET /reference_data/tables_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 119: GET /reference_data/tables_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 120: GET /reference_data/tables_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status has been retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred while attempting to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/reference_data/tables/tables_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 to cancel the task.

  • created - Long - The time in milliseconds since epoch of when the task was created.

  • started - Long - The time in milliseconds since epoch of when the task was started.

  • modified - Long - The time in milliseconds since epoch of when the task was modified.

  • completed - Long - The time in milliseconds since epoch of when the task was completed.

  • number_of_dependents - Long - The number of dependents found. Value is null until task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects 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 the sub-task is in.

    • 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 of when the sub-task was created.

    • started - Long - The time in milliseconds since epoch of when the sub-task was started.

    • modified - Long - The time in milliseconds since epoch of when the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch of when 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>" } ] }

POST /reference_data/tables_dependent_tasks/{task_id}

Cancel the dependent the Reference Data Tables task.

Table 121: POST /reference_data/tables_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 122: POST /reference_data/tables_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 123: POST /reference_data/tables_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 124: POST /reference_data/tables_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 while attempting to update the Dependent Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/reference_data/tables/tables_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 to cancel the task.

  • created - Long - The time in milliseconds since epoch of when the task was created.

  • started - Long - The time in milliseconds since epoch of when the task was started.

  • modified - Long - The time in milliseconds since epoch of when the task was modified.

  • completed - Long - The time in milliseconds since epoch of when the task was completed.

  • number_of_dependents - Long - The number of dependents found. Value is null until task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects 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 the sub-task is in.

    • 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 of when the sub-task was created.

    • started - Long - The time in milliseconds since epoch of when the sub-task was started.

    • modified - Long - The time in milliseconds since epoch of when the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch of when 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>" } ] }

GET /reference_data/tables_dependent_tasks/{task_id}/results

Retrieve the Reference Data Tables Dependent Task Results.

Table 125: GET /reference_data/tables_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 126: GET /reference_data/tables_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 127: GET /reference_data/tables_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Reference Data Tables Dependents have been retrieved

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred while attempting to retrieve the Reference Data Tables

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_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>", "user_has_edit_permissions": true } ]

POST /reference_data/tables/bulk_load/{name}

Adds or updates data in a reference table.

Table 128: POST /reference_data/tables/bulk_load/{name} Resource Details

MIME Type

application/json

Table 129: POST /reference_data/tables/bulk_load/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of table to add or update data in.

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 130: POST /reference_data/tables/bulk_load/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Array

application/json

Required - The JSON-formatted data to add or update in the reference table.

{"key1":{"col1":"Data11","col2":"Data12", "col3":"Data13","col4":"Data14"}, "key2":{"col1":"Data21","col2":"Data22", "col3":"Data23","col4":"Data24"}, "key3":{"col1":"Data31","col2":"Data32", "col3":"Data33","col4":"Data34"}, "key4":{"col1":"Data41","col2":"Data42", "col3":"Data43","col4":"Data44"}, "key5":{"col1":"Data51","col2":"Data52", "col3":"Data53","col4":"Data54"}, "key6":{"col1":"Data61","col2":"Data62", "col3":"Data63","col4":"Data64"}}

Table 131: POST /reference_data/tables/bulk_load/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

Data was successfully added or updated in the reference table.

400

1001

An error occurred parsing the JSON-formatted message body.

404

1002

The reference table does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to add or update data in the reference table.

Response Description

Information about the reference table where data was added or updated. This returns information about the reference table but not the data that it contains.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/tables

Retrieve a list of all reference tables.

Table 132: GET /reference_data/tables Resource Details

MIME Type

application/json

Table 133: GET /reference_data/tables 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 134: GET /reference_data/tables Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference tables

Response Description

A list of all of the reference tables. This returns information about the tables but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" } ]

GET /reference_data/tables/{name}

Return the reference table that is identified by name. If it is provided, limit specifies the number of records to return starting at the record that is specified by offset. If the number is not specified, then the first 20 records are returned.

Table 135: GET /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 136: GET /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table 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.

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 137: GET /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table has been retrieved

404

1002

The reference table does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference table

Response Description

The reference table identified by the name specified in the request. The portion of the reference table's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": { "String": { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } } }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/tables/{name}

Add or update an element in a reference table. The value to be added must be of the appropriate type. Either the type that corresponds to the innerKey that is predefined for the reference table, or the default elementType of the reference table

Table 138: POST /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 139: POST /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to add or update an element in

outer_key

query

Required

String

text/plain

Required - The outer key for the element to add or update

inner_key

query

Required

String

text/plain

Required - The inner key for the element to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference table. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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: POST /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table has had an element added or updated

404

1002

The reference table does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference table

Response Description

Information about the reference table that had an element added or updated. This returns information about the reference table but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

DELETE /reference_data/tables/{name}

Removes a reference table or purge its contents.

Table 141: DELETE /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 142: DELETE /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference table should have its contents purged (true), keeping the reference table structure. If the value is "false" or not specified the reference table will be removed completely.

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: DELETE /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Tables deletion or purge request has been accepted and is in progress

404

1002

The reference table does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference table

Response Description

A status_id to retrieve the Reference Data Tables deletion or purge status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

GET /reference_data/tables/{name}/dependents

Retrieves the dependents of the table.

Table 144: GET /reference_data/tables/{name}/dependents Resource Details

MIME Type

application/json

Table 145: GET /reference_data/tables/{name}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets retrieve dependents 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 146: GET /reference_data/tables/{name}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Reference Data Tables dependent retrieval request has been accepted and is in progress

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to get the dependents for the reference map of sets

Response Description

A status_id to retrieve the Reference Data Tables dependent retrieval status with at /api/system/task_management/task/{status_id}. You can also find the url in the Location header

Response Sample

{ "current_status": { "cancel_requested": true, "cancelled_by": "String", "child_tasks": [ 42 ], "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "progress": 42, "result_url": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" } ] }, "message": "String", "status_location": "String" }

DELETE /reference_data/tables/{name}/{outer_key}/{inner_key}

Removes a value from a reference table.

Table 147: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Resource Details

MIME Type

application/json

Table 148: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to remove a value from

outer_key

path

Required

String

text/plain

Required - The outer key of the value to remove

inner_key

path

Required

String

text/plain

Required - The inner key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference table. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 149: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table had had a value removed

404

1002

The reference table does not exist

404

1003

The record does not exist in the reference table

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the reference table value

Response Description

Information about the reference table that had an element removed. This returns information about table but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/tables

Create a new reference table.

Table 150: POST /reference_data/tables Resource Details

MIME Type

application/json

Table 151: POST /reference_data/tables Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference table to create

element_type

query

Required

String

text/plain

Required - The default element type for the values allowed in the reference table. This is used when values are added or updated in the reference table who's inner key was not defined in the key_name_types parameter. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

outer_key_label

query

Optional

String

text/plain

Optional - The label to describe the outer keys

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

key_name_types

query

Optional

Array<Object>

application/json

Optional - A JSON formatted string. This array creates the inner key names and corresponding value types for the table

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 152: POST /reference_data/tables Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference table was successfully created

409

1004

The reference table could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference table

Response Description

Information about the newly created reference table.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }