Findings Intake API Docs

The Findings Intake API facilitates the ingestion of custom security findings into the XDR data warehouse leveraging the Open Cybersecurity Schema Framework (OCSF v1.4). This enables seamless integration of external threat data, enhancing Cisco XDR's detection and response capabilities.

Note: At this time (September, 2025) the Findings Intake service is in Beta, which means not all features are available yet. The main consumer of this API currently is the new Custom Security Event Workflow. More functionality will be released to the Findings Intake service before the Beta flag is removed. For step-by-step instructions on how to use the new Custom Security Event Workflow, see the Getting Started with Custom Security Events guide.

Use Cases

• Custom Data Integration: allows organizations to bring their own threat intelligence or security findings into Cisco XDR.
• Automated Ingestion: facilitates the automated flow of external findings into the XDR platform.
• Enhanced Correlation: integrates external data with native telemetry sources for comprehensive threat analysis.

How to use the API Docs

Use the interactive documentation to explore the Findings Intake API endpoints. Each request includes a complete description of all required parameters and allows you to try it out instantly 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 are pre-filled, allowing you to make read-only API requests. These credentials allow you to obtain an Access Token, which is stored for subsequent requests and automatically regenerated when it expires.

Note: The interactive documentation uses read-only credentials, and the try it out feature only works with GET and selected POST requests. To try other Findings Intake API requests, go to https://findings.us.security.cisco.com/swagger-ui#/.

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 Findings Intake OpenAPI Specification

Download the Findings Intake OpenAPI specification (OAS) file here.

Sample Code

Below is an example of how to use the Findings Intake API.

Important note: The value of the module-instance-id header is mapped to an Integration Module in your XDR tenant. This is resolved by the Findings Intake API and used as the name of the Custom Event Source. This can be of Module Instance of an existing Integration Module Type (e.g. Splunk), or you can create a placeholder Module Instance using the new Custom OCSF Event Source Module Type (change URL to .eu. or .apjc. as needed). This ID, and the optional Workflow Run ID, are output variable references automatically set by the system when using the Workflow Intent "Custom Security Event".

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
module_instance_id = ''

url = "https://findings.us.security.cisco.com/api/v1/custom_detection_findings"

payload = '''{
    "detection_findings": {
        "attacks": [
            {
                "tactic": { "uid": "TA0001" }
            }
        ],
        "confidence": "Unknown",
        "dispositions": [
            {
                "disposition": "Unknown",
                "disposition_status": "Unknown"
            }
        ],
        "finding_info": { "types": [ "Email" ] },
        "metadata": {
            "labels": [ "intake-api-finding" ]
        },
        "severity": "Unknown",
        "status": "Unknown"
    },
    "email_activity": [
        {
            "activity_name": "Send",
            "direction": "Unknown",
            "dispositions": [
                {
                    "disposition": "Unknown",
                    "disposition_status": "Unknown"
                }
            ],
            "email": {
                "files": [
                    {
                        "hashes": [
                            {
                                "algorithm": "Unknown"
                            }
                        ],
                        "type": "Unknown"
                    }
                ]
            }
        }
    ],
    "network_activity": [
        {
            "activity_name": "Unknown",
            "connection_info": {
                "direction": "Unknown",
                "protocol_num": 1,
                "protocol_ver_id": 0
            },
            "dispositions": [
                {
                    "disposition": "Unknown",
                    "disposition_status": "Unknown"
                }
            ]
        }
    ]
}'''

headers = {
    "Authorization": bearer_token,
    "Accept": "application/json",
    "Content-Type": "application/json",
    "module-instance-id": module_instance_id
}

response = requests.request('POST', url, headers=headers, data = payload)

print(response.text)