Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

REST API V5.0 References

 

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

Analytics Endpoints

Use the references for REST API V5 analytics endpoints.

GET /analytics/custom_actions/actions DEPRECATED

Retrieves a list of available custom actions.

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

MIME Type

application/json

Table 2: GET /analytics/custom_actions/actions 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 3: GET /analytics/custom_actions/actions Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of custom actions have been successfully retrieved.

500

1020

An internal server error occurred while retrieving custom actions.

Response Description

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

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

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

POST /analytics/custom_actions/actions DEPRECATED

Creates a new custom action with the supplied fields.

The custom action must contain the following fields:

  • name - Required - String - Unique name of the custom action within the JSA deployment.

  • description - Optional - String - Description of the custom action.

  • interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Required - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:

    • name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - Required - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Required - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - Required - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

Parameter

Data Type

MIME Type

Description

Sample

custom_action

Object

application/json

Custom action JSON object containing the supplied fields (see above for more details).

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

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

HTTP Response Code

Unique Code

Description

201

 

A new custom action has been successfully created.

422

1005

One or more parameters are invalid in request.

500

1020

An internal server error occurred while posting custom action.

Response Description

The newly created custom action with the following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

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

GET /analytics/custom_actions/interpreters DEPRECATED

Retrieves a list of available custom action interpreters.

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

MIME Type

application/json

Table 9: GET /analytics/custom_actions/interpreters 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 10: GET /analytics/custom_actions/interpreters Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of custom action interpreters have been retrieved.

500

1020

An internal server error occurred while retrieving available custom action interpreters.

Response Description

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

  • id - Number - Unique ID of the custom action interpreter within the JSA deployment.

  • name - String - Name of the custom action interpreter.

Response Sample

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

GET /analytics/custom_actions/interpreters/{interpreter_id} DEPRECATED

Retrieves a custom action interpreter based on supplied interpreter ID.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

interpreter_id

path

Required

Number (Integer)

text/plain

Number id of custom action interpreter to be retrieved.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

HTTP Response Code

Unique Code

Description

200

 

- The requested custom action interpreter has been retrieved.

404

1002

The requested custom action interpreter could not be found.

500

1020

An internal server error occurred while retrieving custom action interpreter with supplied interpreter_id.

Response Description

A custom action interpreter with the following fields:

  • id - Number - Unique ID of the custom action interpreter within the JSA deployment.

  • name - String - Name of the custom action interpreter.

Response Sample

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

GET /analytics/custom_actions/scripts DEPRECATED

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

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

MIME Type

application/json

Table 15: GET /analytics/custom_actions/scripts 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 /analytics/custom_actions/scripts Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested custom action script file has been retrieved.

500

1020

An internal server error occurred while retrieving available custom action script file meta-data.

Response Description

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

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

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

POST /analytics/custom_actions/scripts DEPRECATED

Creates a new custom action script file. Newly created custom action script files require a deployment before use. You can include an optional HTTP header file_name that contains the custom action script file name. If not specified, the custom action script file name defaults to the script ID of the uploaded file.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

Parameter

Data Type

MIME Type

Description

Sample

file

File

application/octet-stream

Required. The custom action script file. Must be supplied with MIME type application/octet-stream.

File

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

HTTP Response Code

Unique Code

Description

201

 

A custom action script file has been created.

500

1020

An internal server error occurred while posting custom action script file.

Response Description

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

  • id - Number - Unique ID of the custom action script within the JSA deployment.

  • name - String - Name of the custom action script.

Response Sample

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

GET /analytics/custom_actions/actions/{action_id} DEPRECATED

Retrieves a custom action based on the supplied action_id.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Long id of the custom action to be retrieved.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

HTTP Response Code

Unique Code

Description

200

 

The requested custom action has been successfully retrieved.

404

1002

The requested custom action could not be found.

500

1020

An internal server error occurred while retrieving custom action with supplied action_id.

Response Description

A custom action with containing following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

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

POST /analytics/custom_actions/actions/{action_id} DEPRECATED

Updates an existing custom action.

The custom action must contain the following fields:

  • id - Required - Number - Unique ID of the custom action within the JSA deployment.

  • name - Optional - String - Unique name of the custom action within the JSA deployment.

  • description - Optional - String - Description of the custom action.

  • interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Required - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:

    • name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - Optional - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Optional - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - Optional - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Number id of the custom action to be updated.

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

Parameter

Data Type

MIME Type

Description

Sample

custom_action

Object

application/json

Custom action JSON object which can contain the supplied fields (see above for more details).

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

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

HTTP Response Code

Unique Code

Description

200

 

The custom action has been updated.

404

1002

The requested custom action could not be found.

422

1005

One or more parameters are invalid in request.

500

1020

An internal server error occurred while updating custom action with supplied action_id.

Response Description

The updated custom action with the following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

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

DELETE /analytics/custom_actions/actions/{action_id} DEPRECATED

Deletes an existing custom action.

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

MIME Type

text/plain

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Number id of the custom action you wish to delete.

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

HTTP Response Code

Unique Code

Description

204

 

The custom action has been deleted.

404

1002

The requested custom action could not be found.

500

1020

An internal server error occurred while deleting custom action with supplied action_id.

Response Description

Empty response with 204 successful response code.

GET /analytics/custom_actions/scripts/{script_id} DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

HTTP Response Code

Unique Code

Description

200

 

The requested custom action script file has been retrieved.

404

1002

The requested custom action script file could not be found.

500

1020

An internal server error occurred while retrieving custom action script file meta-data with supplied script_id.

Response Description

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

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

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

POST /analytics/custom_actions/scripts/{script_id} DEPRECATED

Updates an existing custom action script file. Updated custom action script files require a deployment before use. You can include an optional HTTP header file_name containing the custom action script file name. If not specified, the custom action script file name defaults to the script ID of the uploaded file.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file to be updated.

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

Parameter

Data Type

MIME Type

Description

Sample

file

File

application/octet-stream

Required. The custom action script file. Must be supplied with MIME type application/octet-stream.

File

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

HTTP Response Code

Unique Code

Description

200

 

The custom action script file has been updated.

404

1002

The requested custom action script file could not be found.

500

1020

An internal server error occurred while updating custom action script file with supplied script_id.

Response Description

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

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

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

DELETE /analytics/custom_actions/scripts/{script_id} DEPRECATED

Deletes an existing custom action script file.

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

MIME Type

text/plain

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file to be deleted.

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

HTTP Response Code

Unique Code

Description

204

 

The custom action script file has been deleted.

404

1002

The requested custom action script file could not be found.

422

1005

The requested custom action script file is tied to an existing custom action.

500

1020

An internal server error occurred while deleting custom action script file with supplied script_id.

Response Description

Empty response with a 204 successful response code.

Ariel Endpoints

Use the references for REST API V5 Ariel endpoints.

GET /ariel/databases DEPRECATED

Retrieve Ariel database names.

Table 41: GET /ariel/databases Resource Details

MIME Type

application/json

Table 42: GET /ariel/databases Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 43: GET /ariel/databases Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of Ariel databases.

Response Description

The names of the available Ariel databases.

Response Sample

[ "String" ]

GET /ariel/databases/{database_name} DEPRECATED

Retrieve the columns defined for a specific Ariel database.

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

database_name

path

Required

String

text/plain

