Modsift API Documentation

Comprehensive API reference for content moderation endpoints

Authentication

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://modsift.com/api/v1/endpoint \
  -H "Authorization: your-api-key"

Quickstart

Get up and running with Modsift in minutes. This guide walks you through the essentials: getting your API key, testing policies, and creating your first profile.

1. Get Your API Key

Navigate to Dashboard → API Keys and create a new API key. Include it in the Authorization header of all requests:

Authorization: your-api-key-here

2. Test a Policy

Test any managed policy instantly without creating a profile. Use the policy parameter to evaluate content against a single policy:

curl -X POST https://modsift.com/api/v1/moderate \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I hate you and want to hurt you",
    "policy": {
      "name": "HarassmentDetectionPolicy",
      "threshold": "medium"
    }
  }'

Response:

{
  "request_id": "req_abc123",
  "timestamp": "2025-01-13T10:30:00Z",
  "overall_flagged": true,
  "profile_used": null,
  "policies": {
    "HarassmentDetectionPolicy": {
      "name": "HarassmentDetectionPolicy",
      "policy_type": "managed",
      "flagged": true,
      "severity": "high",
      "threshold_used": "medium",
      "reasoning": "Content contains direct threats and hostile language targeting an individual",
      "relevant_excerpts": [
        "I hate you and want to hurt you"
      ]
    }
  }
}

3. Create a Profile

Profiles let you evaluate content against multiple policies at once. Create a profile with your chosen policies and thresholds:

curl -X POST https://modsift.com/api/v1/profiles \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_first_profile",
    "description": "My content moderation profile",
    "policies": [
      { "name": "HarassmentDetectionPolicy", "threshold": "medium" },
      { "name": "ToxicityDetectionPolicy", "threshold": "low" }
    ]
  }'

Response:

{
  "message": "Profile created successfully",
  "profile": {
    "name": "my_first_profile",
    "description": "My content moderation profile",
    "is_default": false,
    "policies": [
      {
        "name": "HarassmentDetectionPolicy",
        "threshold": "medium",
        "policy_type": "managed"
      },
      {
        "name": "ToxicityDetectionPolicy",
        "threshold": "low",
        "policy_type": "managed"
      }
    ]
  }
}

4. Moderate with Profile

Now use your profile to evaluate content against all attached policies in a single request:

curl -X POST https://modsift.com/api/v1/moderate \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are such an idiot, nobody likes you",
    "profile": "my_first_profile"
  }'

Response:

{
  "request_id": "req_xyz789",
  "timestamp": "2025-01-13T10:35:00Z",
  "overall_flagged": true,
  "profile_used": "my_first_profile",
  "policies": {
    "HarassmentDetectionPolicy": {
      "name": "HarassmentDetectionPolicy",
      "policy_type": "managed",
      "flagged": true,
      "severity": "medium",
      "threshold_used": "medium",
      "reasoning": "Content contains personal insults and demeaning language",
      "relevant_excerpts": [
        "You are such an idiot",
        "nobody likes you"
      ]
    },
    "ToxicityDetectionPolicy": {
      "name": "ToxicityDetectionPolicy",
      "policy_type": "managed",
      "flagged": true,
      "severity": "medium",
      "threshold_used": "low",
      "reasoning": "Content is hostile and intended to demean the recipient",
      "relevant_excerpts": [
        "You are such an idiot, nobody likes you"
      ]
    }
  }
}

5. Create a Custom Policy

Create custom policies for domain-specific rules. Here's an example for a finance application that needs to detect unauthorized financial advice:

curl -X POST https://modsift.com/api/v1/policies/custom \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "no_financial_advice",
    "description": "Flag content that provides specific financial advice",
    "rules": [
      "Content must not recommend specific stocks or investments",
      "Content must not provide personalized financial planning advice",
      "Content must not guarantee investment returns or profits"
    ]
  }'

Response:

{
  "message": "Custom policy created successfully",
  "policy": {
    "name": "no_financial_advice",
    "description": "Flag content that provides specific financial advice",
    "rules": [
      "Content must not recommend specific stocks or investments",
      "Content must not provide personalized financial planning advice",
      "Content must not guarantee investment returns or profits"
    ]
  }
}

6. Use Your Custom Policy

