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 Workbook

Manage workbooks or workflows.

A workbook is a response plan that has been added to a container, while a workbook template is the base object used to create workbooks. When a workbook template is added to a container, a copy of the template is added, which then becomes a workbook.

For information on adding a workbook template to a container, see REST Containers.

/rest/workbook_task filters

Get the tasks for all workbooks.

Syntax 

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

Usage details
By default, returns all tasks for all workbooks. You cannot filter results for a single workbook.

GET

Get workbook tasks belonging to a container.

Request parameters
Retrieve workbooks with the following parameters:

Field Required Type Description
container_id Optional string Identity of the container for the workbooks.
id Optional string Identity of the workbook task.

Example request
Get the workbook tasks belonging to container 1. 

curl -k -u admin:changeme https://localhost/rest/workbook_task?_filter_container_id=1&sort=id&order=desc -G -X GET

Example response
A successful request returns a 200 response and a JSON object containing tasks. 

{
    "count": 38,
    "num_pages": 4,
    "data": [
        {
            "id": 1,
            "name": "Confirmed incident",
            "order": 5,
            "owner": null,
            "role": null,
            "container": 1,
            "phase": 1,
            "description": "Confirmed incident - document the investigation and gather evidence. Attach all relevant information from detection steps to the case",
            "suggestions": {},
            "status": 0,
            "create_time": "2022-10-19T22:15:41.046930Z",
            "modified_time": "2022-10-19T22:15:41.047202Z",
            "notified": false,
            "is_note_required": true,
            "sla": null,
            "sla_type": "minutes",
            "start_time": null,
            "end_time": null,
            "notes": [],
            "files": [],
            "owner_name": null
        },
        ...
    ]
  }

/rest/workbook_template

Create a workbook using /rest/workflow_template or /rest/workbook_template.

Syntax 

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

Usage details
The "Edit Container" permission is required to add or modify workbooks.

POST

Add a workbook template.

Request parameters
Workbook templates are modified with the following parameters.

Field Required Type Description
is_default required Boolean Sets the created workbook to be the default case workbook. Removes the default flag from any other workbook.
name required string The name of the new workbook.
phases optional Array of JSON Objects Contains an array of phase objects that describe the workflow. See /rest/workbook_phase_template for phase object parameters and /rest/workbook_task_template for task object parameters.

Example request
Create a workbook with the name "My Workbook" that includes a phase named "My Phase" and a task named "My Task." 

curl -k -u admin:changeme https://localhost/rest/rest/workbook_template \
-d '{
	"name": "My Workbook",
	"is_default": false,
	"phases": [{
		"name": "My Phase",
		"order": 1,
		"tasks": [{
			"name": "My Task",
			"order": 1,
			"description": "Investigate the event",
			"playbooks": [{
					"scm": "local",
					"playbook": "investigate"
				},
				{
					"scm": "community",
					"playbook": "04_07_2017 - PhishMe"
				}
			],
			"actions": ["geolocate ip", "block_ip"]
		}...]
	}...]
}'

Example response
A successful request will result in a 200 response returning the new workbook Id and success as JSON. 

{
    "id": 10,
    "success": true
}

/rest/workbook_phase_template

Add a phase to a workbook using /rest/workbook_phase_template or /rest/workflow_phase_template.

Syntax 

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

Usage details
Be sure to include the template_id attribute.

POST

Add a phase to an existing workbook template.

Request parameters
A Phase Object describes the stages of life of a case and are composed of multiple tasks.

Field Required Type Description
name required string The name of the phase.
order optional integer Specifies where the order the phase is expected to be executed in relative to other phases in the workbook.
tasks optional Array of JSON Objects Contains an array of task objects that describe the phase. See /rest/workbook_task_template for the task object parameters.
template_id optional integer May only be passed when adding a phase to an existing template.

Example request
Add a phase named "My Phase" and a task named "My Task" to template Id 10. 

curl -k -u admin:changeme https://localhost/rest/rest/workbook_phase_template \
-d '{
  "name": "My Phase",
  "order": 1,
  "template_id": 10,
  "tasks": [
    {
      "name": "My Task",
      "order": 1,
      "description": "Investigate the event",
      "playbooks": [
        { "scm": "local", "playbook": "investigate" },
        { "scm": "community", "playbook": "04_07_2017 - PhishMe" }
      ],
      "actions": [ "geolocate ip", "block_ip" ]
    }...
  ]
}'

Example response

{
    "id": 20,
    "success": true
}

/rest/workbook_phase_template?_filter_template={template_id}

Return all the template phases for the specified template ID. This API filters on a specific template ID. See Filtering for more information on filtering.

Syntax 

https://<username>:<password>@<host>/rest/workbook_phase_template?_filter_template={template_id}

GET

Return all the template phases for the template ID of 1.

Example request
Return all the template phases for the template ID of 1. 

curl -k -u username:password https://localhost/rest/workbook_phase_template?_filter_template=1 -G -X GET

Example response
This returns a template with one phase. 

