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:
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:
2. Test a Policy
Test any managed policy instantly without creating a profile. Use the policy parameter to evaluate content against a single policy:
Response:
3. Create a Profile
Profiles let you evaluate content against multiple policies at once. Create a profile with your chosen policies and thresholds:
Response:
4. Moderate with Profile
Now use your profile to evaluate content against all attached policies in a single request:
Response:
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:
Response:
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:
Response:
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).
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.
ThresholdValue
Defines the minimum severity level that will trigger a flag. Content with severity at or above the threshold will be flagged.
PolicyType
Indicates whether a policy is a pre-built managed policy or a user-defined custom policy.
AttachedPolicy Object
Represents a policy attached to a profile with its configuration.
Core Moderation
/v1/moderatePrimary moderation endpoint for analyzing content against configured policies
Request Body Parameters
contentThe text content to moderate
profileProfile name to use for moderation. Mutually exclusive with 'policy' parameter. Defaults to User's default profile.
policySingle policy to test with {name: string, threshold: ThresholdValue}. Bypasses profiles. Mutually exclusive with 'profile' parameter. Defaults to null.
profile_policy_overridesPer-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
Response Fields
request_idUnique request identifier (format: req_{12_hex_chars})
timestampISO 8601 timestamp of the request
overall_flaggedTrue if any policy triggered a flag
profile_usedName 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.
policiesResults per policy with name, policy_type, flagged, severity, threshold_used, reasoning, and relevant_excerpts (array of up to 3 quotes)
metadata.total_units_usedAPI units consumed by this request
Response Example
Profile Management
/v1/profilesCreate a new moderation profile with policies and thresholds
Request Body Parameters
nameProfile name
Validation: Alphanumeric, hyphens, underscores only. Cannot start with '__'
descriptionProfile description Defaults to "".
attached_policiesPolicies to attach. Object with policy names as keys and AttachedPolicy objects as values Defaults to {}.
default_thresholdDefault threshold for policies without explicit threshold Defaults to "medium".
is_defaultSet as account default profile Defaults to false.
Request Example
Response Fields
nameCreated profile name
created_atISO 8601 timestamp of creation
Response Example
/v1/profilesList all moderation profiles for the authenticated user
Request Example
Response Fields
profilesList of profile summaries
totalTotal number of profiles
Response Example
/v1/profiles/{profile_id}Get detailed information about a specific profile
Path Parameters
profile_idName of the profile to retrieve
Request Example
Response Fields
nameProfile name
descriptionProfile description
attached_policiesAttached policies with configurations
default_thresholdDefault threshold
is_defaultWhether this is the default profile
created_atCreation timestamp
last_modified_atLast modification timestamp
Response Example
/v1/profiles/{profile_id}Update an existing profile's configuration
Path Parameters
profile_idCurrent profile name
Request Body Parameters
nameNew profile name (for renaming)
Validation: Alphanumeric, hyphens, underscores only. Cannot start with '__'
descriptionUpdated description
default_thresholdNew default threshold
is_defaultSet/unset as default
attached_policiesReplace all attached policies
Request Example
Response Fields
nameProfile name (possibly new)
updated_atUpdate timestamp
statusAlways "updated"
Response Example
/v1/profiles/{profile_id}Delete a moderation profile
Path Parameters
profile_idProfile to delete
Request Example
Response Fields
nameDeleted profile name
statusAlways "deleted"
deleted_atDeletion timestamp
Response Example
/v1/profiles/{profile_id}/policiesAttach one or more policies to a profile
Path Parameters
profile_idProfile to attach policies to
Request Body Parameters
namePolicy name (in each policy object)
policy_type"managed" or "custom" (in each policy object)
thresholdThreshold for this policy (in each policy object)
Request Example
Response Fields
nameProfile name
attached_policiesList of attachment results with name, status, and attached_at
messageSuccess message
Response Example
/v1/profiles/{profile_id}/policies/{policy_name}Detach a policy from a profile
Path Parameters
profile_idProfile name
policy_namePolicy to detach (must be attached)
Request Example
Response Fields
nameProfile name
policy_nameDetached policy name
statusAlways "detached"
detached_atDetachment timestamp
Response Example
/v1/profiles/{profile_id}/policies/{policy_name}Update the threshold for a specific policy within a profile
Path Parameters
profile_idProfile name
policy_namePolicy to update (must be attached)
Request Body Parameters
thresholdNew threshold value
Validation: Must be: very_low, low, medium, high, or very_high
Request Example
Response Fields
nameProfile name
policy_nameUpdated policy name
thresholdNew threshold
statusAlways "updated"
updated_atUpdate timestamp
Response Example
Managed Policies
/v1/policies/managedList all available pre-built managed policies
Query Parameters
searchSearch by name or description
limitMax results to return Defaults to 20.
offsetPagination offset Defaults to 0.
Request Example
Response Fields
policiesList of managed policy objects with name, description, rules, created_at, and last_updated
totalTotal matching policies
paginationPagination info with limit, offset, and has_more
Response Example
/v1/policies/managed/{policy_name}Get detailed information about a specific managed policy
Path Parameters
policy_nameManaged policy name
Validation: Must exist in available managed policies
Request Example
Response Fields
namePolicy name
descriptionPolicy description
rulesArray of detection rules
created_atCreation timestamp
last_updatedLast update timestamp
Response Example
Custom Policies
Create your own custom moderation policies with specific detection rules. Custom policies can be attached to profiles and used during content moderation.
/v1/policies/customCreate a new custom moderation policy with your own detection rules.
Request Body Parameters
policy_nameUnique identifier for the policy (alphanumeric, hyphens, underscores)
Validation: Must not start with '__' (reserved for system use)
descriptionDescription of what the policy detects
rulesArray of detection rules as strings
Validation: Must be non-empty array
Request Example
Response Fields
policy_namePolicy identifier
descriptionPolicy description
rulesArray of detection rules
created_atISO 8601 timestamp
Response Example
/v1/policies/customList all custom policies for the authenticated user with pagination.
Query Parameters
limitNumber of policies to return Defaults to 20.
Validation: Between 1 and 100
offsetNumber of policies to skip Defaults to 0.
Request Example
Response Fields
policiesArray of policy summaries
policies[].policy_namePolicy identifier
policies[].descriptionPolicy description
policies[].rules_countNumber of rules in the policy
policies[].created_atISO 8601 timestamp
policies[].updated_atISO 8601 timestamp
totalTotal number of policies
paginationPagination information
pagination.limitLimit used
pagination.offsetOffset used
pagination.has_moreWhether more results exist
Response Example
/v1/policies/custom/{policy_name}Get detailed information about a specific custom policy including all rules.
Path Parameters
policy_nameName of the custom policy
Request Example
Response Fields
policy_namePolicy identifier
descriptionPolicy description
rulesArray of detection rules
created_atISO 8601 timestamp
updated_atISO 8601 timestamp
Response Example
/v1/policies/custom/{policy_name}Update a custom policy. Changes cascade to all profiles using this policy.
Path Parameters
policy_nameName of the custom policy
Request Body Parameters
descriptionUpdated policy description
rulesUpdated array of detection rules
Validation: Must be non-empty array if provided
Request Example
Response Fields
policy_namePolicy identifier
descriptionUpdated description
rulesUpdated rules array
updated_atISO 8601 timestamp
profiles_affectedNumber of profiles using this policy
Response Example
/v1/policies/custom/{policy_name}Delete a custom policy. Automatically removes it from all profiles using it.
Path Parameters
policy_nameName of the custom policy
Request Example
Response Fields
policy_namePolicy identifier
statusDeletion status (always 'deleted')
deleted_atISO 8601 timestamp
profiles_affectedNumber of profiles that used this policy