Authentication
Use API keys for server-to-server communication and programmatic access to the Modsift API. Navigate to Dashboard → API Keys to create a new API key, then include it in the Authorization header of all requests:
Quickstart
Get up and running with Modsift in minutes. This guide walks you through the essentials: testing policies, and creating your first profile.
1. Test a Policy
Test any managed policy instantly without creating a profile. Use the policy parameter to evaluate content against a single policy:
1b. Test with Images
ModSift supports image moderation using base64-encoded data URLs. You can moderate images alone or combined with text:
Note: Images cost 65 units each. Supported formats: JPEG, PNG, GIF, WebP (max 5MB).
2. Create a Profile
Profiles let you evaluate content against multiple policies at once. Create a profile with your chosen policies and thresholds:
3. Moderate with Profile
Now use your profile to evaluate content against all attached policies in a single request:
4. 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:
5. 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:
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
Moderate Content
/v1/moderatePrimary moderation endpoint for analyzing content against configured policies
Request Body Parameters
contentContent to moderate. String for text-only, or array of content blocks `[{type: 'text', text: '...'}, {type: 'image_url', image_url: 'data:image/jpeg;base64,...'}]`. Max 1 image per request, supported formats: jpeg, png, gif, webp (max 5MB).
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
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 text quotes only - never contains image descriptions)
metadata.total_units_usedAPI units consumed by this request (1 unit = 100 characters for text, 65 units per image)
metadata.content_typesArray of content types present in the request. Possible values: `['text']`, `['image_url']`, or `['text', 'image_url']`
metadata.image_countNumber of images in the request (0 for text-only)
Response
Profile Management
Create Profile
/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
Response Fields
nameCreated profile name
created_atISO 8601 timestamp of creation
Response
List Profiles
/v1/profilesList all moderation profiles for the authenticated user
Request
Response Fields
profilesList of profile summaries
totalTotal number of profiles
Response
Get Profile
/v1/profiles/{profile_id}Get detailed information about a specific profile
Path Parameters
profile_idName of the profile to retrieve
Request
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
Update Profile
/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
Response Fields
nameProfile name (possibly new)
updated_atUpdate timestamp
statusAlways "updated"
Response
Delete Profile
/v1/profiles/{profile_id}Delete a moderation profile
Path Parameters
profile_idProfile to delete
Request
Response Fields
nameDeleted profile name
statusAlways "deleted"
deleted_atDeletion timestamp
Response
Attach Policies
/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
Response Fields
nameProfile name
attached_policiesList of attachment results with name, status, and attached_at
messageSuccess message
Response
Detach Policy
/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
Response Fields
nameProfile name
policy_nameDetached policy name
statusAlways "detached"
detached_atDetachment timestamp
Response
Update Policy Threshold
/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
Response Fields
nameProfile name
policy_nameUpdated policy name
thresholdNew threshold
statusAlways "updated"
updated_atUpdate timestamp
Response
Managed Policies
List 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
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
Get Managed Policy
/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
Response Fields
namePolicy name
descriptionPolicy description
rulesArray of detection rules
created_atCreation timestamp
last_updatedLast update timestamp
Response
Custom Policies
Create your own custom moderation policies with specific detection rules. Custom policies can be attached to profiles and used during content moderation.
Create Custom Policy
/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
Response Fields
policy_namePolicy identifier
descriptionPolicy description
rulesArray of detection rules
created_atISO 8601 timestamp
Response
List Custom Policies
/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
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
Get Custom Policy
/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
Response Fields
policy_namePolicy identifier
descriptionPolicy description
rulesArray of detection rules
created_atISO 8601 timestamp
updated_atISO 8601 timestamp
Response
Update Custom Policy
/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
Response Fields
policy_namePolicy identifier
descriptionUpdated description
rulesUpdated rules array
updated_atISO 8601 timestamp
profiles_affectedNumber of profiles using this policy
Response
Delete Custom Policy
/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
Response Fields
policy_namePolicy identifier
statusDeletion status (always 'deleted')
deleted_atISO 8601 timestamp
profiles_affectedNumber of profiles that used this policy