Test your custom policy using single policy mode. You can also attach it to a profile for use alongside other policies:

curl -X POST https://modsift.com/api/v1/moderate \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You should definitely buy ACME stock, it is guaranteed to double in value next month!",
    "policy": {
      "name": "no_financial_advice",
      "threshold": "low"
    }
  }'

Response:

{
  "request_id": "req_fin456",
  "timestamp": "2025-01-13T10:40:00Z",
  "overall_flagged": true,
  "profile_used": null,
  "policies": {
    "no_financial_advice": {
      "name": "no_financial_advice",
      "policy_type": "custom",
      "flagged": true,
      "severity": "high",
      "threshold_used": "low",
      "reasoning": "Content recommends a specific stock purchase and guarantees investment returns",
      "relevant_excerpts": [
        "You should definitely buy ACME stock",
        "guaranteed to double in value"
      ]
    }
  }
}

Core Concepts

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

none → very_low → low → medium → high → very_high

Policy Types

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

Custom Policies: User-defined rules and logic that you can create for your specific moderation needs

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 are collections of policies with specific threshold configurations that 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. Profiles can be set as your account default or specified per request.

Types & Enums

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
}

Core Moderation

POST
/v1/moderate

Primary moderation endpoint for analyzing content against configured policies

Request Body Parameters

content
string
Required

The text content to moderate

profile
string
Optional

Profile name to use for moderation. Mutually exclusive with 'policy' parameter. Defaults to User's default profile.

policy
object
Optional

Single policy to test with {name: string, threshold: ThresholdValue}. Bypasses profiles. Mutually exclusive with 'profile' parameter. Defaults to null.

profile_policy_overrides
object
Optional

Per-profile threshold overrides for specific policies. Object with policy names as keys and ThresholdValue as values. Only used with 'profile' parameter. Defaults to {}.

Request Example

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

Response Fields

request_id
string

Unique request identifier (format: req_{12_hex_chars})

timestamp
string

ISO 8601 timestamp of the request

overall_flagged
boolean

True if any policy triggered a flag

profile_used
string | null

Name of the profile that was applied (either the explicitly requested profile or the default profile if none was specified). Will be null when using the 'policy' parameter.

policies
object

Results per policy with name, policy_type, flagged, severity, threshold_used, reasoning, and relevant_excerpts (array of up to 3 quotes)

metadata.total_units_used
number

API units consumed by this request

Response Example

{
  "request_id": "req_789xyz456abc",
  "timestamp": "2025-05-26T10:30:05Z",
  "overall_flagged": true,
  "profile_used": "ecommerce_strict",
  "policies": {
    "HarassmentDetection": {
      "name": "HarassmentDetection",
      "policy_type": "managed",
      "flagged": true,
      "severity": "high",
      "threshold_used": "medium",
      "reasoning": "Targets an individual with intimidating language",
      "relevant_excerpts": [
        "I'm going to find the CEO's home address",
        "give them a piece of my mind"
      ]
    }
  },
  "metadata": {
    "total_units_used": 2
  }
}

Profile Management

POST
/v1/profiles

Create a new moderation profile with policies and thresholds

Request Body Parameters

name
string
Required

Profile name

Validation: Alphanumeric, hyphens, underscores only. Cannot start with '__'

description
string
Optional

Profile description Defaults to "".

attached_policies
object
Optional

Policies to attach. Object with policy names as keys and AttachedPolicy objects as values Defaults to {}.

default_threshold
ThresholdValue
Optional

Default threshold for policies without explicit threshold Defaults to "medium".

is_default
boolean
Optional

Set as account default profile Defaults to false.

Request Example

curl -X POST https://modsift.com/api/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

name
string

Created profile name

created_at
string

ISO 8601 timestamp of creation

Response Example

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

List all moderation profiles for the authenticated user

Request Example

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

Response Fields

profiles
array

List of profile summaries

total
number

Total number of profiles

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
}
GET
/v1/profiles/{profile_id}

Get detailed information about a specific profile

Path Parameters

profile_id
string
Required

Name of the profile to retrieve

Request Example

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

Response Fields

name
string

Profile name

description
string

Profile description

attached_policies
object

Attached policies with configurations

default_threshold
ThresholdValue

Default threshold

is_default
boolean

Whether this is the default profile

