Cyware

Cyware Orchestrate Open API enables you to engage with the Cyware Orchestrate services programmatically. You can use it to automate and integrate Cyware Orchestrate with other systems in your environment. The Cyware Orchestrate API reference includes the following public Cyware Orchestrate API endpoints:

- Authentication
- Integrations
- Playbooks
- Custom Templates
- Code Snippets
- Persistent Storage
- Dashboards
- Events
- Tags
- Webhooks
    

With Webhooks, users can create and manage Webhook configurations and tokens. Users will be able to access the Cyware Orchestrate application's features based on the permissions assigned for the user in the Cyware Orchestrate application.

## Supported Version

Cyware Orchestrate 3.5.5.0

Orchestrate API Reference

The Open API credentials can be generated by any Cyware Orchestrate user who has access to the Open APIs module on the Cyware Orchestrate application.

## Generate API credentials

Follow these steps to generate API credentials:

1. Navigate to the Open APIs module and click on Add New.
    
2. Fill the API Title for which Cyware Orchestrate integration is required.
    
3. Select an expiry date for expiry of the API credentials.
    
4. Choose a user. The selected user access permission will be automatically mapped to the API configurations. For example, if the selected user does not have access to the “Apps” module, then the configuration will not be allowed to access actions related to Apps feature. If you want the API configuration to have access to all modules, select “System Default” from the list.
    
5. Click **Create,** and you will be able to download the API Keys. The keys will contain the API URL, Access ID and API key.
    
6. Copy the **Access ID**, **Secret Key** and the **Endpoint URL** displayed to you. You can also download these details as a CSV file. You cannot see this details again, once you close this window. Now configure the keys to the required application.
    

## Mandatory Parameters in Cyware Orchestrate API requests

For any API URL request made to the Cyware Orchestrate application, you have to include three mandatory parameters namely **Access ID**, **Expires**, and **Signature**.

- **Access ID** - Access ID is available to you when you generate API credentials from the Cyware Orchestrate application.
    
- **Expires** - Expires indicates when this request expires. Use the below formula to create the expires value. You can give a margin of 10-20 sec for expiry.
    

> **expires** = current time + 20 sec 
  

- **Signature** - Make a signature using the following formula. You can get the access ID and the secret key when you generate API credentials from the Cyware Orchestrate application.
    1. **StringToSign** = access_id + \\n + expires
        
    2. **Signature** = Base64(HMAC-SHA1(secret_key, UTF-8-Encoding-Of(StringToSign)))

Authentication

Returns the status of the test connectivity.

#### **Request Parameters**

This API endpoint does not require any input parameter.

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| status | String | Indicates the status of the connection  <br>Allowed values:  <br>\- ok  <br>\- invalid credentials |

Test Connectivity

Returns the current version of the product.

#### **Request Parameters**

This API endpoint does not require any input parameter.

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| release_version | String | Returns the current version of the product. |

Product Release Version

Cyware Orchestrate includes support for a rich Appstore library that contains a comprehensive list of apps required to integrate, orchestrate, and respond using different security tools you may have in your organisation.  
The Integrations API enables users to integrate different features of the app such as app actions and app instances into their applications seamlessly.

Integrations

Retrieves all the integration apps and the corresponding details of the apps including the supported actions.

### Request Parameters

This API endpoint does not require any input parameter.

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| unique_id | String | The unique ID which is generated dynamically on creating the app. |
| title | String | Title of the app. |
| description | String | A brief description about the app. |
| app_identifier | String | A human readable app identifier consisting of app title and version. |
| published_by | String | Name of the app publisher. |
| version_slug | String | Version details of the app. |
| actions_count | Integer | Number of actions the app can perform. |
| instances_count | Integer | Number of instances of the app |
| app_slug | String | Resource identifier of the application |
| is_installed | Boolean | The corresponding boolean value if the app is installed or not |
| total_instance_count | Integer | Number of instances of the app |
| app_type | String | The app type to indicate if the app is installed, active or inactive |
| created_at | DateTimeField | The creation time of the app |
| modified_at | DateTimeField | The time at which the app was modified |
| package_hash | String | Hash of the app package |
| publisher_logo_url | String | Logo of the publisher of app |
| is_system | Boolean | Indicates if the app is a System app or a Custom app |
| logo_url | String | URL of the app logo |
| download_counter | Integer | Number of times the app has been downloaded |
| lite_enabled | Boolean | Indicates if the app is supported on the Agent, that is if the app is Agent compatible |
| documentation_url | String | URL to the documentation of the app |
| supported_versions | String | The API version supported |
| tier | Integer | Indicates the tier of the app |
| config_template | Array | Configuration template of the app |
| major_agent_version | String | Major version of the agent, if supported |
| minor_agent_version | String | The minor version of the agent, if supported |
| patch_agent_version | String | The current patch version of the agent, if supported |
| logo | String | URL link to the logo of the app |
| major_version | String | Major version number of the app |
| minor_version | String | Minor version number of the app |
| patch_version | String | Current version of the patch |
| categories | Array | List of categories the app belongs to |
| latest_installed_version | String | Latest installed version of app |
| all_installed_versions | Array | Returns all the installed versions of the app |
| created_by | String | User ID of the person who created the app |
| modified_by | String | User ID of the person who modified the app |
| connector_code | String | The connector code of the app |
| supporting_media | Array | The supporting media files |
| python_class_name | String | The python class name of the app |
| playbook_count_all_versions | Integer | Number of Playbooks using the app in all versions |
| created_by_data | Dictionary | The data such as unique ID and name of the creator |
| modified_by_data | Dictionary | The data such as unique ID and name of the last modifier |
| actions_data | Array | The data related to the actions of the app |
| appinstance_set_data | Array | Details of all the instances of an app |

Get Apps

Retrieves details of a specific app such as the corresponding app instances and app actions based on the passed unique ID of the app.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_unique_id | String | Mandatory | Enter the unique ID of the app to retrieve details about the app.  <br>This value is a dynamically generated unique string ID consisting of alpha numeric characters with sections separated by -.  <br>Example: 6d9c0ec4-bdf4-4334-99a0-83fffb7c3af9  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| unique_id | String | The unique ID which is generated dynamically on creating an app |
| title | String | Title of the app |
| description | String | A brief description about the app |
| app_identifier | String | A human readable app identifier consisting of app title and version |
| published_by | String | Name of the publisher |
| version_slug | String | Version details |
| actions_count | Integer | Number of actions the app can perform |
| instances_count | Integer | Number of instances of the app |
| app_slug | String | Resource identifier of the application |
| is_installed | Boolean | The corresponding boolean value if the app is installed or not |
| total_instance_count | Integer | Number of instances of the app |
| app_type | String | The app type to indicate if the app is installed, active or inactive |
| created_at | DateTimeField | The creation time of the app |
| modified_at | DateTimeField | The time at which the app was modified |
| package_hash | String | Hash of the app package |
| publisher_logo_url | String | Logo of the publisher of app |
| is_system | Boolean | Indicates if the app is a System app or a Custom app |
| logo_url | String | URL of the app logo |
| download_counter | Integer | Number of times the app has been downloaded |
| lite_enabled | Boolean | Indicates if the app is supported on the Agent, that is if the app is Agent compatible |
| documentation_url | String | URL to the documentation of the app |
| supported_versions | String | The api version supported |
| tier | Integer | The tier of the app |
| config_template | Array | The configuration template of the app |
| major_agent_version | String | The major version of the agent, if supported |
| minor_agent_version | String | The minor version of the agent, if supported |
| patch_agent_version | String | The current patch version of the agent, if supported |
| logo | String | URL link to the logo of the app |
| major_version | String | Major version number of the app |
| minor_version | String | Minor version number of the app |
| patch_version | String | Current patch version |
| categories | Array | List of categories the app belongs to |
| latest_installed_version | String | Latest installed version of app |
| all_installed_versions | Array | Returns all the installed versions of the app |
| created_by | String | User ID of the person who created the app |
| modified_by | String | User ID of the person who modified the app |
| connector_code | String | The connector code of the app |
| supporting_media | Array | The supporting media files |
| python_class_name | String | The python class name of the app |
| playbook_count_all_versions | Integer | Number of Playbooks using the app in all versions |
| created_by_data | Dictionary | The data such as unique ID and name of the creator |
| modified_by_data | Dictionary | The data such as unique ID and name of the last modifier |
| actions_data | Array | The data related to the actions of the app |
| appinstance_set_data | Array | Details of all the instances of an app |

Get App Details

Retrieves the list of all the available instances of all the apps.

### Request Parameters

This API endpoint does not require any input parameter.

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| app_unique_id | String | Unique ID of the app |
| unique_id | String | Unique ID of the instance |
| created_at | DateTimeField | Date and time when the instance was created |
| modified_at | DateTimeField | Date and time when the instance was last modified |
| title | String | Title of the instance |
| slug | String | Resource identifier of the instance |
| created_by | String | User ID of the creator of the instance |
| modified_by | String | User ID of the last modifier of the instance |
| description | String | Description of the instance |
| tested_date | DateTimeField | Date and time of the testing |
| connectivity_status | String | The connectivity status, that is SUCCESS or FAIL |
| connectivity_message | String | Message elaborating the connectivity status |
| connector_version | String | The version of the connector |
| configuration | Dictionary | The API key to configure the instance |
| app_title | String | Title of the app of the instance |
| is_default | Boolean | Returns if the instance is a default instance or not |
| on_lite | Boolean | Indicates if the instance of the app is supported on the Agent |
| csol_lite_id | String | The Cyware Agent ID |
| connectivity_detail | String | The details related to the connectivity |
| status_code | String | The status code based on the status of the instance |
| lite_model | String | The model of the agent |
| uploaded_file_data | Array | The uploaded file data |
| expiry_mail_sent | Boolean | Returns if the expiry mail has been sent or not |
| tested_by_data | Dictionary | Unique ID and name of the tester |
| created_by_data | Dictionary | Unique ID and name of the creator of the instance |
| modified_by_data | Dictionary | Unique ID and name of the last modifier of the instance |

Get App Instances

Creates an instance for the app based on the entered unique ID of an app.

### Request Parameters

