Custom Rules API

Create custom moderation rules tailored to your platform's needs. Rules can use keywords, regex patterns, or semantic matching.

Endpoints

POST/api/v1/moderation/rulesCreate a new rulerules:write

GET/api/v1/moderation/rulesList all rulesrules:read

GET/api/v1/moderation/rules/:ruleIdGet rule detailsrules:read

PUT/api/v1/moderation/rules/:ruleIdUpdate a rulerules:write

DELETE/api/v1/moderation/rules/:ruleIdDelete a rulerules:write

POST/api/v1/moderation/rules/:ruleId/testTest a rule against contentrules:read

Rule Types

keyword

Match specific words or phrases

{
  "ruleType": "keyword",
  "ruleDefinition": {
    "keywords": ["spam", "scam", "click here"],
    "keywordMatchMode": "any",
    "caseSensitive": false
  }
}

regex

Match patterns using regular expressions

{
  "ruleType": "regex",
  "ruleDefinition": {
    "patterns": [
      "PRIVATE-[0-9]{4}"
    ]
  }
}

semantic

Classify content against your categories using AI

{
  "ruleType": "semantic",
  "ruleDefinition": {
    "semanticCategories": [
      "financial_advice",
      "medical_claims",
      "conspiracy_theories"
    ],
    "semanticThreshold": 0.75
  }
}

combined

Combine multiple matching strategies

{
  "ruleType": "combined",
  "ruleDefinition": {
    "keywords": ["investment", "guaranteed returns"],
    "semanticCategories": ["financial_advice"],
    "semanticThreshold": 0.6,
    "contextExclusions": ["educational", "news"]
  }
}

Create Rule

POST/api/v1/moderation/rules

Request Body

Parameter	Type	Description
`name`required Rule name (1-100 characters).	`string`	Rule name (1-100 characters).
`description` Optional description (max 500 characters).	`string`	Optional description (max 500 characters).
`ruleType`required One of: "keyword", "regex", "semantic", "combined".	`string`	One of: "keyword", "regex", "semantic", "combined".
`ruleDefinition`required Rule matching configuration (varies by type).	`object`	Rule matching configuration (varies by type).
`action`required Action when triggered. One of: "flag", "reject", "escalate".	`string`	Action when triggered. One of: "flag", "reject", "escalate".
`severity` One of: "minor", "moderate", "severe".	`string` Default: "moderate"	One of: "minor", "moderate", "severe".
`priority` Rule priority (1-1000). Lower numbers run first.	`number` Default: 100	Rule priority (1-1000). Lower numbers run first.

Rule Definition Fields

Parameter	Type	Description
`keywords` Keywords to match (for keyword/combined types).	`string[]`	Keywords to match (for keyword/combined types).
`keywordMatchMode` "any" = match any keyword, "all" = match all, "phrase" = exact phrase.	`string` Default: "any"	"any" = match any keyword, "all" = match all, "phrase" = exact phrase.
`caseSensitive` Whether keyword matching is case-sensitive.	`boolean` Default: false	Whether keyword matching is case-sensitive.
`patterns` Regex patterns (for regex/combined types).	`string[]`	Regex patterns (for regex/combined types).
`semanticCategories` AI categories to detect (for semantic/combined).	`string[]`	AI categories to detect (for semantic/combined).
`semanticThreshold` Minimum confidence for semantic match (0-1).	`number` Default: 0.7	Minimum confidence for semantic match (0-1).
`contextExclusions` Case-insensitive substrings of content that bypass this rule. Use narrowly; these are not inferred context labels.	`string[]`	Case-insensitive substrings of content that bypass this rule. Use narrowly; these are not inferred context labels.

Example Request

json

{
  "name": "No Cryptocurrency Promotion",
  "description": "Block promotional content about cryptocurrency investments",
  "ruleType": "combined",
  "ruleDefinition": {
    "keywords": ["buy crypto", "moon", "HODL", "guaranteed returns"],
    "keywordMatchMode": "any",
    "semanticCategories": ["financial_promotion", "cryptocurrency"],
    "semanticThreshold": 0.65,
    "contextExclusions": ["news", "educational"]
  },
  "action": "reject",
  "severity": "moderate",
  "priority": 700
}