created_at
string

Creation timestamp

last_modified_at
string

Last modification timestamp

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"
}
PUT
/v1/profiles/{profile_id}

Update an existing profile's configuration

Path Parameters

profile_id
string
Required

Current profile name

Request Body Parameters

name
string
Optional

New profile name (for renaming)

Validation: Alphanumeric, hyphens, underscores only. Cannot start with '__'

description
string
Optional

Updated description

default_threshold
ThresholdValue
Optional

New default threshold

is_default
boolean
Optional

Set/unset as default

attached_policies
object
Optional

Replace all attached policies

Request Example

curl -X PUT https://modsift.com/api/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

name
string

Profile name (possibly new)

updated_at
string

Update timestamp

status
string

Always "updated"

Response Example

{
  "message": "Profile updated successfully"
}
DELETE
/v1/profiles/{profile_id}

Delete a moderation profile

Path Parameters

profile_id
string
Required

Profile to delete

Request Example

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

Response Fields

name
string

Deleted profile name

status
string

Always "deleted"

deleted_at
string

Deletion timestamp

Response Example

{
  "message": "Profile deleted successfully"
}
POST
/v1/profiles/{profile_id}/policies

Attach one or more policies to a profile

Path Parameters

profile_id
string
Required

Profile to attach policies to

Request Body Parameters

name
string
Required

Policy name (in each policy object)

policy_type
PolicyType
Required

"managed" or "custom" (in each policy object)

threshold
ThresholdValue
Required

Threshold for this policy (in each policy object)

Request Example

curl -X POST https://modsift.com/api/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

name
string

Profile name

attached_policies
array

List of attachment results with name, status, and attached_at

message
string

Success message

Response Example

{
  "message": "Policies attached successfully"
}
DELETE
/v1/profiles/{profile_id}/policies/{policy_name}

Detach a policy from a profile

Path Parameters

profile_id
string
Required

Profile name

policy_name
string
Required

Policy to detach (must be attached)

Request Example

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

Response Fields

name
string

Profile name

policy_name
string

Detached policy name

status
string

Always "detached"

detached_at
string

Detachment timestamp

Response Example

{
  "message": "Policy detached successfully"
}
PUT
/v1/profiles/{profile_id}/policies/{policy_name}

Update the threshold for a specific policy within a profile

Path Parameters

profile_id
string
Required

Profile name

policy_name
string
Required

Policy to update (must be attached)

Request Body Parameters

threshold
ThresholdValue
Required

New threshold value

Validation: Must be: very_low, low, medium, high, or very_high

Request Example

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

Response Fields

name
string

Profile name

policy_name
string

Updated policy name

threshold
ThresholdValue

New threshold

status
string

Always "updated"

updated_at
string

Update timestamp

Response Example

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

Managed Policies

GET
/v1/policies/managed

List all available pre-built managed policies

Query Parameters

search
string
Optional

Search by name or description

limit
integer
Optional

Max results to return Defaults to 20.

offset
integer
Optional

Pagination offset Defaults to 0.

Request Example

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

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

Response Fields

policies
array

List of managed policy objects with name, description, rules, created_at, and last_updated

total
number

Total matching policies

pagination
object

Pagination info with limit, offset, and has_more

Response Example

