API Key Authentication

Use API keys for server-to-server communication and programmatic access to the Modsift API. This is the recommended method for production applications and automated workflows.

Include your API key in the Authorization header:

curl -X GET https://api.modsift.com/v1/endpoint \
  -H "Authorization: your-api-key"

Cognito Authentication

Use Cognito authentication for web application access through the Modsift dashboard. This method is used when users interact with the platform through the browser interface.

For web application access, endpoints are available with the _cognito_ suffix after user login (e.g., /api/v1/moderation/moderate_cognito_)

Severity Levels

The severity scale represents how serious a policy violation is. Each policy evaluates content and assigns a severity level from none (no violation) to very_high (critical violation).

Policy Types

Modsift currently supports managed policies, which are professionally designed and maintained detection rules for common moderation scenarios.

Managed Policies: Pre-built by the platform (e.g., "Harassment Detection", "Profanity Detection")

Thresholds

Thresholds control the sensitivity of each policy by defining the minimum severity level that will trigger a flag. For example, setting a threshold to "medium" means only violations rated medium or higher will be flagged.

Determine when a detected violation should trigger an action. Can be set per policy within each profile and falls back to default_threshold if not specified.

Profiles

Profiles allow you to create different moderation strategies for different contexts. For example, you might use a strict profile for public comments and a lenient profile for private messages.

Collections of policies with specific threshold configurations. Enable different moderation strategies for different use cases. Can be set as account default or specified per request.

SeverityLevel

Represents how serious a policy violation is. Used in moderation responses to indicate the detected severity.

"none" | "very_low" | "low" | "medium" | "high" | "very_high"

ThresholdValue

Defines the minimum severity level that will trigger a flag. Content with severity at or above the threshold will be flagged.

"very_low" | "low" | "medium" | "high" | "very_high"

PolicyType

Indicates whether a policy is a pre-built managed policy or a user-defined custom policy.

"managed" | "custom"

AttachedPolicy Object

Represents a policy attached to a profile with its configuration.

{
  "name": string,            // Policy name
  "policy_type": PolicyType, // "managed" or "custom"
  "threshold": ThresholdValue // Threshold for this policy
}

Request Body Parameters

Request Example

curl -X POST https://api.modsift.com/v1/moderate \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "text to moderate",
    "profile": "ecommerce_strict",
    "policy_overrides": {
      "Harassment Detection": "high",
      "Spam Detector": "very_high"
    },
    "include_reasoning": false
  }'

Response Fields

Response Example

{
  "request_id": "req_789xyz456abc",
  "timestamp": "2025-05-26T10:30:05Z",
  "overall_flagged": true,
  "policies": {
    "HarassmentDetection": {
      "name": "HarassmentDetection",
      "policy_type": "managed",
      "flagged": true,
      "severity": "high",
      "threshold_used": "medium",
      "reasoning": "Content contains threatening language",
      "relevant_excerpt": "threatening excerpt"
    }
  },
  "metadata": {
    "total_units_used": 2
  }
}

Request Body Parameters

Request Example

curl -X POST https://api.modsift.com/v1/profiles \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ecommerce_strict",
    "description": "Strict moderation for e-commerce reviews",
    "attached_policies": {
      "HarassmentDetectionPolicy": {
        "name": "HarassmentDetectionPolicy",
        "policy_type": "managed",
        "threshold": "medium"
      }
    },
    "default_threshold": "medium",
    "is_default": false
  }'

Response Fields

Response Example

{
  "name": "ecommerce_strict",
  "created_at": "2025-05-26T10:30:00Z"
}

Request Example

curl -X GET https://api.modsift.com/v1/profiles \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "profiles": [
    {
      "name": "ecommerce_strict",
      "description": "Strict moderation for e-commerce reviews",
      "is_default": false,
      "attached_policies_count": 3,
      "managed_policies_count": 3,
      "created_at": "2025-05-26T10:30:00Z",
      "last_modified": "2025-05-26T10:30:00Z"
    }
  ],
  "total": 1
}

