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 Approval

Single endpoint that provides details about existing approvals in the system.

/rest/approval

List of all approvals.

Syntax 

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

GET

List of approvals.

Example request
Get a list of approvals. 

curl -k -u admin:changeme https://localhost/rest/approval -G -X GET

Example response
A successful GET will return a 200 response, and a JSON formatted list of approvals. 

{
"count": 5,
"data": [
{
"status": "expired",
"owner_type": "User",
"action_run": 23,
"playbook_run": 60,
"escalated_approval": null,
"name": "prompt_1",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-07-16T23:22:39.149000Z",
"close_time": "2019-07-16T23:52:39.247000Z",
"id": 1,
"due_time": "2019-07-16T23:52:39.115000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 13,
"message": "pending-manual-action",
"type": "manual",
"display": true,
"responses": []
},
{
"status": "expired",
"owner_type": "User",
"action_run": 50,
"playbook_run": 66,
"escalated_approval": null,
"name": "task_1",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-07-29T23:28:43.149000Z",
"close_time": "2019-07-29T23:58:43.209000Z",
"id": 2,
"due_time": "2019-07-29T23:58:43.118000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-manual-action",
"type": "manual",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 51,
"playbook_run": 67,
"escalated_approval": null,
"name": "approval for add tag",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T05:38:05.728000Z",
"close_time": null,
"id": 3,
"due_time": "2019-08-20T05:38:05.726000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 52,
"playbook_run": 68,
"escalated_approval": null,
"name": "approval for add tag",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T05:38:58.723000Z",
"close_time": null,
"id": 4,
"due_time": "2019-08-20T05:38:58.721000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
},
{
"status": "pending",
"owner_type": "Action Reviewer",
"action_run": 53,
"playbook_run": 69,
"escalated_approval": null,
"name": "approval for activate device",
"parent": null,
"node_guid": "eef4c48b-eef2-450e-a1b7-e90d2ef26fed",
"start_time": "2019-08-19T16:25:03.062000Z",
"close_time": null,
"id": 5,
"due_time": "2019-08-20T16:25:03.060000Z",
"version": 1,
"jitc": {},
"asset": null,
"owner": 1,
"message": "pending-approval",
"type": "parameter",
"display": true,
"responses": []
}
],
"num_pages": 1
}

/rest/approval/<id>

Get the data of one approval.

Syntax 

https://<username>:<password>@<host>/rest/approval/<id>

GET

List the approval data from one approval ID.

Example request
Get a list of approvals. 

curl -k -u admin:changeme https://localhost/rest/approval/1 -G -X GET

Example response
A successful GET will return a 200 response, and a JSON formatted list of data for one approval ID. 

{
	"status": "expired",
	"owner_type": "User",
	"action_run": 9,
	"playbook_run": 59,
	"escalated_approval": null,
	"name": "task_1",
	"parent": null,
	"node_guid": "9a8092d6-c3ad-4c61-b92a-005bb179cfc6",
	"start_time": "2020-01-22T19:39:43.239000Z",
	"close_time": "2020-01-22T20:09:43.295000Z",
	"id": 1,
	"due_time": "2020-01-22T20:09:43.221000Z",
	"version": 1,
	"jitc": {},
	"asset": null,
	"owner": 1,
	"message": "pending-manual-action",
	"type": "manual",
	"display": true,
	"responses": []
}

/rest/approval/<id>/detail_summary_view

List details of approvals for a particular container.

Syntax 

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

GET

List details of approvals for a container where 21 is the approval ID in the example request.

Example request
List details of approvals. 

curl -k -u admin:changeme https://localhost/rest/approval/21/detail_summary_view -G -X GET

Example response
A successful GET for approvals 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": "r56jEhzRlV/TR9CWLzDgN0GtxWrYQskkOl5ypVGUCNu1KKfy5f9EA40TY2piQLKCL040OtANINfTtV3vWF5kmElSRfHpb275bkN7didzCPpgpLg0PincyjONjA7P+d4e"
        },
        "product_vendor": "AbuseIPDB",
        "id": 70,
        "name": "abuse_ip_db"
    },
    "action_type": "post ip",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "admin",
    "notification_type": "approvals",
    "type": "asset",
    "notification_targets": [{
        "app_id": 152,
        "parameters": [{
            "comment": "ddd",
            "ip": "3.3.3.33",
            "categories": "dd"
        }],
        "assets": [
            70
        ]
    }]
}

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

{
    "playbook_repo": "local",
    "update_time": "2019-08-19T21:58:03.846035Z",
    "playbook_name": "pb-prompt",
    "container_id": 292,
    "time_left": 1758.571971,
    "next_owner": null,
    "action_name": "prompt_1",
    "due_time": "2019-08-19T22:28:03.817000Z",
    "asset": null,
    "action_type": "prompt",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "admin",
    "notification_type": "prompts",
    "type": "manual",
    "notification_targets": [{
        "app_id": 0,
        "parameters": [{
            "to": "root@localhost",
            "message": "test",
            "mins_to_act": 30,
            "user_ids": [
                1
            ],
            "response_types": [{
                "prompt": "",
                "options": {
                    "type": "message"
                }
            }]
        }],
        "assets": []
    }]
}

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

{
    "update_time": "2019-08-19T22:04:59.289861Z",
    "container_id": 293,
    "time_left": 3383.812224,
    "next_owner": null,
    "action_name": "user initiated task-18172",
    "due_time": "2019-08-19T23:04:59.240000Z",
    "asset": null,
    "action_type": "task",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "admin",
    "notification_type": "manual tasks",
    "type": "manual",
    "notification_targets": []
}

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

{
    "playbook_repo": "local",
    "update_time": "2019-08-19T22:14:06.436276Z",
    "playbook_name": "pb-reviewer",
    "container_id": 294,
    "time_left": 78412.135004,
    "next_owner": null,
    "action_name": "geolocate_ip_1",
    "due_time": "2019-08-20T20:05:58.356000Z",
    "asset": null,
    "action_type": "geolocate ip",
    "container_name": "Testcases.000100-Rest.000230-Custom Status.000200-Custom Status Severity Generator",
    "owner": "admin",
    "notification_type": "action reviews",
    "type": "parameter",
    "notification_targets": [{
        "app_id": 124,
        "parameters": [{
            "ip": "2.3.2.22"
        }],
        "assets": [
            2
        ]
    }]
}

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 prompts, approvals, manual tasks, action reviews.
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


The response varies depending on the notification type, which is a sub-type of approvals. The output is similar to /rest/notification/<id>/detail_summary_view used for mobile. See REST Notification.

Last modified on 08 March, 2023
REST App   REST Artifact

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