CautionLabs API

Send text, get instant true/false moderation flags across twelve harm categories, plus an overall flagged result. One endpoint, simple JSON, production-ready.

RESTJSONHTTPShttps://api.cautionlabs.com

Introduction

The CautionLabs API analyzes user-generated text and returns a boolean flag for each moderation category — true if the category was detected, false if not — plus a top-level flagged field indicating whether any category was triggered. Use it to filter chat, comments, reviews, UGC, and any text-heavy product surface. It is built for English text.

All requests are made over HTTPS. Responses are JSON. There is a single primary endpoint — no versioning sprawl, no graph of micro-endpoints to learn.

Need to keep text inside your own network? The same model is available to run on your infrastructure. See the On-Premises guide.

Base URL: https://api.cautionlabs.com
Need an API key? from the dashboard.

Quickstart

Make your first moderation request in under a minute.

Create a free account and copy your API key from the API Keys page.
Replace YOUR_API_KEY in the examples below.
Send a POST request to /moderation with a JSON body containing text.

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

Authentication

Authenticate every request with a cloud API key in the Authorization header using the Bearer scheme. Private keys, which download on-premises models, are not accepted here.

JSON

Authorization: Bearer YOUR_API_KEY

Keep your key secure

Never expose API keys in client-side code or public repositories.
Call the API from your backend or a trusted proxy.
Replace compromised keys immediately: delete the key on the API Keys page, then create a new one.

Moderate text

Analyze a string of text and receive a boolean flag for each of the twelve moderation categories, plus an overall flagged result.

POST/moderation

Request body

Field	Type	Required	Description
`text`	string	Yes	The text content to analyze. UTF-8 encoded, 1 to 10,000 characters. A text over 3,000 characters is checked in pieces; see Credits & billing.

Example request

curl -X POST https://api.cautionlabs.com/moderation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your content to analyze"}'

Example response

Returns 200 OK with a JSON object containing a categories object (each key a boolean flag) and a top-level flagged boolean that is true if any category was detected.

{
  categories: {
    toxic: false,
    profanity: false,
    hate: false,
    harassment: false,
    self_harm: false,
    adult: false,
    violence: false,
    drugs: false,
    weapons: false,
    pii: false,
    spam: true,
    minor: false,
  },
  flagged: true,
}

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`application/json`

Response fields

Every successful response includes all twelve category flags nested under categories, plus a top-level flagged boolean. Each category is either true (detected) or false (not detected) — no thresholds to tune.

Field	Category	Description
`flagged`	Flagged	Top-level boolean, `true` if any category under `categories` is `true`.
`categories.toxic`	Toxicity	Boolean flag — true if the text contains toxic content
`categories.profanity`	Profanity	Boolean flag — true if the text contains profanity
`categories.hate`	Hate Speech	Boolean flag — true if the text contains hate speech
`categories.harassment`	Harassment	Boolean flag — true if the text contains harassment
`categories.self_harm`	Self-Harm	Boolean flag — true if the text contains self-harm content
`categories.adult`	Adult Content	Boolean flag — true if the text contains adult content
`categories.violence`	Violence	Boolean flag — true if the text contains violent content
`categories.drugs`	Drug Content	Boolean flag — true if the text contains drug-related content
`categories.weapons`	Weapons	Boolean flag — true if the text contains weapons-related content
`categories.pii`	PII Detection	Boolean flag — true if the text contains PII
`categories.spam`	Spam	Boolean flag — true if the text is spam
`categories.minor`	Minor Safety	Boolean flag — true if the text endangers minor safety

Tip: Each category under categories is a boolean — true means the category was detected in the text, false means it wasn't. The top-level flagged field is true if any category is true, so you can gate on it directly without needing to tune thresholds.

Errors

Errors use standard HTTP status codes. The response body is a JSON object with a code and a message. Branch on code, which never changes meaning; message is plain English and may be reworded.

{
  code: 'insufficient_credits',
  message: 'Insufficient Credits',
}

Status	Code	Description
`400`	`invalid_request`	Missing or malformed request body: `text` is missing, empty, or longer than 10,000 characters.
`401`	`unauthorized`	Missing, invalid, or revoked API key.
`402`	`insufficient_credits`	The account does not have enough credits for this request. A text over 3,000 characters needs one credit per started 3,000 characters.
`403`	`wrong_key_type`	A private (on-premises) key was used. This endpoint needs a cloud API key.
`500`	`internal_error`	Unexpected server error. Retry with exponential backoff.

Credits & billing

Each moderation request consumes credits from your account balance.

Purchase additional credits from the Buy Credits page (minimum $5 USD).
$0.40 USD per 1,000 requests — approximately 2,500 credits per $1 USD.
One request is up to 3,000 characters and costs one credit. A longer text, up to 10,000 characters, is checked in pieces of about 3,000 characters, and each piece costs one credit. A flag in any piece flags the whole text, and a 7,500 character text costs 3 credits. Nothing is charged if the request fails.
When credits are exhausted, requests return 402 Payment Required with code insufficient_credits.