Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

The classic playbook editor will be deprecated in early 2025. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.

REST Notification

Single notification endpoint that provides details about existing notifications in the system.

/rest/notification

List details of all notifications.

Syntax 

https://<username>:<password>@<host>/rest/notification

GET

List details of notifications.

Example request
List details of notifications. The example shows the syntax for filtering and sorting. 

curl -k -u uname:pwd https://localhost/rest/notification?_filter_is_read=False&pretty&sort=create_time&order=desc&notifcation_type&due_time -G -X GET

Example response
A successful GET will return a 200 response, and a JSON formatted list of details. Since the example request shows the syntax for filtering and sorting, the example response shows filter responses. See REST Query Data for information about parameters like _pretty and count. 

{
	"count": 6,
	"data": [

		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "0 minutes ago",
			"ttl_minutes": 59,
			"object_id": 62,
			"to_user": 1,
			"create_time": "2019-07-26T19:03:43.729000Z",
			"_pretty_from_user": "",
			"content_type": 10,
			"from_user": null,
			"message": "user initiated task",
			"notification_type": "manualtask",
			"due_time": " 2019-07-26T20:03:43.729000Z",
			"id": 72
		},

		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "0 minutes ago",
			"ttl_minutes": 29,
			"object_id": 61,
			"to_user": 1,
			"create_time": "2019-07-26T19:03:17.058000Z",
			"_pretty_from_user": "",
			"content_type": 10,
			"from_user": null,
			"message": "prompt_1",
			"notification_type": "prompt",
			"due_time": " 2019-07-26T20:03:43.729000Z",
			"id": 71
		},
		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "42 minutes ago",
			"ttl_minutes": 1439,
			"object_id": 60,
			"to_user": 1,
			"create_time": "2019-07-25T20:23:10.372000Z",
			"_pretty_from_user": "",
			"content_type": 10,
			"from_user": null,
			"message": "approval for block ip on asset 'zscaler'",
			"notification_type": "approval",
			"due_time": " 2019-07-26T20:03:43.729000Z",
			"id": 70
		},
		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "43 minutes ago",
			"ttl_minutes": 1439,
			"object_id": 58,
			"to_user": 1,
			"create_time": "2019-07-25T20:22:55.118000Z",
			"_pretty_from_user": "",
			"content_type": 10,
			"from_user": null,
			"message": "approval for block ip",
			"notification_type": "actionreview",
			"due_time": " 2019-07-26T20:03:43.729000Z",
			"id": 68
		},
		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "Today at 07:15 PM",
			"ttl_minutes": 43200,
			"object_id": 20,
			"to_user": 1,
			"create_time": "2019-07-25T19:15:56.065053Z",
			"_pretty_from_user": "adminTester",
			"content_type": 19,
			"from_user": 25,
			"message": "@admin hi",
			"notification_type": "containercomment",
			"id": 67
		},
		{
			"is_read": false,
			"_pretty_to_user": "admin",
			"_pretty_create_time": "Jul 09 at 08:49 PM",
			"ttl_minutes": 0,
			"object_id": 697,
			"to_user": 1,
			"create_time": "2019-07-09T20:49:55.928000Z",
			"_pretty_from_user": "",
			"content_type": 73,
			"from_user": null,
			"message": "Task 'Determine functional impact' of phase 'Analysis and Containment' for case 'HUD Container' has been assigned to you",
			"notification_type": "workflowtask",
			"due_time": " 2019-07-26T20:03:43.729000Z",
			"id": 13
		}
	],
	"num_pages": 1
}

The return values of note follow:

Field Type Description
notification_type String Always displays the notification type for all notifications, and distinguishes between the different types of approvals: action reviews, approvals, manual tasks, and prompts.
due_time String Displays notification due date for any notification that has a due date.
message String Displays message of notification no matter the type, because currently message is empty for approval notifications: message, and approval for block ip.

/rest/notification/<id>/detail_summary_view

List details of notifications for a particular container. The response varies depending on the notification type, which is a sub-type of notifications.

Syntax 

https://<username>:<password>@<host>/rest/notification/<id>/detail_summary_view

GET

List details of notifications for a container where 21 is the container ID in the example request below, but not the ID in the example responses below.

Example request
List details of notifications. 

curl -k -u uname:pwd https://localhost/rest/notification/21/detail_summary_view -G -X GET

Example response
A successful GET for approval notification type will return a 200 response, and a JSON formatted list of details. 

