POST/api/v1/moderation

Single-Item Moderation

Moderate a single piece of content in real-time. Returns a decision with confidence score and any triggered rules.

Authentication

All requests must include a valid API key in the Authorization header:

http

Authorization: Bearer <your cai_live_ API key>

Request Body

Parameter	Type	Description
`content`required The content to moderate. Maximum 100,000 characters.	`string`	The content to moderate. Maximum 100,000 characters.
`contentType` Use "text". Image and mixed requests currently return 503 because their required evaluation is unavailable.	`string` Default: "text"	Use "text". Image and mixed requests currently return 503 because their required evaluation is unavailable.
`context` Optional context to improve moderation accuracy.	`object`	Optional context to improve moderation accuracy.
`context.platformId` Your platform's identifier for tracking.	`string`	Your platform's identifier for tracking.
`context.communityId` Your external community/channel identifier for tracking.	`string`	Your external community/channel identifier for tracking.
`context.authorReputation` Author reputation score (0-100) for context.	`number`	Author reputation score (0-100) for context.
`rulesConfig` Configure which rules to apply.	`object`	Configure which rules to apply.
`rulesConfig.useGlobalSafety` Apply CommunitAI's global safety rules.	`boolean` Default: true	Apply CommunitAI's global safety rules.
`rulesConfig.customRuleIds` Specific active rules owned by your customer. Missing, inactive, or foreign IDs return 503.	`string[]`	Specific active rules owned by your customer. Missing, inactive, or foreign IDs return 503.
`rulesConfig.interpretation` Rule strictness. One of: "strict", "moderate", "permissive".	`string`	Rule strictness. One of: "strict", "moderate", "permissive".
`options` Additional response options.	`object`	Additional response options.
`options.explain` Include human-readable explanation in response.	`boolean` Default: false	Include human-readable explanation in response.
`options.suggestRewrite` Request a rewrite for eligible nonsevere violations. Returned only after it passes the same policies; it is not guaranteed.	`boolean` Default: false	Request a rewrite for eligible nonsevere violations. Returned only after it passes the same policies; it is not guaranteed.
`options.returnConfidence` Include confidence score in response.	`boolean` Default: true	Include confidence score in response.

Example Request

json

{
  "content": "Check out this amazing offer! Click here now!!!",
  "contentType": "text",
  "context": {
    "communityId": "tech-forum",
    "authorReputation": 45
  },
  "rulesConfig": {
    "useGlobalSafety": true,
    "interpretation": "moderate"
  },
  "options": {
    "explain": true,
    "returnConfidence": true
  }
}

Response

Parameter	Type	Description
`success` Whether the request was processed successfully.	`boolean`	Whether the request was processed successfully.
`data.requestId` Unique identifier for this request.	`string`	Unique identifier for this request.
`data.decision` Moderation decision. One of: "approve", "reject", "warn", "review".	`string`	Moderation decision. One of: "approve", "reject", "warn", "review".
`data.confidence` Confidence score from 0 to 1; omitted when options.returnConfidence=false.	`number`	Confidence score from 0 to 1; omitted when options.returnConfidence=false.
`data.rulesTriggered` List of rules that matched the content.	`array`	List of rules that matched the content.
`data.rulesTriggered[].ruleId` Unique rule identifier.	`string`	Unique rule identifier.
`data.rulesTriggered[].ruleName` Human-readable rule name.	`string`	Human-readable rule name.
`data.rulesTriggered[].severity` Rule severity. One of: "low", "moderate", "high", "critical".	`string`	Rule severity. One of: "low", "moderate", "high", "critical".
`data.rulesTriggered[].matchScore` How strongly the content matched this rule (0-1).	`number`	How strongly the content matched this rule (0-1).
`data.explanation` Human-readable explanation (if options.explain=true).	`string`	Human-readable explanation (if options.explain=true).
`data.suggestedRewrite` Optional verified rewrite when requested and available.	`string`	Optional verified rewrite when requested and available.
`data.processingTimeMs` Server-side processing time in milliseconds.	`number`	Server-side processing time in milliseconds.
`data.modelVersion` Actual evaluation provenance, such as a model identifier or custom-rules.	`string`	Actual evaluation provenance, such as a model identifier or custom-rules.

Recorded Response

