DeepModGuideAPI Reference

Policy Chaining Guide

Policy chaining enables sophisticated, multi-stage content moderation workflows by running content through multiple policies sequentially. Instead of running content against a single policy, you can create chains that execute in sequence, with each policy building on the results of the previous ones. This guide covers everything you need to know to implement and optimize policy chains for your use case.

Key Concepts

Sequential Execution: Policies execute one after another in the order you specify. Content must pass each policy to continue to the next.

Early Termination: If any policy in the chain fails (flags content), the chain stops immediately and remaining policies are marked as "abandoned."

Consolidated Results: You receive a single webhook with results from all executed policies, making it easy to handle complex moderation outcomes.

Unified Billing: Chain execution counts as usage for each policy that actually runs (abandoned policies don't count toward usage).

When to Use Policy Chaining

Policy chaining is ideal for scenarios requiring multi-layered content evaluation:

Progressive Filtering

Use Case: Filter content through increasingly specific checks

Spam Detection → Safety Review → Brand Compliance

Benefits:

  • Quickly eliminate obvious spam before expensive safety analysis

  • Only apply brand guidelines to content that passes basic safety

  • Optimize processing costs by filtering early

Compliance Workflows

Use Case: Ensure content meets multiple regulatory requirements

Global Standards → Regional Laws → Industry Regulations

Benefits:

  • Systematic compliance checking

  • Clear audit trail for regulatory purposes

  • Separation of different compliance concerns

Quality Assurance

Use Case: Multi-tier content quality evaluation

Basic Quality → Editorial Standards → Platform Guidelines

Benefits:

  • Escalating quality thresholds

  • Different reviewers for different standards

  • Comprehensive quality control

Setting Up Policy Chains

Prerequisites

Before creating policy chains, ensure:

  1. Active Policies: All policies in the chain must be active

  2. Webhook Configuration: Your organization must have a webhook configured in Organization Settings (required for all production moderation requests)

  3. Proper Access: Policies must belong to your organization

  4. Clear Ordering: Plan the logical sequence of your policies

API Integration

Replace the single policyId parameter with an array of policy identifiers:

Single Policy (Standard):

const response = await fetch('https://api.deepmod.ai/v1/moderation/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DEEPMOD_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    policyId: 'safety-policy',
    content: 'Content to moderate',
  }),
});

const result = await response.json();
console.log('Moderation job ID:', result.moderationJobId);

Policy Chain:

const response = await fetch('https://api.deepmod.ai/v1/moderation/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DEEPMOD_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    policyId: ['safety-policy', 'legal-compliance', 'brand-guidelines'],
    content: 'Content to moderate',
    metadata: {
      userId: 'user_12345',
      contentType: 'comment',
    },
    tags: ['user-generated', 'public'],
  }),
});

const result = await response.json();
console.log('Job ID:', result.moderationJobId, 'Batch ID:', result.batchId);

Response Structure

Chain requests return both a job ID and batch identifier:

{
  "moderationJobId": "job_123456",
  "batchId": "batch_abc123"
}

Single policy requests return only the job ID:

{
  "moderationJobId": "job_123456"
}

Understanding Chain Results

Result Types

Each policy in a chain receives one of four possible results:

Success: Policy passed - content is acceptable according to this policy's rules

Failure: Policy failed - content violates one or more rules, chain stops here

Ambiguous: Policy result is unclear - may pause for human review if enabled

Abandoned: Policy was not executed because an earlier policy in the chain failed

Webhook Payload

Chain completion triggers a Moderation.BatchCompleted webhook:

{
  "id": "job_123456",
  "type": "Moderation.BatchCompleted",
  "data": {
    "batch": {
      "result": "failure",
      "moderation": [
        {
          "policy": "safety-policy",
          "result": "success",
          "ruleGroupResults": [
            {
              "name": "Content Safety",
              "result": "success",
              "averageConfidence": 0.95,
              "ruleResults": [
                {
                  "condition": "must not contain harmful content",
                  "result": "success",
                  "averageConfidence": 0.95,
                  "matchedContent": [
                    {
                      "content": null,
                      "confidence": 0.95
                    }
                  ]
                }
              ]
            }
          ],
          "averageConfidence": 0.95,
          "moderationRunId": 1001
        },
        {
          "policy": "legal-compliance-policy",
          "result": "failure",
          "ruleGroupResults": [
            {
              "name": "Copyright Detection",
              "result": "failure",
              "averageConfidence": 0.87,
              "ruleResults": [
                {
                  "condition": "must not contain copyrighted material",
                  "result": "failure",
                  "averageConfidence": 0.87,
                  "matchedContent": [
                    {
                      "content": "Potential copyright violation detected",
                      "confidence": 0.87
                    }
                  ]
                }
              ]
            }
          ],
          "averageConfidence": 0.87,
          "moderationRunId": 1002
        }
      ]
    },
    "metadata": {
      "userId": "user_123",
      "contentType": "comment"
    },
    "tags": ["user-generated"]
  }
}

Note: The batch.result field indicates the overall outcome of the chain using the highest priority result (failure > ambiguous > success). Abandoned policies are not included in the batch.moderation array. The original metadata and tags from your request are included in the webhook payload for correlation.

Interpreting Results

