Incident Management API Docs

This new Incident Management (IROH/Private-Intel) API allows developers manage their prioritized Incidents, and the related Worklog Notes. You can create a custom Incident, query existing incidents based on MITRE metadata and more. You are also able to retrieve Worklog details for a specific incident and even create a custom Worklog Note.

Note: In Cisco XDR, some Private Intelligence functions (e.g. creating and managing of CTIM objects like Judgements and Indicators) are controlled by the legacy CTIA/Private-Intel API.

Note: In Cisco XDR, performing Incident searching and Investigations are performed by the newer Incidents and Investigations API. The creation of Incidents in Cisco XDR is done with the IROH/Private-Intel API.

Note: In Cisco XDR you can use different formats for the ID of objects. You can use the "GUID" (e.g. 64322795-2xx5-49bd-8d0b-106680ae434a), the "short-ID" (e.g. incident-64322795-2xx5-49bd-8d0b-106680ae434a) and even full "CTIA URL" (legacy) is supported for backward compatibility. This has to do with that the APIs are evolving.

Use Cases

Creating custom Incidents
Querying Incidents based on MITRE metadata
Retrieve all notable events for a specific Incident
Retrieve an Incident summary, containing all related threat context
Exporting the Worklog of an Incident
Creating a custom Worklog note for an Incident

How to use the API Docs

Use the interactive documentation to explore the Incident Management API endpoints. Each request will have a complete description of all the required parameters and it also allows you to instantly try it out in the online console. Code templates are also provided for you to quickly build scripts.

In the interactive explorer, the Client ID and Client Secret has been pre-filled and will allow you to make read-only API requests. These credentials will allow you to get an Access Token, which will be stored for subsequent API requests and regenerated when it expires.

Note: The interactive documentation uses read-only credentials and the try it out feature will only work with GET and selected POSTrequests.

To try other Private-Intel API requests, go to https://visibility.amp.cisco.com/iroh/private-intel/index.html

Generate an Access Token

In the interactive API explorer, the Access Token is automatically generated using the pre-filled Client ID and Client Secret so you do not need to generate it yourself.

If you want to understand how the Access Token is generated from the Client ID and Client Secret credentials, take a look at the Authentication page.

For detailed instructions on how to use the interactive API documentation (or your own Python script), see the Getting Started page.

Download the Private-Intel OpenAPI Specification

Download the Incident Management OpenAPI specification (OAS) file here.

Sample Code

Below is an example of how to use the Incident Management API to retrieve a summary for a specific incident.

import json
import requests

# create headers for API request (See the OAuth2 overview page for sample code to generate an access token)
access_token = 'eyJhbGciO....bPito5n5Q' # truncated example, generate JWT token separately
bearer_token = 'Bearer ' + access_token
incident_id = 'incident-xxxxxxx-88fc-46a8-9d62-b58dbc9a47b6'

# search incidents in the private-intel
url = f'https://visibility.amp.cisco.com/iroh/private-intel/incident/{incident_id}/summary'

headers = {
            'Authorization': bearer_token,
            'Content-Type':'application/json',
            'Accept':'application/json'
}

response = requests.get(url, headers=headers)
print(response.text)

if response.status_code == 200:
    # convert the response to a dict object
    response_json = json.loads(response.text)

    # get the values from an incident (remainder values are accessed in the same way)
    linkedIncidents = response_json['linkedIncidents']
    for linkedIncident in linkedIncidents:
        title = linkedIncident['title']
        description = linkedIncident['description']
    observables = response_json['observables']
    total_count_observables = observables['totalCount']
    severity = response_json['severity']
    total_count_severity = severity['totalCount']

Download OpenAPI Document