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

## Workflow DAG Definition

```python
from dataclasses import dataclass, field

@dataclass
class WorkflowStep:
    """
    Fields:
        step_id: Unique step identifier within the workflow
        name: Human-readable step name
        action: Action function to execute
        depends_on: List of step_ids that must complete first
        condition: Optional expression evaluated before execution
        timeout_minutes: Max execution time before timeout
        on_failure: halt | skip | retry — failure behavior
    """
```

## Tines Automation API

```python
import requests

TINES_URL = "https://tenant.tines.com/api/v1"
HEADERS = {"Authorization": "Bearer <token>", "Content-Type": "application/json"}

# Trigger a story (workflow)
requests.post(f"{TINES_URL}/stories/{story_id}/trigger", headers=HEADERS, json={
    "alert_id": "ALT-001",
    "severity": "critical",
})

# Get story run status
requests.get(f"{TINES_URL}/stories/{story_id}/runs", headers=HEADERS)
```

## PagerDuty Escalation

```python
# Create incident for approval gate escalation
requests.post("https://events.pagerduty.com/v2/enqueue", json={
    "routing_key": "your-integration-key",
    "event_action": "trigger",
    "payload": {
        "summary": "Approval required: incident containment",
        "severity": "critical",
        "source": "workflow-orchestrator",
    },
})
```

## Slack Notification

```python
requests.post("https://slack.com/api/chat.postMessage", headers={
    "Authorization": "Bearer xoxb-your-token",
}, json={
    "channel": "#soc-alerts",
    "text": "Workflow step completed: containment executed",
})
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Workflow completed within SLA |
| 1 | Workflow completed but SLA breached |
| 2 | Workflow execution halted on failure |
