Getting Started with Babel Shield

You'll be moderating content in under 5 minutes. This guide walks you through creating an account, getting an API token, and making your first moderation request.

Prerequisites

  • A Babel Shield account (sign up here)
  • An API token (created in the dashboard after sign-up)
  • A tool to make HTTP requests (cURL, Postman, or your application's HTTP client)

Step 1: Sign Up and Get Your Token

  1. Go to your Babel Shield dashboard and create an account
  2. Log in to the dashboard
  3. Navigate to the token management page
  4. Create a new API token and give it a descriptive name (e.g., "Production API" or "Development")
  5. Copy the token immediately

Important: The token is shown only once. Store it somewhere safe. If you lose it, you'll need to create a new one.

Token Security: When using the official babel-shield.js library, host-restricted tokens in the script tag are protected by domain validation and server-side rate limiting. Note that host restrictions are a defense-in-depth measure -- they can be bypassed by non-browser clients sending spoofed headers, so treat them as a safeguard rather than a primary security control. For custom integrations making direct API calls from client-side code, use a server-side proxy to keep tokens private.

Note: After creating a token, you can optionally configure host restrictions in the dashboard to limit which domains can use the token. This is not available via the API.

Step 2: Verify Your Token

Before moderating content, confirm your token is working by checking your user information.

cURL:

curl https://api.babelshield.ai/api/v1/user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

JavaScript:

const response = await fetch("https://api.babelshield.ai/api/v1/user", {
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
  }
});
const data = await response.json();
console.log(data);

Expected response:

{
  "user": {
    "name": "Jane Smith",
    "email": "[email protected]",
    "current_usage": 0,
    "hard_limit": 200,
    "soft_limit": 150
  },
  "account": {
    "name": "Acme Corp",
    "company": "Acme Inc"
  },
  "token": {
    "name": "Production API",
    "abilities": [
      "moderate content",
      "view tokens"
    ],
    "last_used_at": null,
    "expires_at": null
  }
}

The current_usage, hard_limit, and soft_limit fields track your API usage. When current_usage reaches hard_limit, requests will be blocked. Check these values to monitor your quota.

Step 3: Moderate Your First Content

Send content to the moderation endpoint:

cURL:

curl -X POST https://api.babelshield.ai/api/v1/moderate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"payload": "Hello, this is a test message"}'

JavaScript:

const response = await fetch("https://api.babelshield.ai/api/v1/moderate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    payload: "Hello, this is a test message"
  })
});
const data = await response.json();
console.log(data);

Expected response:

{
  "results": {
    "category_scores": {
      "spam": 0,
      "profanity": 0,
      "sexual": 0,
      "offensive": 0,
      "violence": 0,
      "hate": 0,
      "harassment": 0,
      "self-harm": 0,
      "deception": 0,
      "garbage": 0,
      "crypto": 0,
      "illicit": 0,
      "injection": 0
    },
    "primary_category": null,
    "response_summary": "The content appears to be a benign greeting with no moderation concerns."
  },
  "meta": {
    "req_id": "8f3ddc6d-8445-40f9-9508-0979f9a3eafc",
    "service_ip": null,
    "response_time_ms": 1250,
    "flagged": false,
    "categories_flagged": [],
    "effective_thresholds": {
      "spam": 70,
      "profanity": 50,
      "sexual": 75,
      "offensive": 75,
      "violence": 75,
      "hate": 30,
      "harassment": 75,
      "self-harm": 75,
      "deception": 75,
      "garbage": 75,
      "crypto": 90,
      "illicit": 75,
      "injection": 80
    },
    "primary_category": null,
    "primary_score": 0,
    "pii": {
      "sanitized": false,
      "counts": { "creditCard": 0, "ssn": 0, "phone": 0, "ipAddress": 0, "email": 0 }
    },
    "relevance_flag": null,
    "version": "v1",
    "timestamp": "2026-02-27T12:00:00.000000Z"
  }
}

This clean message scores 0 across all 13 categories -- nothing was flagged. relevance_flag is an advisory off-topic-for-source signal (true/false/null); it never affects flagged.

Step 4: Interpret the Results

When reviewing a moderation response, check these three fields in order:

  1. meta.flagged -- Did anything exceed a threshold? This is your simplest yes/no signal.
  2. meta.categories_flagged -- Which categories triggered? This tells you what kind of content was detected.
  3. results.category_scores -- What were the exact scores? Use this for fine-grained decisions.

Score Interpretation

Score Range Interpretation Typical Action
0-20 Very unlikely to contain this category Auto-approve
21-50 Low confidence Usually safe, monitor if needed
51-79 Moderate confidence Queue for human review
80-100 High confidence Flag or block

Default thresholds are category-specific (for example: spam=70, profanity=50, hate=30, crypto=90, injection=80; most others 75). Content is flagged when any category score meets or exceeds its threshold.

Flagging is advisory, not enforcement. Your application decides what to do with flagged content -- block it, queue it for human review, or log it for later analysis.

Troubleshooting

  • 401 Unauthorized: Your token is invalid or missing. Check the Authorization header format: Bearer YOUR_API_TOKEN
  • 403 Forbidden: Insufficient permissions. Your token may not have the moderate content ability. Contact your administrator.
  • 422 Unprocessable Entity: The request body is invalid. Check the error details in the response errors field.
  • 429 Too Many Requests: You've hit your usage limit. Check your remaining quota with GET /api/v1/user.

See the Error Reference in the API Reference for full details.

Next Steps

Now that you've made your first moderation request, explore the full capabilities:

  • Configuration Reference -- All configuration options, thresholds, feedback modes, and proxy setup
  • API Reference -- Complete endpoint documentation, category filtering, threshold overrides, caching options, and security best practices
  • Category filtering -- Analyze only specific categories by passing a categories array
  • Custom thresholds -- Override thresholds per-request with options.thresholds
  • Caching -- Control cache duration with options.cache_ttl (60-86400 seconds)
  • Host-restricted tokens -- Secure browser-side API calls by limiting tokens to specific domains (configured in the dashboard)