TorkTORK
Docs/API Reference/Notification Routing

Notification Routing API

Configure how governance alerts are routed to stakeholders, with escalation policies and channel-specific delivery.

Endpoints

GET/v1/notifications/routingGet routing configuration
PUT/v1/notifications/routingUpdate routing rules
POST/v1/notifications/testSend test notification

Authentication

All notification routing endpoints require API key authentication via the x-tork-api-key header or Authorization: Bearer header.

Admin Rate Limit
These endpoints are subject to admin-level rate limiting.

Get Routing Configuration

GET/v1/notifications/routing

Returns the current routing configuration including rules, stakeholders, escalation settings, and recent notification history.

Response Fields

FieldTypeDescription
configobjectCurrent routing configuration with rules, stakeholders, and escalation settings
historyarrayLast 50 notification deliveries with timestamps and status
labels.stakeholdersstring[]Available stakeholder identifiers
labels.channelsstring[]Delivery channels: email, slack, webhook, sms
labels.eventsstring[]Supported event types for routing rules

Example

bash
curl -X GET "https://api.tork.network/v1/notifications/routing" \
  -H "x-tork-api-key: tork_sk_your_api_key"
json
{
  "config": {
    "stakeholders": [
      { "id": "eng-lead", "name": "Engineering Lead", "channels": ["email", "slack"] }
    ],
    "rules": [
      { "event": "PII_DETECTED", "severity_min": 3, "stakeholder_ids": ["eng-lead"], "channels": ["slack"] }
    ],
    "escalation": {
      "critical_timeout_minutes": 15,
      "high_timeout_minutes": 60
    }
  },
  "history": [
    { "id": "ntf_abc123", "event": "PII_DETECTED", "severity": 4, "delivered_at": "2026-02-12T10:00:00Z", "channel": "slack", "status": "delivered" }
  ],
  "labels": {
    "stakeholders": ["eng-lead", "security-team", "compliance"],
    "channels": ["email", "slack", "webhook", "sms"],
    "events": ["PII_DETECTED", "EMERGENCY_SHUTDOWN", "POLICY_VIOLATION", "SCORING_ANOMALY"]
  }
}

Update Routing Rules

PUT/v1/notifications/routing

Updates routing rules, stakeholders, or escalation configuration. All fields are optional — only provided fields are updated.

Request Body

ParameterTypeRequiredDescription
stakeholdersarrayNoArray of stakeholder objects with id, name, and channels
rulesarrayNoArray of routing rules with event, severity_min, stakeholder_ids, and channels
escalationobjectNoEscalation timeouts configuration
escalation.critical_timeout_minutesnumberNoMinutes before critical alerts escalate (min: 5)
escalation.high_timeout_minutesnumberNoMinutes before high-severity alerts escalate (min: 15)

Example

bash
curl -X PUT "https://api.tork.network/v1/notifications/routing" \
  -H "x-tork-api-key: tork_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "escalation": {
      "critical_timeout_minutes": 10,
      "high_timeout_minutes": 30
    },
    "rules": [
      {
        "event": "EMERGENCY_SHUTDOWN",
        "severity_min": 1,
        "stakeholder_ids": ["eng-lead", "security-team"],
        "channels": ["slack", "email", "sms"]
      }
    ]
  }'
json
{
  "config": {
    "stakeholders": [...],
    "rules": [
      { "event": "EMERGENCY_SHUTDOWN", "severity_min": 1, "stakeholder_ids": ["eng-lead", "security-team"], "channels": ["slack", "email", "sms"] }
    ],
    "escalation": {
      "critical_timeout_minutes": 10,
      "high_timeout_minutes": 30
    }
  }
}

Send Test Notification

POST/v1/notifications/test

Send a test notification through the routing engine. Use dry_run to preview routing without delivering.

Request Body

ParameterTypeRequiredDescription
event_typestringYesEvent type to simulate (see valid values below)
severitynumberNoSeverity level 1-5 (clamped to range)
dry_runbooleanNoIf true, preview routing without delivering

Valid event types: PII_DETECTED, EMERGENCY_SHUTDOWN, POLICY_VIOLATION, SCORING_ANOMALY, BOUNTY_SUBMISSION, HIGH_AUTONOMY, RATE_LIMIT_EXCEEDED, KEY_REVOKED

Example: Dry Run

bash
curl -X POST "https://api.tork.network/v1/notifications/test" \
  -H "x-tork-api-key: tork_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "PII_DETECTED",
    "severity": 4,
    "dry_run": true
  }'
json
{
  "mode": "preview",
  "event_type": "PII_DETECTED",
  "severity": 4,
  "matched_rules": 2,
  "would_notify": [
    { "stakeholder": "eng-lead", "channel": "slack" },
    { "stakeholder": "security-team", "channel": "email" }
  ]
}

Error Responses

StatusDescription
400Invalid request body (e.g., invalid event_type, escalation timeout below minimum)
401Missing or invalid API key
429Rate limit exceeded
500Internal server error