{
	"update_time": "2019-08-19T21:43:58.892936Z",
	"container_id": 291,
	"time_left": 80128.535132,
	"next_owner": null,
	"action_name": "user initiated post ip action",
	"due_time": "2019-08-20T20:05:57.814000Z",
	"asset": {
		"action_whitelist": {},
		"validation": {},
		"tenants": [],
		"description": "Default Asset Configuration for AbuseIPDB",
		"tags": [],
		"type": "reputation",
		"primary_voting": 0,
		"product_version": "",
		"effective_user": 2,
		"product_name": "AbuseIPDB",
		"disabled": false,
		"token": null,
		"version": 1,
		"secondary_voting": 0,
		"configuration": {
			"api_key": "<encrypted_key>"
		},
		"product_vendor": "AbuseIPDB",
		"id": 70,
		"name": "abuse_ip_db"
	},
	"action_type": "post ip",
	"container_name": "Possible Malicious Email",
	"owner": "admin",
	"notification_type": "approval",
	"type": "asset",
	"notification_targets": [{
		"app_id": 152,
		"parameters": [{
			"comment": "Possibly malicious IP address",
			"ip": "1.2.3.4",
			"categories": "phishing"
		}],
		"assets": [
			70
		]
	}]
}

Example response
A successful GET for prompt notification type will return a 200 response, and a JSON formatted list of details. 

{
	"playbook_repo": "local",
	"update_time": "2019-09-05T23:06:14.828588Z",
	"playbook_name": "Detect Malicious Domains",
	"container_id": 6355,
	"time_left": null,
	"next_owner": null,
	"action_name": "prompt_1",
	"container_name": "Malicious URL Request Attempt",
	"owner": "admin",
	"notification_type": "prompt",
	"escalated_approval": null,
	"due_time": "2019-09-05T23:06:14.709000Z",
	"jitc": {},
	"asset": null,
	"action_type": "prompt",
	"type": "manual",
	"notification_targets": [{
		"app_id": 0,
		"parameters": [{
			"to": "admin@example.com",
			"message": "Malicious domain detected",
			"mins_to_act": 30,
			"user_ids": [1],
			"response_types": [{
				"prompt": "General comments on domain",
				"options": {
					"type": "message"
				}
			}, {
				"prompt": "Have any users visited this malicious address?",
				"options": {
					"type": "list",
					"choices": ["Yes", "No"]
				}
			}]
		}],
		"assets": []
	}]
}

Example response
A successful GET for manualtask notification type will return a 200 response, and a JSON formatted list of details. 

{
	"update_time": "2019-09-05T01:34:58.002459Z",
	"container_id": 6325,
	"time_left": null,
	"next_owner": null,
	"action_name": "user initiated task",
	"container_name": "Possible Malicious Email",
	"owner": "admin",
	"notification_type": "manualtask",
	"escalated_approval": null,
	"due_time": "2019-09-05T01:34:57.833000Z",
	"jitc": {},
	"asset": null,
	"action_type": "task",
	"type": "manual",
	"notification_targets": []
}

Example response
A successful GET for actionreview notification type will return a 200 response, and a JSON formatted list of details. 

{
	"playbook_repo": "local",
	"update_time": "2019-09-05T20:27:15.311964Z",
	"playbook_name": "Detect and Respond Against Malicious Domains",
	"container_id": 6354,
	"time_left": 32711.14501,
	"next_owner": null,
	"action_name": "block_ip",
	"container_name": "ASN Transaction",
	"owner": "admin",
	"notification_type": "actionreview",
	"escalated_approval": null,
	"due_time": "2019-09-06T08:27:15.301000Z",
	"jitc": {},
	"asset": null,
	"action_type": "block ip",
	"type": "parameter",
	"notification_targets": [{
		"app_id": 124,
		"parameters": [{
			"is_source_address": "",
			"ip": "1.1.1.1"
		}],
		"assets": [170]
	}]
}

The return values of note follow:

Field Type Description
asset JSON Object Can be empty depending on the notification type and if it contains an asset. See REST Assets for further information about assets.
container_id String The container Id of the playbook action run.
due_time String Time (UTC) when this action is due ( time at which the SLA expires/expired ).
next_owner String The next owner for an approval, such as admin.
notification_targets JSON Object JSON object containing a variety of parameters entered in response to prompt.
notification_type String prompt, approval, manualtask, actionreview.
owner String The current owner's display name, such as admin.
playbook_name String The playbook name.
playbook_repo String The name of the the playbook repository.
prompt String The options available to respond to a prompt such as:
  • list: a list of pre-selected strings
  • message: a user-inputted string
  • range: a number in the range specified by the prompt response

It returns a dictionary that organizes the response answer percentage by response.

time_left String The due time minus the current time, in seconds.
type String Mapping for prettifying notification types, such as:
  • prompt -> prompts
  • asset -> approvals
  • task -> manual tasks
  • parameter -> action reviews
Last modified on 08 March, 2023
REST Note   REST Playbook

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters