REST Playbook

/rest/playbook

GET

Gets a playbook based on the name provided.

Request parameters
Specify the name parameter to get a playbook with that exact name. For more API filtering information, see Filtering in the Query for Data article.

Field	Required	Type	Description
_filter_name	Optional	string	The exact name of the playbook you want to retrieve, specified within quotes.

Example request
Get a playbook named advanced_playbook_tutorial.

curl -k -u username:password https://localhost/rest/playbook?_filter_name="advanced_playbook_tutorial"

Example response
A successful GET returns an x-gzip file of the specified playbook.

/rest/playbook/<id>

Retrieves or updates a playbook, based on its id.

Syntax

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

GET

Gets the playbook corresponding to the id provided.

Request parameters
Specify the id parameter to get a playbook with that exact id. For more API filtering information, see Filtering in the Query for Data article.

Field	Required	Type	Description
<id>	Required	string	The id of the playbook you want to update or retrieve.

Example request
Get the playbook with the id=123, along with all of its attributes and payload.

curl -k -u username:password https://localhost/rest/playbook/123

Example response
A successful GET returns a JSON payload representing the specified playbook with this general structure:

{
   "tags": [ ], 
   "id": 123, 
   "active": false, 
   "playbook_trigger": "artifact_created", 
   "blockly": false, 
   ... 
}

POST

Updates specific attributes of the playbook corresponding to the id provided.

Request parameters
You can modify playbooks by using the following parameters.

Field	Required	Type	Description
playbook_id	Required	integer	Id of the playbook to run automatically when the trigger condition is met.
active	Optional	boolean	Sets the playbook as active or inactive, when active, the playbook will run automatically based on the playbook_trigger described later in this table. Playbooks in draft mode cannot be marked active.
cancel_runs	Optional	boolean	Setting this field to true when transitioning from active to inactive will cancel any current playbook runs associated with the playbook.
playbook_trigger	Optional	string	Run the playbook automatically when the condition you specify occurs. This setting requires that the Active toggle, described earlier in this table, is set to True. Conditions you can specify include: "artifact_created": A user, including the automated user, creates an artifact within a specified container. "container_resolved": A user moves the container into a status within the Resolved status group, such as Closed. The playbook is not automatically run if the container is resolved by an automation user, an app, or by another playbook. Default: If you do not specify a string described in this table, by default, a playbook marked as active will run automatically when an event is ingested with a label matching the playbook's label.

The following requests return similar responses. A sample response is provided at the end of this section.

Example request: Set as inactive and cancel playbook runs
Set playbook Id 42 as inactive and cancel its playbook runs.

curl -k -u username:password https://localhost/rest/playbook/42 \
-d '{
  "active": false,
  "cancel_runs": true
}'

Example request: run playbook based on artifact created condition
Cause playbook 123 to run automatically when an artifact is created.

curl -X POST -u 'username:password' -d '{"playbook_trigger": "artifact_created"}' -k https://localhost/rest/playbook/123

Example response
All successful POSTs return a descriptive message and success indicator.

{
    "message": "Operation successful",
    "success": true
}

/rest/import_playbook

POST

Imports a playbook.

Request parameters

Field	Required	Type	Description
playbook	Required	String	The base64-encoded, gzipped playbook TAR file that you want to import.
scm/scm_id	Required	Name or ID of the repository	The repository where the playbook is saved.
force	Optional	boolean	Set to true to override an existing playbook in the same repository with the same name.

Example request
Imports a playbook.