| Attribute | Attribute Type | **Required** | Description |
| --- | --- | --- | --- |
| app_unique_id | String | Mandatory | Enter the unique ID of the app |
| title | String | Mandatory | Enter the title of the app instance |
| configuration | Dictionary | Optional | Enter the API key to configure the instance |
| is_default | Boolean | Optional | Returns if the instance is a default instance or not |
| expiry_date | DateTimeField | Optional | Enter the expiry date of the app instance |
| description | String | Optional | Enter the description of the app instance |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| app_unique_id | String | The unique ID of the app |
| unique_id | String | The Unique ID of the instance |
| created_at | DateTimeField | The date and time when the instance was created |
| modified_at | DateTimeField | The date and time when the instance was last modified |
| title | String | The title of the instance |
| slug | String | The resource identifier of the instance |
| created_by | String | The user ID of the user that has created the instance |
| modified_by | String | The user ID of the last modifier of the instance |
| expiry_date | DateTimeField | The expiry date of the instance |
| description | String | The description of the instance |
| is_default | Boolean | Returns if the instance is a default instance or not |
| connectivity_status | String | The connectivity status, that is SUCCESS or FAIL |
| connector_version | String | The version of the app |
| configuration | Dictionary | The API key to configure the instance |
| lite_model | String | The model of the agent |
| app_title | String | The title of the app of the instance |
| on_lite | Boolean | Indicates if the instance of the app is Cyware agent compatible or not |
| csol_lite_id | String | The Cyware Agent ID |
| connectivity_message | String | The message elaborating the connectivity status |
| connectivity_detail | String | The details related to the connectivity |
| status_code | String | The status code based on the status of the instance |
| uploaded_file_data | Array | The uploaded file data |
| tested_by | String | The unique ID of the user tested |
| tested_by_data | Dictionary | The unique ID and name of the tester |
| created_by_data | Dictionary | The unique ID and name of the creator of the instance |
| modified_by_data | Dictionary | The unique ID and name of the last modifier of the instance |
| expiry_mail_sent | Boolean | Returns if the instance expiry mail has been sent or not |

Create App Instance

Retrieves all the details specific to the instance ID.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | String | Mandatory | Unique ID of the instance to retrieve details about the app instance.  <br>It is a dynamically generated unique string ID consisting of alpha numeric characters with sections separated by -.  <br>  <br>Example: d6a03423-52fd-479b-a79d-85102e53861f  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| app_unique_id | String | Unique ID of the app |
| unique_id | String | Unique ID of the instance |
| created_at | DateTimeField | Date and time when the instance was created |
| modified_at | DateTimeField | Date and time when the instance was last modified |
| title | String | Title of the instance |
| slug | String | Resource identifier of the instance |
| created_by | String | Unique ID of the creator of the instance |
| modified_by | String | Unique ID of the last modifier of the instance |
| description | String | Description of the instance |
| tested_date | DateTimeField | Date and time of the testing |
| connectivity_status | String | The connectivity status, that is SUCCESS or FAIL |
| connectivity_message | String | Message elaborating the connectivity status |
| connector_version | String | The connector version |
| configuration | Dictionary | The API key to configure the instance |
| app_title | String | Title of the app of the instance |
| is_default | Boolean | Returns if the instance is a default instance or not |
| on_lite | Boolean | Indicates if the instance of the app is supported on the Agent |
| csol_lite_id | String | Cyware agent ID |
| connectivity_detail | String | The details related to the connectivity |
| status_code | String | The status code based on the status of the instance. |
| lite_model | String | The model of the agent |
| uploaded_file_data | Array | The uploaded file data |
| expiry_mail_sent | Boolean | Returns if the expiry mail has been sent or not |
| tested_by_data | Dictionary | Unique ID and name of the tester |
| created_by_data | Dictionary | Unique ID and name of the creator of the instance |
| modified_by_data | Dictionary | Unique ID and name of the last modifier of the instance |

Get App Instance Details

Tests the connectivity of an app instance.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | String | Mandatory | Enter the unique ID of the instance to retrieve details about the app instance.  <br>It is a dynamically generated unique string ID consisting of alpha numeric characters with sections separated by -.  <br>Example: d6a03423-52fd-479b-a79d-85102e53861f  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| connectivity_message | String | The message conveying the connectivity status |
| connectivity_status | String | The connectivity status, that is SUCCESS or FAIL |
| connectivity_detail | String | The details related to the connectivity |
| tested_by | String | The unique ID of the user that has tested the app instance |
| tested_date | DateTimeField | The date and time when the instance was tested |
| title | String | The title of the app instance |
| status_code | String | The status code based on the status of the instance. |
| is_lite | Boolean | Indicates if the app instance is agent compatible or not |
| unique_id | String | The unique ID of the app instance |
| tested_by_data | Dictionary | The unique ID and name of the user that has tested the instance |

Test App Instance Connectivity

Retrieves the list of all the available actions of all the apps.

### Request Parameters

This API endpoint does not require any input parameter.

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| title | String | Title of the app action |
| description | String | Description of the action |
| action_identifier | String | Unique identifier of the action |
| app_identifier | String | Unique identifier of the app to which the action belongs |
| return_values | Object | The different return values of the action |
| title | String | Title of the return value |
| description | String | Description of the return value |
| data_source | String | Source of the return values |
| accepted_params | Object | The details of the accepted parameters |
| unique_id | String | Unique ID of the action |
| app_unique_id | String | Unique ID of the app with which the action is associated |
| created_by | String | Unique ID of the creator of the action |
| modified_by | String | Unique ID of the last modifier of the action |
| created_at | DateTimeField | Date and time when the action was created |
| modified_at | DateTimeField | Date and time when the action was last modified |
| app_slug | String | Resource identifier of the associated app |
| connector_version | String | The connector version |
| app_title | String | Title of the app |
| system_app | Boolean | Returns true if the app is a Cyware app or false if the app is a custom app |
| created_by_data | Dictionary | Unique ID and name of the creator of the action |
| modified_by_data | Dictionary | Unique ID and name of the last modifier of the action |

Get App Actions

Retrieves the details of a unique action ID provided.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| action_id | String | Mandatory | Unique ID of the action to retrieve the action details.  <br>It is a dynamically generated unique string ID consisting of alpha numeric characters with sections separated by -.  <br>Example: 52091b28-5daa-42f3-9eb9-926994a91ca5  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| title | String | Title of the app action |
| description | String | Description of the action |
| action_identifier | String | Unique identifier of the action |
| app_identifier | String | Unique identifier of the app to which the action belongs to |
| return_values | Object | Different return values of the action |
| title | String | Title of the return value |
| description | String | Description of the return value |
| data_source | String | Source of the return values |
| accepted_params | Object | The details of the accepted parameters |
| unique_id | String | Unique ID of the action |
| app_unique_id | String | Unique ID of the app with which the action is associated |
| created_by | String | Unique ID of the creator of the action |
| modified_by | String | Unique ID of the last modifier of the action |
| created_at | DateTimeField | Date and time when the action was created |
| modified_at | DateTimeField | Date and time when the action was last modified |
| app_slug | String | Resource identifier of the associated app |
| connector_version | String | The connector version |
| app_title | String | Title of the app |
| system_app | Boolean | Returns true if the app is a Cyware app or false if the app is a custom app |
| created_by_data | Dictionary | Unique ID and name of the creator of the action |
| modified_by_data | Dictionary | Unique ID and name of the last modifier of the action |

Get Action Details

Execute an action of the app by passing the required parameters in the body.

### Body/Payload Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_identifier | String | Mandatory | Identifier of the App |
| action_identifier  <br> | String | Mandatory | Identifier of the Action |
| action_params | Dictionary | Mandatory | Parameters required for action execution |
| app_instance_slug | String | Mandatory | Resource identifier of the app instance |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| filescan_id | String | The file scan ID, if a file is passed for scanning |
| permalink | String | URL link to the source execution |
| resource | String | Resource passed to the action |
| response_code | Integer | The response code |
| scan_date | DateTimeField | Date and time of the scan |
| scan_id | String | The scan ID |
| scans | Dictionary | Details of all the scans performed with their result |
| total | Integer | Total number of scans |
| url | String | The URL passed |
| verbose_msg | String | Verbose message of the status of an action |
| status_code | Integer | The status code of the action execution. |
| execution_status | String | The status of the action execution. The possible values are SUCCESS, ERROR, WAITING, or UNTESTED |

Execute Action

Download a zip file of the app by passing the app identifier. The received response can simply be downloaded and saved as a zip file.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_identifier | String | Mandatory | The app identifier can be passed as a URL slug to get a response which can be saved as a file to download the zip of the app.  <br>  <br>Example: abuse_ipdb  <br> |

### Response Parameters

This API endpoint has no response parameters. However, the result of this API can be saved as a file.

Download App Package

Installs custom apps on your Orchestrate instance.

**Request Parameters**

This API endpoint accepts the request payload as form data. For more information, see Body (form-data).

**Response Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| unique_id | String | Returns the unique ID of the app. |
| title | String | Returns the title of the app. |
| description | String | Returns the description of the app. |
| app_identifier | String | Returns the human-readable app identifier. |
| published_by | String | Returns the name of the publisher. |
| published_date | Timestamp | Returns the published date of the app. |
| connector_version | String | Returns the connector version of the app. |
| actions_count | Integer | Returns the number of actions available in the app. |
| lite_enabled | Boolean | Returns true if the app is agent compatible, else false. |
| supported_versions | Array | Returns the supported API versions of the app. |
| tier | Integer | (Deprecated) Returns the corresponding integer value of the app publisher. |
| app_slug | String | Returns the slug name of the app. |
| logo | String | Returns the link to the app logo. |
| is_installed | Boolean | Returns true if the app is installed, else false. |
| major_version | String | Returns the major version of the app. |
| categories | Array | Returns the list of app categories. |
| latest_installed_version | String | Returns the latest installed version of the app. |
| all_installed_version | Array | Returns the details of all versions of the app that are installed. |
| created_by | String | Returns the unique ID of the user who created the app. |
| modified_by | String | Returns the unique ID of the user who last modified the app. |
| app_type | String | Returns the type of app. |
| connector code | String | Returns the connetor code of the app. |
| created_at | Timestamp | Returns the timestamp of the app creation. |
| modified_at | Timestamp | Returns the timestamp of the app modification. |
| package_hash | String | Returns the encoded hash of the app package. |
| python_class_name | String | Returns the class name of the app. |
| supported_products | Array | Returns the array of supported products such as CO. |
| version_status | Array | Returns the array of version statuses. |
| is_system | Boolean | Returns true if the app is system app, else false. |
| download_counter | Integer | Returns the number of times the app is downloaded. |
| instances_count | Integer | Returns the number of instances of the app. |
| documentation_url | String | Returns the documenation link of the app. |
| config_template | Array | Returns the configuration template of the app. |
| major_agent_version | String | Returns the major version of the agent if the app is agent compatible. |
| minor_agent_version | String | Returns the minor version of the agent if the app is agent compatible. |
| patch_agent_version | String | Returns the current patch version of the agent if the app is agent compatible. |
| minor_version | String | Returns the minor version number of the app. |
| patch_version | String | Returns the patch version number of the app |
| total_instance_count | Integer | Returns the total number of instances of the app. |
| supporting_media | Array | (Deprecated)Returns the array of supported media. |
| publisher_logo_url | Array | Returns the link to the logo which is published by the publisher. |
| is_active | Boolean | Returns true if the status of app is active, else false. |