From an isolated HTTP test on October 9, 2026 with a customer-owned keyword rule and global safety disabled. The 12 ms value is this observation, not a latency promise.

json

{
  "success": true,
  "data": {
    "requestId": "b80df991-c565-4ebe-bb5f-02ce87074b65",
    "decision": "reject",
    "confidence": 1,
    "rulesTriggered": [
      {
        "ruleId": "4a539406-f9de-4068-95c6-3e8be8dc7d88",
        "ruleName": "Protect private phone numbers",
        "severity": "low",
        "matchScore": 1
      }
    ],
    "explanation": "Custom rules triggered: Protect private phone numbers",
    "processingTimeMs": 12,
    "modelVersion": "custom-rules"
  }
}

Error Responses

400VALIDATION_ERROR

Request body is invalid or missing required fields.

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } }

401UNAUTHORIZED

The Authorization header is missing or contains an invalid key.

{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } }

403FORBIDDEN

Your API key lacks the 'moderate:single' permission.

{ "success": false, "error": { "code": "FORBIDDEN", "message": "API key does not have required permission" } }

429RATE_LIMIT_EXCEEDED

You've exceeded your plan's request limit. Retry after the indicated time.

{ "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded" } }

503MODERATION_UNAVAILABLE

A required provider, policy evaluation, or persistence step failed. Hold the content; this is not an approval. Disabled deployments return SERVICE_UNAVAILABLE.

{ "success": false, "error": { "code": "MODERATION_UNAVAILABLE", "message": "Required moderation is unavailable" } }

500INTERNAL_ERROR

Server error. Contact support if this persists.

{ "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } }

Code Examples

TypeScript

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.
});

async function moderatePost(content: string, communityId: string) {
  const result = await client.moderate({
    content,
    contentType: "text",
    context: { communityId },
    options: { explain: true },
  });

  switch (result.decision) {
    case "approve":
      return { allowed: true };
    case "reject":
      return { allowed: false, reason: result.explanation };
    case "warn":
      return { allowed: true, flagged: true };
    case "review":
      return { allowed: false, pending: true, requestId: result.requestId };
  }
}

cURL

bash

curl -X POST https://www.communitai.org/api/v1/moderation \
  -H "Authorization: Bearer $COMMUNITAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello world!",
    "contentType": "text",
    "options": {
      "explain": true
    }
  }'

Request Body

Parameter	Type	Description
`content`required The content to moderate. Maximum 100,000 characters.	`string`	The content to moderate. Maximum 100,000 characters.
`contentType` Use "text". Image and mixed requests currently return 503 because their required evaluation is unavailable.	`string` Default: "text"	Use "text". Image and mixed requests currently return 503 because their required evaluation is unavailable.
`context` Optional context to improve moderation accuracy.	`object`	Optional context to improve moderation accuracy.
`context.platformId` Your platform's identifier for tracking.	`string`	Your platform's identifier for tracking.
`context.communityId` Your external community/channel identifier for tracking.	`string`	Your external community/channel identifier for tracking.
`context.authorReputation` Author reputation score (0-100) for context.	`number`	Author reputation score (0-100) for context.
`rulesConfig` Configure which rules to apply.	`object`	Configure which rules to apply.
`rulesConfig.useGlobalSafety` Apply CommunitAI's global safety rules.	`boolean` Default: true	Apply CommunitAI's global safety rules.
`rulesConfig.customRuleIds` Specific active rules owned by your customer. Missing, inactive, or foreign IDs return 503.	`string[]`	Specific active rules owned by your customer. Missing, inactive, or foreign IDs return 503.
`rulesConfig.interpretation` Rule strictness. One of: "strict", "moderate", "permissive".	`string`	Rule strictness. One of: "strict", "moderate", "permissive".
`options` Additional response options.	`object`	Additional response options.
`options.explain` Include human-readable explanation in response.	`boolean` Default: false	Include human-readable explanation in response.
`options.suggestRewrite` Request a rewrite for eligible nonsevere violations. Returned only after it passes the same policies; it is not guaranteed.	`boolean` Default: false	Request a rewrite for eligible nonsevere violations. Returned only after it passes the same policies; it is not guaranteed.
`options.returnConfidence` Include confidence score in response.	`boolean` Default: true	Include confidence score in response.

Example Request

json