curl -k -u username:password https://localhost/rest/import_playbook \
-d '{
   "playbook": "H4sIAAGrUmUC/+1YbW/bNhDOZ/8KQvvgJHMUUW+2jGZYkWZYgTUI0Hb7EBgCI1G2WolUKSqNF/i/j9SLLSux7CZzgGw6A7bFO97xjs9Rd1RP1dNfr9Dd7xj5mB3shbSCNv1qmmGu/stxqOlQPwB3By9AWcoRE+YP/p+kj0DMwxifQdtxHGhbhqMOh5puj8zeQUf/eYrRXRwSHyQRmt9Q+lVN5nvJf9vO8x0OLVj/zbNfN61G/pu6OTwA2kvmfzJDhGWb5bbxXykpitLr5V+9ME4o40A6ymmssizCKUBpNVDxv6SU9AJGY+AjjuXZAUpO9TwA8tvHEUdCrY8DQIkrw8wPPUo4CglmR+MeEFQZ8/FNNj3sL+WOgIeiCPv9o14u91P+DPpTTCPqCTtumLiwD27E09dcYp2zMnS2MlmoYphnjBTrakxCHg8pObukRPiQZp6H07R8WukrnhlOs4hXXOGFH+HyIQgjjhn2XeFIGAidaZOxPtkTEKSxG2Skbv74+Ot3xKbpo4FSGguvwqUsw9UI7Ntc9RjcawtwDxd9NaAsRrz0+LpPUIz7kwE47H/8fH5+cfHu4l0fhEEVBICjFIP+b2/f/yEYR0elmQQxMU/4lIIzcD1pDqooSTDxD+/zcUlKmChjoEBVVw3VVAY5Y1Et+l+mUik4z+MLzqmPwUeJrv1YKwP/Fws5BnOasXJjBXSE4ZnYeFVVX87TC+Lv0c8KXgI/NTACsb2DGgDOVn8HQELsrAFcIY3SFItUuFbKN5EyaeRpdYAEIQnT2SqxZYbGMWLzxzNkNeNBcnQ4ezU4K0DQlWl7I7Xr/7r+r+v/uv6v6v9kef+y/Z9t28Nm/2drRtf/vQQVtbmS91HRXBTnARKl/mBt1L2LI1m2vxG/v7w5ld9l6a7ISm5KmZyofCblU/i3KLYqAYoEr9YBiCZxfaQYxanHwkQ2I1JVOXvJxv4Up4JxvTYs6f7BSNFn+FKN7EpdzeXUzf/pDbVL6VRUUR6+FOWMnKW1i10JVbmYSzO+SVRgaop5pVFvF6s06m5IlAeCi8ETnNaXTsPdnNZ3c1rf3Wm4m9PwcafXRiYNOMxQOpNzTQdpAcZecBOMAjz0xeGBkWOZDjY8y9CGGraskWNYTTgRscT0AQhzlvbo8Gbkrkkg/xYRD/utUrnkFxpKoIueeZPIYrDZTnVVcClaKhmH6tpEaZlTgENrE+HzJFdX6Or9wKoUzBhleUg3SbTbb9jeIPQdMRKSaaudO8GEAggb2PKkMqGjOnXaJecEnl8nMooueDs04C7QwKJB3wsw4DZgSMv7hcVQ13YCgv4sIHjVO2791mTbjE9lGEJyi1MeTsW81kkvhDePEoI9Tplc2wd09yHcuE3r8ueUBOH08Xf62ozqWmij1GQXc+9zkHmWbWNoGScGhKMTUzOME3TjoxNo+r4zNEeeA9FOq/8Ts7TcxtvWvKnyMbcPfyBxm/dk27JXbxNZXcNtx8P6De2TQMHwtyxk2L+qm23f5vZFLXPLXb0mmMj4Fp9XgQ1xlEdIONYqvXgSwqoFlXm9l7NR33Y2lsafeTw6o7bT0TJN1dpSpy0e1Fk8r7OUVVxqIuIsSzLupgn2hAzJoqjGE2XmZmbVrC7hgDJOY9QIgpLM+Uy8AG9XyWrU2ak3w7E8rhVL1VRYL02U2hxbhfLjlMmwqBobhmV2yruTfI803TiB8AQan3RjrOljOFTtoT104M+aNtYq5YrPUMDduKiR671WhG5wtJ4oynFhssSfKJyLA3PSW3QXFx111FFHHT2L/gFBns5AACgAAA==",
	"scm": "local",
	"force": true
}'

Example response
A successful POST returns a success indicator and an import message.

{
    "success": true,
    "message": [
        true,
        "Playbook \"example_playbook\" imported"
    ]
}

For a workflow example using this API, see Use case: Export and import playbook in this article.

/rest/playbook/<id>/export

GET

Exports a playbook.

Example request
Export a playbook.

curl -k -u username:password --output <FILE> https://localhost/rest/playbook/1/export 

Example response
A successful GET returns an x-gzip file to the location set in the --output flag.

For a workflow example using this API, see Use case: Export and import playbook in this article.

/rest/playbook_resource_usage/<playbook_id>

GET

Gets the playbook run statistics for a specific playbook.

Request parameters

Field	Required	Type	Description
block_names	Optional	List	Filters on specified list of block names.
playbook_run_ids	Optional	List	Calculates the playbook run statistics for the specified playbook using only the specified list of playbook run IDs. playbook_run_ids and time_range are mutually exclusive.
time_range	Optional	List with 2 elements: start_time and end_time	Calculates the playbook run statistics for a given playbook only for playbook runs in that time range. Express the start and end of the time_range with only dates (['2022-09-13', '2022-09-14']) or with both dates and times (['2022-09-13T17:00', '2022-09-14T17:00']). time_range and playbook_run_ids are mutually exclusive.

The following requests return similar responses. A sample response is provided at the end of this list.

Example request using playbook ID
Get the playbook run statistics for playbook 27.

curl -k -u username:password https://localhost/rest/playbook_resource_usage/27

Example request using time_range
Get the playbook run statistics for playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022.

curl -k -u username:password https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']

Example request using playbook ID and specific playbook run IDs
Get the playbook run statistics for playbook 27 for playbook runs 40 and 41.

curl -k -u username:password https://localhost/rest/playbook_resource_usage/27?playbook_run_id=[40,41]

