Orchestrate API Reference (CO)

## Sections
• [Orchestrate API Reference](https://orchestrateapi.cyware.com/cyware-orchestrate-api-reference-theneo.md): 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 Orchestrate Product Documentation . The Orchestrate open API allows for programmatic interaction with Orchestrate services, enabling automation and integration with other systems in your environment. For AI agents and LLM-based discovery, see the Orchestrate API Reference LLM-friendly API guide . Supported Orchestrate Version : 3.5.5.0 and later versions. The API reference includes public Orchestrate API endpoints for the following modules: Integrations Integrate security tools seamlessly with Orchestrate's App Store. Playbooks Automate and orchestrate security operations with playbooks. Authenticate Custom Templates Code Snippets Persistent List Analytics Events Tags Webhooks
• [Authentication](https://orchestrateapi.cyware.com/authentication.md): Users with access to Cyware Orchestrate's Open APIs module can generate the credentials for API authentication. Generate Open API Credentials 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 Configure Open API . Mandatory Query Parameters for Requests 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: Access ID : Indicates the access ID linked to your Orchestrate Open API. For example, 57d008xx-7xxx-xx-b27a-1feb943d0xxx. Expires : Indicates the validity of the signature parameter. The signature becomes invalid if not used within the specified expiry duration. You can use expires = current time + 30 seconds for authentication. You can specify a margin of 10 to 30 seconds for expiration. Signature : 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. Create a StringToSign value using the StringToSign = access_id + \n + expires formula. Create a Signature value using the Signature = Base64(HMAC-SHA1UTF-8-Encoding-Of(secret_key), UTF-8-Encoding-Of(StringToSign)) formula. The following Python code is a sample to generate a signature for endpoint authentication: Python def generate_signature(access_id, secret_key): expires = int(time.time() + 30) # expires in 30 seconds to_sign = '{}\n{}'.format(access_id, expires) signature = base64.b64encode( hmac.new( secret_key.encode('utf-8'), to_sign.encode('utf-8'), hashlib.sha1 ).digest()).decode() return expires, signature #Example: #access_id = "7e4e6a9c-11ca-40f4-95af-edae017358d0" #secret_key = "e61e92fb-bfd9-4cef-9b21-6f1e8211b77b" #Generate signature: #expires, signature = generate_signature(access_id, secret_key)
  • [Test Connectivity](https://orchestrateapi.cyware.com/authentication/test-connectivity.md): Returns the status of the test connectivity with the Orchestrate application.
  • [Product Release Version](https://orchestrateapi.cyware.com/authentication/product-release-version.md): Returns the current version of the Orchestrate application.
• [Integrations](https://orchestrateapi.cyware.com/integrations.md): 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 Apps . You can perform the following actions in this module: Retrieve App and Instance Details : Fetch details of available apps and instances, including details of a specific app and instance. Test Instance Connectivity : Verify the connectivity of a specific app instance to ensure successful integration. Retrieve App Actions and Details : Fetch a list of actions associated with an app and detailed information about each action. Execute App Actions : Run specific actions of an app. Download App Package : Download the ZIP file for a specific app to enable offline access. Install Custom Apps : Add new custom applications by uploading and installing app packages.
  • [Get Apps](https://orchestrateapi.cyware.com/integrations/get-apps.md): Returns a list of apps from My Apps in Orchestrate.
  • [Get App Details](https://orchestrateapi.cyware.com/integrations/get-app-details.md): Returns the details of a specific app.
  • [Get App Instances](https://orchestrateapi.cyware.com/integrations/list-app-instances.md): Retrieves a list of available instances for all apps. To retrieve instances of a specific app, pass the unique ID of the app.
  • [Create App Instance](https://orchestrateapi.cyware.com/integrations/create-app-instance.md): Create an instance in a specific app.
  • [Get App Instance Details](https://orchestrateapi.cyware.com/integrations/get-app-instance-details.md): Returns the details of a specific instance.
  • [Test App Instance Connectivity](https://orchestrateapi.cyware.com/integrations/test-app-instance-connectivity.md): Verify the connectivity of an app instance.
  • [Get App Actions](https://orchestrateapi.cyware.com/integrations/get-app-actions.md): Returns a list of all available actions from all apps. To retrieve actions of a specific app, pass the Unique ID of the app.
  • [Get Action Details](https://orchestrateapi.cyware.com/integrations/get-action-details.md): Returns the details of a specific action.
  • [Execute Action](https://orchestrateapi.cyware.com/integrations/execute-action.md): Execute an app action by passing the required parameters in the payload.
  • [Download App Package](https://orchestrateapi.cyware.com/integrations/download-app-package.md): Download the app's ZIP file by entering the app identifier. You can save the response as a ZIP file to your device.
  • [Install Custom Apps](https://orchestrateapi.cyware.com/integrations/install-custom-apps.md): Install custom apps on the Orchestrate application.
• [Playbooks](https://orchestrateapi.cyware.com/playbook.md): 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 Playbooks . You can perform the following actions in this module: Export Playbook : Export playbook details for backup or external use. Retrieve Playbooks and Details : Fetch the list of playbooks and specific playbook details. Retrieve Playbook Run Logs and Run Details : Fetch the list of playbook results, run logs, and specific run log details. Execute and Manage Playbooks : Run or terminate specific playbooks. Download Playbook and Node Results : Fetch and download results of a specific playbook or a specific node output for analysis.
  • [Get Playbooks](https://orchestrateapi.cyware.com/playbook/open-playbook.md): Returns a list of active playbooks in Orchestrate.
  • [Get Playbook Details](https://orchestrateapi.cyware.com/playbook/get-playbook.md): 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.
  • [Get Playbook Result](https://orchestrateapi.cyware.com/playbook/get-playbook-result.md): 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.
  • [Get Playbook Run Logs](https://orchestrateapi.cyware.com/playbook/list-playbook-run-logs.md): Retrieves the list of playbook run logs along with the associated playbook data.
  • [Get Playbook Run Log Details](https://orchestrateapi.cyware.com/playbook/get-playbook-detail-run-log.md): Returns run logs of a specific playbook.
  • [Get Node Result Details](https://orchestrateapi.cyware.com/playbook/get-node-result-details.md): Returns the details of a specific node.
  • [Run Playbook](https://orchestrateapi.cyware.com/playbook/run-playbook.md): Run a playbook by passing the playbook unique ID through the payload.
  • [Export Playbook](https://orchestrateapi.cyware.com/playbook/export-playbook.md): Returns the export of a playbook in JSON format.
  • [Download Playbook Result](https://orchestrateapi.cyware.com/playbook/playbook-result-download.md): Download the input data of the playbook. This endpoint is used to download large files.
  • [Download Node Result](https://orchestrateapi.cyware.com/playbook/node-result-download.md): Download the input data or output data of a playbook node. This endpoint is used to download large files.
  • [Bulk Terminate Playbook Runs](https://orchestrateapi.cyware.com/playbook/bulk-terminate-api-view.md): 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.
• [Custom Email Templates](https://orchestrateapi.cyware.com/custom-templates.md): Email templates are predefined email layouts with a header and body in rich text format. Analysts can reuse and customize these templates, reducing the effort required to compose emails from scratch. These templates can be used in playbooks to automate email notifications. They are compatible with applications that support Rich Text Format fields, such as the Cyware Email Service - Send Email in Rich Text Format action and more. For more information, see Email Templates . You can perform the following actions in this module: Get Custom Email Template List: Retrieve a list of available email templates. Get Custom Email Template Details: Retrieve detailed information about a specific email template.
  • [Get Custom Email Template List](https://orchestrateapi.cyware.com/custom-templates/custom-template-list.md): Returns the list of custom email templates.
  • [Get Custom Email Template Details](https://orchestrateapi.cyware.com/custom-templates/custom-template-detail.md): Returns details of a specific custom email template.
• [Code Snippets](https://orchestrateapi.cyware.com/code-snippets.md): Code snippets are reusable blocks of code, such as functions, loops, and conditional statements. They support the creation of custom nodes, including custom actions and conditions, within playbooks. Analysts can leverage a centralized library of reusable code to streamline workflows and reduce effort. This allows them to customize code pieces that are used in multiple playbook workflows from one location. For more information, see Code Snippets . You can perform the following actions in this module: Retrieve Code Snippets : Retrieve a list of available code snippets. Retrieve Code Snippet Details : Fetch detailed information about a specific code snippet.
  • [Get Code Snippets List](https://orchestrateapi.cyware.com/code-snippets/code-snippets-list.md): Returns the list of code snippets.
  • [Get Code Snippet Details](https://orchestrateapi.cyware.com/code-snippets/code-snippets-detail.md): Returns details of a specific code snippet.
• [Persistent List](https://orchestrateapi.cyware.com/persistent-list.md): Persistent List is a collection of key-value pairs that analysts can use to store data and then look up 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. Analysts can then retrieve the data defined in a persistent list using any playbook node. For more information, see Persistent List . You can perform the following actions in this module: Retrieve Persistent Lists and Details : Fetch a list of all persistent storage objects and fetch detailed information about a specific object using its unique identifier. Create and Update Persistent Lists : Create new persistent storage objects or modify existing ones to update their details. Delete Persistent Storage Objects : Remove a specific persistent storage object from Orchestrate. Retrieve Persistent List Slugs : Get a list of unique resource identifiers for all persistent lists. Retrieve Playbooks Associated with a Persistent List : Get details and count of playbooks associated with a specific persistent storage object.
  • [Get Persistent Lists](https://orchestrateapi.cyware.com/persistent-list/persistent-lists.md): Returns a list of persistent lists.
  • [Get Persistent List Details](https://orchestrateapi.cyware.com/persistent-list/persistent-list-details.md): Returns the details of a specific persistent list.
  • [Create a Persistent List](https://orchestrateapi.cyware.com/persistent-list/create-a-persistent-list.md): Create a persistent list in Orchestrate.
  • [Update a Persistent List](https://orchestrateapi.cyware.com/persistent-list/update-a-persistent-list.md): Update the details of a specific persistent list.
  • [Delete Persistent Storage Object](https://orchestrateapi.cyware.com/persistent-list/delete-persistent-storage-object.md): Delete a persistent list by passing the unique ID. You can delete the persistent list only if it is not used in a playbook. A successful request returns a 200 status code, else the response includes a non_field_error object.
  • [Get Persistent List Slugs](https://orchestrateapi.cyware.com/persistent-list/get-persistent-list-slugs.md): Returns a list of persistent list slugs.
  • [Get Playbooks Associated with Persistent List](https://orchestrateapi.cyware.com/persistent-list/get-persistent-storage-object-associated-playbooks.md): Returns the details of playbooks that contain the specified persistent list.
  • [Get Playbooks Count Associated with Persistent List](https://orchestrateapi.cyware.com/persistent-list/get-persistent-storage-object-associated-playbooks-count.md): Returns the playbook count containing the specified persistent list.
• [Analytics](https://orchestrateapi.cyware.com/analytics.md): The Analytics Dashboard in Orchestrate provides an overview of activities across modules. Upon signing in, users can view dashboards that offer insights into playbook workflows, app performance, instance usage, and action execution. By analyzing key metrics such as frequently used playbooks and actions, analysts can optimize workflows and enhance automation. Dashboards also help identify underutilized events, diagnose execution errors, and refine automated responses, reducing manual intervention. For more information, see Analytics Dashboard . You can perform the following actions in this module: Retrieve Playbook Execution Metrics : Get insights on playbook run count, most active playbooks, and average playbook execution time. Retrieve App and Instance Usage Metrics : Get insights into the most used and most active apps, instances, and actions. Retrieve Event Processing Metrics : Get insights on event count, unprocessed events, events with errors, and incoming source events.
  • [Get Playbook Run Count](https://orchestrateapi.cyware.com/analytics/playbook-run-count.md): Returns the number of times playbooks were executed for the non-purged data within the specified date range.
  • [Get Most Active Playbooks](https://orchestrateapi.cyware.com/analytics/most-active-playbook.md): Returns playbooks with the highest number of executions for the non-purged data.
  • [Get Playbook Average Execution Time](https://orchestrateapi.cyware.com/analytics/playbook-avg-execution-time.md): Returns the average execution time of playbooks for the non-purged data.
  • [Get Most Used Instance](https://orchestrateapi.cyware.com/analytics/most-used-instance.md): Returns the most used instances in playbooks for the non-purged data.
  • [Get Most Used Apps](https://orchestrateapi.cyware.com/analytics/most-used-apps.md): Returns the most used apps in playbooks for the non-purged data.
  • [Get Most Used Actions](https://orchestrateapi.cyware.com/analytics/most-used-actions.md): Returns the most used actions in playbooks for the non-purged data.
  • [Get Most Active Actions](https://orchestrateapi.cyware.com/analytics/most-active-actions.md): Retrieves the most executed actions in playbooks for the non-purged data.
  • [Get Most Active Apps](https://orchestrateapi.cyware.com/analytics/most-active-apps.md): Returns the most utilized apps in playbooks for the non-purged data.
  • [Get Most Active Instances](https://orchestrateapi.cyware.com/analytics/most-active-instances.md): Returns the most frequently used instances in playbook executions for the non-purged data.
  • [Get Event Count](https://orchestrateapi.cyware.com/analytics/event-count.md): Returns the count of automatic and manual events created in Cyware Orchestrate for the non-purged data.
  • [Get Incoming Source Events](https://orchestrateapi.cyware.com/analytics/incoming-source-events.md): Returns the count of incoming source events from the configured event source app for non-purged data.
  • [Get Unprocessed Events](https://orchestrateapi.cyware.com/analytics/unprocessed-events.md): Returns the number of unprocessed events for the non-purged data.
  • [Get Events With Error](https://orchestrateapi.cyware.com/analytics/events-with-error.md): Returns the number of events that failed due to errors or system issues during playbook execution.
• [Events](https://orchestrateapi.cyware.com/events.md): A Source Event acts as a trigger for a playbook to execute. You can configure triggers to automatically trigger the execution of a playbook based on the occurrence of an event. These events can occur in Orchestrate or on external platforms such as Respond, Intel Exchange, Splunk, and more. You can configure the source event app and source event type to execute pre-configured playbook workflows. For more information, see Events . When a Source Event is triggered in Cyware Orchestrate, it carries the Source Event Data from integrated tools like Splunk, Respond, and other apps. This data is transmitted in JSON format via the Cyware Orchestrate REST API. Authorization These APIs require an OpenAPI access ID and a generated secret key for authentication. You can perform the following actions in this module: Create Events : Create new events with either detailed or concise response data. Retrieve Source Events and Details : Fetch a list of all source events and retrieve the details of a specific event. Configure and Manage Events : Configure events by passing the app identifier, action identifier, and labels through the payload. Download Event Data : Export event data for further analysis.
  • [Create Event](https://orchestrateapi.cyware.com/events/create-event.md): Create an event by passing the app identifier, action identifier, and data through the payload.
  • [Create Event (v2)](https://orchestrateapi.cyware.com/events/create-event-v2.md): Create an event by passing the app identifier, action identifier, and data through the payload. This endpoint provides a concise response with key parameters. This API is available in Orchestrate v3.5.9 onwards.
  • [Get Events](https://orchestrateapi.cyware.com/events/list-source-events.md): Returns the list of triggered events.
  • [Get Event Details](https://orchestrateapi.cyware.com/events/source-event-details.md): Returns the details of a specific triggered event.
  • [Configure Trigger](https://orchestrateapi.cyware.com/events/configure-event.md): Configure a trigger by passing the app identifier, action identifier, and labels through the payload.
  • [Download Event Data](https://orchestrateapi.cyware.com/events/event-data-downlaod.md): Download large files from event data.
• [Tags](https://orchestrateapi.cyware.com/tags.md): A playbook tag can be used to define role-based access control (RBAC) for playbooks. To configure RBAC, analysts must create playbook tags and associate them with both playbooks and user groups in Respond. Members of a Respond user group can execute playbooks only if the assigned tags match those of the user group. For more information, see Create Playbook Tags . You can perform the following actions in this module: Retrieve Tags : Fetch the list of tags. Retrieve Tag Details : Fetch the details of a specific tag.
  • [Get Tags List](https://orchestrateapi.cyware.com/tags/get-list-of-tags.md): Returns the list of tags.
  • [Get Tag Details](https://orchestrateapi.cyware.com/tags/get-tag-details.md): Returns the details of a specific tag.
• [Webhooks](https://orchestrateapi.cyware.com/webhooks.md): 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 Orchestrate application. Webhooks module allows users to create and manage webhook configurations and tokens. Users will be able to access features based on the permissions assigned to the user in the Orchestrate application. For more information, see Configure Webhooks . Authentication These APIs require a webhook token as a mandatory parameter. Generate Webhook Credentials Navigate to the Admin Panel and select Webhooks . Click Add Webhook and enter the webhook details. After entering the details, click Generate Webhook URL . After the webhook URL is generated, copy the token and the Base URL displayed to you, and then configure the keys in the required application. You can perform the following actions in this module: Test Connectivity : Verify the webhook connection to ensure a successful event creation. Create Events : Create new events with either detailed or concise response data. Create Events through Payload : Create new events by passing the app identifier, action identifier, and data through the payload.
  • [Test connectivity](https://orchestrateapi.cyware.com/webhooks/test-connectivity.md): Use this API to test the connectivity.
  • [Create Event](https://orchestrateapi.cyware.com/webhooks/create-event.md): Creates an event by passing the app identifier and action identifier through the URL and data through the payload. Note : Starting from Orchestrate v3.5.9, the webhook URLs generated in the Orchestrate platform are updated to provide concise responses with key parameters 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 .
  • [Create Event (v2)](https://orchestrateapi.cyware.com/webhooks/create-event-v2.md): Creates an event by passing the app identifier and action identifier through the URL and data through the 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 .
  • [Create Events through Payload](https://orchestrateapi.cyware.com/webhooks/create-events-through-payload.md): 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 a concise response with key parameters. 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 .
  • [Create Events through Payload (v2)](https://orchestrateapi.cyware.com/webhooks/create-events-through-payload-v2.md): 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.