{
  "policies": [
    {
      "name": "GraphicViolenceDetectionPolicy",
      "description": "Detects graphic and extreme depictions of violence, gore, death, severe physical injury, or dismemberment",
      "rules": [
        "Identifies detailed graphic depictions of death or dying",
        "Detects explicit descriptions of severe physical injuries or dismemberment",
        "Identifies gratuitous gore, blood, or bodily harm descriptions",
        "Detects celebration or glorification of extreme violence or torture"
      ],
      "created_at": "2025-12-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "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": "HateSpeechDetectionPolicy",
      "description": "Detects hate speech and discriminatory content targeting protected characteristics",
      "rules": [
        "Identifies hate speech targeting race, ethnicity, nationality, or caste",
        "Detects discrimination based on gender, sexual orientation, or gender identity",
        "Identifies religious intolerance and attacks on disability status",
        "Detects threatening variants of hate speech with calls to violence or harm",
        "Recognizes coded language and dogwhistles used to express hateful ideologies"
      ],
      "created_at": "2025-12-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "name": "IllegalActivityDetectionPolicy",
      "description": "Detects promotion of illegal activities and instructions for illegal acts",
      "rules": [
        "Identifies instructions or advice for committing illegal acts",
        "Detects promotion of illegal drug production, trafficking, or distribution",
        "Identifies illegal weapons sales, trafficking, or manufacturing instructions",
        "Detects planning or coordination of violent illegal activities",
        "Recognizes fraud schemes, hacking instructions, or other cyber crimes"
      ],
      "created_at": "2025-12-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "name": "NSFWContentDetectionPolicy",
      "description": "Detects not-safe-for-work content including sexual, violent, and disturbing material inappropriate for professional or public settings",
      "rules": [
        "Identifies sexual or adult content descriptions",
        "Detects graphic violence and gore depictions",
        "Identifies disturbing or shocking imagery descriptions",
        "Detects explicit romantic or sexual scenarios",
        "Recognizes extreme violent acts"
      ],
      "created_at": "2025-01-06T00:00:00Z",
      "last_updated": "2025-01-06T00:00: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",
        "Identifies sexually explicit or graphic content descriptions"
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "name": "SelfHarmDetectionPolicy",
      "description": "Detects content promoting or encouraging self-harm",
      "rules": [
        "Identifies content promoting or glorifying self-harm, suicide, or eating disorders",
        "Detects expressions of intent to engage in self-harming behavior",
        "Identifies detailed instructions or methods for self-harm or suicide",
        "Recognizes encouragement of others to engage in self-destructive behaviors"
      ],
      "created_at": "2025-12-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "name": "SexualContentDetectionPolicy",
      "description": "Detects sexual content and any content involving minors",
      "rules": [
        "Identifies sexually explicit content meant to cause sexual arousal",
        "Detects descriptions of sexual activity or explicit sexual content",
        "Identifies promotion of sexual services including escort services",
        "Detects any sexual content involving, describing, or soliciting minors",
        "Recognizes sexualization of children or CSAM references"
      ],
      "created_at": "2025-12-15T10:00:00Z",
      "last_updated": "2025-12-15T10:00:00Z"
    },
    {
      "name": "ToxicityDetectionPolicy",
      "description": "Detects toxic behavior including rude, disrespectful, and unreasonable language that degrades conversation quality",
      "rules": [
        "Identifies rude and disrespectful language",
        "Detects unnecessarily hostile or aggressive tone",
        "Identifies provocative or inflammatory comments",
        "Detects condescending or dismissive language",
        "Recognizes bad faith arguments and trolling behavior"
      ],
      "created_at": "2025-01-06T00:00:00Z",
      "last_updated": "2025-01-06T00:00:00Z"
    },
    {
      "name": "ViolenceDetectionPolicy",
      "description": "Identifies violent content and credible threats",
      "rules": [
        "Detects descriptions or threats of physical violence",
        "Identifies references to weapons in threatening contexts"
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "last_updated": "2025-05-18T09:15:00Z"
    }
  ],
  "total": 10,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}
GET
/v1/policies/managed/{policy_name}

Get detailed information about a specific managed policy

Path Parameters

policy_name
string
Required

Managed policy name

Validation: Must exist in available managed policies

Request Example

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

Response Fields

name
string

Policy name

description
string

Policy description

rules
array

Array of detection rules

created_at
string

Creation timestamp

last_updated
string

Last update timestamp

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"
}

Custom Policies

Create your own custom moderation policies with specific detection rules. Custom policies can be attached to profiles and used during content moderation.

POST
/v1/policies/custom

Create a new custom moderation policy with your own detection rules.

Request Body Parameters

policy_name
string
Required

Unique identifier for the policy (alphanumeric, hyphens, underscores)

Validation: Must not start with '__' (reserved for system use)

description
string
Required

Description of what the policy detects

rules
array
Required

Array of detection rules as strings

Validation: Must be non-empty array

Request Example

curl -X POST https://modsift.com/api/v1/policies/custom \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_name": "no_doxxing_threats",
    "description": "Flag content that threatens to find or share personal information",
    "rules": [
      "Detects attempts to find home addresses",
      "Detects threats to share private contact information"
    ]
  }'

Response Fields

policy_name
string

Policy identifier

