<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# SOAR Playbook Development — API Reference

## Cortex XSOAR API

```python
import requests

XSOAR_URL = "https://xsoar.corp.local"
API_KEY = "your-api-key"
HEADERS = {"Authorization": API_KEY, "Content-Type": "application/json"}

# Create incident
resp = requests.post(f"{XSOAR_URL}/incident", headers=HEADERS, json={
    "name": "Malware detected on workstation-42",
    "type": "Malware",
    "severity": 3,
    "labels": [{"type": "host", "value": "workstation-42"}],
})

# Run playbook on incident
requests.post(f"{XSOAR_URL}/incident/investigate", headers=HEADERS, json={
    "id": "12345",
    "playbookId": "isolate-compromised-host",
})

# Get playbook execution status
resp = requests.get(f"{XSOAR_URL}/inv-playbook/12345", headers=HEADERS)
```

## Shuffle SOAR API

```python
SHUFFLE_URL = "https://shuffle.corp.local"
SHUFFLE_API = "your-shuffle-api-key"

# Trigger workflow
requests.post(f"{SHUFFLE_URL}/api/v1/workflows/{workflow_id}/execute", headers={
    "Authorization": f"Bearer {SHUFFLE_API}",
}, json={"execution_argument": json.dumps(alert_data)})

# Get execution results
requests.get(f"{SHUFFLE_URL}/api/v1/workflows/{workflow_id}/executions", headers={
    "Authorization": f"Bearer {SHUFFLE_API}",
})
```

## Jira Ticket Creation

```python
from jira import JIRA

jira = JIRA(server="https://jira.corp.local", basic_auth=("svc-soar", "token"))

issue = jira.create_issue(
    project="SEC",
    summary="Security incident: malware on workstation-42",
    description="Automated ticket from SOAR playbook.",
    issuetype={"name": "Incident"},
    priority={"name": "Critical"},
)
```

## Playbook Action Contract

```python
def action_function(alert: dict, context: dict) -> dict:
    """
    Parameters:
        alert: Original alert data with keys: alert_id, hostname, severity, source
        context: Accumulated results from prior steps

    Returns:
        dict with action-specific output; must be JSON-serializable

    Raises:
        Exception: triggers on_failure handler in playbook engine
    """
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Playbook completed successfully |
| 1 | Playbook completed with warnings |
| 2 | Playbook execution failed |