Response

HTTP 201 returns an object containing rule. Its ID is a UUID. The SDK unwraps that object and returns the created rule directly.

typescript

console.log(rule.id, rule.name, rule.isActive);
console.log(rule.createdAt, rule.updatedAt);

Test Rule

POST/api/v1/moderation/rules/:ruleId/test

Test one rule against 1–10,000 characters of content. This evaluates the rule directly without creating a completed moderation request. The HTTP response contains rule, test, and result; result has triggered, explanation, and matches. The SDK returns result directly. Semantic evaluation still requires an available provider.

json

{
  "content": "Buy DOGE now! 100x guaranteed returns! This is your chance to moon!"
}

Code Examples

typescript

import { CommunitAIModerator } from '@communitai/maas';
import { env } from '@/env';

const client = new CommunitAIModerator({
  apiKey: env.COMMUNITAI_API_KEY, // Import your application's validated server configuration.
});

// Create a rule
const rule = await client.createRule({
  name: "No Personal Attacks",
  ruleType: "semantic",
  ruleDefinition: {
    semanticCategories: ["personal_attack", "harassment"],
    semanticThreshold: 0.7,
  },
  action: "reject",
  severity: "severe",
});

console.log(`Created rule: ${rule.id}`);

// Test the rule
const test = await client.testRule(rule.id, "You're an idiot and should be banned");

console.log(test.triggered, test.explanation, test.matches);

// List all rules
const rules = await client.listRules({ activeOnly: true });
console.log(`Active rules: ${rules.length}`);

// Disable a rule
await client.updateRule(rule.id, { isActive: false });

Example Semantic Categories

Categories are your text descriptions sent to the classifier, not a fixed enum. Choose precise descriptions for your policy. These are examples:

Safety

hate_speech
harassment
violence
self_harm
sexual_content
dangerous_activity

Spam & Fraud

spam
scam
phishing
fake_news
misinformation
clickbait

Financial

financial_advice
financial_promotion
cryptocurrency
investment_scheme
gambling

Content

personal_attack
profanity
adult_content
political_content
religious_content

Custom Rules API

Create custom moderation rules tailored to your platform's needs. Rules can use keywords, regex patterns, or semantic matching.

Endpoints

POST/api/v1/moderation/rulesCreate a new rulerules:write

GET/api/v1/moderation/rulesList all rulesrules:read

GET/api/v1/moderation/rules/:ruleIdGet rule detailsrules:read

PUT/api/v1/moderation/rules/:ruleIdUpdate a rulerules:write

DELETE/api/v1/moderation/rules/:ruleIdDelete a rulerules:write

POST/api/v1/moderation/rules/:ruleId/testTest a rule against contentrules:read

Rule Types

keyword

Match specific words or phrases

{
  "ruleType": "keyword",
  "ruleDefinition": {
    "keywords": ["spam", "scam", "click here"],
    "keywordMatchMode": "any",
    "caseSensitive": false
  }
}

regex

Match patterns using regular expressions

{
  "ruleType": "regex",
  "ruleDefinition": {
    "patterns": [
      "PRIVATE-[0-9]{4}"
    ]
  }
}

semantic

Classify content against your categories using AI

{
  "ruleType": "semantic",
  "ruleDefinition": {
    "semanticCategories": [
      "financial_advice",
      "medical_claims",
      "conspiracy_theories"
    ],
    "semanticThreshold": 0.75
  }
}

combined

Combine multiple matching strategies

{
  "ruleType": "combined",
  "ruleDefinition": {
    "keywords": ["investment", "guaranteed returns"],
    "semanticCategories": ["financial_advice"],
    "semanticThreshold": 0.6,
    "contextExclusions": ["educational", "news"]
  }
}

Create Rule

POST/api/v1/moderation/rules

Request Body

