Smart Rule Builder API

API reference for the Smart Rule Builder (Org DLP Rules). All endpoints are org-scoped and require admin authentication. See the Smart Rule Builder admin guide for feature documentation and best practices.

Base path: /api/orgs/{org_id}/dlp-rules

Authentication: Authorization: Bearer <admin-jwt> on all requests. Requires org-admin or platform-admin role.

Path parameters: org_id (UUID) — the organization ID, present on all endpoints.

---

POST /api/orgs/{org_id}/dlp-rules/generate-regex

Generate a regex pattern from a natural language description using a three-tier LLM escalation chain (Haiku -> Sonnet -> Opus). Each candidate regex is mechanically tested against the provided examples.

Request Body

Field	Type	Required	Description
description	string	Yes	Natural language description of what to detect. 1–2,000 characters.
positive_examples	string[]	Yes	Strings that should match. At least one required.
negative_examples	string[]	Yes	Strings that should not match. At least one required.

{
  "description": "Internal project codes in the format PROJ-XXXX where X is a digit",
  "positive_examples": ["PROJ-1234", "PROJ-0001", "See PROJ-9999 for details"],
  "negative_examples": ["PROJECT-123", "proj-1234", "PROJ-ABCD"]
}

Response

{
  "candidate_regex": "PROJ-\\d{4}",
  "model_used": "haiku",
  "pass_rate": 1.0,
  "recommendation": "regex"
}

Field	Type	Description
candidate_regex	string or null	The generated regex, or null if all models failed.
model_used	string or null	Which model succeeded: haiku, sonnet, opus, or null.
pass_rate	float	Fraction of examples passed by the best candidate (0.0–1.0).
recommendation	string	regex if a pattern was found, ai_detector if all models failed.

Error Responses

Status	Condition
422	Validation error (empty description, no examples).
503	No Anthropic provider configured.

---

GET /api/orgs/{org_id}/dlp-rules/

List all custom DLP rules for the organization (paginated). Soft-deleted rules are excluded.

Response

[
  {
    "id": "a1b2c3d4-...",
    "org_id": "e5f6a7b8-...",
    "rule_type": "custom_pattern",
    "name": "Internal Project Codes",
    "pattern": "PROJ-\\d{4}",
    "target_rule_id": null,
    "enabled": true,
    "action_tier": "redact",
    "custom_entity_type": "internal_project_code",
    "ai_description": null,
    "ai_examples_positive": null,
    "ai_examples_negative": null,
    "ai_engine": null,
    "auto_regex_candidate": "PROJ-\\d{4}",
    "auto_regex_model": "haiku",
    "created_by": "f9e8d7c6-...",
    "created_at": "2026-03-15T10:30:00Z",
    "updated_at": "2026-03-15T10:30:00Z"
  }
]

---

POST /api/orgs/{org_id}/dlp-rules/

Create a new org DLP rule. The rule_type field determines which fields are required.

Request Body

Field	Type	Required	Default	Description
rule_type	string	Yes	—	custom_pattern, suppress_default, or ai_detector.
name	string	Yes	—	Human-readable label. 1–255 characters.
pattern	string	Conditional	null	Required for custom_pattern. Must be valid Python regex.
target_rule_id	string	Conditional	null	Required for suppress_default. Platform rule name/ID to suppress.
enabled	boolean	No	true	Whether the rule is active.
action_tier	string	No	log_only	log_only, redact, block, or prompt.
custom_entity_type	string	No	null	Custom label for matches. Defaults to org_custom_pattern at runtime.
ai_description	string	Conditional	null	Required for ai_detector. Natural language description.
ai_examples_positive	string[]	No	null	Examples that should match (for ai_detector).
ai_examples_negative	string[]	No	null	Examples that should not match (for ai_detector).
ai_engine	string	Conditional	null	Required for ai_detector. nli or llm.
auto_regex_candidate	string	No	null	Regex from the AI generator (stored for audit).
auto_regex_model	string	No	null	Which model generated the regex: haiku, sonnet, or opus.

Validation Rules

• custom_pattern — pattern is required and must compile as a valid Python regex.
• suppress_default — target_rule_id is required.
• ai_detector — ai_description and ai_engine are required. ai_engine must be nli or llm.

Example: Custom Pattern

{
  "rule_type": "custom_pattern",
  "name": "Internal Project Codes",
  "pattern": "PROJ-\\d{4}",
  "action_tier": "redact",
  "custom_entity_type": "internal_project_code",
  "auto_regex_candidate": "PROJ-\\d{4}",
  "auto_regex_model": "haiku"
}

Example: Suppress Default

{
  "rule_type": "suppress_default",
  "name": "Disable UK Phone Number Detection",
  "target_rule_id": "uk_phone_number"
}

Example: AI Detector

{
  "rule_type": "ai_detector",
  "name": "Project Aurora References",
  "ai_description": "References to Project Aurora internal milestones, codenames, or deliverables",
  "ai_engine": "nli",
  "ai_examples_positive": ["Aurora Phase 2 milestone", "the Aurora deliverable is due Friday"],
  "ai_examples_negative": ["aurora borealis forecast", "the Aurora database migration"],
  "action_tier": "log_only"
}

Response