Required. The name of the Ariel database that contains the columns that you want to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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 46: GET /ariel/databases/{database_name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database columns were retrieved.

404

1002

The database does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the database columns.

Response Description

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

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String" } ] }

GET /ariel/searches DEPRECATED

Retrieve the list of Ariel searches. This includes search_ids for completed and active searches.

Table 47: GET /ariel/searches Resource Details

MIME Type

application/json

Table 48: GET /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 49: GET /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of searches.

Response Description

A list of search IDs.

Response Sample

[ "String" ]

POST /ariel/searches DEPRECATED

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

This endpoint only accepts SELECT and RUN query expressions.

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

Table 50: POST /ariel/searches Resource Details

MIME Type

application/json

Table 51: POST /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_expression

query

Required

String

text/plain

Required - The AQL query to execute.

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 52: POST /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new Ariel search was successfully created.

409

1004

The search could not be created, the requested search ID provided in the query_expression is already in use. Please use a unique search ID (or allow one to be generated).

422

2000

The query_expression contains invalid AQL syntax.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to create a new search.

Response Description

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

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

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

GET /ariel/searches/{search_id} DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The identifier for an Ariel search.

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 55: GET /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search information was retrieved.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the search information.

Response Description

Information about the specified search, including the search status.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

POST /ariel/searches/{search_id} DEPRECATED

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

  • To cancel an active search, set the status parameter to CANCELED. This stops the search and keeps any search results that were collected before the search was canceled.

  • The results for a completed search can be saved by setting the save_results parameter to true. This ensures that the search is not automatically removed when it expires in accordance with the retention policy.

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

Note

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The ID of the search to update.

save_results

query

Optional

String

text/plain

Optional. The only accepted value is true. If this value is provided, the search results will not be deleted by the search expiration removal process.

status

query

Optional

String

text/plain

Optional. The only accepted value is CANCELED. If this value is provided, the search will be canceled.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

HTTP Response Code

Unique Code

Description

200

 

The search was updated.

404

1002

The search does not exist.

409

1008

The current status of the search prevented the search results from being saved.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to update the search.

Response Description

Information about the specified search that was updated.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

DELETE /ariel/searches/{search_id} DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required - The search_id of the search to delete.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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

HTTP Response Code

Unique Code

Description

202

 

The delete request has been accepted.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to delete the search.

Response Description

Information about the deleted search.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

GET /ariel/searches/{search_id}/results DEPRECATED

Retrieve the results of the Ariel search that is identified by the search_id. The Accepts request header indicates the format of the result. The format can be JSON, CSV, XML, or tabular text.

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

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

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

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

MIME Type

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

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

The ID of the search criteria for the returned results.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

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

HTTP Response Code

Unique Code

Description

200

 

The search results were retrieved.

404

1002

The search does not exist.

404

1003

Search results not found. The search is still in progress.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the search results.

Response Description

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

Response Sample

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

Asset Model Endpoints

Use the references for REST API V5 Asset Model endpoints.

GET /asset_model/assets DEPRECATED

List all assets found in the model.

Table 65: GET /asset_model/assets Resource Details

MIME Type

application/json

Table 66: GET /asset_model/assets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 67: GET /asset_model/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

500

1020

The server encountered an error while trying to retrieve the assets.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

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

POST /asset_model/assets/{asset_id} DEPRECATED

Update an asset with several pertinent pieces of information.

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

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

MIME Type

text/plain

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

asset_id

path

Required

String

text/plain

Unique identifier of the asset to update.

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

Parameter

Data Type

MIME Type

Description

Sample

asset

JSON

application/json

JSON representation of an asset.

{ "properties": [ { "type_id": 1001, "value": "given name value" }, { "type_id": 1002, "value": "unified name value" } ] }

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

HTTP Response Code

Unique Code

Description

202

 

The request to update the asset was successful. The update will take place when the asset profile application receives the request.

422

1005

One or more of the requested property updates were invalid.

500

1020

The server encountered an error registering the update with the asset profile application.

Response Description

Information about the asset that was updated.

Response Sample

String

GET /asset_model/properties DEPRECATED

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

Table 72: GET /asset_model/properties Resource Details

MIME Type

application/json

Table 73: GET /asset_model/properties Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 74: GET /asset_model/properties Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of asset property types completed successfully.

500

1020

An error occurred while trying to retrieve the list of asset property types.

Response Description

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

Response Sample

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

GET /asset_model/saved_searches DEPRECATED

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

Table 75: GET /asset_model/saved_searches Resource Details

MIME Type

application/json

Table 76: GET /asset_model/saved_searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 77: GET /asset_model/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of saved searches completed successfully.

500

1020

The server encountered an error while trying to retrieve the list of saved searches.

Response Description

List of saved searches. Per saved search: id, name and list of filters that make up this saved search.

Response Sample

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

GET /asset_model/saved_searches/{saved_search_id}/results DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

String

text/plain

Unique identifier of the saved search used to retrieve assets.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

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

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

422

1005

The unique identifier of the saved search provided was invalid.

500

1003

The server encountered an error executing the saved search.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

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

Authentication Endpoints

Use the references for REST API V5 authentication endpoints.

POST /auth/logout DEPRECATED

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

Table 81: POST /auth/logout Resource Details

MIME Type

text/plain

There are no parameters for this endpoint.

Table 82: POST /auth/logout Response Codes

HTTP Response Code

Unique Code

Description

200

 

The session was invalidated.

Response Description

Returns true. Throws exception upon failure.

Response Sample

true

Configuration Endpoints

Use the references for REST API V5 configuration endpoints.

GET /config/domain_management/domains DEPRECATED

Retrieves the list of all domains, active and deleted (including the default domain).

The list is ordered by domain ID. If domains were never configured, only the default domain is returned.

Table 83: GET /config/domain_management/domains Resource Details

MIME Type

application/json

Table 84: GET /config/domain_management/domains Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 85: GET /config/domain_management/domains Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain list has been successfully retrieved.

500

1020

An error occurred while the domain list was being retrieved.

Response Description

The list of domain objects.

Response Sample

[ { "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 } ]

POST /config/domain_management/domains DEPRECATED

Creates a new domain.

Table 86: POST /config/domain_management/domains Resource Details

MIME Type

application/json

Table 87: POST /config/domain_management/domains Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 88: POST /config/domain_management/domains Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

domain

Object

application/json

A domain JSON object (its id parameter is ignored).

{ "asset_scanner_ids": [42], "custom_properties": [{"capture_result": "String", "id": 42}], "deleted": true, "description": "String", "event_collector_ids": [42], "flow_collector_ids": [42], "flow_source_ids": [42], "log_source_group_ids": [42], "log_source_ids": [42], "name": "String", "qvm_scanner_ids": [42], "tenant_id": 42 }

Table 89: POST /config/domain_management/domains Response Codes

HTTP Response Code

Unique Code

Description

201

 

The domain has been successfully created.

409

1004

A domain object parameter already exists.

422

1005

A domain object parameter is invalid.

500

1020

An error occurred while the domain was being created.

Response Description

A created domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

GET /config/domain_management/domains/{domain_id} DEPRECATED

Retrieves a domain by domain ID.

Table 90: GET /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 91: GET /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 92: GET /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully retrieved.

404

1002

No domain was found for the provided domain id.

500

1020

An error occurred while the domain was being retrieved.

Response Description

A domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

POST /config/domain_management/domains/{domain_id} DEPRECATED

Updates an existing domain.

Table 93: POST /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 94: POST /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object to update.

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 95: POST /config/domain_management/domains/{domain_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

domain

Object

application/json

A domain JSON object.

{ "asset_scanner_ids": [42], "custom_properties": [{"capture_result": "String", "id": 42}], "deleted": true, "description": "String", "event_collector_ids": [42], "flow_collector_ids": [42], "flow_source_ids": [42], "log_source_group_ids": [42], "log_source_ids": [42], "name": "String", "qvm_scanner_ids": [42], "tenant_id": 42 }

Table 96: POST /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully updated.

404

1002

No domain was found for the provided domain id.

409

1004

A domain object parameter already exists.

422

1005

A domain object parameter is invalid.

500

1020

An error occurred while the domain was being updated.

Response Description

The updated domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

DELETE /config/domain_management/domains/{domain_id} DEPRECATED

Deletes a domain by domain ID. All domain mappings are also deleted.

Table 97: DELETE /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 98: DELETE /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object to delete.

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 99: DELETE /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully deleted.

404

1002

No domain was found for the provided domain id.

422

1005

Default domain cannot be deleted.

500

1020

An error occurred while the domain was being deleted.

Response Description

The deleted domain object with its parameter deleted set to true.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

GET /config/access/tenant_management/tenants DEPRECATED

Retrieve the list of all tenants ordered by tenant ID.

Table 100: GET /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 101: GET /config/access/tenant_management/tenants Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Table 102: GET /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant list was successfully retrieved.

500

1020

An error occurred while the tenant list was being retrieved.

Response Description

Aa list of all the tenants.

Response Sample

[ { "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" } ]

POST /config/access/tenant_management/tenants DEPRECATED

Create a new tenant.

Table 103: POST /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 104: POST /config/access/tenant_management/tenants Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 105: POST /config/access/tenant_management/tenants Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 106: POST /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new tenant was created successfully and returned the new tenant object.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to create the tenant.

Response Description

A created tenant object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/access/tenant_management/tenants/{tenant_id} DEPRECATED

Retrieve a tenant by tenant id.

Table 107: GET /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 108: GET /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_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 109: GET /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was successfully retrieved.

404

1002

No tenant was found for the provided tenant id.

500

1020

An error occurred while the tenant was being retrieved.

Response Description

The associated tenants object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

POST /config/access/tenant_management/tenants/{tenant_id} DEPRECATED

Update a tenant.

Table 110: POST /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 111: POST /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - Integer - the tenant id to modify

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 112: POST /config/access/tenant_management/tenants/{tenant_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 113: POST /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

A tenant profile that was updated successfully and returned the updated tenant object.

404

1002

The tenant profile does not exist.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to retrieve/update the given tenant profile.

Response Description

The updated tenant object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

DELETE /config/access/tenant_management/tenants/{tenant_id} DEPRECATED

Deletes a tenant by tenant ID.

Table 114: DELETE /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 115: DELETE /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - String - id associated to a tenant

Table 116: DELETE /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was deleted successfully (soft delete).

404

1002

The tenant does not exists.

500

1020

An error occurred while deleting tenant.

Response Description

the deleted tenant object with its parameter deleted set to true

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/extension_management/extensions DEPRECATED

Retrieve a list of extensions.

Table 117: GET /config/extension_management/extensions Resource Details

MIME Type

application/json

Table 118: GET /config/extension_management/extensions Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

sort

query

Optional

String

text/plain

Optional - This parameter is used to sort the elements in a list.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

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 119: GET /config/extension_management/extensions Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of extensions has been retrieved.

422

22608

The supplied filter is invalid.

422

22615

Unknown status used in filter.

422

22610

The selected field cannot be utilized for sorting.

422

22609

Only top-level-elements of the root entity can be sorted on.

500

22602

An error has occurred while trying to retrieve the list of extensions.

Response Description

A list of extensions. Each extension contains the following fields:

  • id - Number - Unique ID of this extension within the JSA deployment.

  • name - String - The name of the extension.

  • description - String - The description of the extension.

  • author - String - The author (person who generated) the extension.

  • version - String - The version of the extension.

  • supported_languages - Array of strings - The language tags supported by this extension.

  • exported_qradar_version - String - The version of the JSA deployment this extension was exported from.

  • min_qradar_version - String - The minimum JSA version required for the extension to function properly.

  • file_location - String - The location of the extension file on disk.

  • size - Number - The size in bytes of the extension file.

  • signed - String - The state of the extension's signature.

  • beta - Boolean - True if the extension is considered to be beta or experimental.

  • added_by - String - The user or authorized service that added the extension to JSA.

  • installed_by - String The user or authorized service that installed the extension.

  • add_time - Number - The date/time at which the extension was added to JSA, represented as number of milliseconds since Unix epoch.

  • install_time - Number - The date/time at which the extension was installed, represented as number of milliseconds since Unix epoch.

  • full_uninstall - Boolean - True if the extension and all of its contents can be fully uninstalled.

  • status - String - The tag corresponding to the current status of the extension. Possible values are UPLOADED, UPLOADING, INSTALLED, INSTALLING, INSTALL_FAILED, UNINSTALLED, UNINSTALLING, UNINSTALL_FAILED, NOT_INSTALLED, PREVIEWING, NONE.

  • contents - Array of objects representing an item contained within the extension. Each object has the following fields:

    • content_type_id - Number - The ID of the content type.

    • content_type_name - String - The name of the content type.

    • identifier - String - The descriptive name/identifier of the item.

Response Sample

[ { "file_location": "/store/cmt/exports/custom_rule.zip", "supported_languages": [ "en_US" ], "contents": [ { "content_type_id": 3, "identifier": "No Description Supplied", "content_type_name": "custom_rule" }, { "content_type_id": 28, "identifier": "Asset Reconciliation IPv4 Blacklist", "content_type_name": "reference_data" }, { "content_type_id": 28, "identifier": "Asset Reconciliation IPv4 Whitelist", "content_type_name": "reference_data" }, { "content_type_id": 32, "identifier": "No Description Supplied", "content_type_name": "reference_data_rules" } ], "status": "INSTALLED", "signed": "NOT_SIGNED", "full_uninstall": false, "min_qradar_version": null, "beta": false, "version": "7.2.6.20150825133843", "size": 8575, "id": 59, "author": "admin", "description": null, "exported_qradar_version": null, "name": "custom_rule.xml", "install_time": 1440788704856, "installed_by": "admin", "added_by": "admin", "add_time": 1440693660702 }, { "file_location": "/store/cmt/exports/qidmap.xml", "supported_languages": [ "en_US" ], "contents": [ { "content_type_id": 27, "identifier": "", "content_type_name": "qidmap" } ], "status": "INSTALLED", "signed": "NOT_SIGNED", "full_uninstall": false, "min_qradar_version": null, "beta": false, "version": "7.2.6.20150821144442", "size": 675, "id": 2, "author": "admin", "description": null, "exported_qradar_version": null, "name": "qidmap.xml", "install_time": 1440612194941, "installed_by": "admin", "added_by": "admin", "add_time": 1440555001236 } ]

POST /config/extension_management/extensions DEPRECATED

Uploads the supplied extension file to the JSA system.

Table 120: POST /config/extension_management/extensions Resource Details

MIME Type

application/json

Table 121: POST /config/extension_management/extensions Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 122: POST /config/extension_management/extensions Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

file

File

application/x-gzip

Required - The Extension file. Must be a properly-formed JSA extension/content export, either an XML file or an XML within a ZIP or TAR.GZ archive. Must be provided with MIME type application/xml, application/zip, application/x-gzip or multipart/form-data

File

Table 123: POST /config/extension_management/extensions Response Codes

HTTP Response Code

Unique Code

Description

201

 

The supplied extension file has been uploaded.

409

22613

The supplied extension file can not be uploaded because it shares the same hub_id and version as one of the extensions in the system.

422

22607

The supplied extension could not be validated successfully

422

22616

The supplied manifest for the extension is invalid.

500

22602

An error has occurred while trying to upload the extension file.

Response Description

An extension containing the following fields:

  • id - Number - Unique ID of this extension within the JSA deployment.

  • name - String - The name of the extension.

  • description - String - The description of the extension.

  • author - String - The author (person who generated) the extension.

  • version - String - The version of the extension.

  • supported_languages - Array of strings - The language tags supported by this extension.

  • exported_qradar_version - String - The version of the JSA deployment this extension was exported from.

  • min_qradar_version - String - The minimum JSA version required for the extension to function properly.

  • file_location - String - The location of the extension file on disk.

  • size - Number - The size in bytes of the extension file.

  • signed - String - The state of the extension's signature.

  • beta - Boolean - True if the extension is considered to be beta or experimental.

  • added_by - String - The user or authorized service that added the extension to JSA.

  • installed_by - String The user or authorized service that installed the extension.

  • add_time - Number - The date/time at which the extension was added to JSA, represented as number of milliseconds since Unix epoch.

  • install_time - Number - The date/time at which the extension was installed, represented as number of milliseconds since Unix epoch.

  • full_uninstall - Boolean - True if the extension and all of its contents can be fully uninstalled.

  • status - String - The tag corresponding to the current status of the extension. Possible values are UPLOADED, UPLOADING, INSTALLED, INSTALLING, INSTALL_FAILED, UNINSTALLED, UNINSTALLING, UNINSTALL_FAILED, NOT_INSTALLED, PREVIEWING, NONE.

  • contents - Array of objects representing an item contained within the extension. Each object has the following fields:

    • content_type_id - Number - The ID of the content type.

    • content_type_name - String - The name of the content type.

    • identifier - String - The descriptive name/identifier of the item.

Response Sample

{ "file_location": "/store/cmt/exports/qidmaps.xml", "supported_languages": [ "en_US" ], "contents": [ { "content_type_id": 27, "identifier": "", "content_type_name": "qidmap" } ], "status": "INSTALLED", "signed": "NOT_SIGNED", "full_uninstall": false, "min_qradar_version": null, "beta": false, "version": "7.2.6.20150821144442", "size": 675, "id": 2, "author": "admin", "description": null, "exported_qradar_version": null, "name": "qidmaps.xml", "install_time": 1440612194941, "installed_by": "admin", "added_by": "admin", "add_time": 1440555001236 }

GET /config/extension_management/extensions/{extension_id} DEPRECATED

Retrieves an extension based on the supplied extension ID.

Table 124: GET /config/extension_management/extensions/{extension_id} Resource Details

MIME Type

application/json

Table 125: GET /config/extension_management/extensions/{extension_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

extension_id

path

Required

Number (Integer)

text/plain

Required - The id of the extension.

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 126: GET /config/extension_management/extensions/{extension_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested extension has been retrieved.

404

22603

The requested extension cannot be found.

422

22606

A supplied numeric parameter was not positive.

500

22602

An error has occurred while trying to retrieve the requested extension.

Response Description

An extension containing the following fields:

  • id - Number - Unique ID of this extension within the JSA deployment.

  • name - String - The name of the extension.

  • description - String - The description of the extension.

  • author - String - The author (person who generated) the extension.

  • version - String - The version of the extension.

  • supported_languages - Array of strings - The language tags supported by this extension.

  • exported_qradar_version - String - The version of the JSA deployment this extension was exported from.

  • min_qradar_version - String - The minimum JSA version required for the extension to function properly.

  • file_location - String - The location of the extension file on disk.

  • size - Number - The size in bytes of the extension file.

  • signed - String - The state of the extension's signature.

  • beta - Boolean - True if the extension is considered to be beta or experimental.

  • added_by - String - The user or authorized service that added the extension to JSA.

  • installed_by - String The user or authorized service that installed the extension.

  • add_time - Number - The date/time at which the extension was added to JSA, represented as number of milliseconds since Unix epoch.

  • install_time - Number - The date/time at which the extension was installed, represented as number of milliseconds since Unix epoch.

  • full_uninstall - Boolean - True if the extension and all of its contents can be fully uninstalled.

  • status - String - The tag corresponding to the current status of the extension. Possible values are UPLOADED, UPLOADING, INSTALLED, INSTALLING, INSTALL_FAILED, UNINSTALLED, UNINSTALLING, UNINSTALL_FAILED, NOT_INSTALLED, PREVIEWING, NONE.

  • contents - Array of objects representing an item contained within the extension. Each object has the following fields:

    • content_type_id - Number - The ID of the content type.

    • content_type_name - String - The name of the content type.

    • identifier - String - The descriptive name/identifier of the item.

Response Sample

{ "file_location": "/store/cmt/exports/qidmaps.xml", "supported_languages": [ "en_US" ], "contents": [ { "content_type_id": 27, "identifier": "", "content_type_name": "qidmap" } ], "status": "INSTALLED", "signed": "NOT_SIGNED", "full_uninstall": false, "min_qradar_version": null, "beta": false, "version": "7.2.6.20150821144442", "size": 675, "id": 2, "author": "admin", "description": null, "exported_qradar_version": null, "name": "qidmaps.xml", "install_time": 1440612194941, "installed_by": "admin", "added_by": "admin", "add_time": 1440555001236 }

POST /config/extension_management/extensions/{extension_id} DEPRECATED

Installs the Extension corresponding to the supplied extension ID. Alternatively can be used to preview an extension, showing what values are applied if the extension is installed.

Table 127: POST /config/extension_management/extensions/{extension_id} Resource Details

MIME Type

application/json

Table 128: POST /config/extension_management/extensions/{extension_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

extension_id

path

Required

Number (Integer)

text/plain

Required - The id of the extension.

action_type

query

Required

String

text/plain

Required - The desired action to take on the Extension (INSTALL or PREVIEW)

overwrite

query

Optional

Boolean

text/plain

Optional - If true, any existing items on the importing system will be overwritten if the extension contains the same items. If false, existing items will be preserved, and the corresponding items in the extension will be skipped.

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 129: POST /config/extension_management/extensions/{extension_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The requested install or preview task has been started.

404

22603

The requested extension cannot be found.

404

22604

The task status for status_id cannot be found.

409

22612

The supplied extension cannot be installed/previewed because it is already installed

409

22611

The supplied extension cannot be installed/previewed because it is already in the process of being installed/previewed.

409

22618

The requested task can not be initiated because another preview/install task is already in progress.

422

22605

The supplied action type is invalid

422

22606

A supplied numeric parameter was not positive.

500

22602

An error has occurred while trying to install or preview the requested extension.

Response Description

A JSON string depicting the accepted task for previewing/installing an extension:

  • message - String - description of the accepted task.

  • status_location - String - the url of the task status.

  • current_status - String - a JSON object depicting the current status of the task.

Response Sample

{ "message": "Uninstalling an extension", "status_location": "https://1.1.1.1/console/restapi/api/config/extension_management/ extensions_task_status/101", "current_status": { "progress": 0, "result_url": null, "cancelled_by": null, "status": "QUEUED", "task_components": null, "modified": 1440891410849, "id": 101, "message": "Queued Extension uninstallation task for extension id 2", "created_by": "admin", "created": 1440891410629, "maximum": 0, "cancel_requested": false, "name": "Extension uninstallation task", "child_tasks": null, "started": 1440891410847, "completed": null } }

DELETE /config/extension_management/extensions/{extension_id} DEPRECATED

Uninstall an extension based on the supplied extension ID. This is an asynchronous action.

Table 130: DELETE /config/extension_management/extensions/{extension_id} Resource Details

MIME Type

application/json

Table 131: DELETE /config/extension_management/extensions/{extension_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

extension_id

path

Required

Number (Integer)

text/plain

Required - The id of the extension to be uninstalled.

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 132: DELETE /config/extension_management/extensions/{extension_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The requested uninstall task has been started.

404

22603

The requested extension cannot be found.

404

22604

The task status for status_id cannot be found.

409

22611

The supplied extension cannot be uninstalled because it is already in the process of being uninstalled.

409

22617

The extension can not be uninstalled because it is already in the process of being previewed/installed.

422

22606

A supplied numeric parameter was not positive.

500

22602

An error has occurred while trying to uninstall an extension.

Response Description

A JSON string depicting the accepted task for uninstalling an extension:

  • message - String - description of the accepted task.

  • status_location - String - the url of the task status.

  • current_status - String - a JSON object depicting the current status of the task.

Response Sample

{ "message": "Uninstalling an extension", "status_location": "https://1.1.1.1/console/restapi/api/config/extension_management/ extensions_task_status/101", "current_status": { "progress": 0, "result_url": null, "cancelled_by": null, "status": "QUEUED", "task_components": null, "modified": 1440891410849, "id": 101, "message": "Queued Extension uninstallation task for extension id 2", "created_by": "admin", "created": 1440891410629, "maximum": 0, "cancel_requested": false, "name": "Extension uninstallation task", "child_tasks": null, "started": 1440891410847, "completed": null } }

GET /config/extension_management/extensions_task_status/{status_id} DEPRECATED

Retrieves the tasks status based on the status ID.

Table 133: GET /config/extension_management/extensions_task_status/{status_id} Resource Details

MIME Type

application/json

Table 134: GET /config/extension_management/extensions_task_status/{status_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

status_id

path

Required

Number (Integer)

text/plain

Required - the id of the task status.

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 135: GET /config/extension_management/extensions_task_status/{status_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested task status has been retrieved.

404

22604

The task status for status_id cannot be found.

422

22606

A supplied numeric parameter was not positive.

500

22602

An error has occurred while trying to retrieve the task status.

Response Description

A task status containing the following fields:

  • id - Number - The ID of the task status.

  • name - String - The name of the task status.

  • status - String - A string that represents the current state of the task status.

  • message - String - A message regarding the current state of the task.

  • progress - Number - The current progress of the task

  • minimum - Number - The minimum progress of the task.

  • maximum - Number - The maximum progress of the task.

  • created_by - String - The username of the user who created the task.

  • cancelled_by - String - The username of the user who cancelled the task.

  • created - Number - The date/time at which this task was created, represented as number of milliseconds since Unix epoch.

  • started - Number - The date/time at which this task was started, represented as number of milliseconds since Unix epoch.

  • modified - Number - The date/time at which this task was last modified, represented as number of milliseconds since Unix epoch.

  • completed - Number - The date/time at which this task was completed, represented as number of milliseconds since Unix epoch.

  • result_url - String - The url where the result can be viewed.

  • cancel_requested - Boolean - True if cancel has been requested.

  • child_tasks - Array - Array of child task id's that are executed asynchronously from this task.

  • task_components - Array - Array of task components that are executed sequentially.

Response Sample

{ "progress": 0, "result_url": "", "cancelled_by": "", "status": "COMPLETED", "task_components": null, "modified": 1440891517961, "id": 102, "message": "Completed Extension uninstallation task for extension id 56", "created_by": "admin", "created": 1440891514006, "maximum": 0, "cancel_requested": false, "name": "Extension uninstallation task", "child_tasks": null, "started": 1440891514041, "completed": 1440891515224 }

GET /config/extension_management/extensions_task_status/{status_id}/results DEPRECATED

Retrieves the tasks status results based on the status ID.

Table 136: GET /config/extension_management/extensions_task_status/{status_id}/results Resource Details

MIME Type

application/json

Table 137: GET /config/extension_management/extensions_task_status/{status_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

status_id

path

Required

Number (Integer)

text/plain

Required - The id of the task status.

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 138: GET /config/extension_management/extensions_task_status/{status_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested results of the task status have been retrieved.

404

22604

The task status for status_id cannot be found.

404

22614

The task results are not available.

422

22606

A supplied numeric parameter was not positive.

500

22602

An error has occurred while trying to retrieve the results of a task status.

Response Description

A JSON object representing the result of an Extension preview, install or uninstall task. It contains the following fields:

  • id - Number - The ID of the extension.

  • task_type - String - The type of task that was issued against the Extension.

  • content - Array - An array of JSON objects representing the contents of the extension and what action is associated with each content item for the task that was executed. Each content item contains the following fields:

    • name - String - The name of the content item.

    • content_type_id - Number - The ID of the type of the content item.

    • content_type_name - String - The name of the type of the content item.

    • action - String - The action taken for the content item.

Response Sample

{ "id": 56, "task_type": "UNINSTALL", "content": [ { "content_type_id": 3, "name": "SYSTEM-1607", "action": "SKIP", "content_type_name": "custom_rule" }, { "content_type_id": 28, "name": "Asset Reconciliation IPv4 Whitelist", "action": "SKIP", "content_type_name": "reference_data" } ] }

GUI Application Framework Endpoints

Use the references for REST API V5 GUI application framework endpoints.

GET /gui_app_framework/application_creation_task DEPRECATED

Retrieve a list of status details of all asynchronous requests to create applications.

Table 139: GET /gui_app_framework/application_creation_task Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 140: GET /gui_app_framework/application_creation_task Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of status details.

Response Description

The details of the requests to create applications.

Response Sample

[ { "application_id":"101", "status":"String <one of: CREATING, COMPLETED, CANCELLED, ERROR>", "error_messages": [ { "code":"String <one of: ERROR_DB_UNAVAILABLE, ERROR_FRAMEWORK_UNAVAILABLE, ERROR_CREATING_IMAGE, ERROR_STARTING_CONTAINER>", "message":"String" } ] } ]

POST /gui_app_framework/application_creation_task DEPRECATED

Create a new application within the Application framework, and register it with JSA. The application is created asynchronously. A reference to the application_id is returned and should be used in subsequent API calls to determine the status of the application installation.

Table 141: POST /gui_app_framework/application_creation_task Resource Details

MIME Type

application/json

Table 142: POST /gui_app_framework/application_creation_task Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

package

zip

application/zip

A zip file, that contains custom code, and a application manifest JSON file descriptor

null

Table 143: POST /gui_app_framework/application_creation_task Response Codes

HTTP Response Code

Unique Code

Description

201

 

The application was installed and registered successfully.

422

1005

The provided application is invalid. See messages for further details.

500

1020

The application could not be created.

Response Description

Application id and status.

Response Sample

[ { "application_id":"101", "status":"String <one of: CREATING, COMPLETED, CANCELLED, ERROR>", "error_messages": [ { "code":"String <one of: ERROR_DB_UNAVAILABLE, ERROR_FRAMEWORK_UNAVAILABLE, ERROR_CREATING_IMAGE, ERROR_STARTING_CONTAINER>", "message":"String" } ] } ]

GET /gui_app_framework/application_creation_task/{application_id} DEPRECATED

Retrieve a list of status details of a asynchronous request to create application.

Table 144: GET /gui_app_framework/application_creation_task/{application_id} Resource Details

MIME Type

application/json

Table 145: GET /gui_app_framework/application_creation_task/{application_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

application_id

path

Required

Number (Integer)

text/plain

Required - Get the status details of this application defined by application_id returned by the initial POST on application_creation_task.

Table 146: GET /gui_app_framework/application_creation_task/{application_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

404

1002

The application_id is invalid or could not be found.

500

1020

An error occurred while attempting to retrieve the list of status details.

Response Description

The details of the request to create application.

Response Sample

[ { "application_id":"101", "status":"String <one of: CREATING, COMPLETED, CANCELLED, ERROR>", "error_messages": [ { "code":"String <one of: ERROR_DB_UNAVAILABLE, ERROR_FRAMEWORK_UNAVAILABLE, ERROR_CREATING_IMAGE, ERROR_STARTING_CONTAINER>", "message":"String" } ] } ]

POST /gui_app_framework/application_creation_task/{application_id} DEPRECATED

Update a new application install within the Application framework. The application_id and a status are required.

Table 147: POST /gui_app_framework/application_creation_task/{application_id} Resource Details

MIME Type

application/json

Table 148: POST /gui_app_framework/application_creation_task/{application_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

application_id

path

Required

Number (Integer)

text/plain

Required - The application_id to cancel installing.

status

query

Required

String

text/plain

Required - The status to update the application install to. Currently only CANCELLED is supported

Table 149: POST /gui_app_framework/application_creation_task/{application_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The application was cancelled installing and unregistered successfully.

404

1002

The application_id is invalid or could not be found.

422

1005

The status is not valid.

500

1020

An error occurred when attempting to update the Application request state.

Response Description

Application id and status.

Response Sample

[ { "application_id":"101", "status":"String <one of: CREATING, COMPLETED, CANCELLED, ERROR>", "error_messages": [ { "code":"String <one of: ERROR_DB_UNAVAILABLE, ERROR_FRAMEWORK_UNAVAILABLE, ERROR_CREATING_IMAGE, ERROR_STARTING_CONTAINER>", "message":"String" } ] } ]

GET /gui_app_framework/applications DEPRECATED

Retrieve a list of applications that are installed on the console, with their manifest JSON structures and current status.

Table 150: GET /gui_app_framework/applications Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 151: GET /gui_app_framework/applications Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of applications.

Response Description

The list of applications.

Response Sample

[ { "application_state":{ "application_id":"101", "status":"String <one of: CREATING, RUNNING, STOPPED, ERROR>", "error_message": "String" } , "manifest":{ "name":"Sample Application", "description":"An example of how to create an application manifest", "version":"0.0.1", "areas": [ { "id":"Qapp1_HelloWorld", "url":"http://9.21.118.58:5000", "text":"QApp1", "description":"Loading a dockerised web app into a tab inside JSA", "required_capabilities":["ADMIN"] } ], "dashboard_items": [ { "text":"Sample Item", "description":"Sample dashboard item that is a copy of most recent offenses", "rest_method":"sampleDashboardItem", "required_capabilities":["ADMIN"] } ], "rest_methods": [ { "name":"sampleDashboardItem", "url":"/static/sampleDashboardItemResponse.json", "method":"GET", "argument_names":[], "required_capabilities":["ADMIN"] }, { "name":"sampleToolbarMethod", "url":"/static/sampleToolbarButtonResponse.json", "method":"GET", "argument_names":["context"], "required_capabilities":["ADMIN"] }, { "name":"sampleIPInformation", "url":"/static/sampleIPInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleUserInformation", "url":"/static/sampleUserInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleURLInformation", "url":"/static/sampleURLInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"addToReferenceSet", "url":"/addToReferenceSet", "method":"GET", "argument_names":["data"] } ], "configuration_pages": [ { "text":"Open IBM.com", "description":"Loading IBM.com in a new window", "icon":null, "url":"https://www.ibm.com/us/en/", "required_capabilities":["ADMIN"] } ], "gui_actions": [ { "id":"addToReferenceSet", "text":"Add To Reference Set", "description":"Adds to a reference set", "icon":null, "rest_method":"addToReferenceSet", "javascript":"alert(result)", "groups":[ "ipPopup" ], "required_capabilities":[ "ADMIN" ] }, { "id":"sampleToolbarButton", "text":"Sample Toolbar Button", "description":"Sample toolbar button that calls a REST method, passing an offense ID along", "icon":null, "rest_method":"sampleToolbarMethod", "javascript":"alert(result)", "groups":[ "OffenseListToolbar" ], "required_capabilities":[ "ADMIN" ] } ], "page_scripts": [ { "app_name":"SEM", "page_id":"OffenseList", "scripts":["/static/sampleScriptInclude.js"] } ], "metadata_providers": [ { "rest_method":"sampleIPInformation", "metadata_type":"ip" }, { "rest_method":"sampleUserInformation", "metadata_type":"userName" }, { "rest_method":"sampleURLInformation", "metadata_type":"ariel:URL" } ] } } ]

GET /gui_app_framework/applications/{application_id} DEPRECATED

Retrieve a specific application that is installed on the console with manifest JSON structure and current status.

Table 152: GET /gui_app_framework/applications/{application_id} Resource Details

MIME Type

application/json

Table 153: GET /gui_app_framework/applications/{application_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

application_id

path

Required

Number (Integer)

text/plain

Required - Get specific installed application defined by application_id returned by the initial POST on application_creation_task.

Table 154: GET /gui_app_framework/applications/{application_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The application was retrieved.

404

1002

The applicationid is invalid or could not be found.

500

1020

An error occurred while attempting to retrieve the application.

Response Description

The specific application.

Response Sample

[ { "application_state":{ "application_id":"101", "status":"String <one of: CREATING, RUNNING, STOPPED, ERROR>", "error_message": "String" } , "manifest":{ "name":"Sample Application", "description":"An example of how to create an application manifest", "version":"0.0.1", "areas": [ { "id":"Qapp1_HelloWorld", "url":"http://9.21.118.58:5000", "text":"QApp1", "description":"Loading a dockerised web app into a tab inside JSA", "required_capabilities":["ADMIN"] } ], "dashboard_items": [ { "text":"Sample Item", "description":"Sample dashboard item that is a copy of most recent offenses", "rest_method":"sampleDashboardItem", "required_capabilities":["ADMIN"] } ], "rest_methods": [ { "name":"sampleDashboardItem", "url":"/static/sampleDashboardItemResponse.json", "method":"GET", "argument_names":[], "required_capabilities":["ADMIN"] }, { "name":"sampleToolbarMethod", "url":"/static/sampleToolbarButtonResponse.json", "method":"GET", "argument_names":["context"], "required_capabilities":["ADMIN"] }, { "name":"sampleIPInformation", "url":"/static/sampleIPInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleUserInformation", "url":"/static/sampleUserInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleURLInformation", "url":"/static/sampleURLInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"addToReferenceSet", "url":"/addToReferenceSet", "method":"GET", "argument_names":["data"] } ], "configuration_pages": [ { "text":"Open IBM.com", "description":"Loading IBM.com in a new window", "icon":null, "url":"https://www.ibm.com/us/en/", "required_capabilities":["ADMIN"] } ], "gui_actions": [ { "id":"addToReferenceSet", "text":"Add To Reference Set", "description":"Adds to a reference set", "icon":null, "rest_method":"addToReferenceSet", "javascript":"alert(result)", "groups":[ "ipPopup" ], "required_capabilities":[ "ADMIN" ] }, { "id":"sampleToolbarButton", "text":"Sample Toolbar Button", "description":"Sample toolbar button that calls a REST method, passing an offense ID along", "icon":null, "rest_method":"sampleToolbarMethod", "javascript":"alert(result)", "groups":[ "OffenseListToolbar" ], "required_capabilities":[ "ADMIN" ] } ], "page_scripts": [ { "app_name":"SEM", "page_id":"OffenseList", "scripts":["/static/sampleScriptInclude.js"] } ], "metadata_providers": [ { "rest_method":"sampleIPInformation", "metadata_type":"ip" }, { "rest_method":"sampleUserInformation", "metadata_type":"userName" }, { "rest_method":"sampleURLInformation", "metadata_type":"ariel:URL" } ] } } ]

POST /gui_app_framework/applications/{application_id} DEPRECATED

Update an application. Start or stop an application by setting status to RUNNING or STOPPED respectively.

Table 155: POST /gui_app_framework/applications/{application_id} Resource Details

MIME Type

application/json

Table 156: POST /gui_app_framework/applications/{application_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

application_id

path

Required

Number (Integer)

text/plain

Required - The applicationId of the application to update.

status

query

Required

String

text/plain

Required - The status of the application to set to RUNNING or STOPPED.

Table 157: POST /gui_app_framework/applications/{application_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The application has been successfully updated

404

1002

The applicationId does not exist.

422

1005

The application status is not valid.

500

1020

An error occurred while attempting to update the application.

Response Description

Application structure including application status.

Response Sample

[ { "application_state":{ "application_id":"101", "status":"String <one of: CREATING, RUNNING, STOPPED, ERROR>", "error_message": "String" } , "manifest":{ "name":"Sample Application", "description":"An example of how to create an application manifest", "version":"0.0.1", "areas": [ { "id":"Qapp1_HelloWorld", "url":"http://9.21.118.58:5000", "text":"QApp1", "description":"Loading a dockerised web app into a tab inside JSA", "required_capabilities":["ADMIN"] } ], "dashboard_items": [ { "text":"Sample Item", "description":"Sample dashboard item that is a copy of most recent offenses", "rest_method":"sampleDashboardItem", "required_capabilities":["ADMIN"] } ], "rest_methods": [ { "name":"sampleDashboardItem", "url":"/static/sampleDashboardItemResponse.json", "method":"GET", "argument_names":[], "required_capabilities":["ADMIN"] }, { "name":"sampleToolbarMethod", "url":"/static/sampleToolbarButtonResponse.json", "method":"GET", "argument_names":["context"], "required_capabilities":["ADMIN"] }, { "name":"sampleIPInformation", "url":"/static/sampleIPInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleUserInformation", "url":"/static/sampleUserInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"sampleURLInformation", "url":"/static/sampleURLInformationResponse.json", "method":"GET", "argument_names":["metaDataContext"], "required_capabilities":["ADMIN"] }, { "name":"addToReferenceSet", "url":"/addToReferenceSet", "method":"GET", "argument_names":["data"] } ], "configuration_pages": [ { "text":"Open IBM.com", "description":"Loading IBM.com in a new window", "icon":null, "url":"https://www.ibm.com/us/en/", "required_capabilities":["ADMIN"] } ], "gui_actions": [ { "id":"addToReferenceSet", "text":"Add To Reference Set", "description":"Adds to a reference set", "icon":null, "rest_method":"addToReferenceSet", "javascript":"alert(result)", "groups":[ "ipPopup" ], "required_capabilities":[ "ADMIN" ] }, { "id":"sampleToolbarButton", "text":"Sample Toolbar Button", "description":"Sample toolbar button that calls a REST method, passing an offense ID along", "icon":null, "rest_method":"sampleToolbarMethod", "javascript":"alert(result)", "groups":[ "OffenseListToolbar" ], "required_capabilities":[ "ADMIN" ] } ], "page_scripts": [ { "app_name":"SEM", "page_id":"OffenseList", "scripts":["/static/sampleScriptInclude.js"] } ], "metadata_providers": [ { "rest_method":"sampleIPInformation", "metadata_type":"ip" }, { "rest_method":"sampleUserInformation", "metadata_type":"userName" }, { "rest_method":"sampleURLInformation", "metadata_type":"ariel:URL" } ] } } ]

DELETE /gui_app_framework/applications/{application_id} DEPRECATED

Delete an application.

Table 158: DELETE /gui_app_framework/applications/{application_id} Resource Details

MIME Type

text/plain

Table 159: DELETE /gui_app_framework/applications/{application_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

application_id

path

Required

Number (Integer)

text/plain

Required - The applicationId of the application to delete.

Table 160: DELETE /gui_app_framework/applications/{application_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The application has been successfully unregistered.

404

1002

The applicationId does not exist.

500

1020

An error occurred while attempting to delete the application.

Response Description

Successful response code 204 No content.

Response Sample

Help Endpoints

Use the references for REST API V5 Help endpoints.

GET /help/capabilities DEPRECATED

List the JSA API capabilities. The response will contain all available RESTful resources. We allow every authenticated user to access this method, but restrict the output based on their user capabilities.

Table 161: GET /help/capabilities Resource Details

MIME Type

application/json

Table 162: GET /help/capabilities Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

categories

query

Optional

Array<String>

application/json

Optional - Restrict your search to this list of capabilities

paths

query

Optional

Array<String>

application/json

Optional - Restrict your search to these paths only

httpMethods

query

Optional

Array<String>

application/json

Optional - Restrict your search to these HTTP methods

version

query

Optional

String

text/plain

Optional - Restrict your search to this version (or below)

showExperimental

query

Optional

Boolean

text/plain

Optional - If true, we include experimental endpoints (default is true)

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.

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 163: GET /help/capabilities Response Codes

HTTP Response Code

Unique Code

Description

200

 

The API capabilities list was retrieved.

422

1001

Invalid input

422

1002

Our internal mapping has an unexpected structure or contains an invalid element value

500

1003

A generic error has occurred while retrieving our capabilities

Response Description

Endpoints you are able to access, mapped against versions they belong to. If full content is not requested, values will be null.

Response Sample

{ "categories": [ { "apis": [ { "httpMethod": "String <one of: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH>", "operations": [ { "additionalFiltering": true, "deprecated": true, "description": "String", "errorResponses": [ { "code": 42, "description": "String", "uniqueCode": 42 } ], "httpMethod": "String", "lastSupportedVersion": "String", "parameters": [ { "allowMultiple": true, "defaultValue": "String", "description": "String", "name": "String", "pathIndex": 42, "required": true, "source": "String", "supportedContentTypes": [ { "dataType": "String", "mimeType": "String", "sample": "String" } ] } ], "removalTarget": "String", "removed": true, "responseClass": "String", "responseDescription": { "description": "String", "properties": [ { "description": "String", "name": "String" } ] }, "successResponses": [ { "code": 42, "description": "String" } ], "summary": "String", "supportedContentTypes": [ { "dataType": "String", "mimeType": "String", "sample": "String" } ], "version": "String", "visibility": "String" } ], "path": "String" } ], "path": "String" } ], "path": "String" }

JSA Vulnerability Manager Endpoints

Use the references for REST API V5 JSA Vulnerability Manager endpoints.

GET /qvm/assets DEPRECATED

List the assets with discovered vulnerabilities present in the asset model. The response contains all available RESTful resources.

Table 164: GET /qvm/assets Resource Details

MIME Type

application/json

Table 165: GET /qvm/assets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 166: GET /qvm/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by asset completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of assets data.

GET /qvm/filters DEPRECATED

Get a list of the allowable filters that can be used or applied against /qvm endpoints.

  • /qvm/assets

  • /qvm/vulns

  • /qvm/vulninstances

  • /qvm/openservices

  • /qvm/networks

  • queries

Table 167: GET /qvm/filters Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 168: GET /qvm/filters Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search executed successfully

420

9102

An error occurred while executing the search

Response Description

List of Filters.

GET /qvm/network DEPRECATED

List the networks present in the asset model with vulnerabilities present. The response contains all available RESTful resources

Table 169: GET /qvm/network Resource Details

MIME Type

application/json

Table 170: GET /qvm/network Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 171: GET /qvm/network Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by network completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of network related data.

GET /qvm/openservices DEPRECATED

List the openservices present in the asset model with vulnerabilities present. The response will contain all available RESTful resources.

Table 172: GET /qvm/openservices Resource Details

MIME Type

application/json

Table 173: GET /qvm/openservices Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 174: GET /qvm/openservices Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by open service completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of open services related data.

GET /qvm/savedsearches DEPRECATED

Get a list of saved searches that can be applied against /qvm endpoints.

A list of saved searches that can be applied against the following endpoints:

  • /qvm/assets

  • /qvm/vulns

  • /qvm/vulninstances

  • /qvm/openservices

  • /qvm/networks

  • queries

Table 175: GET /qvm/savedsearches Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 176: GET /qvm/savedsearches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of saved searches completed successfully

420

9103

An error occurred while trying to retrieve the list of saved searches

Response Description

List of saved searches. Per saved search: id, name and list of filters that make up this saved search.

POST /qvm/tickets/assign DEPRECATED

Update the remediation ticket for the assigned vulnerability.

Table 177: POST /qvm/tickets/assign Resource Details

MIME Type

application/json

Table 178: POST /qvm/tickets/assign Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

ticket

JSON

application/json

'ticketId': required.

'priority' one of required : Critical, Major, Minor, Warning, Informational.

'status' one of required : Opened, Fixed, Re-Opened, Closed .

'dueDate' Optional : yyyy-MM-dd HH:mm:ss.

'assignedUser' required : valid JSA user account name or a valid email.

'comment' Optional : text.

'commentUser' Optional : valid JSA user account name, if not included will default current API user.

[ { "ticketId":"1000", "status":"Opened", "priority":"Critical", "dueDate":"2015-01-04 12:00:00", "assignedUser":"admin", "comment":"testComment", "commentUser":"admin" } ]

Table 179: POST /qvm/tickets/assign Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to assign a ticket completed successfully

420

9104

An error occurred while trying to assign a ticket due to invalid arguments

Response Description

Success message if update succeed.

GET /qvm/vulninstances DEPRECATED

List the Vulnerability Instances present in the asset model. The response will contain all available RESTful resources

Table 180: GET /qvm/vulninstances Resource Details

MIME Type

application/json

Table 181: GET /qvm/vulninstances Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 182: GET /qvm/vulninstances Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by instance completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of vulnerability instance data.

GET /qvm/vulns DEPRECATED

List the Vulnerabilities present in the asset model. The response will contain all available RESTful resources.

Table 183: GET /qvm/vulns Resource Details

MIME Type

application/json

Table 184: GET /qvm/vulns Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 185: GET /qvm/vulns Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of vulnerability data.

Reference Data Endpoints

Use the references for REST API V5 reference data endpoints.

GET /reference_data/map_of_sets DEPRECATED

Retrieve a list of all reference map of sets.

Table 186: GET /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 187: 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 188: 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 DEPRECATED

Create a new reference map of sets.

Table 189: POST /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 190: 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 191: 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" }

GET /reference_data/map_of_sets/{name} DEPRECATED

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 192: GET /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 193: 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 194: 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} DEPRECATED

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

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

MIME Type

application/json

Table 196: 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 197: 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} DEPRECATED

Remove a map of sets or purge its contents.

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

MIME Type

application/json

Table 199: 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 200: 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 DEPRECATED

Retrieves the dependents of the Map of Sets.

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

MIME Type

application/json

Table 202: 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 203: 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}/value/{key} DEPRECATED

Remove a value from a reference map of sets.

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

MIME Type

application/json

Table 205: DELETE /reference_data/map_of_sets/{name}/value/{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 206: DELETE /reference_data/map_of_sets/{name}/value/{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/maps DEPRECATED

Retrieve a list of all reference maps.

Table 207: GET /reference_data/maps Resource Details

MIME Type

application/json

Table 208: 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 209: 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 DEPRECATED

Create a new reference map.

Table 210: POST /reference_data/maps Resource Details

MIME Type

application/json

Table 211: 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 212: 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" }

GET /reference_data/maps/{name} DEPRECATED

Retrieve the reference map identified by 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 213: GET /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 214: 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 215: 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} DEPRECATED

Add or update an element in a reference map.

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

MIME Type

application/json

Table 217: 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 218: 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} DEPRECATED

Remove a reference map or purge its contents.

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

MIME Type

application/json

Table 220: 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 221: 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 DEPRECATED

Retrieves the dependents of the Map.

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

MIME Type

application/json

Table 223: 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 224: 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}/value/{key} DEPRECATED

Remove a value from a reference map.

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

MIME Type

application/json

Table 226: DELETE /reference_data/maps/{name}/value/{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 227: DELETE /reference_data/maps/{name}/value/{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/sets DEPRECATED

Retrieve a list of all reference sets.

Table 228: GET /reference_data/sets Resource Details

MIME Type

application/json

Table 229: 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 230: 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 DEPRECATED

Create a new reference set.

Table 231: POST /reference_data/sets Resource Details

MIME Type

application/json

Table 232: 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 233: 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>" }

GET /reference_data/sets/{name} DEPRECATED

Retrieve the reference set identified by 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 234: GET /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 235: 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 236: 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} DEPRECATED

Add or update an element in a reference set.

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

MIME Type

application/json

Table 238: 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 239: 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} DEPRECATED

Remove a reference set or purge its contents.

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

MIME Type

application/json

Table 241: 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 242: 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" }

GET /reference_data/sets/{name}/dependents DEPRECATED

Retrieves the dependents of the set.

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

MIME Type

application/json

Table 244: 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 245: 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" }

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

Remove a value from a reference set.

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

MIME Type

application/json

Table 247: DELETE /reference_data/sets/{name}/value/{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 248: DELETE /reference_data/sets/{name}/value/{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>" }

POST /reference_data/sets/bulk_load/{name} DEPRECATED

Add or update data in a reference set.

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

MIME Type

application/json

Table 250: 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 251: 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 252: 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/tables DEPRECATED

Retrieve a list of all reference tables.

Table 253: GET /reference_data/tables Resource Details

MIME Type

application/json

Table 254: 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 255: 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>" } ]

POST /reference_data/tables DEPRECATED

Create a new reference table.

Table 256: POST /reference_data/tables Resource Details

MIME Type

application/json

Table 257: 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 258: 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>" }

GET /reference_data/tables/{name} DEPRECATED

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 259: GET /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 260: 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 261: 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} DEPRECATED

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 262: POST /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 263: 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 264: 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} DEPRECATED

Remove a reference table or purge its contents.

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

MIME Type

application/json

Table 266: 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 267: 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 DEPRECATED

Retrieves the dependents of the Table.

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

MIME Type

application/json

Table 269: 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 270: 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}/value/{outer_key}/{inner_key} DEPRECATED

Remove a value from a reference table.

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

MIME Type

application/json

Table 272: DELETE /reference_data/tables/{name}/value/{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 273: DELETE /reference_data/tables/{name}/value/{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>" }

Scanner Endpoints

Use the references for REST API V5 scanner endpoints.

GET /scanner/profiles DEPRECATED

Retrieves all of the currently created scan profiles.

No parameters are required and the following information should be retrieved for each scan profile.

  • scanProfileId

  • scanProfileName

  • description

  • scanType

  • scannerName

Table 274: GET /scanner/profiles Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 275: GET /scanner/profiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The list of scan profiles was successfully returned

500

1030

Occurs when an attempt is made to list scan profiles when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

POST /scanner/profiles/create DEPRECATED

Initiates a request to create a new Scan Profile.

The request takes one parameter - createScanRequest, which is just a POJO. To create the scan, you will need to build up a JSON object that contains the Scan Profile name and IP addresses to scan. For example:

{'name':'New Scan Profile', 'ips':['10.100.85.135']}

Table 276: POST /scanner/profiles/create Resource Details

MIME Type

text/plain

Table 277: POST /scanner/profiles/create Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

JSON

application/json

null

null

Table 278: POST /scanner/profiles/create Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully created

419

9101

Occurs when a parameter is missing or invalid

500

1030

Occurs when an attempt is made to create a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been created successfully or not.

Response Sample

String

POST /scanner/profiles/start DEPRECATED

Initiates a request to start an already created scanProfile.

The request takes one parameter - scanProfileId. To get a list of scanProfileIds, get a list of the current scan profiles by initiating a 'profiles' request on the scanner endpoint. The scanProfileId is validated and an appropriate message is returned.

Table 279: POST /scanner/profiles/start Resource Details

MIME Type

text/plain

Table 280: POST /scanner/profiles/start Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

scanProfileId

query

Required

String

text/plain

The unique id of the scan profile we want to start

Table 281: POST /scanner/profiles/start Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully started

403

1000

Occurs if the user does not have permission to start a scan, or the scan is in progress

500

1030

Occurs when an attempt is made to start a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been started successfully or not.

Response Sample

String

GET /scanner/scanprofiles DEPRECATED

Retrieves all of the currently created scan profiles.

No parameters are required and the following information should be retrieved for each scan profile.

  • scanProfileId

  • scanProfileName

  • description

  • scanType

  • scannerName

  • schedule

  • status

  • progress

  • endTime

  • duration

Table 282: GET /scanner/scanprofiles Resource Details

MIME Type

application/json

Table 283: GET /scanner/scanprofiles Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 284: GET /scanner/scanprofiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The list of scan profiles was successfully returned

500

1030

Occurs when an attempt is made to list scan profiles when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

[ { "description": "String", "duration": { "days": 42, "hours": 42, "minutes": 42, "months": 42, "seconds": 42.5, "type": "String", "value": "String", "years": 42 }, "endTime": { "date": 42, "day": 42, "hours": 42, "minutes": 42, "month": 42, "seconds": 42, "time": 42, "timezoneOffset": 42, "year": 42 }, "progress": 42, "scanProfileId": 42, "scanProfileName": "String", "scanType": "String", "scannerName": "String", "schedule": "String", "status": "String" } ]

POST /scanner/scanprofiles DEPRECATED

Initiates a request to create a new scanProfile.

The request takes one parameter - createScanRequest, which is just a POJO. To create the scan, you will need to build up a JSON object that contains the Scan Profile name and hosts to scan. For example:

{'name':'New Scan Profile', 'hosts':['10.100.85.135']}

Table 285: POST /scanner/scanprofiles Resource Details

MIME Type

text/plain

Table 286: POST /scanner/scanprofiles Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

Object

application/json

null

{ "description": "String", "hosts": [ "String" ], "name": "String" }

Table 287: POST /scanner/scanprofiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully created

500

1030

Occurs when an attempt is made to create a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been created successfully or not.

Response Sample

String

GET /scanner/scanprofiles/{profileid} DEPRECATED

Retrieves a scan profile for a given Scan Profile ID.

No parameters are required and the following information should be retrieved for each scan profile.

  • scanProfileId

  • name

  • description

  • scanType

  • scannerName

  • schedule

  • status

  • progress

  • endTime

  • duration

Table 288: GET /scanner/scanprofiles/{profileid} Resource Details

MIME Type

application/json

Table 289: GET /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile we need to retrieve information 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.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

Table 290: GET /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan profile was successfully returned

500

1030

Occurs when an attempt is made to list a scan profile when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

[ { "description": "String", "duration": { "days": 42, "hours": 42, "minutes": 42, "months": 42, "seconds": 42.5, "type": "String", "value": "String", "years": 42 }, "endTime": { "date": 42, "day": 42, "hours": 42, "minutes": 42, "month": 42, "seconds": 42, "time": 42, "timezoneOffset": 42, "year": 42 }, "progress": 42, "scanProfileId": 42, "scanProfileName": "String", "scanType": "String", "scannerName": "String", "schedule": "String", "status": "String" } ]

POST /scanner/scanprofiles/{profileid} DEPRECATED

Update a scan profile. The Scan Profile ID is required.

The following information on a scan profile can be updated:

  • name

  • description

  • IP addresses

For example:

{'name':'Updated Scan Profile', 'ips':['10.100.85.135']}

Table 291: POST /scanner/scanprofiles/{profileid} Resource Details

MIME Type

application/json

Table 292: POST /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile used to update

Table 293: POST /scanner/scanprofiles/{profileid} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

JSON

application/json

null

null

Table 294: POST /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The scan profile was successfully updated

500

1030

Occurs when an attempt is made to update a scan profile when certain conditions are not met, or when too many scan requests have been made

Response Description

A message to indicate whether the scan profile has updated or not.

DELETE /scanner/scanprofiles/{profileid} DEPRECATED

Initiates a request to delete a scanProfile. The request takes one parameter - the Scan Profile ID.

Table 295: DELETE /scanner/scanprofiles/{profileid} Resource Details

MIME Type

text/plain

Table 296: DELETE /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

null

Table 297: DELETE /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The scan has been successfully deleted

500

1030

Occurs when an attempt is made to delete a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been deleted successfully or not.

Response Sample

String

POST /scanner/scanprofiles/{profileid}/start DEPRECATED

Initiates a request to start an already created scanProfile.

The request takes one parameter, scanProfileId, and one optional parameter, ips. To get a list of scanProfileIds, simply get a list of the current scan profiles by initiating a 'profiles' request on the scanner endpoint. The scanProfileId, is validated and an appropriate message returned.

Table 298: POST /scanner/scanprofiles/{profileid}/start Resource Details

MIME Type

text/plain

Table 299: POST /scanner/scanprofiles/{profileid}/start Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile we want to start

Table 300: POST /scanner/scanprofiles/{profileid}/start Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

ips

JSON

application/json

null

null

Table 301: POST /scanner/scanprofiles/{profileid}/start Response Codes

HTTP Response Code

Unique Code

Description

202

 

The scan has been successfully started

403

1000

Occurs if the user does not have permission to start a scan, or the scan is in progress

500

1030

Occurs when an attempt is made to start a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been started successfully or not.

Response Sample

String

SIEM Endpoints

Use the references for REST API V5 SIEM endpoints.

GET /siem/local_destination_addresses DEPRECATED

Retrieve a list offense local destination addresses currently in the system.

Table 302: GET /siem/local_destination_addresses Resource Details

MIME Type

application/json

Table 303: GET /siem/local_destination_addresses 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 304: GET /siem/local_destination_addresses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The local destination address list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the local destination address list was being retrieved.

Response Description

An array of local destination address objects. A local destination address object contains the following fields:

  • id - Number - The ID of the destination address.

  • local_destination_ip - String - The IP address.

  • magnitude - Number - The magnitude of the destination address.

  • network - String - The network of the destination address.

  • offense_ids - Array of Numbers - List of offense IDs the destination address is part of.

  • source_address_ids - Array of Numbers - List of source address IDs associated with the destination address.

  • event_flow_count - Number - The number of events and flows that are associated with the destination address.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

[ { "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_ip": "String", "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_address_ids": [ 42 ] } ]

GET /siem/local_destination_addresses/{local_destination_address_id} DEPRECATED

Retrieve an offense local destination address.

Table 305: GET /siem/local_destination_addresses/{local_destination_address_id} Resource Details

MIME Type

application/json

Table 306: GET /siem/local_destination_addresses/{local_destination_address_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

local_destination_address_id

path

Required

Number (Integer)

text/plain

Required - The ID of the local destination address to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 307: GET /siem/local_destination_addresses/{local_destination_address_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The local destination was retrieved.

404

1002

No local destination address was found for the provided local_destination_address_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the local destination address was being retrieved.

Response Description

A local destination address object. A local destination address object contains the following fields:

  • id - Number - The ID of the destination address.

  • local_destination_ip - String - The IP address.

  • magnitude - Number - The magnitude of the destination address.

  • network - String - The network of the destination address.

  • offense_ids - Array of Numbers - List of offense IDs the destination address is part of.

  • source_address_ids - Array of Numbers - List of source address IDs associated with the destination address.

  • event_flow_count - Number - The number of events and flows that are associated with the destination address.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

{ "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_ip": "String", "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_address_ids": [ 42 ] }

GET /siem/offense_closing_reasons DEPRECATED

Retrieve a list of all offense closing reasons.

Table 308: GET /siem/offense_closing_reasons Resource Details

MIME Type

application/json

Table 309: GET /siem/offense_closing_reasons Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

include_reserved

query

Optional

Boolean

text/plain

Optional - If true, reserved closing reasons are included in the response. Defaults to false. Reserved closing reasons cannot be used to close an offense.

include_deleted

query

Optional

Boolean

text/plain

Optional - If true, deleted closing reasons are included in the response. Defaults to false. Deleted closing reasons cannot be used to close an offense.

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 310: GET /siem/offense_closing_reasons Response Codes

HTTP Response Code

Unique Code

Description

200

 

The closing reasons list was retrieved.

500

1020

An error occurred while the closing reasons list was being retrieved.

Response Description

An array of ClosingReason objects. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

[ { "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" } ]

POST /siem/offense_closing_reasons DEPRECATED

Create an offense closing reason.

Table 311: POST /siem/offense_closing_reasons Resource Details

MIME Type

application/json

Table 312: POST /siem/offense_closing_reasons Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

reason

query

Required

String

text/plain

Required - The text of the offense closing reason must be 5 - 60 characters in length.

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 313: POST /siem/offense_closing_reasons Response Codes

HTTP Response Code

Unique Code

Description

201

 

The closing reason was created.

409

1004

The closing reason already exists.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to create the closing reason.

Response Description

A ClosingReason object. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

{ "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" }

GET /siem/offense_closing_reasons/{closing_reason_id} DEPRECATED

Retrieve an offense closing reason.

Table 314: GET /siem/offense_closing_reasons/{closing_reason_id} Resource Details

MIME Type

application/json

Table 315: GET /siem/offense_closing_reasons/{closing_reason_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

closing_reason_id

path

Required

Number (Integer)

text/plain

Required - The closing reason ID.

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 316: GET /siem/offense_closing_reasons/{closing_reason_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The closing reason was retrieved.

404

1002

No closing reason was found for the provided closing_reason_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the closing reason.

Response Description

A ClosingReason object. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

{ "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" }

GET /siem/offenses DEPRECATED

Retrieve a list of offenses currently in the system.

Table 317: GET /siem/offenses Resource Details

MIME Type

application/json

Table 318: GET /siem/offenses 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 319: GET /siem/offenses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the offense list was being retrieved.

Response Description

An array of Offense objects. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense. Filtering is not supported on this field.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense. Filtering is not supported on this field.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense. Filtering is not supported on this field.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED". The following operators are not supported when you filter on this field: "<", ">", "<=", ">=", "BETWEEN".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 320: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

[{"credibility": 42, "source_address_ids": [42], "remote_destination_count": 42, "local_destination_address_ids": [42], "assigned_to": "String", "local_destination_count": 42, "source_count": 42, "start_time": 42, "id": 42, "destination_networks": ["String"], "inactive": true, "protected": true, "policy_category_count": 42, "description": "String", "category_count": 42, "domain_id": 42, "relevance": 42, "device_count": 42, "security_category_count": 42, "flow_count": 42, "event_count": 42, "offense_source": "String", "status": "String <one of: OPEN, HIDDEN, CLOSED>", "magnitude": 42, "severity": 42, "username_count": 42, "closing_user": "String", "follow_up": true, "closing_reason_id": 42, "close_time": 42, "source_network": "String", "last_updated_time": 42, "categories": ["String"], "offense_type": 42}]

GET /siem/offenses/{offense_id} DEPRECATED

Retrieve an offense structure that describes properties of an offense.

Table 321: GET /siem/offenses/{offense_id} Resource Details

MIME Type

application/json

Table 322: GET /siem/offenses/{offense_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID.

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 323: GET /siem/offenses/{offense_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense was retrieved.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the offense was being retrieved.

Response Description

An Offense object. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 324: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

{ "assigned_to": "String", "categories": [ "String" ], "category_count": 42, "close_time": 42, "closing_reason_id": 42, "closing_user": "String", "credibility": 42, "description": "String", "destination_networks": [ "String" ], "device_count": 42, "domain_id": 42, "event_count": 42, "flow_count": 42, "follow_up": true, "id": 42, "inactive": true, "last_updated_time": 42, "local_destination_address_ids": [ 42 ], "local_destination_count": 42, "magnitude": 42, "offense_source": "String", "offense_type": 42, "policy_category_count": 42, "protected": true, "relevance": 42, "remote_destination_count": 42, "security_category_count": 42, "severity": 42, "source_address_ids": [ 42 ], "source_count": 42, "source_network": "String", "start_time": 42, "status": "String <one of: OPEN, HIDDEN, CLOSED>", "username_count": 42 }

POST /siem/offenses/{offense_id} DEPRECATED

Update an offense.

Table 325: POST /siem/offenses/{offense_id} Resource Details

MIME Type

application/json

Table 326: POST /siem/offenses/{offense_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The ID of the offense to update.

protected

query

Optional

Boolean

text/plain

Optional - Set to true to protect the offense.

follow_up

query

Optional

Boolean

text/plain

Optional - Set to true to set the follow up flag on the offense.

status

query

Optional

String

text/plain

Optional - The new status for the offense. Set to one of: OPEN, HIDDEN, CLOSED. When the status of an offense is being set to CLOSED, a valid closing_reason_id must be provided. To hide an offense, use the HIDDEN status. To show a previously hidden offense, use the OPEN status.

closing_reason_id

query

Optional

Number (Integer)

text/plain

Optional - The ID of a closing reason. You must provide a valid closing_reason_id when you close an offense.

assigned_to

query

Optional

String

text/plain

Optional - A user to assign the offense to.

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 327: POST /siem/offenses/{offense_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense was updated.

403

1009

User does not have the required capability to assign an offense.

404

1002

No offense was found for the provided offense_id.

409

1008

Request cannot be completed due to the state of the offense.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the offense was being updated.

Response Description

An updated Offense object. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 328: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

{ "assigned_to": "String", "categories": [ "String" ], "category_count": 42, "close_time": 42, "closing_reason_id": 42, "closing_user": "String", "credibility": 42, "description": "String", "destination_networks": [ "String" ], "device_count": 42, "domain_id": 42, "event_count": 42, "flow_count": 42, "follow_up": true, "id": 42, "inactive": true, "last_updated_time": 42, "local_destination_address_ids": [ 42 ], "local_destination_count": 42, "magnitude": 42, "offense_source": "String", "offense_type": 42, "policy_category_count": 42, "protected": true, "relevance": 42, "remote_destination_count": 42, "security_category_count": 42, "severity": 42, "source_address_ids": [ 42 ], "source_count": 42, "source_network": "String", "start_time": 42, "status": "String <one of: OPEN, HIDDEN, CLOSED>", "username_count": 42 }

GET /siem/offenses/{offense_id}/notes DEPRECATED

Retrieve a list of notes for an offense.

Table 329: GET /siem/offenses/{offense_id}/notes Resource Details

MIME Type

application/json

Table 330: GET /siem/offenses/{offense_id}/notes Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to retrieve the notes 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.

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 331: GET /siem/offenses/{offense_id}/notes Response Codes

HTTP Response Code

Unique Code

Description

200

 

The note list was retrieved.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the note list was being retrieved.

Response Description

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

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

[ { "create_time": 42, "id": 42, "note_text": "String", "username": "String" } ]

POST /siem/offenses/{offense_id}/notes DEPRECATED

Create a note on an offense.

Table 332: POST /siem/offenses/{offense_id}/notes Resource Details

MIME Type

application/json

Table 333: POST /siem/offenses/{offense_id}/notes Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to add the note to.

note_text

query

Required

String

text/plain

Required - The note text.

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 334: POST /siem/offenses/{offense_id}/notes Response Codes

HTTP Response Code

Unique Code

Description

201

 

The note was created.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to create the note.

Response Description

The Note object that was created. A Note object contains the following fields:

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

{ "create_time": 42, "id": 42, "note_text": "String", "username": "String" }

GET /siem/offenses/{offense_id}/notes/{note_id} DEPRECATED

Retrieve a note for an offense.

Table 335: GET /siem/offenses/{offense_id}/notes/{note_id} Resource Details

MIME Type

application/json

Table 336: GET /siem/offenses/{offense_id}/notes/{note_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to retrieve the note from.

note_id

path

Required

Number (Integer)

text/plain

Required - The note ID.

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 337: GET /siem/offenses/{offense_id}/notes/{note_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The note was retrieved.

404

1002

No offense was found for the provided offense_id.

404

1003

No note was found for the provided note_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the note.

Response Description

The Note object for the note ID. A Note object contains the following fields:

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

{ "create_time": 42, "id": 42, "note_text": "String", "username": "String" }

GET /siem/source_addresses DEPRECATED

Retrieve a list offense source addresses currently in the system.

Table 338: GET /siem/source_addresses Resource Details

MIME Type

application/json

Table 339: GET /siem/source_addresses 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 340: GET /siem/source_addresses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The source address list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the source address list was being retrieved.

Response Description

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

  • id - Number - The ID of the source.

  • source_ip - String - The IP address.

  • magnitude - Number - The magnitude of the source address.

  • network - String - The network of the source address.

  • offense_ids - Array of Numbers - List of offense IDs the source is part of.

  • local_destination_address_ids - Array of Numbers - List of local destination address IDs associated with the source address.

  • event_flow_count - Number - The number of events and flows that are associated with the source.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

[ { "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_address_ids": [ 42 ], "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_ip": "String" } ]

GET /siem/source_addresses/{source_address_id} DEPRECATED

Retrieve an offense source address.

Table 341: GET /siem/source_addresses/{source_address_id} Resource Details

MIME Type

application/json

Table 342: GET /siem/source_addresses/{source_address_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

source_address_id

path

Required

Number (Integer)

text/plain

Required - The ID of the source address to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 343: GET /siem/source_addresses/{source_address_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The source address was retrieved.

404

1002

No source address was found for the provided source_address_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the source address was being retrieved.

Response Description

A source address object. A source address object contains the following fields:

  • id - Number - The ID of the source.

  • source_ip - String - The IP address.

  • magnitude - Number - The magnitude of the source address.

  • network - String - The network of the source address.

  • offense_ids - Array of Numbers - List of offense IDs the source is part of.

  • local_destination_address_ids - Array of Numbers - List of local destination address IDs associated with the source address.

  • event_flow_count - Number - The number of events and flows that are associated with the source.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

{ "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_address_ids": [ 42 ], "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_ip": "String" }

System Endpoints

Use the references for REST API V5 system endpoints.

GET /system/servers DEPRECATED

Retrieve a list of all server hosts in the deployment.

Table 344: GET /system/servers Resource Details

MIME Type

application/json

Table 345: GET /system/servers Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

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 346: GET /system/servers Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of server records has been successfully retrieved.

500

1020

An error has occurred while trying to retrieve the requested servers.

Response Description

A list of the servers. A server record contains the following fields:

  • hostname - String - hostname

  • managed_host_id - Number - Id of the managed host the server host belongs to

  • private_ip - String - The private ip of this server

  • status - String - The status of this server

Response Sample

[ { "hostname": "String", "managed_host_id": 42, "private_ip": "String", "server_id": 42, "status": "String" } ]

GET /system/servers/{server_id} DEPRECATED

Retrieve a server host based on the supplied server ID.

Table 347: GET /system/servers/{server_id} Resource Details

MIME Type

application/json

Table 348: GET /system/servers/{server_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server

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 349: GET /system/servers/{server_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested server record has been retrieved.

404

1002

The requested server record with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

500

1020

An error has occurred while trying to retrieve the requested server host with the given Id.

Response Description

A server record containing the following fields:

  • email_server_address - String - email server address

  • hostname - String - hostname

  • managed_host_id - Number - Id of the managed host the server host belongs to

  • private_ip - String - The private ip of this server

  • status - String - The status of this server

Response Sample

{ "email_server_address": "String", "hostname": "String", "managed_host_id": 42, "private_ip": "String", "server_id": 42, "status": "String" }

POST /system/servers/{server_id} DEPRECATED

Updates an existing server.

Table 350: POST /system/servers/{server_id} Resource Details

MIME Type

application/json

Table 351: POST /system/servers/{server_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server.

Table 352: POST /system/servers/{server_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

details

Object

application/json

Required - A server details record containing the following field:

email_server_address - String - email server address. Must be a valid server address that the server can connect to through port 25.

{ "email_server_address": "String" }

Table 353: POST /system/servers/{server_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The server record has been updated.

404

1002

The requested server record with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

422

1006

Cannot connect to the mail server address on port 25.

500

1020

An error has occurred while trying to retrieve the requested server host with the given Id.

Response Description

The updated server record containing the following fields:

  • email_server_address - String - email server address.

  • hostname - String - hostname

  • managed_host_id - Number - Id of the managed host the server host belongs to

  • private_ip - String - The private ip of this server

  • status - String - The status of this server

Response Sample

{ "email_server_address": "String", "hostname": "String", "managed_host_id": 42, "private_ip": "String", "server_id": 42, "status": "String" }

GET /system/servers/{server_id}/firewall_rules DEPRECATED

Retrieve a list of access control firewall rules based on the supplied server ID.

Table 354: GET /system/servers/{server_id}/firewall_rules Resource Details

MIME Type

application/json

Table 355: GET /system/servers/{server_id}/firewall_rules Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

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 356: GET /system/servers/{server_id}/firewall_rules Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rules records have been retrieved.

404

1002

The requested server with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

500

1020

An error has occurred while trying to retrieve the requested access control firewall rules on the server with the given Id.

Response Description

A list of the rules. Each rule record contains the following fields:

  • is_any_source_ip - Boolean - Whether any source IP is accepted

  • port_range - String - A port range in the format of start-end

  • port_type - String - one of: ANY, SINGLE, RANGE

  • protocol - String - one of: ANY, TCP, UDP

  • single_port - String - A single port

  • source_ip - String - A specific IP address

Response Sample

[ { "is_any_source_ip": true, "port_range": "String", "port_type": "String <one of: ANY, SINGLE, RANGE>", "protocol": "String <one of: ANY, TCP, UDP>", "single_port": "String", "source_ip": "String" } ]

PUT /system/servers/{server_id}/firewall_rules DEPRECATED

Set the access control firewall rules based on the supplied server ID.

Table 357: PUT /system/servers/{server_id}/firewall_rules Resource Details

MIME Type

application/json

Table 358: PUT /system/servers/{server_id}/firewall_rules Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server.

Table 359: PUT /system/servers/{server_id}/firewall_rules Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

rules

Array<Object>

application/json

Required - A list of new rules in a JSON string. Each rule record contains the following field:

  • is_any_source_ip - Boolean - Whether any source IP is accepted

  • port_range - String - A port range in the format of start-end

  • port_type - String - one of: ANY, SINGLE, RANGE

  • protocol - String - one of: ANY, TCP, UDP

  • single_port - String - A single port

  • source_ip - String - A specific IP address.

[ { "is_any_source_ip": true, "port_range": "String", "port_type": "String <one of: ANY, SINGLE, RANGE>", "protocol": "String <one of: ANY, TCP, UDP>", "single_port": "String", "source_ip": "String" } ]

Table 360: PUT /system/servers/{server_id}/firewall_rules Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rules have been updated.

404

1002

The requested server with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

500

1020

An error has occurred while trying to set the access control firewall rules on the server with the given Id.

Response Description

A list of the rules in a JSON string. Each rule contains the following fields:

  • is_any_source_ip - Boolean - Whether any source IP is accepted

  • port_range - String - A port range in the format of start-end

  • port_type - String - one of: ANY, SINGLE, RANGE

  • protocol - String - one of: ANY, TCP, UDP

  • single_port - String - A single port

  • source_ip - String - A specific IP address

Response Sample

[ { "is_any_source_ip": true, "port_range": "String", "port_type": "String <one of: ANY, SINGLE, RANGE>", "protocol": "String <one of: ANY, TCP, UDP>", "single_port": "String", "source_ip": "String" } ]

GET /system/servers/{server_id}/network_interfaces/ethernet DEPRECATED

Retrieve a list of the ethernet network interfaces based on the supplied server ID.

Table 361: GET /system/servers/{server_id}/network_interfaces/ethernet Resource Details

MIME Type

application/json

Table 362: GET /system/servers/{server_id}/network_interfaces/ethernet Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

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 363: GET /system/servers/{server_id}/network_interfaces/ethernet Response Codes

HTTP Response Code

Unique Code

Description

200

 

A list of the ethernet network interfaces have been retrieved.

404

1002

The requested server with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

500

1020

An error has occurred while trying to retrieve the ethernet interfaces on the server with the given Id.

Response Description

A list of the ethernet network interfaces. Each ethernet network interface contains the following fields:

  • device_name - String - The name of the network interface

  • desc - String - The description of the network interface

  • role - String - The role of the network interface. one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled

  • ipversion - String - The version of the ip address configured on the network interface. one of: ipv4, ipv6

  • ip - String - The ip configured on the network interface

  • mask - String - The netmask configured on the network interface

  • gateway - String - The gateway configured on the network interface

  • is_auto_ip - Boolean - Is the ip auto configured

  • is_cable_linked - Boolean - Is the network interface cable linked.

  • is_moving_config_with_active_ha - Boolean - Will apply the same settings to a new active HA server during failover.

  • hacrossover_params - String - A map of key-value pairs of HA crossover parameters if the network interface is used for HA crossover.

Response Sample

[ { "desc": "String", "device_name": "String", "gateway": "String", "hacrossover_params": { "String": "String" }, "ip": "String", "ipversion": "String <one of: ipv4, ipv6>", "is_auto_ip": true, "is_cable_linked": true, "is_moving_config_with_active_ha": true, "mask": "String", "role": "String <one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled, slave, slave_disabled>", } ]

POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} DEPRECATED

Update an ethernet network interface based on the supplied server ID and device name.

Table 364: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Resource Details

MIME Type

application/json

Table 365: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

server_id

path

Required

Number (Integer)

text/plain

Required - The id of the server.

device_name

path

Required

String

text/plain

Required - The name of an existing ethernet network interface. The interface cannot be the management interface, HA crossover interface or a slave of a bonded interface.

Table 366: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

details

Object

application/json

Required - An ethernet network interface record containing the following fields:

role - String - The role of the network interface. Must be one of: regular, monitor, disabled

ipversion - String - The version of the ip address configured on the network interface. one of: ipv4, ipv6

ip - String - The ip configured on the network interface. Required when ipversion is ipv4 or (ipversion is ipv6 and is_auto_ip is false). The subnet computed from the ip and the mask must not be the same subnet configured on the management interface.

mask - String - The netmask configured on the network interface. Required when ipversion is ipv4. The subnet computed from the ip and the mask must not be the same subnet configured on the management interface.

gateway - String - The gateway configured on the network interface. Optional when ipversion is ipv4. Empty value means the network interface will use the default gateway. Does not need in ipv6

is_auto_ip - Boolean - Is the ip auto configured. Required

is_moving_config_with_active_ha - Boolean - Will apply the same settings to a new active HA server during failover. Can be true only when the server host is an active HA server host

{ "gateway": "String", "ip": "String", "ipversion": "String <one of: ipv4, ipv6>", "is_moving_config_with_active_ha": true, "mask": "String", "role": "String <one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled, slave, slave_disabled>" }

Table 367: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The network interface has been updated.

404

1002

The requested server with the given server_id cannot be found.

422

1005

One or more parameters are invalid in request.

500

1020

An error has occurred while trying to update the specified ethernet interfaces on the server with the given Id.

Response Description

The updated ethernet network interface containing the following fields:

  • device_name - String - The name of the network interface

  • role - String - The role of the network interface. one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled

  • ipversion - String - The version of the ip address configured on the network interface. one of: ipv4, ipv6

  • ip - String - The ip configured on the network interface

  • mask - String - The netmask configured on the network interface

  • gateway - String - The gateway configured on the network interface

  • is_auto_ip - Boolean - Is the ip auto configured

  • is_moving_config_with_active_ha - Boolean - Will apply the same settings to a new active HA server during failover.

Response Sample

{ "desc": "String", "device_name": "String", "gateway": "String", "hacrossover_params": { "String": "String" }, "ip": "String", "ipversion": "String <one of: ipv4, ipv6>", "is_auto_ip": true, "is_cable_linked": true, "is_moving_config_with_active_ha": true, "mask": "String", "role": "String <one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled, slave, slave_disabled>", }