{
  "content": "Check out this amazing offer! Click here now!!!",
  "contentType": "text",
  "context": {
    "communityId": "tech-forum",
    "authorReputation": 45
  },
  "rulesConfig": {
    "useGlobalSafety": true,
    "interpretation": "moderate"
  },
  "options": {
    "explain": true,
    "returnConfidence": true
  }
}

Response

Parameter	Type	Description
`success` Whether the request was processed successfully.	`boolean`	Whether the request was processed successfully.
`data.requestId` Unique identifier for this request.	`string`	Unique identifier for this request.
`data.decision` Moderation decision. One of: "approve", "reject", "warn", "review".	`string`	Moderation decision. One of: "approve", "reject", "warn", "review".
`data.confidence` Confidence score from 0 to 1; omitted when options.returnConfidence=false.	`number`	Confidence score from 0 to 1; omitted when options.returnConfidence=false.
`data.rulesTriggered` List of rules that matched the content.	`array`	List of rules that matched the content.
`data.rulesTriggered[].ruleId` Unique rule identifier.	`string`	Unique rule identifier.
`data.rulesTriggered[].ruleName` Human-readable rule name.	`string`	Human-readable rule name.
`data.rulesTriggered[].severity` Rule severity. One of: "low", "moderate", "high", "critical".	`string`	Rule severity. One of: "low", "moderate", "high", "critical".
`data.rulesTriggered[].matchScore` How strongly the content matched this rule (0-1).	`number`	How strongly the content matched this rule (0-1).
`data.explanation` Human-readable explanation (if options.explain=true).	`string`	Human-readable explanation (if options.explain=true).
`data.suggestedRewrite` Optional verified rewrite when requested and available.	`string`	Optional verified rewrite when requested and available.
`data.processingTimeMs` Server-side processing time in milliseconds.	`number`	Server-side processing time in milliseconds.
`data.modelVersion` Actual evaluation provenance, such as a model identifier or custom-rules.	`string`	Actual evaluation provenance, such as a model identifier or custom-rules.

Recorded Response

From an isolated HTTP test on October 9, 2026 with a customer-owned keyword rule and global safety disabled. The 12 ms value is this observation, not a latency promise.

json

{
  "success": true,
  "data": {
    "requestId": "b80df991-c565-4ebe-bb5f-02ce87074b65",
    "decision": "reject",
    "confidence": 1,
    "rulesTriggered": [
      {
        "ruleId": "4a539406-f9de-4068-95c6-3e8be8dc7d88",
        "ruleName": "Protect private phone numbers",
        "severity": "low",
        "matchScore": 1
      }
    ],
    "explanation": "Custom rules triggered: Protect private phone numbers",
    "processingTimeMs": 12,
    "modelVersion": "custom-rules"
  }
}

Error Responses

400VALIDATION_ERROR

Request body is invalid or missing required fields.

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } }

401UNAUTHORIZED

The Authorization header is missing or contains an invalid key.

{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } }

403FORBIDDEN

Your API key lacks the 'moderate:single' permission.

{ "success": false, "error": { "code": "FORBIDDEN", "message": "API key does not have required permission" } }

429RATE_LIMIT_EXCEEDED

You've exceeded your plan's request limit. Retry after the indicated time.

{ "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded" } }

503MODERATION_UNAVAILABLE

A required provider, policy evaluation, or persistence step failed. Hold the content; this is not an approval. Disabled deployments return SERVICE_UNAVAILABLE.

{ "success": false, "error": { "code": "MODERATION_UNAVAILABLE", "message": "Required moderation is unavailable" } }

500INTERNAL_ERROR

Server error. Contact support if this persists.

{ "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } }

Code Examples

TypeScript

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.
});

async function moderatePost(content: string, communityId: string) {
  const result = await client.moderate({
    content,
    contentType: "text",
    context: { communityId },
    options: { explain: true },
  });

  switch (result.decision) {
    case "approve":
      return { allowed: true };
    case "reject":
      return { allowed: false, reason: result.explanation };
    case "warn":
      return { allowed: true, flagged: true };
    case "review":
      return { allowed: false, pending: true, requestId: result.requestId };
  }
}

cURL

bash

curl -X POST https://www.communitai.org/api/v1/moderation \
  -H "Authorization: Bearer $COMMUNITAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello world!",
    "contentType": "text",
    "options": {
      "explain": true
    }
  }'