{
    "count": 1,
    "num_pages": 1,
    "data": [
        {
            "id": 1,
            "name": "Ingestion",
            "order": 1,
            "create_time": "2023-09-14T23:49:14.844069Z",
            "modified_time": "2023-09-14T23:49:14.844784Z",
            "template": 1,
            "sla": null,
            "sla_type": "minutes",
            "tasks": [
                {
                    "id": 1,
                    "name": "Create ticket",
                    "order": 1,
                    "owner": null,
                    "role": null,
                    "phase": 1,
                    "description": "Create any necessary tickets or tracking documents describing the initial conditions of the suspicious email investigation. As additional information is collected or actions are taken in the following tasks and phases, update the ticket with links and relevant information to allow collaboration and tracking.",
                    "suggestions": {
                        "actions": [
                            "create ticket",
                            "send email",
                            "send message"
                        ],
                        "playbooks": [
                            {
                                "scm": "community",
                                "playbook": "user_approved_ticket_creation"
                            }
                        ]
                    },
                    "create_time": "2023-09-14T23:49:14.849168Z",
                    "modified_time": "2023-09-14T23:49:14.850297Z",
                    "is_note_required": true,
                    "sla": null,
                    "sla_type": "minutes"
                },
                {
                    "id": 2,
                    "name": "Ingest email",
                    "order": 2,
                    "owner": null,
                    "role": null,
                    "phase": 1,
                    "description": "Identify and ingest the suspicious email into Splunk SOAR. Actual steps vary depending on how the Splunk SOAR event is created and where the suspicious email resides. For example, if the suspicious email is sent to a dedicated email address for suspected phishing attempts, Splunk SOAR can poll that inbox directly with an App such as IMAP, EWS for Exchange, EWS for Office, or GSuite for GMail. This will create the event in Splunk SOAR and populate it with email headers, URL artifacts, domain artifacts, file attachments, to/from addresses, the text of the raw email, and other metadata. Alternatively, if the email is not already ingested directly into Splunk SOAR the \"get email\" action may be useful to retrieve it. For example, if a Splunk Notable Event based on the Email datamodel is used to detect a suspicious email, Splunk SOAR may be able to run \"get email\" to ingest the email based on the IMAP UID or other identifier. Another possible scenario is that the email of interest is included as an attachment on the email received by Splunk SOAR. In this case the \"extract email\" action may be able to ingest the email if it is in the .msg or .eml format.",
                    "suggestions": {
                        "actions": [
                            "get email",
                            "extract email"
                        ]
                    },
                    "create_time": "2023-09-14T23:49:14.852849Z",
                    "modified_time": "2023-09-14T23:49:14.853606Z",
                    "is_note_required": true,
                    "sla": null,
                    "sla_type": "minutes"
                }
            ]
        }
       
    ]
}

/rest/workbook_task_template

Add a task to an existing phase using /rest/workbook_task_template or /rest/workflow_task_template.

Syntax 

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

Usage details
Be sure to include the phase_id attribute.

POST

Add a task to an existing phase.

Request parameters
A Task Object indicates what activities should be taken on a case and may include playbooks, Splunk SOAR actions, or manual activities taken by a person.

Field Required Type Description
actions required Array of strings Array of action names that are expected to be carried out.
description required string A textual description of the task to be performed.
playbooks required Array of JSON Objects An array describing what playbook should be run. Each JSON object should contain 2 key-value pairs. They should have an "scm" key where the value is the name of the Source Control repository and a "playbook" key where the value is the name of the playbook within that repository.
phase_id optional integer May only be passed when adding a task to an existing phase.
name required string A human friendly name for the task.
order optional integer Order in which the task is expected to be carried out relative to other tasks in the phase.
owner optional integer or string The account name or numeric ID of the user or role who is the current owner of the container.

Example request
Add a task named "My Task" to existing phase Id 20. 

curl -k -u admin:changeme https://localhost/rest/workbook_task_template \
-d '{
	"name": "My Task",
	"order": 1,
	"owner": 2,
	"phase_id": 20,
	"description": "Investigate the event",
	"playbooks": [{
			"scm": "local",
			"playbook": "investigate"
		},
		{
			"scm": "community",
			"playbook": "04_07_2017 - PhishMe"
		}
	],
	"actions": ["geolocate ip", "block_ip"]
}'

Example response
A successful request will result in a 200 response returning the new task id and success as JSON. 

{
    "id": 30,
    "success": true
}

Optional /rest/workbook_phase/ filters

Get the phases of a workbook.

/rest/workflow_phase?_filter_container_id

Syntax 

https://<username>:<password>@<host>/rest/workbook_phase?_filter_container_id=<arguments>

GET

Get the phases of a workbook.

Example request
Get the phases of workbook Id 259. 

curl -k -u admin:changeme https://localhost/rest/workflow_phase?_filter_container_id=259 -G -X GET

Example response
A successful request returns a 200 response and a JSON object containing the phases for the workbook. 

{
  "count": 5,
  "data": [
      {
          "status": 0,
          "tasks": [ 
              {
                  "status": 0,
                  "files": [],
                  "owner_name": null,
                  "container": 259,
                  "name": "Determine if an incident has occurred",
                  "notified": false,
                  "start_time": null,
                  "suggestions": {},
                  "modified_time": "2019-05-30T19:06:24.687501Z",
                  "id": 5,
                  "phase": 1,
                  "create_time": "2019-05-30T19:06:24.687190Z",
                  "role": null,
                  "sla_type": "minutes",
                  "sla": null,
                  "owner": null,
                  "end_time": null,
                  "notes": [],
                  "order": 1,
                  "is_note_required": true,
                  "description": ""
              }, ...
          ],
          "container": 259,
          "name": "Detection",
          "start_time": null,
          "modified_time": "2019-05-30T19:06:24.658201Z",
          "id": 1,
          "create_time": "2019-05-30T19:06:24.657855Z",
          "sla_type": "minutes",
          "sla": null,
          "order": 1,
          "end_time": null
      }, ...
      {
          "status": 0,
          "tasks": [ ...
          ],
          "container": 259,
          "name": "Post Incident Activity",
          "start_time": "2019-05-30T19:06:25.670935Z",
          "modified_time": "2019-05-30T19:06:25.672107Z",
          "id": 5,
          "create_time": "2019-05-30T19:06:24.745617Z",
          "sla_type": "minutes",
          "sla": null,
          "order": 5,
          "end_time": null
      }
  ],
  "num_pages": 1
}
Last modified on 22 September, 2023
REST Warm standby  

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