Path Parameters

Request Example

curl -X GET https://api.modsift.com/v1/profiles/ecommerce_strict \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "name": "ecommerce_strict",
  "description": "Strict moderation for e-commerce reviews",
  "attached_policies": {
    "HarassmentDetectionPolicy": {
      "name": "HarassmentDetectionPolicy",
      "policy_type": "managed",
      "threshold": "medium"
    }
  },
  "default_threshold": "medium",
  "is_default": false,
  "created_at": "2025-05-26T10:30:00Z",
  "last_modified_at": "2025-05-26T10:30:00Z"
}

Path Parameters

Request Body Parameters

Request Example

curl -X PUT https://api.modsift.com/v1/profiles/ecommerce_strict \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ecommerce_very_strict",
    "attached_policies": {
      "HarassmentDetectionPolicy": {
        "name": "HarassmentDetectionPolicy",
        "policy_type": "managed",
        "threshold": "medium"
      }
    },
    "default_threshold": "low",
    "is_default": true
  }'

Response Fields

Response Example

{
  "message": "Profile updated successfully"
}

Path Parameters

Request Example

curl -X DELETE https://api.modsift.com/v1/profiles/ecommerce_strict \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "message": "Profile deleted successfully"
}

Path Parameters

Request Body Parameters

Request Example

curl -X POST https://api.modsift.com/v1/profiles/ecommerce_strict/policies \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "HarassmentDetectionPolicy",
      "policy_type": "managed",
      "threshold": "medium"
    },
    {
      "name": "ViolenceDetectionPolicy",
      "policy_type": "managed",
      "threshold": "medium"
    }
  ]'

Response Fields

Response Example

{
  "message": "Policies attached successfully"
}

Path Parameters

Request Example

curl -X DELETE https://api.modsift.com/v1/profiles/ecommerce_strict/policies/HarassmentDetectionPolicy \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "message": "Policy detached successfully"
}

Path Parameters

Request Body Parameters

Request Example

curl -X PUT https://api.modsift.com/v1/profiles/ecommerce_strict/policies/HarassmentDetectionPolicy \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": "high"
  }'

Response Fields

Response Example

{
  "message": "Policy threshold updated successfully"
}

Query Parameters

Request Example

curl -X GET https://api.modsift.com/v1/policies/managed \
  -H "Authorization: your-api-key"

# With query parameters
curl -X GET "https://api.modsift.com/v1/policies/managed?limit=10&offset=0" \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "policies": [
    {
      "name": "HarassmentDetectionPolicy",
      "description": "Detects harassment, bullying, and targeted attacks",
      "rules": [
        "Identifies direct personal attacks and insults",
        "Detects threatening or intimidating language",
        "Identifies attempts to share or find personal information"
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "last_updated": "2025-05-20T14:30:00Z"
    },
    {
      "name": "ProfanityDetectionPolicy",
      "description": "Detects offensive language and profanity",
      "rules": [
        "Identifies explicit profanity and vulgar language",
        "Detects offensive slurs and derogatory terms",
        "Recognizes filter bypass attempts"
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "last_updated": "2025-06-10T09:15:00Z"
    }
  ],
  "total": 2,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Path Parameters

Request Example

curl -X GET https://api.modsift.com/v1/policies/managed/HarassmentDetectionPolicy \
  -H "Authorization: your-api-key"

Response Fields

Response Example

{
  "name": "HarassmentDetectionPolicy",
  "description": "Detects harassment, bullying, and targeted attacks",
  "rules": [
    "Identifies direct personal attacks and insults",
    "Detects threatening or intimidating language",
    "Identifies attempts to share or find personal information"
  ],
  "created_at": "2025-01-15T10:00:00Z",
  "last_updated": "2025-05-20T14:30:00Z"
}