Install Custom Apps

Playbooks are a set of actions that are designed and configured as a sequence, to perform a multitude of security automation and orchestration tasks in the Incident response process within an organization. You can schedule Playbooks to run using input from application sources or are automatically triggered using one or more events. Using Playbooks, a security team can perform various tasks such as analyzing vulnerabilities, Indicators of Compromise (IOC’s), searching for suspicious logs, and many more. Playbooks also help in effectively connecting the different security tools to create an effective and integrated security environment.

Playbooks

Retrieves a list of user created Playbooks.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| page | Integer | Optional | Enter the page number to go to the mentioned page. |
| page_size | Integer | Optional | Enter the number of items to be returned on the page. |
| scheduled | Boolean | Optional | Choose if the Playbook is scheduled to run or not. |
| labels | String | Optional | Enter the label name. |
| tags | String | Optional | Enter the tag name. |
| apps | String | Optional | Enter the app identifier value. |
| actions | String | Optional | Enter the app action identifier. |
| is_active | Boolean | Optional | Choose if the status of the Playbook is active or not. |
| modified | String | Optional | Enter the last modified time of the Playbook.  <br>Example:  <br>last_month / last_year / last_week |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | Count of the total Playbook run logs |
| results | List of JSON | List of Playbooks as JSON objects |
| title | String | Title of the Playbook |
| readable_id | String | The Playbook readable ID |
| status | String | The status of the Playbook  <br>Allowed values:  <br>\- active  <br>\- inactive |
| unique_id | String | The unique ID which is generated dynamically on Playbook creation |
| playbook_last_run | Date Time Field | Last run time of the Playbook |
| sub_playbook | Integer | The count of the number of Sub Playbooks |
| apps_count | Integer | The count of the number of apps used in the Playbook |
| app_action | JSON | The app name as key for the JSON containing list of actions along with logo |
| description | String | Description of the Playbook |
| categories | List | The list of categories |
| tags | List | The list of tags |
| tags_data | List | List of JSON showing tag data |
| type | String | Type of the Playbook (UI/SCRIPT) |
| labels | List | The list of labels |
| output_params | JSON | The output parameters as key- value pairs as a JSON list |

Get Playbooks

Get Playbook Details

Retrieves the Playbook result based on the unique ID of the Playbook result. If no payload is passed, it simply returns the complete list of Playbook Run Logs.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| page | Integer | Optional | Enter the page number to go to the mentioned page. |
| page_size | Integer | Optional | Enter the number of items to be returned per page. |
| playbook | String | Optional | Enter the unique ID of the Playbook.  <br>Example :  <br>903b87b71-4120-9c63-04b4df60ab4b |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | Count of the total Playbook run logs |
| results | List of JSON | The list of Playbook run logs |
| unique_id | String | The unique ID which is generated dynamically on Playbook run |
| created | Date Time Field | The Playbook created data and time stamp |
| modified | Date Time Field | The Playbook modified data and time stamp |
| status | String | Playbook run status |
| source | String | The source that initiated the Playbook run  <br>Example: User, Playbook |
| run_details | String | Details of who executed the Playbook |
| cron_expression | String | The cron string used for scheduling |
| playbook_data | JSON | Details of the Playbook |
| title | String | Title of the Playbook |
| unique_id | String | The unique ID which is generated dynamically on Playbook creation |
| type | String | Type of the Playbook (UI/SCRIPT) |
| readable_id | String | The Playbook readable ID |
| labels | List | The list of labels |
| categories | List | The list of categories |
| status | String | The status of the Playbook  <br>Allowed values:  <br>\- active  <br>\- inactive |
| playbook_last_run | Date Time Field | Last run time of the Playbook |
| sub_playbook | Integer | The count of the number of Sub Playbooks |
| apps_count | Integer | The count of the number of apps used in the Playbook |
| app_action | JSON | The app name as key for the JSON containing list of actions along with logo |
| description | String | Description of the Playbook |
| output_params | JSON | The output parameters as key- value pairs as a JSON list |
| event_data | JSON | Details of the triggered event |
| ran_by_data | JSON | Complete details of the user who executed the Playbook |
| source_playbook_result_data | JSON | The associated Playbook result data |
| sub_playbooks | Integer | The count of the number of Sub Playbooks |
| playbook_summary | List of JSON | List of JSON containing app name and its actions |
| execution_time | Time in seconds | The execution time in seconds |
| readable_id | String | The Run log readable ID |

Get Playbook Result

Retrieves the list of Playbook run logs along with the Playbook data.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| page | Integer | Optional | Enter the page number to go to. |
| page_size | Integer | Optional | Enter the number of items to be returned per page. |
| q | String | Optional | Enter playbook title, playbook ID, event title or run log ID to retrieve the associated run logs. |
| playbook_status | String | Optional | Enter the status of the Playbook.  <br>Allowed values:  <br>\- active  <br>\- inactive |
| status | String | Optional | Enter the Playbook run status.  <br>Allowed values :  <br>\- SUCCESS  <br>\- PARTIAL_SUCCESS  <br>\- IN_PROGRESS  <br>\- ERROR  <br>\- SYSTEM_ERROR  <br>\- ON_HOLD  <br>\- IN_QUEUE  <br>\- WAITING  <br>\- TERMINATED |
| source_playbook_result__is_null | Boolean | Optional | Choose to display the results of the associated Playbook.  <br>Allowed values:  <br>\- True  <br>\- False |
| apps_list | String | Optional | Enter the unique ID of the app. |
| playbook | String | Optional | Enter the unique ID of the Playbook.  <br>Example :  <br>903b87b71-4120-9c63-04b4df60ab4b |
| actions_list | String | Optional | Enter the unique ID of the app action. |
| ran_by | String | Optional | Enter the unique ID of the user. |
| scheduled | Boolean | Optional | Enter if the Playbook is scheduled or not.  <br>Allowed values:  <br>\- True  <br>\- False |
| run_at | String | Optional | Enter the Playbook execution date.  <br>Example:  <br>last_month / last_year / last_week |
| run_at__lte | Integer | Optional | Enter the custom date which is less than or equal to the current time in unix time stamp.  <br>Example:  <br>1642530599 |
| run_at__gte | Integer | Optional | Enter the custom date greater than or equal to the current time in unix time stamp.  <br>Example:  <br>1642530599 |
| ordering | String | Optional | Enter the sort list based on different fields.  <br>Example:  <br>last modified(-modified),  <br>execution time(-execution_time),  <br>last run(-created) |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | Count of the total Playbook run logs |
| results | List of JSON | List of Playbook run logs |
| unique_id | String | The unique ID which is generated dynamically on Playbook execution |
| created | Date Time Field | The Playbook created data and time stamp |
| modified | Date Time Field | The Playbook modified data and time stamp |
| status | String | Playbook run status |
| source | String | The source that initiated the Playbook run  <br>Example: User, Playbook |
| run_details | String | Details of who executed the Playbook |
| cron_expression | String | The cron string used for scheduling |
| playbook_data | JSON | Details of the Playbook |
| title | String | Title of the Playbook |
| unique_id | String | The unique ID which is generated dynamically on Playbook creation |
| type | String | Type of the Playbook (UI/SCRIPT) |
| readable_id | String | Playbook readable ID |
| labels | List | The list of labels |
| categories | List | The list of categories |
| status | String | The status of the Playbook  <br>Allowed values:  <br>\- active  <br>\- inactive |
| playbook_last_run | Date Time Field | Playbook last run time |
| sub_playbook | Integer | The count of the number of Sub Playbooks |
| apps_count | Integer | Count of the number of apps used in the Playbook |
| app_action | JSON | The app name as key for the JSON containing list of actions along with logo |
| description | String | Description of the Playbook |
| output_params | JSON | The output parameters as key- value pairs as a JSON list |
| event_data | JSON | Details of the triggered event |
| ran_by_data | JSON | Details of the user |
| source_playbook_result_data | JSON | The source Playbook result data |
| sub_playbooks | Integer | The Sub Playbooks count |
| playbook_summary | List of JSON | List of JSON containing app name and its actions |
| execution_time | Time in seconds | The execution time in seconds |
| readable_id | String | The Run log readable ID |

Get Playbook Run Logs

Retrieves the details of the Playbook execution results along with the node data and results.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| playbook_result_unique_id | String | Mandatory | Unique ID generated during the playbook run |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| status | String | The Playbook run status |
| unique_id | String | The unique ID which is generated dynamically on Playbook execution |
| created | Date Time Field | The Playbook created data and time stamp |
| modified | Date Time Field | The Playbook modified data and time stamp |
| event_data | JSON | Details of the triggered event |
| error | JSON | The error results |
| ran_by_data | JSON | Complete details of who executed the Playbook |
| source_playbook_result_data | JSON | The associated Playbook result data |
| run_details | String | Details such as full name of who ran the Playbook |
| source | String | The source that initiated the Playbook run  <br>Example: User, Playbook |
| cron_expression | String | The cron string used for scheduling |
| sub_playbook | Integer | Count of the number of Sub Playbooks |
| auto_terminate_time | Date Time Field | Timestamp of when the Playbook was terminated |
| readable_id | String | The run log readable ID |
| splitted_columns | Array of Strings | Displays the following values of a Playbook result and node result that are more than 4 MB  <br>\- Input Values (initial_params)  <br>\- Output Values (result) |
| initial_params | JSON | The initial parameter key-value pairs as JSON |
| playbook_data | JSON | Details of the Playbook |
| title | String | Title of the Playbook |
| readable_id | String | The Playbook readable ID |
| status | String | The status of the Playbook  <br>Allowed values:  <br>\- active  <br>\- inactive |
| unique_id | String | The unique ID which is generated dynamically on Playbook creation |
| playbook_last_run | Date Time Field | Last run time of the Playbook |
| sub_playbook | Integer | The count of the number of Sub Playbooks |
| apps_count | Integer | The count of the number of apps used in the Playbook |
| app_action | JSON | The app name as key for the JSON containing list of actions along with logo |
| description | String | Description of the Playbook |
| categories | List | The list of categories |
| type | String | Type of the Playbook (UI/SCRIPT) |
| labels | List | The list of labels |
| output_params | JSON | The output parameters as key- value pairs as a JSON list |
| node_results | List of JSON | List of nodes as per the execution order of each node |

