> ## Documentation Index
> Fetch the complete documentation index at: https://guardiandocs.korymsmith.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /v1/moderate/text
> Moderate a single text
## Endpoint
```
POST /v1/moderate/text
```
Analyzes a single text through all three models (sexism classifier, toxicity transformer, rule engine) and returns a comprehensive moderation response with ensemble scoring.
## Request
### Headers
| Header | Value | Required |
| -------------- | ------------------ | -------- |
| `Content-Type` | `application/json` | Yes |
### Body Parameters
The text to moderate. Should be a non-empty string.
**Min length**: 1 character
**Max length**: 10,000 characters (recommended)
### Request Example
```bash cURL theme={null}
curl -X POST "http://localhost:8000/v1/moderate/text" \
-H "Content-Type: application/json" \
-d '{
"text": "Your text to moderate here"
}'
```
```python Python SDK theme={null}
from guardian_api import GuardianClient
client = GuardianClient(base_url="http://localhost:8000")
result = client.moderate_text("Your text to moderate here")
print(result)
```
```javascript JavaScript SDK theme={null}
import { GuardianClient } from 'guardian-api-sdk';
const client = new GuardianClient({
baseUrl: 'http://localhost:8000'
});
const result = await client.moderateText('Your text to moderate here');
console.log(result);
```
```python Python (requests) theme={null}
import requests
response = requests.post(
"http://localhost:8000/v1/moderate/text",
json={"text": "Your text to moderate here"}
)
print(response.json())
```
```javascript JavaScript (fetch) theme={null}
const response = await fetch('http://localhost:8000/v1/moderate/text', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text: 'Your text to moderate here' })
});
const data = await response.json();
console.log(data);
```
## Response
Returns a [ModerationResponse](/api-reference/schemas/response#moderation-response) object with:
* Individual model outputs (`label`)
* Ensemble decision (`ensemble`)
* Metadata (`meta`)
### Response Schema
```json theme={null}
{
"text": "string",
"label": {
"sexism": {
"score": "number",
"severity": "string",
"model_version": "string",
"threshold_met": "boolean"
},
"toxicity": {
"overall": "number",
"insult": "number",
"threat": "number",
"identity_attack": "number",
"profanity": "number",
"model_version": "string"
},
"rules": {
"slur_detected": "boolean",
"threat_detected": "boolean",
"self_harm_flag": "boolean",
"profanity_flag": "boolean",
"caps_abuse": "boolean",
"character_repetition": "boolean",
"model_version": "string"
}
},
"ensemble": {
"summary": "string",
"primary_issue": "string",
"score": "number",
"severity": "string"
},
"meta": {
"processing_time_ms": "integer",
"models_used": ["string"]
}
}
```
### Success Response (200)
```json theme={null}
{
"text": "I love this product!",
"label": {
"sexism": {
"score": 0.043,
"severity": "low",
"model_version": "sexism_lasso_v1",
"threshold_met": false
},
"toxicity": {
"overall": 0.021,
"insult": 0.012,
"threat": 0.008,
"identity_attack": 0.010,
"profanity": 0.015,
"model_version": "toxic_roberta_v1"
},
"rules": {
"slur_detected": false,
"threat_detected": false,
"self_harm_flag": false,
"profanity_flag": false,
"caps_abuse": false,
"character_repetition": false,
"model_version": "rules_v1"
}
},
"ensemble": {
"summary": "likely_safe",
"primary_issue": "none",
"score": 0.024,
"severity": "low"
},
"meta": {
"processing_time_ms": 19,
"models_used": [
"sexism_lasso_v1",
"toxic_roberta_v1",
"rules_v1"
]
}
}
```
```json theme={null}
{
"text": "Women belong in the kitchen",
"label": {
"sexism": {
"score": 0.847,
"severity": "high",
"model_version": "sexism_lasso_v1",
"threshold_met": true
},
"toxicity": {
"overall": 0.621,
"insult": 0.543,
"threat": 0.087,
"identity_attack": 0.621,
"profanity": 0.124,
"model_version": "toxic_roberta_v1"
},
"rules": {
"slur_detected": false,
"threat_detected": false,
"self_harm_flag": false,
"profanity_flag": false,
"caps_abuse": false,
"character_repetition": false,
"model_version": "rules_v1"
}
},
"ensemble": {
"summary": "highly_harmful",
"primary_issue": "sexism",
"score": 0.689,
"severity": "high"
},
"meta": {
"processing_time_ms": 27,
"models_used": [
"sexism_lasso_v1",
"toxic_roberta_v1",
"rules_v1"
]
}
}
```
### Error Responses
**Cause**: Invalid request body or empty text
```json theme={null}
{
"detail": [
{
"loc": ["body", "text"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
```
**Cause**: Request body doesn't match expected schema
```json theme={null}
{
"detail": [
{
"loc": ["body", "text"],
"msg": "str type expected",
"type": "type_error.str"
}
]
}
```
**Cause**: Server error during processing
```json theme={null}
{
"detail": "Error processing moderation: [error message]"
}
```
## Performance
| Metric | Value |
| ------------------------- | ------------------------ |
| **Average Response Time** | 20-40ms |
| **With GPU** | 15-25ms |
| **Without GPU** | 40-60ms |
| **Rate Limit** | Configurable (via Redis) |
For optimal performance with multiple texts, use the [batch endpoint](/api-reference/moderate-batch) instead of making multiple individual requests.
## Use Cases
* **Real-time moderation**: Moderate user comments before posting
* **Content filtering**: Screen user-generated content
* **Chat moderation**: Filter messages in real-time
* **Form validation**: Check text inputs on submission
## Best Practices
The API handles preprocessing automatically. Send raw user input without manual cleaning.
Rely on `ensemble.summary` for quick decisions. Individual model outputs are available for detailed analysis.
Implement proper error handling. The API returns detailed error messages.
Track `processing_time_ms` to monitor performance and detect issues.
## Related Endpoints
Moderate multiple texts at once
Check API health status
## See Also
* [Response Structure](/concepts/response-structure) - Understanding the response
* [Ensemble Logic](/concepts/ensemble) - How scores are calculated
* [Python SDK](/sdks/python) - Python client library
* [JavaScript SDK](/sdks/javascript) - JavaScript/TypeScript client library