Returns the created rule as an OrgDLPRuleResponse (see GET response above). Status 201.

---

GET /api/orgs/{org_id}/dlp-rules/{rule_id}

Retrieve a single rule by ID.

Path Parameters

Parameter	Type	Description
rule_id	UUID	The rule ID.

Response

Returns an OrgDLPRuleResponse object.

---

PUT /api/orgs/{org_id}/dlp-rules/{rule_id}

Update an existing rule. Only provided fields are modified. Changing enabled from true to false (or vice versa) writes a dedicated enabled or disabled audit action.

Request Body

All fields are optional. Only include fields you want to change.

Field	Type	Description
name	string	1–255 characters.
pattern	string	Must be valid Python regex if provided.
enabled	boolean	Enable or disable the rule.
action_tier	string	log_only, redact, block, or prompt.
custom_entity_type	string	Custom label for matches.
ai_description	string	Updated natural language description.
ai_examples_positive	string[]	Updated positive examples.
ai_examples_negative	string[]	Updated negative examples.
ai_engine	string	nli or llm.
auto_regex_candidate	string	Updated auto-generated regex.
auto_regex_model	string	Model that generated the regex.

Response

Returns the updated rule as an OrgDLPRuleResponse object.

---

DELETE /api/orgs/{org_id}/dlp-rules/{rule_id}

Soft-delete a rule. The rule is marked with a deleted_at timestamp and excluded from active evaluation. Returns 204 No Content.

---

POST /api/orgs/{org_id}/dlp-rules/{rule_id}/test

Test a rule against sample text. Returns all matches found by the rule’s detection engine.

Request Body

Field	Type	Required	Description
sample_text	string	Yes	Text to test against. 1–10,000 characters.

{
  "sample_text": "Please review PROJ-1234 and PROJ-5678 before the deadline."
}

Response

{
  "match_count": 2,
  "engine": "regex",
  "matches": [
    {
      "matched_text": "PROJ-1234",
      "start": 14,
      "end": 23,
      "confidence": 1.0
    },
    {
      "matched_text": "PROJ-5678",
      "start": 28,
      "end": 37,
      "confidence": 1.0
    }
  ]
}

Field	Type	Description
match_count	integer	Total matches found.
engine	string	Detection engine used: regex, nli, or llm.
matches	array	List of match objects.
matches[].matched_text	string	The text that matched.
matches[].start	integer	Start character offset.
matches[].end	integer	End character offset.
matches[].confidence	float	Confidence score. 1.0 for regex; variable for NLI/LLM.

---

GET /api/orgs/{org_id}/dlp-rules/effective

Returns the merged effective rule set for the organization: platform defaults combined with org custom rules and suppressions. This is the authoritative view of what the DLP pipeline evaluates.

Response

{
  "org_id": "e5f6a7b8-...",
  "platform_rules_count": 42,
  "org_rules_count": 3,
  "suppressed_count": 1,
  "rules": [
    {
      "name": "Credit Card Number",
      "source": "platform",
      "rule_type": "platform_default",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5]...)\\b",
      "enabled": true,
      "suppressed": false,
      "suppressed_by": null
    },
    {
      "name": "UK Phone Number",
      "source": "platform",
      "rule_type": "platform_default",
      "pattern": "...",
      "enabled": true,
      "suppressed": true,
      "suppressed_by": "b2c3d4e5-..."
    },
    {
      "name": "Internal Project Codes",
      "source": "org",
      "rule_type": "custom_pattern",
      "pattern": "PROJ-\\d{4}",
      "enabled": true,
      "suppressed": false,
      "suppressed_by": null
    }
  ]
}

Field	Type	Description
org_id	string	Organization UUID.
platform_rules_count	integer	Number of platform default rules.
org_rules_count	integer	Number of org custom rules.
suppressed_count	integer	Number of platform rules suppressed by org rules.
rules	array	Merged rule list.
rules[].name	string	Rule name.
rules[].source	string	platform or org.
rules[].rule_type	string	platform_default, custom_pattern, or suppress_default.
rules[].pattern	string or null	Regex pattern (if applicable).
rules[].enabled	boolean	Whether the rule is active.
rules[].suppressed	boolean	Whether a platform rule is suppressed by an org rule.
rules[].suppressed_by	string or null	UUID of the suppressing org rule.

---

DLP Scan Level

These endpoints control the DLP scan depth for the organization. They use a separate base path.

Base path: /api/v1/admin/org/dlp-scan-level

GET /api/v1/admin/org/dlp-scan-level

Returns the current DLP scan level for the admin’s organization.

Response

{
  "org_id": "e5f6a7b8-...",
  "scan_level": "full",
  "updated_at": "2026-03-15T10:30:00Z"
}

Field	Type	Description
org_id	UUID	Organization ID.
scan_level	string	full, regex_only, or off.
updated_at	datetime or null	Last change timestamp. null if default has never been overridden.

PUT /api/v1/admin/org/dlp-scan-level

Set the DLP scan level for the admin’s organization.

Request Body

Field	Type	Required	Description
scan_level	string	Yes	full, regex_only, or off.

{
  "scan_level": "regex_only"
}

Response

Returns the updated OrgDLPScanLevelResponse.