Parameter	Type	Description
`name`required Rule name (1-100 characters).	`string`	Rule name (1-100 characters).
`description` Optional description (max 500 characters).	`string`	Optional description (max 500 characters).
`ruleType`required One of: "keyword", "regex", "semantic", "combined".	`string`	One of: "keyword", "regex", "semantic", "combined".
`ruleDefinition`required Rule matching configuration (varies by type).	`object`	Rule matching configuration (varies by type).
`action`required Action when triggered. One of: "flag", "reject", "escalate".	`string`	Action when triggered. One of: "flag", "reject", "escalate".
`severity` One of: "minor", "moderate", "severe".	`string` Default: "moderate"	One of: "minor", "moderate", "severe".
`priority` Rule priority (1-1000). Lower numbers run first.	`number` Default: 100	Rule priority (1-1000). Lower numbers run first.

Rule Definition Fields

Parameter	Type	Description
`keywords` Keywords to match (for keyword/combined types).	`string[]`	Keywords to match (for keyword/combined types).
`keywordMatchMode` "any" = match any keyword, "all" = match all, "phrase" = exact phrase.	`string` Default: "any"	"any" = match any keyword, "all" = match all, "phrase" = exact phrase.
`caseSensitive` Whether keyword matching is case-sensitive.	`boolean` Default: false	Whether keyword matching is case-sensitive.
`patterns` Regex patterns (for regex/combined types).	`string[]`	Regex patterns (for regex/combined types).
`semanticCategories` AI categories to detect (for semantic/combined).	`string[]`	AI categories to detect (for semantic/combined).
`semanticThreshold` Minimum confidence for semantic match (0-1).	`number` Default: 0.7	Minimum confidence for semantic match (0-1).
`contextExclusions` Case-insensitive substrings of content that bypass this rule. Use narrowly; these are not inferred context labels.	`string[]`	Case-insensitive substrings of content that bypass this rule. Use narrowly; these are not inferred context labels.

Example Request

json

{
  "name": "No Cryptocurrency Promotion",
  "description": "Block promotional content about cryptocurrency investments",
  "ruleType": "combined",
  "ruleDefinition": {
    "keywords": ["buy crypto", "moon", "HODL", "guaranteed returns"],
    "keywordMatchMode": "any",
    "semanticCategories": ["financial_promotion", "cryptocurrency"],
    "semanticThreshold": 0.65,
    "contextExclusions": ["news", "educational"]
  },
  "action": "reject",
  "severity": "moderate",
  "priority": 700
}

Response

HTTP 201 returns an object containing rule. Its ID is a UUID. The SDK unwraps that object and returns the created rule directly.

typescript

console.log(rule.id, rule.name, rule.isActive);
console.log(rule.createdAt, rule.updatedAt);

Test Rule

POST/api/v1/moderation/rules/:ruleId/test

json

{
  "content": "Buy DOGE now! 100x guaranteed returns! This is your chance to moon!"
}

Code Examples

typescript

import { CommunitAIModerator } from '@communitai/maas';
import { env } from '@/env';

const client = new CommunitAIModerator({
  apiKey: env.COMMUNITAI_API_KEY, // Import your application's validated server configuration.
});

// Create a rule
const rule = await client.createRule({
  name: "No Personal Attacks",
  ruleType: "semantic",
  ruleDefinition: {
    semanticCategories: ["personal_attack", "harassment"],
    semanticThreshold: 0.7,
  },
  action: "reject",
  severity: "severe",
});

console.log(`Created rule: ${rule.id}`);

// Test the rule
const test = await client.testRule(rule.id, "You're an idiot and should be banned");

console.log(test.triggered, test.explanation, test.matches);

// List all rules
const rules = await client.listRules({ activeOnly: true });
console.log(`Active rules: ${rules.length}`);

// Disable a rule
await client.updateRule(rule.id, { isActive: false });

Example Semantic Categories

Categories are your text descriptions sent to the classifier, not a fixed enum. Choose precise descriptions for your policy. These are examples:

Safety

hate_speech
harassment
violence
self_harm
sexual_content
dangerous_activity

Spam & Fraud

spam
scam
phishing
fake_news
misinformation
clickbait

Financial

financial_advice
financial_promotion
cryptocurrency
investment_scheme
gambling

Content

personal_attack
profanity
adult_content
political_content
religious_content