API Documentation

Get a moderation decision in under 5 minutes. Create an account, get an API key from the dashboard, and send your first request:

curl -X POST https://api.hushsafe.com/v1/moderate \
  -H "Authorization: Bearer hs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!"}'

All API requests require a Bearer token in the Authorization header. Keys begin with hs_live_ and are shown once at creation.

Authorization: Bearer hs_live_<your_key>

Keys are HMAC-SHA256 hashed server-side. If a key is compromised, revoke it immediately from API Keys and generate a new one.

Moderate a single piece of text.

Request body

Example request

curl -X POST https://api.hushsafe.com/v1/moderate \
  -H "Authorization: Bearer hs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "I hate you so much"}'

Example response

{
  "request_id": "req_01HX4ZMQKP8J5N3TG7R2WBAC9D",
  "decision": "BLOCK",
  "scores": {
    "hate": 0.92,
    "harassment": 0.87,
    "sexual": 0.03,
    "self_harm": 0.01,
    "violence": 0.08,
    "spam": 0.04,
    "threat": 0.44
  },
  "explanation": "High hate and harassment signals — contains dehumanizing language targeting a person.",
  "tier_reached": 1,
  "latency_ms": 7,
  "model_version": "xlm-roberta-v2.1-onnx-int8",
  "language": "en",
  "watermark": {
    "signed": true,
    "algorithm": "HMAC-SHA256",
    "dsa_compliant": true
  }
}

Moderate a multi-turn conversation with context-aware risk signals.

Supports up to 20 turns. Returns standard moderation output plus context_risk signals: secrecy patterns, age/minor references, sexualization escalation, and late-turn escalation.

{
  "turns": [
    { "role": "user", "text": "hey wanna hang out?" },
    { "role": "assistant", "text": "sure, where?" },
    { "role": "user", "text": "don't tell your parents, let's meet alone" }
  ]
}

Moderate up to 100 texts in a single request. Processed in parallel (max 10 concurrent).

{
  "items": [
    { "id": "msg_1", "text": "Hello world" },
    { "id": "msg_2", "text": "I will hurt you" }
  ]
}

Re-run a retained request payload under the current model and policy. Useful for debugging threshold changes and policy DSL effects. Requires retention_days > 0 in config.

Returns a plain-English explanation of what would need to change for the decision to flip to a specified target decision.

{ "target_decision": "PASS" }
// Response:
{
  "current_decision": "BLOCK",
  "target_decision": "PASS",
  "explanation": "The harassment score (0.87) would need to drop below 0.35 (your PASS threshold). The phrase 'I hate you' accounts for most of this signal.",
  "policy_band": "harassment"
}

All scores are returned for every request, regardless of which tier resolved it. Scores range from 0.0 (clean) to 1.0 (high confidence positive signal).

Rate limit status is returned in response headers: X-RateLimit-Remaining, X-RateLimit-Reset. When exceeded, HTTP 429 is returned with a Retry-After header.

Both SDKs include TypeScript types, retry logic, and support for all API endpoints. Source code is available on GitHub.