Rules API

The Rules API lets you programmatically manage scoring rules, including creating, updating, and testing rules.

List Rules

GET /v1/rules

Query Parameters:
  category    string    Filter by category (identity, email, endpoint, training, custom)
  status      string    Filter by status (active, inactive)
  page        integer   Page number
  per_page    integer   Results per page

Response:
{
  "data": [
    {
      "id": "rule_abc123",
      "name": "Phishing Link Clicked",
      "event_type": "sim.link_clicked",
      "category": "email",
      "impact": -25,
      "cooldown": "24h",
      "conditions": {},
      "priority": 200,
      "is_default": true,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": { ... }
}

Get Rule

GET /v1/rules/:id

Create Rule

POST /v1/rules

Body:
{
  "name": "Custom Policy Violation",
  "event_type": "custom.policy_violation",
  "category": "custom",
  "impact": -15,
  "cooldown": "1h",
  "conditions": {
    "severity": "medium"
  },
  "priority": 100
}

Response:
{
  "id": "rule_new789",
  "name": "Custom Policy Violation",
  "status": "active",
  ...
}

Update Rule

PATCH /v1/rules/:id

Body:
{
  "impact": -20,
  "cooldown": "2h"
}
Rule Changes
Rule changes take effect immediately for new events. Existing scores are not retroactively recalculated. Use the recalculation endpoint if needed.

Delete Rule

DELETE /v1/rules/:id

Note: Default rules cannot be deleted, only deactivated.

Test Rule (Dry Run)

POST /v1/rules/:id/test

Query Parameters:
  from        string    Start date for historical evaluation
  to          string    End date for historical evaluation

Response:
{
  "rule_id": "rule_new789",
  "events_matched": 45,
  "employees_affected": 32,
  "average_impact": -15,
  "score_changes": [
    {
      "employee_id": "emp_abc123",
      "current_score": 72,
      "projected_score": 57
    }
  ]
}

Trigger Recalculation

POST /v1/rules/recalculate

Body:
{
  "scope": "all"  // or "department": "Engineering"
}

Note: This is an async operation. Response includes a
job_id to poll for completion.
Rate Limits
Recalculation requests are limited to 1 per hour for Professional plans and 4 per hour for Enterprise plans.

Next Steps