description
string

Policy description

rules
array

Array of detection rules

created_at
string

ISO 8601 timestamp

Response Example

{
  "policy_name": "no_doxxing_threats",
  "description": "Flag content that threatens to find or share personal information",
  "rules": [
    "Detects attempts to find home addresses",
    "Detects threats to share private contact information"
  ],
  "created_at": "2025-05-26T10:30:00Z"
}
GET
/v1/policies/custom

List all custom policies for the authenticated user with pagination.

Query Parameters

limit
number
Optional

Number of policies to return Defaults to 20.

Validation: Between 1 and 100

offset
number
Optional

Number of policies to skip Defaults to 0.

Request Example

curl -X GET "https://modsift.com/api/v1/policies/custom?limit=20&offset=0" \
  -H "Authorization: your-api-key"

Response Fields

policies
array

Array of policy summaries

policies[].policy_name
string

Policy identifier

policies[].description
string

Policy description

policies[].rules_count
number

Number of rules in the policy

policies[].created_at
string

ISO 8601 timestamp

policies[].updated_at
string

ISO 8601 timestamp

total
number

Total number of policies

pagination
object

Pagination information

pagination.limit
number

Limit used

pagination.offset
number

Offset used

pagination.has_more
boolean

Whether more results exist

Response Example

{
  "policies": [
    {
      "policy_name": "no_doxxing_threats",
      "description": "Flag content that threatens to find or share personal information",
      "rules_count": 2,
      "created_at": "2025-05-26T10:30:00Z",
      "updated_at": "2025-05-26T10:30:00Z"
    }
  ],
  "total": 1,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}
GET
/v1/policies/custom/{policy_name}

Get detailed information about a specific custom policy including all rules.

Path Parameters

policy_name
string
Required

Name of the custom policy

Request Example

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

Response Fields

policy_name
string

Policy identifier

description
string

Policy description

rules
array

Array of detection rules

created_at
string

ISO 8601 timestamp

updated_at
string

ISO 8601 timestamp

Response Example

{
  "policy_name": "no_doxxing_threats",
  "description": "Flag content that threatens to find or share personal information",
  "rules": [
    "Detects attempts to find home addresses",
    "Detects threats to share private contact information"
  ],
  "created_at": "2025-05-26T10:30:00Z",
  "updated_at": "2025-05-26T10:30:00Z"
}
PUT
/v1/policies/custom/{policy_name}

Update a custom policy. Changes cascade to all profiles using this policy.

Path Parameters

policy_name
string
Required

Name of the custom policy

Request Body Parameters

description
string
Optional

Updated policy description

rules
array
Optional

Updated array of detection rules

Validation: Must be non-empty array if provided

Request Example

curl -X PUT https://modsift.com/api/v1/policies/custom/no_doxxing_threats \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Enhanced policy for detecting doxxing threats",
    "rules": [
      "Detects attempts to find home addresses",
      "Detects threats to share private contact information",
      "Detects requests for personal information"
    ]
  }'

Response Fields

policy_name
string

Policy identifier

description
string

Updated description

rules
array

Updated rules array

updated_at
string

ISO 8601 timestamp

profiles_affected
number

Number of profiles using this policy

Response Example

{
  "policy_name": "no_doxxing_threats",
  "description": "Enhanced policy for detecting doxxing threats",
  "rules": [
    "Detects attempts to find home addresses",
    "Detects threats to share private contact information",
    "Detects requests for personal information"
  ],
  "updated_at": "2025-05-26T11:00:00Z",
  "profiles_affected": 3
}
DELETE
/v1/policies/custom/{policy_name}

Delete a custom policy. Automatically removes it from all profiles using it.

Path Parameters

policy_name
string
Required

Name of the custom policy

Request Example

curl -X DELETE https://modsift.com/api/v1/policies/custom/no_doxxing_threats \
  -H "Authorization: your-api-key"

Response Fields

policy_name
string

Policy identifier

status
string

Deletion status (always 'deleted')

deleted_at
string

ISO 8601 timestamp

profiles_affected
number

Number of profiles that used this policy

Response Example

{
  "policy_name": "no_doxxing_threats",
  "status": "deleted",
  "deleted_at": "2025-05-26T11:30:00Z",
  "profiles_affected": 3
}