To determine the overall outcome of a chain, examine the batchResult field:

  • Chain Success: batchResult: "success" - All executed policies passed

  • Chain Failure: batchResult: "failure" - At least one policy failed

  • Chain Ambiguous: batchResult: "ambiguous" - At least one policy was ambiguous (and none failed)

You can also examine individual policy results in the batch.moderation array to understand which specific policies contributed to the overall outcome. Abandoned policies (those not executed due to earlier failures) are not included in the batch.moderation array.

Human Review in Chains

Review Behavior

When a policy in a chain requires human review:

  1. Chain Pauses: Execution stops at the ambiguous policy

  2. Review Process: Human reviewer evaluates the content

  3. Resume or Stop: Based on review outcome:

    • Approved: Chain continues to next policy

    • Rejected: Chain stops, remaining policies abandoned

Review Configuration

Enable human review at the individual policy level:

// Policy configuration
{
  "name": "Legal Compliance",
  "reviewMode": "humanReview",
  "confidenceThreshold": 0.8
}

Best Practices for Review in Chains:

  • Place policies requiring frequent review later in the chain

  • Use clear review guidelines for chain context

  • Train reviewers on chain implications

  • Monitor review turnaround times

Optimization Strategies

Chain Ordering

Place Fastest Policies First: Start with quick checks to filter out obvious violations

Good: Spam Detection → Content Analysis → Brand Review
Poor: Brand Review → Content Analysis → Spam Detection

Order by Failure Rate: Put policies most likely to fail earlier

Good: Safety (high fail rate) → Legal (medium) → Brand (low)
Poor: Brand (low fail rate) → Legal (medium) → Safety (high)

Policy Design

Single Responsibility: Each policy should focus on one concern

Good: Separate policies for safety, legal, brand
Poor: One mega-policy handling all concerns

Complementary Rules: Avoid overlapping rules between chain policies

Good: Safety focuses on harm, Legal on compliance
Poor: Both policies check for hate speech

Performance Optimization

Test Chain Performance: Monitor execution times and optimize ordering

Use Metadata: Pass context to help policies make faster decisions

Monitor Abandonment Rates: High abandonment might indicate poor ordering

Monitoring and Analytics

Key Metrics

Chain Completion Rate: Percentage of chains that complete successfully

Average Chain Length: How many policies typically execute before stopping

Policy Abandonment Rate: Which policies are most often skipped

Review Impact: How often human review pauses chain execution

Dashboard Views

Use tags and metadata to analyze chain performance:

{
  "tags": ["chain:content-quality", "region:eu"],
  "metadata": {
    "chainType": "progressive-filtering",
    "priority": "high"
  }
}

Troubleshooting Common Issues

High Abandonment on Later Policies:

  • Review chain ordering

  • Consider combining rarely-reached policies

  • Analyze if early policies are too strict

Frequent Review Pauses:

  • Adjust confidence thresholds

  • Train reviewers on chain context

  • Consider review-free policies for speed

Long Execution Times:

  • Optimize policy rule complexity

  • Reorder based on execution speed

  • Consider parallel processing alternatives

Best Practices

Chain Design

  1. Start Simple: Begin with 2-3 policies and add more as needed

  2. Clear Purpose: Each policy should have a distinct, well-defined purpose

  3. Logical Flow: Order policies in a way that makes business sense

  4. Document Chains: Keep clear documentation of chain purpose and logic

Integration

  1. Handle All Results: Build webhook handlers that process all four result types

  2. Idempotent Handlers: Ensure webhook handlers can safely process duplicate events

  3. Error Recovery: Plan for chain failures and have fallback procedures

  4. Testing: Thoroughly test chains with representative content samples

Monitoring

  1. Track Performance: Monitor chain completion rates and execution times

  2. Analyze Patterns: Use metadata and tags to understand chain behavior

  3. Regular Review: Periodically review chain performance and optimize

  4. Alert on Issues: Set up alerts for unusual failure or abandonment rates

Advanced Use Cases

A/B Testing Policy Changes

Test new policies by adding them to chains:

Current: Safety → Legal → Brand
Test: Safety → Legal → New_Brand → Brand

Compare results to validate improvements.

Dynamic Chain Selection

Use metadata to select different chains for different content types:

const chainMap = {
  'user-comment': ['safety', 'community-guidelines'],
  'brand-content': ['safety', 'legal', 'brand'],
  'ugc-video': ['safety', 'copyright', 'community'],
};

const policyChain = chainMap[contentType] || ['safety'];

Regional Compliance Chains

Create location-specific chains:

Global: Base Safety → Universal Legal
EU: Base Safety → Universal Legal → GDPR Compliance
US: Base Safety → Universal Legal → Section 230 Review

Summary

Policy chaining enables sophisticated, multi-stage content moderation workflows that can significantly improve the accuracy and efficiency of your content moderation processes. By following the best practices and strategies outlined in this guide, you can create robust, scalable moderation chains that meet your specific requirements.

Key takeaways:

  • Order policies strategically for optimal performance

  • Design policies with single, clear responsibilities

  • Monitor chain performance and optimize regularly

  • Handle all result types in your webhook handlers

  • Test thoroughly before production deployment

For additional support with policy chaining implementation, contact our support team or refer to the specific API documentation for technical details.