Connect your platform to enterprise-grade content moderation in minutes with our RESTful API, native SDKs for six languages, webhooks, custom model training, and flexible response pipelines designed around your unique requirements.
From a single REST endpoint to fully customized moderation pipelines, our platform adapts to your architecture rather than the other way around.
Clean, versioned REST endpoints with predictable resource URLs, standard HTTP methods, and consistent JSON responses that follow OpenAPI 3.1 specifications for automated code generation.
Official, maintained SDKs for Python, Node.js, Java, Go, Ruby, and PHP with idiomatic patterns, full type safety, built-in retry logic, and comprehensive test suites for each language ecosystem.
Event-driven webhook delivery with HMAC signature verification, configurable retry policies, dead-letter queues, and granular event filtering so your systems react instantly to moderation decisions.
Choose between API key authentication for server-to-server calls or OAuth 2.0 flows for user-delegated access, with scoped permissions, key rotation, and audit logging built in.
Train custom classifiers on your own labeled data to detect platform-specific violations, brand guidelines, or industry-regulated content categories not covered by the default models.
Submit thousands of items in a single batch request or use async endpoints with callback URLs for long-running jobs, enabling efficient backfill and bulk moderation workflows.
Our official SDKs are not thin HTTP wrappers. Each library is built by engineers who live in that language ecosystem, following idiomatic conventions, leveraging native async patterns, and shipping with full type definitions so your IDE provides complete autocomplete and compile-time safety.
Every API call follows a clean, predictable lifecycle: authenticate, submit content, receive a structured JSON response with confidence scores, category labels, and optional metadata passthrough. Synchronous endpoints return within 50 ms; async endpoints accept a callback URL and POST the result when processing completes.
Developers choose our API because it is fast to integrate, reliable in production, and flexible enough to handle any moderation workflow at any scale.
The ContentModerationAPI is built on a resource-oriented RESTful architecture that treats every piece of content, every moderation decision, and every policy rule as a first-class resource with its own URL, lifecycle, and set of allowed HTTP methods. This design ensures that developers who understand REST conventions can predict endpoint behavior without consulting the documentation for every call. Resources are organized into logical groups such as /v2/moderate/text, /v2/moderate/image, and /v2/moderate/video, each supporting POST for submission, GET for status retrieval on async jobs, and DELETE for cancellation of pending work.
All request and response bodies use JSON with consistent field naming in snake_case. Every response includes a top-level request_id for tracing, a status field indicating the outcome, and a data object containing the actual moderation results. Error responses follow the RFC 7807 Problem Details standard, providing a machine-readable type URI, a human-readable title and detail, and an optional errors array for validation failures. This consistency means your error-handling code works identically across every endpoint without special cases.
We version our API at the URL level. The current production version is v2, and we guarantee backward compatibility within a major version for at least twenty-four months after a successor version launches. When we introduce breaking changes, they land exclusively in the next major version, and we provide automated migration tooling in each SDK that rewrites deprecated patterns. Minor additions such as new optional fields, new event types, and new query parameters are introduced within the current version and are always additive, ensuring that existing integrations continue to function without modification.
The Python SDK is distributed through PyPI under the package name contentmoderationapi and supports Python 3.8 and above. It provides both synchronous and asynchronous client classes, with the async client built on httpx and fully compatible with asyncio, Trio, and AnyIO runtimes. Request and response objects are defined as Pydantic models, giving developers runtime validation, automatic serialization, and rich IDE autocompletion. The SDK includes a built-in retry handler with configurable exponential backoff, jitter, and maximum attempt limits that respect the Retry-After header returned by the API when rate limits are exceeded.
Common usage patterns are covered by convenience methods such as client.moderate_text(), client.moderate_image(), and client.moderate_batch(), while advanced users can construct arbitrary requests using the lower-level client.request() method. Logging integrates with Python's standard logging module, and the SDK ships with a structured JSON formatter that works well with centralized log aggregation systems. Every release is tested against CPython and PyPy on Linux, macOS, and Windows, and the test suite achieves one hundred percent line coverage of the public API surface.
The Node.js SDK is published on npm as @contentmoderationapi/node and ships as a dual ESM and CommonJS package with full TypeScript declarations. It works with Node.js 18 and above, Deno, and Bun, and leverages the built-in fetch API when available, falling back to undici on older Node versions. Every method returns a typed Promise, and the SDK exports Zod schemas that mirror the API's JSON Schema definitions, allowing developers to validate webhook payloads and API responses at the boundary of their applications.
The client supports automatic pagination via async iterators, so listing moderation jobs or fetching audit logs is as simple as for await (const job of client.jobs.list()). A middleware hook system lets developers inject custom logic before requests are sent or after responses are received, which is useful for adding observability headers, logging request durations, or transforming payloads to match internal data models. The SDK also includes a lightweight Express middleware that verifies webhook signatures and parses event payloads, reducing the boilerplate required to accept webhook deliveries to a single line of code.
The Java SDK is published to Maven Central and targets Java 11+, using immutable builder patterns for request construction and CompletableFuture for asynchronous operations. It integrates with SLF4J for logging, Micrometer for metrics, and Spring Boot via an auto-configuration starter that registers a ModerationClient bean from application properties. The Go SDK is a single module installable via go get, uses native context.Context propagation for cancellation and timeouts, and returns structured error types that can be inspected with errors.Is and errors.As. The Ruby SDK is a gem compatible with Ruby 3.0 and above, following Ruby conventions with method names in snake_case, keyword arguments, and Faraday-based HTTP transport that supports connection pooling. The PHP SDK is distributed through Composer, supports PHP 8.1 and above, implements PSR-7 and PSR-18 interfaces for HTTP interoperability, and includes a Laravel service provider for automatic dependency injection and configuration binding.
Webhooks are the backbone of our event-driven integration model. Rather than polling for moderation results, your application registers one or more endpoint URLs in the dashboard or via the API, selects the event types it cares about, and begins receiving HTTPS POST requests within milliseconds of each event occurring. Every webhook payload includes a unique event_id, a type field such as moderation.completed or appeal.submitted, a created_at ISO 8601 timestamp, and a data object containing the full event details.
Security is handled through HMAC-SHA256 signatures. Each webhook endpoint has a unique signing secret, and every delivery includes an X-Signature-256 header containing the hex-encoded HMAC of the raw request body. Our SDKs provide a one-line verification function that computes the expected signature and compares it in constant time to prevent timing attacks. If your endpoint returns a non-2xx status code, the delivery system retries with exponential backoff at intervals of 10 seconds, 30 seconds, 1 minute, 5 minutes, 15 minutes, 1 hour, and 6 hours, for a total of seven retry attempts over roughly seven hours. Failed deliveries that exhaust all retries are written to a dead-letter queue accessible through the dashboard and the API, where they can be inspected, replayed individually, or bulk-replayed with a single command.
Event filtering lets you subscribe to only the events relevant to each endpoint. A content routing service might subscribe to moderation.completed and moderation.escalated, while an analytics pipeline might subscribe to moderation.completed and batch.finished. Filters support wildcard patterns, so subscribing to moderation.* captures all moderation lifecycle events without needing to enumerate them individually. Each endpoint can also specify a minimum severity threshold, so a Slack notification webhook only fires when high-severity content is detected rather than on every routine moderation pass.
The API supports two authentication mechanisms designed for different use cases. API key authentication is the simplest path and is recommended for server-to-server integrations where a single long-lived credential is stored securely in environment variables or a secrets manager. Each API key is scoped to a specific project and can be restricted to a subset of endpoints, IP address ranges, and daily request quotas. Keys are transmitted in the Authorization header using the Bearer scheme, and the API validates them against a distributed key store with sub-millisecond lookup times. Key rotation is supported without downtime: you create a new key, update your deployment, and then revoke the old key, and both keys are valid concurrently during the overlap period.
OAuth 2.0 is available for integrations that act on behalf of end users, such as a third-party moderation dashboard where different team members have different permission levels. We support the Authorization Code flow with PKCE for web and mobile applications and the Client Credentials flow for machine-to-machine communication. Access tokens are short-lived JWTs with a default expiration of one hour, and refresh tokens are long-lived opaque tokens that can be exchanged for new access tokens without user interaction. Token scopes map to specific API capabilities such as moderate:read, moderate:write, policy:admin, and billing:read, providing fine-grained access control that follows the principle of least privilege.
Rate limiting protects the platform and ensures fair resource allocation among all customers. Limits are enforced per API key at two levels: a per-second burst limit that prevents individual keys from monopolizing backend capacity, and a per-month quota that aligns with the customer's subscription tier. The current default limits are 100 requests per second for the synchronous moderation endpoints and 1,000 requests per second for the batch submission endpoint, though enterprise plans can negotiate higher ceilings. Every API response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so that clients can implement proactive throttling rather than waiting for a 429 response.
When a request exceeds the rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. All of our official SDKs handle this automatically with configurable retry logic that respects the Retry-After value, adds randomized jitter to prevent thundering herd effects, and caps the total number of retries to avoid infinite loops. For customers who occasionally need to exceed their normal limits during planned migration events or marketing campaigns, we offer temporary limit increases that can be requested through the dashboard or the API up to 48 hours in advance.
Robust error handling is essential for production integrations, and the API is designed to make error recovery straightforward. Errors fall into three categories: client errors (4xx), server errors (5xx), and network errors. Client errors indicate problems with the request itself, such as invalid JSON, missing required fields, unsupported content types, or authentication failures. These errors are deterministic and should not be retried without modifying the request. Server errors indicate transient problems on our side, such as temporary overload or an upstream dependency failure, and are safe to retry with exponential backoff. Network errors, including connection timeouts and DNS resolution failures, should also be retried.
Our recommended retry strategy uses exponential backoff with full jitter. The initial delay is 500 milliseconds, and each subsequent attempt doubles the delay up to a maximum of 30 seconds, with a random jitter between zero and the computed delay added to each wait. This approach spreads retry traffic over time and prevents synchronized retries from amplifying load spikes. The SDK implementations follow this strategy by default and expose configuration options for the initial delay, maximum delay, maximum number of attempts, and a predicate function that determines which errors are retryable. For idempotent endpoints such as moderation submissions that include a client-generated idempotency_key, retries are safe even for POST requests because the server deduplicates requests by key and returns the original response.
Every account includes access to a sandbox environment at sandbox.contentmoderationapi.net that mirrors the production API with identical endpoints, authentication mechanisms, and response formats but processes requests against synthetic data and does not affect production quotas or billing. The sandbox is designed for integration testing, CI/CD pipelines, and developer onboarding, allowing teams to exercise every API feature, including webhooks, batch processing, and custom models, without incurring costs or risking accidental moderation of real user content.
The sandbox supports deterministic test fixtures that return predictable responses based on specific input patterns. Submitting the text __test_toxic__ always returns a high-toxicity score, while __test_clean__ always returns a clean score, making it easy to write automated tests that verify your application's handling of different moderation outcomes. Webhook deliveries from the sandbox are sent to the same endpoints configured for production but include a sandbox: true flag in the payload, allowing your webhook handler to distinguish test events from real ones. Rate limits in the sandbox are intentionally lower than production to encourage realistic testing of your retry and throttling logic under constrained conditions.
The default moderation models cover a broad set of categories including toxicity, hate speech, sexual content, violence, spam, and personally identifiable information. However, many platforms have unique content policies that require custom detection capabilities. Our custom model training pipeline lets you upload labeled datasets of content that violates or complies with your specific policies, and our infrastructure trains a specialized classifier that runs alongside the default models. Custom models are versioned, and you can promote a trained version to production, roll back to a previous version, or run A/B tests between versions to measure accuracy improvements before committing to a deployment.
Custom categories extend the standard taxonomy with labels meaningful to your business. An e-commerce marketplace might add categories such as counterfeit_goods, prohibited_chemicals, and misleading_claims. A healthcare platform might add unverified_medical_advice and prescription_solicitation. Each custom category can have its own confidence threshold, and the API response includes scores for both default and custom categories in a single unified payload. Training requires a minimum of 500 labeled examples per category, and we provide annotation tooling in the dashboard that supports team-based labeling workflows with inter-annotator agreement metrics to ensure data quality before training begins.
Every moderation category returns a confidence score between 0.0 and 1.0, and you control the decision threshold that determines whether content is flagged, allowed, or sent for human review. The default threshold of 0.5 provides a balanced trade-off between precision and recall, but you can adjust it per category to match your platform's risk tolerance. Lowering the threshold for the child_safety category to 0.3 catches more potential violations at the cost of more false positives, while raising the profanity threshold to 0.8 allows mild language through unless the model is highly confident. Threshold changes take effect immediately and do not require retraining or redeployment.
Our calibration dashboard visualizes the precision-recall curve for each category based on your historical moderation data, showing exactly how changing the threshold will affect your false positive and false negative rates. This data-driven approach removes guesswork from threshold tuning and lets you make informed decisions about the acceptable error trade-offs for each type of content violation. You can also configure different thresholds for different content routes, applying stricter standards to public comments visible to all users while allowing more permissive thresholds for private messages where the risk of widespread harm is lower.
For content types that require longer processing times, such as video analysis or large image batches, the API supports asynchronous submission with callback URLs. You POST the content to the async endpoint along with a callback_url parameter pointing to your server. The API immediately returns a 202 Accepted response with a job_id that you can use to check status via polling if needed. When processing completes, the API sends an HTTPS POST to your callback URL with the full moderation result, the original job_id, and any metadata you attached to the initial request.
Callback deliveries use the same HMAC signature verification and retry logic as webhooks, ensuring reliable delivery even if your callback endpoint experiences temporary downtime. You can register a default callback URL at the project level and override it on a per-request basis, which is useful when different services within your architecture handle different content types. The callback payload includes a processing_time_ms field indicating how long the analysis took, a model_version field identifying which model version produced the result, and a metadata field echoing back any custom key-value pairs you included in the original request, enabling seamless correlation between the submitted content and the asynchronous result in your application's data layer.
The batch processing API is designed for high-throughput scenarios such as backfilling moderation decisions for historical content, re-scanning content after a policy change, or processing large content imports from platform migrations. A single batch request can contain up to 10,000 items, each with its own content payload and optional metadata. The API accepts the batch, assigns it a batch_id, and processes items in parallel across our distributed infrastructure. Progress is reported through webhook events at configurable intervals and through a polling endpoint that returns the percentage of items completed, the count of items flagged, and an estimated time to completion.
Batch results are delivered in two ways: as individual webhook events for each completed item, which is useful for real-time processing pipelines, and as a downloadable JSONL file containing all results once the entire batch finishes, which is more efficient for bulk data processing. The batch API supports priority levels that control how quickly items are processed relative to real-time traffic, ensuring that bulk backfill operations do not degrade latency for live moderation requests. You can also pause, resume, and cancel batches in progress, providing operational control over long-running jobs that may need to yield to higher-priority work.
The API supports three response formats selected via the response_format parameter. The full format returns the complete moderation analysis including confidence scores for every category, detailed explanations of flagged content, token-level annotations for text, and bounding box coordinates for flagged regions in images. The summary format returns only the overall decision, the highest-scoring category, and its confidence score, reducing payload size by approximately eighty percent. The scores_only format returns a flat object mapping category names to confidence scores, which is the most compact representation and is useful for applications that implement their own decision logic based on raw scores.
Metadata passthrough allows you to attach arbitrary key-value pairs to each moderation request using the metadata field. These pairs are stored with the request, included in the response, echoed in webhook deliveries and async callbacks, and indexed for search in the audit log. Common use cases include passing your internal content ID so that webhook handlers can update the correct record in your database, attaching the user ID who submitted the content for downstream analytics, including a content type tag that your routing logic uses to direct flagged content to the appropriate review queue, and adding geographic or language context that supplements the API's own detection. Metadata values can be strings, numbers, or booleans, and each request supports up to 50 metadata fields with a combined size limit of 8 KB.
Content routing rules let you define conditional logic that determines how moderation results are processed downstream. Rules are expressed as JSON predicates evaluated against the moderation response, and actions include sending the content to a specific review queue, triggering a webhook to a designated endpoint, automatically applying a content label, or executing a custom serverless function hosted on our edge network. For example, you might create a rule that routes any image with a violence score above 0.7 to your trust-and-safety team's Slack channel while simultaneously adding a needs_review flag in your database via a webhook.
Rules are evaluated in priority order, and multiple rules can match a single moderation result, enabling layered workflows where content passes through several stages of automated processing before reaching a human reviewer. The rule engine supports logical operators (AND, OR, NOT), comparison operators (greater than, less than, equals, contains), and field path expressions that can reference nested values deep within the moderation response. Rules can be managed through the dashboard with a visual builder or through the API for programmatic configuration management, and changes take effect within seconds without requiring application restarts or redeployments.
Pipeline customization extends routing with the ability to chain multiple processing steps into a single moderation pipeline. A typical pipeline might first run text through language detection, then apply the appropriate language-specific moderation model, then check against a custom blocklist of platform-specific terms, and finally apply content routing rules based on the combined results. Pipelines are defined as YAML or JSON configurations, versioned in your source control alongside application code, and deployed through the API. This infrastructure-as-code approach ensures that moderation pipeline changes go through the same review and approval processes as application code changes, reducing the risk of accidental misconfigurations in a system that directly impacts user safety.
Production integrations should always include a fallback path for when the moderation API is unreachable. The recommended pattern is to queue content for moderation asynchronously and allow it to be published in a provisional state, then apply the moderation decision retroactively when the API responds. This approach ensures that a moderation service outage does not block content creation on your platform. For content categories where pre-publication moderation is legally or ethically required, such as child safety, implement a circuit breaker pattern that holds content in a pending state and alerts your operations team when the breaker opens, rather than allowing unmoderated content through.
Instrument your integration with metrics that track request latency percentiles, error rates by type, retry counts, webhook delivery success rates, and queue depths for content awaiting moderation. All of our SDKs emit events that can be captured by your observability stack, and the API itself exposes a /v2/health endpoint and a /v2/metrics endpoint that report aggregate performance data for your project. Set up alerts on latency spikes, elevated error rates, and webhook delivery failures so that your team is notified before integration issues affect end users. Our status page at status.contentmoderationapi.net provides real-time incident updates and historical uptime data, and we offer a dedicated webhook that pushes status changes to your incident management system.
Store API keys in a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or Google Secret Manager rather than in environment variables or configuration files. Restrict each key's permissions to only the endpoints your integration actually calls, and rotate keys on a regular schedule or immediately after any suspected compromise. For webhook endpoints, always verify the HMAC signature before processing the payload, reject requests with timestamps older than five minutes to prevent replay attacks, and serve your webhook endpoint over HTTPS with a certificate from a trusted certificate authority. If your integration handles personally identifiable information, enable the API's PII redaction feature to strip sensitive data from moderation responses and audit logs, reducing the scope of data your systems need to protect.
Common questions about integrating and customizing the Content Moderation API for your platform.
Start building with our API in minutes. Free sandbox access, official SDKs for six languages, and dedicated integration support for enterprise teams.