Get Playbook Run Log Details

Get Node Result Details

Executes a Playbook by passing a unique ID of the Playbook through the body.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| playbook_unique_id | String | Mandatory | Unique ID of the playbook |
| data | JSON | Optional | Manual data to run the Playbook |
| runLog | String | Optional | Unique ID of run log to fetch the run log data for Playbook execution |
| event | String | Optional | Unique ID of event to fetch the event data for Playbook execution |
| email_notification_details | JSON | Optional | Json containing from_email, user_emails and redirect_url to send notification for non orchestrate platform users |
| user_emails | LIST | Mandatory | List of email ids for sending the playbook paused notification for external platform users |
| from_email | String | Optional | By default from_email will be picked from the smtp configuration else the mail will be sent from this sender |
| redirect_url | String | Optional | Redirect URL link for the response option in email. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| playbook_result_unique_id | JSON | The unique ID generated for the Playbook result |

Run Playbook

Retrieves the export of the Playbooks in JSON format.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| playbook_unique_id | String | Mandatory | Enter the unique ID generated for the Playbook. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| title | String | Title of the Playbook |
| start_node | String | Internal ID of the start node for the Playbook |
| nodes | JSON | The node details as key-value pairs, where Internal ID indicates the key, and node details indicate the value |
| type | String | Type of the node |
| title | String | Title of the node |
| description | String | Description of the node |
| actions | JSON | Returns details of the action such as action identifier, input data, action type, app instances, and action data |
| action | String | Action identifier used in this action node |
| parameter_data_source | JSON | Input data for the action |
| action_type | String | Type of the action node |
| app_instances | List | List of the selected instances |
| action_data | JSON | Details containing the app, version of the app, and the selected action |
| output_params | JSON | The output parameters for the node, if configured |
| save_customized_result | Boolean | Returns true to save the customized result of the node, else returns false |
| save_result | Boolean | Returns true to save the output of the node, else returns false |
| run_async | Boolean | Returns true to run the node synchronously, else returns false |
| extra_params | JSON | Details of the position and node validation |
| edges | List | List containing the source and destination nodes of the edge |
| type | String | Type of the Playbook (UI/SCRIPT) |
| labels | List | The list of labels |
| tags | List | The list of tags |
| status | String | The Playbook run status |
| output_params | JSON | The output parameters as key-value pairs as a JSON list |
| is_runnable | Boolean | Returns true if it is a Cyware Playbook, and returns false if it is a user-created Playbook |
| description | String | Description of the Playbook |
| cron_expression | String | The cron string used for scheduling |
| schedule_info | JSON | Details of the Playbook schedule |

Export Playbook

Downloads the input data of the playbook. This endpoint is used to download large files.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| field | String | Mandatory | Column name for which file will be generated. The column name can be found in the splitted_columns field. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| file_url | String | The URL of the file to download. |

Download Playbook Result

Downloads the input data or output data of a playbook node. This endpoint is used to download large files.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| field | String | Mandatory | Column name for which file will be generated. The column name can be found in the splitted_columns field. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| file_url | String | Pre-signed url of file to download |

Download Node Result

Terminate playbook runs in bulk. You can terminate a maximum of 100 playbook runs at a time with the run status in progress, in-queue, waiting, or on hold.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| playbook_result_unique_ids | List | Mandatory | List of playbook run unique IDs |

#### Response Parameters

There are no response parameters. If the task results as a success, the status of the response will be 200.

Bulk Terminate Playbook Runs

Email templates are pre-defined email layouts in rich text format that includes an email header and email body. Analysts can reuse email templates with predefined content and customize them, reducing the time and effort required to compose emails from scratch.

Custom Email Templates

Returns the list of custom email templates.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| q | String | Optional | Search email templates using the title. |
| page | Integer | Optional | Enter the page number to navigate to the required page. |
| page_size | Integer | Optional | Enter the number of items to be displayed per page. |
| ordering | String | Optional | Enter the ordering to sort the custom templates.  <br>Example:  <br>created, modified |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and the previous URL of the email templates in the list. |
| count | Integer | The total count of the custom email templates. |
| results | List of JSON | The list of the custom templates. |
| created | Date Time Field | The creation date of the custom email template. |
| unique_id | String | The unique ID of the custom email template. |
| title | String | The title of the custom email template. |
| description | String | The description of the custom email template. |
| created_by_data | JSON | Provides the details of the user who has created the custom email template. This contains first_name, last_name, full_name and unique_id of the user. |

Get Custom Email Template List

Retrieves details of a custom email template based on the provided unique ID of the custom email template.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| unique_id | String | Mandatory | The unique ID of the custom template. You can retrieve the unique ID of the custom email template using the "Get Custom Template List" endpoint. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| created | Date Time Field | The creation date of the custom template. |
| unique_id | String | The unique ID of the custom email template. |
| title | String | The title of the custom template. |
| description | String | The description of the custom email template. |
| created_by_data | JSON | Provides the details of the user who has created the custom template. This contains first_name, last_name, full_name and unique_id of the user. |
| template_body | String | HTML template of the email content in string format. |

Get Custom Email Template Details

Code snippets are reusable blocks of code that you can create in Orchestrate. They can include functions, loops, or conditional statements. You can use them to create custom nodes such as custom actions and custom conditions in playbooks.

Code Snippets

Returns the list of code snippets

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| q | String | Optional | Search a code snippet using the title. |
| page | Integer | Optional | Enter the page number to navigate to the required page. |
| page_size | Integer | Optional | Enter the number of items to be displayed per page. |
| ordering | String | Optional | Enter the ordering to sort the code snippets.  <br>Example:  <br>created, modified |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and the previous URL of the code snippets in the list. |
| count | Integer | The total count of the code snippets. |
| results | List of JSON | The list of the code snippets. |
| created | Date Time Field | The creation date and time of the code snippet. |
| unique_id | String | The unique ID of the code snippet. |
| title | String | The title of the code snippet. |
| description | String | The description of the code snippet. |
| created_by_data | JSON | Information of the user who has created the code snippet. This contains first_name, last_name, full_name, and unique_id of the user. |

Get Code Snippets List

Retrieves details of a specific code snippet based on the passed unique ID of the code snippet.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| unique_id | String | Mandatory | The unique ID of the code snippet. You can use the "Get Code Snippet List" endpoint to retrieve the unique ID of the code snippet. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and the previous URL of the code snippets in the list. |
| count | Integer | The total count of the code snippets. |
| results | List of JSON | The list of the code snippets |
| created | Date Time Field | The creation date and time of the code snippet. |
| unique_id | String | The unique ID of the code snippet. |
| title | String | The title of the code snippet. |
| description | String | The description of the code snippet. |
| created_by_data | JSON | Information of the user created the code snippet. This contains first_name, last_name, full_name and unique_id of the user. |
| code | String | Python Code in string format. |

Get Code Snippet Details

Persistent List is a collection of key-value pairs that analysts can use to store data, and then lookup from this data to use in a Playbook or Playbook node. Data stored in a persistent list can survive system reboots, system crashes, and more.

Persistent List

Retrieves a list of Persistent Lists.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| page | Integer | Optional | Enter the page number to navigate to the required page. |
| page_size | Integer | Optional | Enter the number of Persistent Lists to be displayed per page. |
| q | String | Optional | Enter the query string to retrieve the Persistent Lists. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | Count of the total Persistent Lists |
| results | JSON | The list of Persistent Lists |
| title | String | The title of Persistent List |
| unique_id | String | The unique ID of the Persistent List |
| readable_id | String | The readable ID of the Persistent List |
| slug | String | A short unique label of a Persistent List |
| description | String | The description of the Persistent List |
| created | Date Time Field | The created date and time of a Persistent List |
| modified | Date Time Field | The modified date and time of a Persistent List |
| created_by_data | JSON | The details of a user that has created a Persistent List such as first_name, last_name, full_name, unique_id |
| modified_by_data | JSON | The details of a user or a Playbook that has modified a Persistent List |
| modified_by | String | The details of what has modified a Persistent List, a user or a Playbook execution |
| playbook_data | JSON | The details of a Playbook that has modified a Persistent List |
| first_name, last_name, full_name | String | The details of a user that has modified a Persistent List. These details are displayed when the modified_by_data has user data |
| display_name | String | The display name of a user or Playbook that has modified a Persistent List |

Get Persistent Lists

Retrieves the details of a Persistent List based on the unique ID.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| persistent_storage_unique_id | String | Mandatory | Enter the unique ID of a Persistent List. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| title | String | The title of the Persistent List |
| unique_id | String | The unique ID of a Persistent List |
| readable_id | String | The readable ID of a Persistent List |
| slug | String | A short unique label of a Persistent List |
| description | String | The description of a Persistent List |
| created | Date Time Field | The created date and time of a Persistent List |
| modified | Date Time Field | The modified date and time of a Persistent List |
| created_by_data | JSON | The details of a user containing first_name, last_name, full_name, unique_id |
| modified_by_data | JSON | The details of who has modified a Persistent List |
| modified_by | String | The details of what has modified a Persistent List, a user or a Playbook execution |
| playbook_data | JSON | The overview details of a Playbook, if Persistent List is modified by a Playbook |
| first_name, last_name, full_name | String | The details of a user, if Persistent List is modified by a user |
| display_name | String | The display name of a user or a Playbook that has modified a Persistent List |
| storage_manager_data | JSON | The object containing the unique_id and data |
| unique_id | String | The unique ID of a Persistent List |
| data | JSON | The data stored in a Persistent List |

Get Persistent List Details