Example response using any of the previously mentioned example requests
Depending on the request used, the exact response might differ from this example response.
Each top-level name, like geolocate_ip_1 and on_finish, corresponds to the name of a function in the playbook.

{
    "filter_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 16,
        "avg_db_query_latency": "0:00:00.039000",
        "avg_duration": "0:00:00.025333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "geolocate_ip_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 7,
        "avg_db_query_latency": "0:00:00.018000",
        "avg_duration": "0:00:00.022333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "join_random_get_requests": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 5,
        "avg_db_query_latency": "0:00:00.008500",
        "avg_duration": "0:00:00.121833",
        "times_called": 6,
        "times_succeeded": 6,
        "custom_function_scores": []
    },
    "on_finish": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 1,
        "avg_db_query_latency": "0:00:00.002000",
        "avg_duration": "0:00:00.002000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "on_start": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 8,
        "avg_db_query_latency": "0:00:00.004000",
        "avg_duration": "0:00:00.058000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "random_get_requests": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 14868,
        "avg_http_number_requests": 2,
        "avg_http_latency": "0:00:00.200000",
        "avg_db_number_queries": 3,
        "avg_db_query_latency": "0:00:00.007000",
        "avg_duration": "0:00:00.231000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
    "resource_score_cf_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 3,
        "avg_db_query_latency": "0:00:00.006000",
        "avg_duration": "0:00:00.026000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": [
            {
                "avg_http_bytes_in_requests": 0,
                "avg_http_bytes_in_responses": 0,
                "avg_http_number_requests": 0,
                "avg_http_latency": "0:00:00",
                "avg_db_number_queries": 0,
                "avg_db_query_latency": "0:00:00",
                "avg_duration": "0:00:00.000667",
                "times_called": 3,
                "times_succeeded": 3,
                "custom_function_id": 85,
                "custom_function_name": "resource_score_cf",
                "custom_function_scm": "local"
            }
        ]
    }
}

Example request using playbook ID and specific playbook block names
Get the playbook run statistics for all runs of playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022 for playbook block names on_start and geolocate_ip_1.

curl -k -u username:password https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']&block_names=['on_start', 'geolocate_ip_1']

You can also combine the block names with specific playbook run IDs or with a time_range.

• Example request using playbook ID, specific playbook run IDs, and specific playbook block names
  Get the playbook run statistics for playbook 27, run IDs 40 and 41, for playbook block names on_start and geolocate_ip_1.

  curl -k -u username:password https://localhost/rest/playbook_resource_usage/27?playbook_run_id=[40,41]&block_names=['on_start', 'geolocate_ip_1']
  

• Example request using playbook ID, a specific time_frame, and specific playbook block names
  Get the playbook run statistics for all runs of playbook 27 between 5:00pm on September 13, 2022 and 5:00pm on September 14, 2022 for playbook block names on_start and geolocate_ip_1.

  curl -k -u username:password https://localhost/rest/playbook_resource_usage/27?time_range=['2022-09-13T17:00', '2022-09-14T17:00']&block_names=['on_start', 'geolocate_ip_1']
  

Example response using time_range and specific playbook block names
A successful GET returns all of the playbook run statistics for the specified playbook within the specified date/time span, for the specific block names.

{
    "on_start": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 8,
        "avg_db_query_latency": "0:00:00.004000",
        "avg_duration": "0:00:00.058000",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    },
     "geolocate_ip_1": {
        "avg_http_bytes_in_requests": 0,
        "avg_http_bytes_in_responses": 0,
        "avg_http_number_requests": 0,
        "avg_http_latency": "0:00:00",
        "avg_db_number_queries": 7,
        "avg_db_query_latency": "0:00:00.018000",
        "avg_duration": "0:00:00.022333",
        "times_called": 3,
        "times_succeeded": 3,
        "custom_function_scores": []
    }
}

Notes:

• Custom functions have section titles including _cf and are associated with the blocks that call them. Statistics can show custom code that includes multiple, consecutive phantom.custom_function() calls.
• Statistics are not provided for action/app runs, but are provided for the playbook block that runs the action/apps. Statistics show the time taken for the block to complete, not for the action to complete. Even if the action fails, the statistics might show the block as a success because the block successfully started the action.

Use case: Export and import playbook

This sample workflow shows how to export a playbook from one instance to another or to back up and restore a playbook on the same instance.

You must have the base64 command line function for this workflow.

To export a playbook and then import it, follow these steps. Use the code samples linked in relevant sections of this article.

1. Export the playbook by calling /rest/playbook/<id>/export API.
   If you already have a playbook TGZ file on your system, start with Step 2, using the existing playbook file.
2. In a command line, enter this base64 command: base64 -i <downloaded or existing TGZ file>
3. Copy the output for use in the next step.
4. In the desired location, import the playbook you just downloaded using the /rest/import_playbook API. For the "playbook" field, use the output you copied in Step 3.