Creates a Persistent List.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| title | String | Optional | Enter the title of a Persistent List. |
| storage_manager_data | JSON | Optional | Stores the data object which contains the key-value pair to be passed to the Persistent List. |
| data | JSON | Optional | JSON object which contains the key-value pair to be passed to the Persistent List |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| title | String | The title of a Persistent List |
| unique_id | String | The unique ID of a Persistent List |
| readable_id | String | The readable ID of a Persistent List |
| slug | String | A short unique label of a Persistent List |
| description | String | The description of a Persistent List |
| created | Date Time Field | The created date and time of a Persistent List |
| modified | Date Time Field | The modified date and time of a Persistent List |
| created_by_data | JSON | The overview details of a user containing the first_name, last_name, full_name, unique_id |
| modified_by_data | JSON | The details of a user or a Playbook that has modified a Persistent List. I |
| modified_by | String | The details of what has modified a Persistent List, a user or a Playbook execution. It will be a user during creation. |
| first_name, last_name, full_name | String | The details of a user that has modified a Persistent List |
| display_name | String | The display name of a user or a Playbook that has modified a Persistent List |
| storage_manager_data | JSON | JSON object contains the unique_id and data |
| unique_id | String | The unique ID of a Persistent List |
| data | JSON | JSON object of data stored |

Create a Persistent List

Updates the details of a Persistent List.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| persistent_storage_unique_id | String | Mandatory | The unique ID of a Persistent List. |
| title | String | Optional | The title of a Persistent List |
| storage_manager_data | JSON | Optional | JSON object contains data |
| data | JSON | Optional | JSON object contains data to be stored |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| title | String | The updated title of a Persistent List |
| unique_id | String | The unique ID of a Persistent List |
| readable_id | String | The readable ID of a Persistent list |
| slug | String | A short unique label of a Persistent List |
| description | String | The description of a Persistent List |
| created | Date Time Field | The created date and time of a Persistent List |
| modified | Date Time Field | The modified date and time of a Persistent List |
| created_by_data | JSON | The overview details of a user containing first_name, last_name, full_name, unique_id that has created a Persistent List |
| modified_by_data | JSON | The details of a user or a Playbook that has modified a Persistent List |
| modified_by | String | The details of what has modified a Persistent List, a user or a Playbook execution |
| playbook_data | JSON | The overview details of a Playbook, if Persistent List is modified by a Playbook |
| first_name, last_name, full_name | String | The details of a user that has modified a Persistent List. These details are displayed when the modified_by_data has user data  <br> |
| display_name | String | The display name of a user or a Playbook that has modified a Persistent List |
| storage_manager_data | JSON | JSON object contains the unique_id and data -- |
| unique_id | String | The unique ID of a Persistent List |
| data | JSON | Updated JSON object of data stored |

Update a Persistent List

Deletes Persistent Lists based on the unique ID. A Persistent List can be deleted only if it is not used in a Playbook. On successful delete, it returns the status code as 200 else it returns the result with non_field_error object

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| persistent_storage_unique_id | String | Mandatory | Enter the unique ID of the Persistent List. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| result | JSON | An object containing reason to unable to delete a Persistent List |
| non_field_error | String | The reason to unable to delete a Persistent List. |
| status_code | Integer | A status code for the failure |

Delete Persistent Storage Object

Provides overview details of the Persistent Lists based on the Persistent List slug or title.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| page | Integer | Optional | Enter the page number to navigate to the required page. |
| page_size | Integer | Optional | Enter the number of Persistent Lists to be displayed per page. |
| q | String | Optional | Enter the query string to retrieve the Persistent Lists based on the slug or title. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | The total count of the Persistent Lists |
| results | List of JSON | The list of Persistent Lists |
| title | String | The title of a Persistent List |
| unique_id | String | The unique ID of the Persistent List. |
| slug | String | A short unique label of a Persistent List. |

Get Persistent List Slugs

Provides overview details of the Playbooks containing the specified Persistent List based on the unique ID.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| persistent_storage_unique_id | String | Mandatory | The unique ID of a Persistent List. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and previous URL |
| count | Integer | The total count of Playbooks containing the Persistent List |
| results | List of JSON | The list of Playbooks |
| title | String | The title of the Playbook |
| unique_id | String | The unique ID of the Playbook |
| readable_id | String | The readable ID of the Playbook |
| description | String | The description of the Playbook |
| schedule_info | String | The scheduled information of the Playbook |

Get Playbooks Associated with Persistent List

Provides the count of the Playbooks containing the specified Persistent List based on the entered unique ID.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| persistent_storage_unique_id | String | Mandatory | The unique ID of a Persistent List. |

#### Response Parameters

| **Attribute** | **Attribute Type** | **Description** |
| --- | --- | --- |
| result | JSON | Contains count key |
| count | Integer | The total count of Playbooks |

Get Playbooks Count Associated with Persistent List

The Analytics Open API enables analysts to gauge the performances of Playbooks, Apps, Instances and Actions. The Analysts can get analytics for a particular timeframe by passing the start and end time as a unix timestamp.

Analytics

Retrieves the number of times a Playbook has ran for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value as playbook_run_count to get the Playbook run count value.  <br>Example: categorize_by=playbook_run_count  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Represents the date in "Month DD, YYYY" format |
| value | Integer | Indicates the number of Playbooks run on the day |

Get Playbook Run Count

Returns the most active Playbook based on the number of times a Playbook has run for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value as most_active_playbooks to retrieve the most active Playbook.  <br>Example: categorize_by=most_active_playbooks |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the Playbook |
| value | Integer | Indicates the number of times the Playbook was run |

Get Most Active Playbooks

Returns the average execution time of the Playbook for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to playbook_avg_execution_time, to get the average execution time of the Playbook.  <br>Example: categorize_by=playbook_avg_execution_time  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the Playbook |
| value | Integer | Indicates the average execution time of the Playbook |

Get Playbook Average Execution Time

Returns the most used instances for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value as most_used_instances to get the most used instances.  <br>Example: categorize_by=most_used_instances  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the instance |
| value | Integer | Indicates the number of times the instance was used |

Get Most Used Instance

Returns the most used apps for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to most_used_apps to get the most used apps.  <br>Example: categorize_by=most_used_apps  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the app |
| value | Integer | Indicates the number of times the app was used |

Get Most Used Apps

Returns the most used actions for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to most_used_aactions to get the most used actions.  <br>Example: categorize_by=most_used_actions  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the action |
| value | Integer | Indicates the number of times the action was used |

Get Most Used Actions

Returns the most active actions for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to most_active_actions to get the most executed actions in a Playbook.  <br>Example: categorize_by=most_active_actions  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the action |
| value | Integer | Indicates the number of times an action as executed in a Playbook |

Get Most Active Actions

Returns the most utilized apps in Playbooks for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to most_active_actions to get the most utilized apps in Playbooks.  <br>Example: categorize_by=most_active_apps  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the action |
| value | Integer | Indicates the number of times an app has been utilized in Playbooks |

Get Most Active Apps

Returns the most utilized instances in Playbooks for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to most_active_instances, to get the most utilized instances in Playbooks.  <br>Example: categorize_by=most_active_intsances  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the action |
| value | Integer | Indicates the number of times an instance has been utilized in Playbooks |

Get Most Active Instances

Returns the number of automatic or manual events created in Cyware Orchestrate for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to event_count to get the the number of automatic or manual events.  <br>Example: categorize_by=event_count |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Represents the date in "Month DD, YYYY" format |
| value | Integer | Indicates the number of events created on the day |

Get Event Count

Returns the incoming source event count from the configured event source app for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to incoming_source_of_events to get the incoming source event values.  <br>Example: categorize_by=incoming_source_of_events  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Title of the event source app |
| value | Integer | Indicates the number of incoming event source of the app |

Get Incoming Source Events

Returns the number of unprocessed events for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to unprocessed_events to get the number of unprocessed events.  <br>Example: categorize_by=unprocessed_events  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Represents the percentage of unprocessed events |
| total_value | Integer | Indicates the total number of events |
| value | Integer | Indicates the number of unprocessed events |

Get Unprocessed Events

Returns the number of events that caused an error or system error during the Playbook execution for the non purged data.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| categorize_by | String | Mandatory | Set this value to event_count to get events with an error value.  <br>Example: categorize_by=event_count  <br> |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| data | Object | Contains the Analytics data |
| label | String | Represents the events causing an error |
| total_value | Integer | Indicates the total number of events |
| value | Integer | Indicates the number of events that caused error |

Get Events With Error

A Source Event is a trigger for a Playbook to come into action and run. Examples of Source Events include an Incident being created in Cyware Fusion and Threat Response (CFTR), an alert being generated in Splunk, etc. A Source Event that is triggered in Cyware Orchestrate brings along with its Source Event Data from the integrated tool like Splunk. The data is sent in the JSON format via Cyware Orchestrate REST API.

Users can create an Event manually and run Playbook by tagging Labels to the Event and the required Playbook. A Playbook scheduled using a Cron Expression or run as a part of another manually created Event may also trigger multiple Events from Sources based on the Playbook workflow Actions. Source Events created from the Source Events module and various Source applications can be viewed in the Source Events module.

### Authorization

These API's requires Open API Access ID and Secret Key generated.

Events

Creates an event by passing the app identifier, action identifier and data through the body.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| title | String | Mandatory | Enter the title of the event. |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs.  <br>To retrieve app_identifier, sign in to Orchestrate and go to **Configure Triggers**. The app_identifier is the value displayed in the **Source App** column. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action.  <br>To retrieve the action_identifier, sign in to Orchestrate and go to **Configure Triggers**. The action_identifier is the value displayed in the **Event Type** column. |
| data | JSON | Optional | Enter the data to be passed for the event |
| extra_data | JSON | Optional | Specify any extra data to be passed for the event. |
| labels | String | Optional | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to **Triggers** > **Labels**. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs, which is the value of **Source App** in the **Configure Triggers module** of Orchestrate. |
| action_identifier | String | Unique identifier of the action, which is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | The unique ID which is generated dynamically for the event. |
| created | Date Time Field | The created date and time of the event. |
| modified | Date Time | The date and time when the event was last modified. |
| title | String | Title of the event. |
| source | String | Source of the event through which it is triggered. For example, openapi |
| labels | List | List of the label names associated with the event. |
| labels _data | List | Details of the label associated with the event. Details include title and color. |
| created_by | String | Unique ID of the user who created the event. |
| created_by_data | JSON | Details of the user who triggered the event. Details include unique_id, first_name, last_name, and full_name. |
| data | JSON | Data passed to the event. |
| extra_data | JSON | Any extra data passed to the event |
| processed | Boolean | Indicates if the event is processed or not. |
| execution_error | Boolean | Indicates if the event execution error occurred or not. |
| readble_id | String | Readable ID of the event. For example, TE7b4213b4-7. |
| splitted_columns | List | List of fields that consist large data. You can use the following API to download the large data files:  <br>Get Event Data Download. |

Create Event

Creates an event by passing the app identifier, action identifier and data through the body and provides a concise response with key parameters.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| title | String | Mandatory | Enter the title of the event. |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs.  <br>To retrieve app_identifier, sign in to Orchestrate and go to **Configure Triggers**. The app_identifier is the value displayed in the **Source App** column. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action.  <br>To retrieve the action_identifier, sign in to Orchestrate and go to **Configure Triggers**. The action_identifier is the value displayed in the **Event Type** column. |
| data | JSON | Optional | Enter the data to be passed for the event |
| extra_data | JSON | Optional | Specify any extra data to be passed for the event. |
| labels | String | Optional | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to **Triggers** > **Labels** |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs, which is the value of **Source App** in the **Configure Triggers module** of Orchestrate. |
| action_identifier | String | Unique identifier of the action, which is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | The unique ID which is generated dynamically for the event. |
| created | Date Time Field | The created date and time of the event. |
| modified | Date Time | The date and time when the event was last modified. |
| title | String | Title of the event. |

Create Event (v2)

Returns the list of triggered events.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| unique_id | String | Optional | Enter the unique ID of the event. |
| page | Integer | Optional | Enter the page number to navigate to the required page. |
| page_size | Integer | Optional | Enter the number of items to be displayed per page. |
| source | String | Optional | Enter the source of the triggered event.  <br>Example :  <br>OpenAPI, Webhooks, Platform |
| title | String | Optional | Enter the keyword to search in title of triggered events. |
| app_identifier | String | Optional | Enter the keyword to search in app_identifier (source app_. |
| action_identifier | String | Optional | Enter the keyword to search in action_identifer (event type). |
| q | String | Optional | Enter the keyword to search in title (event title), app_identifier (source app), action_identifer (event type) and unique_id (event ID). |
| created | String | Optional | Enter the created date of the triggered event.  <br>Example:  <br>last_month, last_year , last_week |
| created__lte | Integer | Optional | Enter the custom date which is less than or equal to unix time stamp.  <br>Example:  <br>1642530599 |
| created__gte | Integer | Optional | Enter the custom date which is greater than or equal to unix time stamp.  <br>Example:  <br>1642530599 |
| ordering | String | Optional | Enter the ordering to sort the triggered events.  <br>Example:  <br>created, relevance (only for search on data) |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| link | JSON | Indicates the next and the previous URL |
| count | Integer | The total count of the triggered events |
| results | List of JSON | The list of the triggered events |
| created | Date Time Field | The triggered event date and time |
| readabled_id | String | Unique ID to identify an event. For example, TE2ace5e5f-4 |
| unique_id | String | The unique ID of the triggered event |
| title | String | The title of the Playbook |
| labels | List | The names of the labels |
| labels_data | List | The details of the label |
| app_identifier | String | The unique identifier of the app to which the action belongs to |
| action_identifier | String | The unique identifier of the action |
| processed | Boolean | Indicates if the event is processed or not |
| execution_error | Boolean | The event execution error occurrence |
| source | String | The event source through which the event is triggered |

Get Source Events

Returns the details of a triggered event.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| event_unique_id | String | Mandatory | Enter the unique ID of the event. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| created | Date Time Field | Event triggered date and time |
| readabled_id | String | Human readable ID of the event |
| unique_id | String | Unique ID to identify an event |
| title | String | Title of the Playbook |
| labels | List | Names of the labels |
| labels_data | List | Details of the label |
| app_identifier | String | Unique identifier of the app to which the action belongs |
| action_identifier | String | Unique identifier of the action |
| created_by | String | Unique ID of the user created |
| created_by_data | JSON | User data of the event created unique_id, first_name, last_name, full_name |
| data | JSON | data passed to the event |
| extra_data | JSON | extra data passed to the event |
| processed | Boolean | Indicates if the event is processed or not |
| execution_error | Boolean | Event execution error occurrence |
| source | String | Event source through which it triggered |
| splitted_columns | Array of String | Indicates that event data is more than 4 MB. |

Get Source Event Details

Configures event by passing the app identifier, action identifier and labels through the body.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| labels | List | Mandatory | Enter the list of label names. |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs |
| action_identifier | String | Unique identifier of the action |
| labels | List | List of label names |
| labels_data | List | Details of the label |
| unique_id | String | The unique ID which is generated dynamically for the event |
| created | Date Time Field | Configured date and time of the event |
| modified | Date Time Field | Modified date and time of the event |
| created_by_data | JSON | Details of the user who created the event |
| modified_by_data | JSON | Details of the user who modified the event |
| is_active | Boolean | Status of the event |

Configure event

Downloads larger files from event data. This endpoint is used to download large files.

#### Request Parameters

| **Parameter** | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| field | String | Mandatory | Column name for which file will be generated. The column name can be found in the splitted_columns field. |

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| file_url | String | The URL of the file to download. |

Download Event Data

Playbook Tags are attributes associated with a playbook to categorize them based on specific threat models and methodologies. Users can choose to skip or select Playbook Tags in the incident response tool (currently limited to CFTR) to assign RBAC permissions. For example, for entry-level Threat Intel Analysts, SOC Managers/Incident Managers can provide a restrictive set of permissions like editing or running specific playbooks, preventing access to view playbooks depending on the Playbook category.

The Incident Response process in CFTR can be executed effectively with the dynamic access of Playbooks from CSOL. With this feature, Playbooks Tags can be managed in CSOL and used in CFTR to provide Role-Based Access.

Get Tags List

Retrieves the details of a tag based on the tag unique ID passed through URL.

#### Request Parameters

This API endpoint does not require any input parameter.

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| unique_id | String | The unique ID which is generated dynamically for the tag |
| title | String | Title of the tag |
| description | String | Description of the tag |
| created | Date Time Field | Tag created date and time |
| modified | Date Time Field | Tag modified date and time |
| color | String | Color code of the tag |
| created_by_data | JSON | Details of the user who created the tag |
| modified_by_data | JSON | Details of the user who modified the tag |
| playbook_count | Integer | Playbooks count under the tag |

Get Tag Details

Webhooks are serialized messages/information sent from one application to another's unique URL over the web. Webhooks enable Analysts to bypass data exchange complications by generating token-based URLs and authenticating endpoints whenever events (GET and POST requests) are triggered in the CSOL application.

**Webhooks** module allows users to create and manage Webhook configurations and tokens. Users will be able to access the CSOL application's features based on the permissions assigned for the user in the CSOL application.

## Authentication

These API's requires webhook token as mandatory parameter.

### Generate Webhook Credentials

1.  Navigate to the **Admin Panel** on the left sidebar and click **Webhook** module.
2.  Start by clicking the “Add Webhook“ button from the top right corner of the page.
3.  Enter the Webhook details.
4.  After entering the details, click the "Generate Token" button.
5.  After creation, copy the **token** and the **Base URL** displayed to you. Now configure the keys to the required application.

Webhooks

Use this API to test the connectivity.

#### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| status | String | Indicates the status of the connection.  <br>Example : ok |

Test connectivity

Creates an event by passing the app identifier and action identifier through the URL and data through payload.

**Note**: Starting from Orchestrate v3.5.9, the webhook URLs generated in the Orchestrate platform are updated to provide concise response with key parametes such as title, readable_id, source, and more. To retrieve a detailed response, remove the `/v2` from the webhook URL. The following is the example webhook URL that retrieves the detailed response: `https:///soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356`.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| data | Object | Mandatory | Enter the data for action execution. |
| title | String | optional | Enter the title for data. |
| labels | String | Optional | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to **Triggers** > **Labels**. |

### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs. This is the value of **Source App** in the **Configure Triggers** module of Orchestrate. |
| action_identifier | String | Unique identifier of the action. This is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | The unique ID which is generated dynamically for the event. |
| created | Date Time Field | The created date and time of the event. |
| modified | Date Time | The last modified date and time of the event. |
| title | String | Title of the event. |
| source | String | Source of the event through which it is triggered. For example, openapi. |
| labels | List | List of the label names associated with the event. |
| labels _data | List | Details of the label associated with the event. Details include title and color. |
| created_by | String | Unique ID of the user who created the event. |
| created_by_data | JSON | Details of the user who triggered the event. Details include unique_id, first_name, last_name, and full_name. |
| data | JSON | Data passed to the event. |
| extra_data | JSON | Any extra data passed to the event |
| processed | Boolean | Indicates if the event is processed or not |
| execution_error | Boolean | Indicates if the event execution error occurred or not. |
| readble_id | String | Readable ID of the event. For example, TE7b4213b4-7. |
| splitted_column | List | List of fields that consist large data. You can use the following API to download the large data files:  <br>Get Event Data Download. |

Creates an event by passing the app identifier and action identifier through the URL and data through payload. This API provides a concise response with key parameters.

**Note**: This API is available in Orchestrate v3.5.9 onwards.

To retrieve a detailed response, remove the `/v2` from the webhook URL. The following is the example webhook URL that retrieves the detailed response: `https:///soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356`.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs.  <br>To retrieve app_identifier, sign in to Orchestrate and go to **Configure Triggers**. The app_identifier is the value displayed in the **Source App** column. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action.  <br>To retrieve the action_identifier, sign in to Orchestrate and go to **Configure Triggers**. The action_identifier is the value displayed in the **Event Type** column. |
| data | Object | Mandatory | Enter the data for action execution. |
| labels | String | Optiomnal | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to **Triggers** > **Labels**.  <br>Note: |

### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs. This is the value of **Source App** in the **Configure Triggers** module of Orchestrate. |
| action_identifier | String | Unique identifier of the action. This is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | The unique ID which is generated dynamically for the event. |
| created | Date Time Field | The created date and time of the event. |
| modified | Date Time | The last modified date and time of the event. |
| title | String | Title of the event. |
| source | String | Source of the event through which it is triggered. For example, openapi. |

Creates an event by passing the app identifier, action identifier and data through the payload.

**Note**: Starting from Orchestrate v3.5.9, the webhook URLs generated on the Orchestrate platform are updated to provide concise response with key parametes. To retrieve a detailed response, remove the `/v2` from the webhook URL. The following is the example webhook URL that retrieves the detailed response: `https:///soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356`.

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs.  <br>To retrieve app_identifier, sign in to Orchestrate and go to **Configure Triggers**. The app_identifier is the value displayed in the **Source App** column. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action.  <br>To retrieve the action_identifier, sign in to Orchestrate and go to **Configure Triggers**. The action_identifier is the value displayed in the **Event Type** column. |
| data | Object/String | Mandatory | Provide the data required for action execution. |
| labels | String | Optional | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to **Triggers** > **Labels**.  <br>**Note**:  <br>If you do not add labels, applicable labels will be automatically applied based on the action_identifier and app_identifier provided. The mappings in **Configure Triggers** in Orchestrate will be used to assign labels accordingly. If no relevant labels are found, then the event will have no labels. |

### Response Parameters

| Attribute | Attribute Type | Description |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs. This is the value of **Source App** in the **Configure Triggers** module of Orchestrate. |
| action_identifier | String | Unique identifier of the action. This is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | Dynamically generated unique ID of the event. |
| readable_id | String | Readable ID of the event. For example, TE78db2d7d-8. |
| created | DateTime Field | Date and time of the event creation. |
| title | String | Title of the event. |
| source | String | Source of the event through which it is triggered. For example, openapi |

Create Events through Payload

Creates an event by passing the app identifier, action identifier and data through the payload. This API endpoint provides a concise response with key parameters.

**Note**: This API is available in Orchestrate v3.5.9 onwards.

To retrieve a detailed response, remove the `/v2` from the webhook URL. The following is the example webhook URL that retrieves the detailed response: `https:///soarapi/webhooks_auth/events/?token=1df121212-121x-1212-3434-a67823232356.`

### Request Parameters

| Attribute | Attribute Type | Required | Description |
| --- | --- | --- | --- |
| app_identifier | String | Mandatory | Enter the unique identifier of the app to which the action belongs.  <br>To retrieve app_identifier, sign in to Orchestrate and go to **Configure Triggers**. The app_identifier is the value displayed in the **Source App** column. |
| action_identifier | String | Mandatory | Enter the unique identifier of the action.  <br>To retrieve the action_identifier, sign in to Orchestrate and go to **Configure Triggers**. The action_identifier is the value displayed in the **Event Type** column. |
| data | Object/String | Mandatory | Provide the data required for action execution. |
| labels | String | Optional | Enter labels for the events.  <br>To view the list of labels, sign in Orchestrate and go to Triggers > Labels.  <br>**Note**:  <br>If you do not add labels, applicable labels will be automatically added based on the action_identifier and app_identifier provided. The mappings in **Configure Triggers** in Orchestrate will be used to assign labels accordingly. If no relevant labels are found, then the event will have no labels. |

### Response Parameters

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| app_identifier | String | Unique identifier of the app to which the action belongs. This is the value of **Source App** in the **Configure Triggers** module of Orchestrate. |
| action_identifier | String | Unique identifier of the action. This is the value of **Event Type** in the **Configure Triggers** module of Orchestrate. |
| unique_id | String | The unique ID which is generated dynamically for the event. |
| created | Date Time Field | The created date and time of the event. |
| modified | Date Time | The last modified date and time of the event. |
| title | String | Title of the event. |
| source | String | Source of the event through which it is triggered. For example, openapi. |
| labels | List | List of the label names associated with the event. |
| labels _data | List | Details of the label associated with the event. Details include title and color. |
| created_by | String | Unique ID of the user who created the event. |
| created_by_data | JSON | Details of the user who triggered the event. Details include unique_id, first_name, last_name, and full_name. |
| data | JSON | Data passed to the event. |
| extra_data | JSON | Any extra data passed to the event |
| processed | Boolean | Indicates if the event is processed or not |
| execution_error | Boolean | Indicates if the event execution error occurred or not. |
| readble_id | String | Readable ID of the event. For example, TE7b4213b4-7. |
| splitted_columns | List | List of fields that consist large data. You can use the following API to download the large data files:  <br>Get Event Data Download. |

Create Events through Payload (v2)

Default

Orchestrate API Reference (CO)

accessid

secretkey

Production

Sample

Sandbox

<p class="slate-p " >Orchestrate enables security analysts to gather threat data from multiple sources and automate responses to threats and vulnerabilities through advanced workflows. This leads to faster detection, improved analysis, and efficient management of the security operations lifecycle. For more information, see <a href="https://techdocs.cyware.com/en/299672-303736-product-documentation.html" target="_blank">Orchestrate Product Documentation</a>.</p><p class="slate-p " >The Orchestrate open API allows for programmatic interaction with Orchestrate services, enabling automation and integration with other systems in your environment. </p><div class="card-box" style="width:60%;"><svg width="32" height="32" viewBox="0 0 24 24" fill="none" class="icon-style" xmlns="http://www.w3.org/2000/svg"> <g clipPath="url(#clip0_2631_5104)"> <path d="M17 0C16.7348 0 16.4804 0.105357 16.2929 0.292893C16.1054 0.48043 16 0.734784 16 1C16 3.949 13.417 5 11 5H4C2.93913 5 1.92172 5.42143 1.17157 6.17157C0.421427 6.92172 0 7.93913 0 9L0 11C0.00218416 11.5987 0.139462 12.1893 0.401603 12.7276C0.663743 13.2659 1.04399 13.7381 1.514 14.109L5.086 22.081C5.34004 22.6521 5.75417 23.1373 6.27827 23.4779C6.80237 23.8185 7.41396 23.9998 8.039 24C8.53631 23.9997 9.02565 23.875 9.46247 23.6373C9.89929 23.3996 10.2697 23.0564 10.54 22.639C10.8104 22.2215 10.972 21.7431 11.0103 21.2473C11.0485 20.7515 10.9621 20.2539 10.759 19.8L8.559 15H11C13.417 15 16 16.051 16 19C16 19.2652 16.1054 19.5196 16.2929 19.7071C16.4804 19.8946 16.7348 20 17 20C17.2652 20 17.5196 19.8946 17.7071 19.7071C17.8946 19.5196 18 19.2652 18 19V1C18 0.734784 17.8946 0.48043 17.7071 0.292893C17.5196 0.105357 17.2652 0 17 0V0ZM8.937 20.619C9.00324 20.7686 9.03109 20.9323 9.01804 21.0954C9.005 21.2585 8.95145 21.4157 8.86227 21.5529C8.77309 21.69 8.65109 21.8027 8.50733 21.8808C8.36357 21.9589 8.20259 21.9999 8.039 22C7.8004 21.9998 7.56697 21.9304 7.36709 21.8001C7.1672 21.6698 7.00945 21.4842 6.913 21.266L4.105 15H6.359L8.937 20.619ZM16 14.6C14.5713 13.4992 12.8024 12.9331 11 13H4C3.46957 13 2.96086 12.7893 2.58579 12.4142C2.21071 12.0391 2 11.5304 2 11V9C2 8.46957 2.21071 7.96086 2.58579 7.58579C2.96086 7.21071 3.46957 7 4 7H11C12.8018 7.0683 14.5706 6.50403 16 5.405V14.6ZM23.9 15.452C23.8413 15.5696 23.7601 15.6744 23.6609 15.7606C23.5617 15.8467 23.4465 15.9125 23.3218 15.9541C23.1972 15.9957 23.0656 16.0123 22.9345 16.0031C22.8035 15.9938 22.6755 15.9588 22.558 15.9L20.558 14.9C20.3206 14.7814 20.1401 14.5735 20.0561 14.3218C19.972 14.0701 19.9915 13.7954 20.11 13.558C20.2286 13.3206 20.4365 13.1401 20.6882 13.0561C20.9399 12.972 21.2146 12.9914 21.452 13.11L23.452 14.11C23.6882 14.2285 23.8678 14.4356 23.9518 14.6861C24.0357 14.9366 24.0171 15.2102 23.9 15.447V15.452ZM20.11 6.452C20.0512 6.33448 20.0162 6.20653 20.0069 6.07546C19.9977 5.9444 20.0143 5.81279 20.0559 5.68816C20.0975 5.56353 20.1633 5.44832 20.2494 5.34912C20.3356 5.24991 20.4404 5.16866 20.558 5.11L22.558 4.11C22.7954 3.99145 23.0701 3.97205 23.3218 4.05606C23.5735 4.14008 23.7815 4.32063 23.9 4.558C24.0186 4.79537 24.038 5.07011 23.9539 5.32178C23.8699 5.57346 23.6894 5.78145 23.452 5.9L21.452 6.9C21.3345 6.95876 21.2065 6.99378 21.0755 7.00306C20.9444 7.01234 20.8128 6.99571 20.6882 6.9541C20.5635 6.9125 20.4483 6.84674 20.3491 6.76058C20.2499 6.67443 20.1687 6.56957 20.11 6.452ZM20 10C20 9.73478 20.1054 9.48043 20.2929 9.29289C20.4804 9.10536 20.7348 9 21 9H23C23.2652 9 23.5196 9.10536 23.7071 9.29289C23.8946 9.48043 24 9.73478 24 10C24 10.2652 23.8946 10.5196 23.7071 10.7071C23.5196 10.8946 23.2652 11 23 11H21C20.7348 11 20.4804 10.8946 20.2929 10.7071C20.1054 10.5196 20 10.2652 20 10Z" fill="#374957"/> </g> <defs> <clipPath id="clip0_2631_5104"> <rect width="32" height="32" fill="white"/> </clipPath> </defs> </svg><div ><p class="slate-p " ><strong class="slate-bold">Supported Orchestrate Version</strong>: 3.5.5.0 and later versions.</p></div></div><p class="slate-p " >The API reference includes public Orchestrate API endpoints for the following modules:</p><div class=card-group-box style="width:100%; min-width:540px;"><a href="https://orchestrateapi.cyware.com/integrations" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/62860912-278f-4162-9977-8a5557405173.png class=card-icon></img><div ><h3 class="slate-h3 " >Integrations</h3><p class="slate-p " >Integrate security tools seamlessly with Orchestrate&apos;s App Store.</p></div></a><a href="https://orchestrateapi.cyware.com/playbook" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/f18fa5c0-0356-45ec-a560-e44654723079.png class=card-icon></img><div ><h3 class="slate-h3 " >Playbooks</h3><p class="slate-p " >Automate and orchestrate security operations with playbooks.</p></div></a></div><div class=card-group-box style="width:100%; min-width:540px;"><a href="https://orchestrateapi.cyware.com/authentication" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/658327d9-b39d-4f8a-bf3f-d494bb0e7b8e.png class=card-icon></img><div ><p class="slate-p " >Authenticate</p></div></a><a href="https://orchestrateapi.cyware.com/custom-templates" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/a5648031-e4ae-425d-8a5f-a207c11e229e.png class=card-icon></img><div ><p class="slate-p " >Custom Templates</p></div></a><a href="https://orchestrateapi.cyware.com/code-snippets" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/f8dfb9d6-4811-4c75-8d6d-7245ee53bf18.png class=card-icon></img><div ><p class="slate-p " >Code Snippets</p></div></a><a href="https://orchestrateapi.cyware.com/persistent-list" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/4189ed64-e1cb-405d-8717-c551da87aabc.png class=card-icon></img><div ><p class="slate-p " >Persistent List</p></div></a></div><div class=card-group-box style="width:100%; min-width:540px;"><a href="https://orchestrateapi.cyware.com/analytics" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/9e51cc57-e2ea-4fd0-9ecd-95bca92d7d63.png class=card-icon></img><div ><p class="slate-p " >Analytics</p></div></a><a href="https://orchestrateapi.cyware.com/events" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/1f33b851-3cbb-4d1d-96b0-dd3359c79bb9.png class=card-icon></img><div ><p class="slate-p " >Events</p><p class="slate-p " ></p></div></a><a href="https://orchestrateapi.cyware.com/tags" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/d32ffec4-2585-44f4-bc36-14b28cc38fcb.png class=card-icon></img><div ><p class="slate-p " >Tags</p><p class="slate-p " ></p></div></a><a href="https://orchestrateapi.cyware.com/webhooks" target="_blank" class="card-box-anchor"><img src=https://d24lr4zqs1tgqh.cloudfront.net/b53a7d0c-2b4a-477a-8269-a9dbba5267b8.png class=card-icon></img><div ><p class="slate-p " >Webhooks</p></div></a></div><p class="slate-p " ></p><p class="slate-p " ></p>

Orchestrate enables security analysts to gather threat data from multiple sources and automate responses to threats and vulnerabilities through advanced workflows. This leads to faster detection, improved analysis, and efficient management of the security operations lifecycle. For more information, see 

The Orchestrate open API allows for programmatic interaction with Orchestrate services, enabling automation and integration with other systems in your environment. 

The API reference includes public Orchestrate API endpoints for the following modules:

<p class="slate-p " >Users with access to Cyware Orchestrate&apos;s Open APIs module can generate the credentials for API authentication.</p><h2 class="slate-h2 " >Generate Open API Credentials</h2><p class="slate-p " >You can generate open API credentials in the Orchestrate application to access the open API endpoints. For more information on how to generate Open API credentials in Orchestrate, see <a href="https://techdocs.cyware.com/en/299672-439044-configure-open-api.html#299672-439044-configure-open-api" target="_blank">Configure Open API</a>.</p><h3 class="slate-h3 " >Mandatory Query Parameters for Requests</h3><p class="slate-p " >After you have generated open API credentials, use them to authenticate your API requests. Ensure the following parameters are included in the query of each request:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Access ID</strong>:<strong class="slate-bold"> </strong>Indicates the access ID linked to your Orchestrate Open API credentials. For example, 57d008xx-7xxx-xx-b27a-1feb943d0xxx.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Expires</strong>: Indicates the validity of the signature parameter. The signature becomes invalid if not used within the specified expiry duration. You can use
<code class="slate-code">expires = current time + 20 seconds</code> for authentication. You can specify a margin of 10 to 15 seconds for expiration.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Signature</strong>: Signature is a combination of the access ID, secret key, and expiration parameters to authenticate API requests. The signature is hashed using the HMAC-SHA1 algorithm and then encoded using the Base64 scheme.</div><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Create a StringToSign value using the <code class="slate-code">StringToSign = access_id + \n + expires</code><em class="slate-italic"> </em>formula.</div></li><li class="slate-li " ><div style="position:relative">Create a Signature value using the <code class="slate-code">Signature = Base64(HMAC-SHA1(secret_key, UTF-8-Encoding-Of(StringToSign)))</code> formula.</div></li></ul></li></ul><p class="slate-p " >The following Python code is a sample to generate a signature for endpoint authentication:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Python</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-python keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">import base64
import hashlib
import hmac
import time
expires = int(time.time() + 20) # expires in 20 sec
def generate_signature(access_id, secret_key, expires):
 to_sign = &apos;{}\n{}&apos;.format(access_id, expires)
 return base64.b64encode(
     hmac.new(
         secret_key.encode(&apos;utf-8&apos;),
         to_sign.encode(&apos;utf-8&apos;),
         hashlib.sha1
     ).digest())</div><div class="slate-code_line">#Example:
#access_id = &quot;7e4e6a9c-11ca-40f4-95af-edae017358d0&quot;
#secret_key = &quot;e61e92fb-bfd9-4cef-9b21-6f1e8211b77b&quot;</div><div class="slate-code_line">#signature = generate_signature(access_id, secret_key, expires)
#signature = generate_signature(access_id, secret_key, expires)</div></div></code></pre></div><p class="slate-p " ></p><p class="slate-p " ></p>

Users with access to Cyware Orchestrate's Open APIs module can generate the credentials for API authentication.

You can generate open API credentials in the Orchestrate application to access the open API endpoints. For more information on how to generate Open API credentials in Orchestrate, see 

After you have generated open API credentials, use them to authenticate your API requests. Ensure the following parameters are included in the query of each request:

The following Python code is a sample to generate a signature for endpoint authentication:

<p class="slate-p " >Cyware Orchestrate offers a robust App Store with a comprehensive library of apps required to integrate, orchestrate, and respond using various security tools within your organization. These integrations support tasks like threat data collection, prioritization, and other analytics, enabling a holistic approach to orchestration from a unified platform. For more information, see <a href="https://techdocs.cyware.com/en/299672-334102-integrations.html" target="_blank">Integrations</a>. </p><p class="slate-p " >You can perform the following actions in this module:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Retrieve App and Instance Details</strong>: Fetch details of available apps and instances, including details of a specific app and instance.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Test Instance Connectivity</strong>: Verify the connectivity of a specific app instance to ensure successful integration.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Retrieve App Actions and Details</strong>: Fetch a list of actions associated with an app and detailed information about each action.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Execute App Actions</strong>: Run specific actions of an app.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Download App Package</strong>: Download the ZIP file for a specific app to enable offline access.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Install Custom Apps</strong>: Add new custom applications by uploading and installing app packages.</div></li></ul><p class="slate-p " ></p>

Cyware Orchestrate offers a robust App Store with a comprehensive library of apps required to integrate, orchestrate, and respond using various security tools within your organization. These integrations support tasks like threat data collection, prioritization, and other analytics, enabling a holistic approach to orchestration from a unified platform. For more information, see 

You can perform the following actions in this module:

<p class="slate-p " >Playbooks are a structured sequence of actions organized into workflows to automate and orchestrate security responses, standardizing processes for effective incident and threat management. Orchestrate offers manual and automated playbooks to meet your organization&apos;s specific needs. </p><p class="slate-p " >Playbooks can be scheduled based on application input sources or automatically triggered by specific events. Additionally, playbooks facilitate seamless integration between different security tools, creating a more connected and efficient security environment. For more information, see <a href="https://techdocs.cyware.com/en/299672-315972-playbooks.html" target="_blank">Playbooks</a>.</p><p class="slate-p " >You can perform the following actions in this module:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Export Playbook</strong>: Export playbook details for backup or external use.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Retrieve Playbooks and Details</strong>: Fetch the list of playbooks and specific playbook details.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Retrieve Playbook Run Logs and Run Details</strong>: Fetch the list of playbook results, run logs, and specific run log details.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Execute and Manage Playbooks</strong>:<strong class="slate-bold"> </strong>Run or terminate specific playbooks.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Download Playbook and Node Results</strong>:<strong class="slate-bold"> </strong>Fetch and download results of a specific playbook or a specific node output for analysis.</div></li></ul><p class="slate-p " ></p>

Playbooks are a structured sequence of actions organized into workflows to automate and orchestrate security responses, standardizing processes for effective incident and threat management. Orchestrate offers manual and automated playbooks to meet your organization's specific needs. 

Playbooks can be scheduled based on application input sources or automatically triggered by specific events. Additionally, playbooks facilitate seamless integration between different security tools, creating a more connected and efficient security environment. For more information, see 

<p class="slate-p " >Returns a list of active playbooks in Orchestrate.</p>

Returns a list of active playbooks in Orchestrate.

Pass the page number to retrieve the playbook list.

page

Pass the number of items to retrieve per page.

page_size

Pass true or false to filter playbooks based on their scheduled status.

scheduled

labels

apps

Pass the `action_identifier` identifier of the app action. You can retrieve the `action_identifier` of actions using the **Get App Actions** endpoint.

actions

Pass true for active playbooks and false for inactive playbooks.

is_active

Pass the last modified value to filter playbooks based on their last modified time.

modified

Returns the link to the previous and next page.

link

Returns the total number of playbooks created by Orchestrate users.

count

Returns the list of playbooks as JSON objects.


results

<p class="slate-p " ><p class="slate-p " >Returns playbook details based on the playbook ID passed. If no ID is passed, it returns the complete list of both user-created and system playbooks.</p></p>

Pass the unique ID of a playbook to retrieve details of a specific playbook. You can retrieve unique IDs of playbook using the **Get Playbooks** endpoint.

unique_id

Pass the page number to retrieve the list of playbooks.

Pass true to retrieve playbooks that are scheduled.

Pass the unique ID of the tags to retrieve playbooks.

Pass the label name to retrieve playbooks.

Pass the app identifier. You can retrieve the app identifier using the **Get Apps** endpoint.

Pass the action identifier of an action. You can retrieve the action identifier using the **Get App Actions** endpoint.

Pass true to filter active playbooks, else false.

Returns the details of the playbooks. Each object provides details of one playbook.

<p class="slate-p " >Returns the playbook runlogs based on the unique ID of the playbook. If no payload is passed, it returns the complete list of playbook run logs.</p>

Sections