← API documentation

Perspective-compatible API

A drop-in replacement for Perspective API's comments:analyze. Migrating? Start with the migration guide.

Endpoints

Base URL: https://cleanmod.dev. CORS is enabled, but call the API from your backend so your key stays private.

POST/v1alpha1/comments:analyzeScore a comment (Perspective's AnalyzeComment).
POST/v1alpha1/comments:suggestscoreAccepted and acknowledged. Nothing is stored and it doesn't count toward quota.
GET/$discovery/rest?version=v1alpha1Discovery document for Google's client libraries. Also at /discovery/v1/apis/commentanalyzer/v1alpha1/rest.

Authentication

Use a CleanMod API key from your dashboard. Any of these work:

  • Authorization: Bearer YOUR_API_KEY (recommended)
  • ?key=YOUR_API_KEY query parameter, as Perspective clients send it
  • x-goog-api-key or x-api-key header

Keys in a query string tend to be recorded in proxy and hosting logs along the way, ours included, which is why the header is recommended. CleanMod keeps only a hash of your key and redacts keys from the moderation logs it writes.

Request

FieldTypeNotes
comment.textstring, requiredThe comment to score. Max 20 KB.
comment.typeenumPLAIN_TEXT (default). HTML is rejected, as on Perspective.
requestedAttributesmap, requiredAttribute name → config, e.g. {"TOXICITY": {}}. See the attribute table below.
requestedAttributes.*.scoreThresholdnumberScores below this value are left out of the response.
requestedAttributes.*.scoreTypeenumPROBABILITY only (the default).
languagesstring[]ISO 639-1 / BCP-47 codes. If omitted, the language is detected.
doNotStorebooleanOnly a hash of the comment is stored, never the text.
spanAnnotationsbooleanAccepted. Span scores are always returned (see below).
clientTokenstringEchoed back in the response.
dropUnsupportedAttributesbooleanSkip attributes that are unknown or not supported for the language instead of returning an error.
context, sessionId, communityId—Accepted and ignored.
Example request
curl -X POST https://cleanmod.dev/v1alpha1/comments:analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": { "text": "friendly greetings from python" },
    "requestedAttributes": { "TOXICITY": {} }
  }'

Response

The same shape as Perspective's AnalyzeCommentResponse. All scores are probabilities between 0 and 1.

Example response
{
  "attributeScores": {
    "TOXICITY": {
      "spanScores": [
        { "begin": 0, "end": 30, "score": { "value": 0.0113647086545825, "type": "PROBABILITY" } }
      ],
      "summaryScore": { "value": 0.0113647086545825, "type": "PROBABILITY" }
    }
  },
  "languages": ["en"],
  "detectedLanguages": ["en"]
}
  • summaryScore: the score for the whole comment.
  • spanScores: one span for comments up to about 1,000 characters; longer comments get one span per ~1,000-character chunk, and the summary is the highest chunk score. Offsets are UTF-16 code units, end-exclusive. Spans are not per-sentence as on Perspective.
  • languages: the languages you sent, or the detected one.
  • detectedLanguages: only present when the language was detected. If the text was too short to detect, it is ["und"] and the comment is scored as English.
  • clientToken: echoed if you sent one.

Attributes and languages

The _EXPERIMENTAL versions of the six production attributes return the same scores. Other Perspective attributes (FLIRTATION, SPAM, the New York Times and bridging attributes) return Unknown requested attribute.

English only, for now. Comments in other languages, whether sent in languages or detected, return LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE. Request a language.

Perspective attributeWhat it scoresLanguages on CleanMod
TOXICITYRude, disrespectful or unreasonable commentsEnglish
SEVERE_TOXICITYVery hateful, aggressive or disrespectful commentsEnglish
IDENTITY_ATTACKNegative or hateful comments targeting identityEnglish
INSULTInsulting, inflammatory or negative comments toward a personEnglish
PROFANITYSwear words, curse words and other obscene languageEnglish
THREATIntent to inflict pain, injury or violenceEnglish
SEXUALLY_EXPLICITReferences to sexual acts or body partsEnglish

Scores come from open Detoxify-family models and don't match Perspective's numerically. Re-check your thresholds.

Errors

Errors use Google's error envelope with Perspective's documented messages:

{
  "error": {
    "code": 400,
    "message": "Attribute INSULT does not support request languages: es",
    "status": "INVALID_ARGUMENT",
    "details": [{
      "@type": "type.googleapis.com/google.commentanalyzer.v1alpha1.Error",
      "errorType": "LANGUAGE_NOT_SUPPORTED_BY_ATTRIBUTE",
      "languageNotSupportedByAttributeError": {
        "requestedLanguages": ["es"],
        "attribute": "INSULT"
      }
    }, {
      "@type": "type.googleapis.com/google.rpc.Help",
      "links": [{
        "description": "Request support for more languages",
        "url": "https://cleanmod.dev/languages"
      }]
    }]
  }
}
HTTPstatusmessage
400INVALID_ARGUMENTAPI key not valid. Please pass a valid API key.
403PERMISSION_DENIEDPermission denied on the service. (no API key sent)
400INVALID_ARGUMENTComment must be non-empty.
400INVALID_ARGUMENTComment text too long.
400INVALID_ARGUMENTMissing requested_attributes
400INVALID_ARGUMENTUnknown requested attribute: <ATTR>
400INVALID_ARGUMENTAttribute <ATTR> does not support request languages: <langs>
400INVALID_ARGUMENTRequested score type <TYPE> is not supported by attribute <ATTR>
400INVALID_ARGUMENTCurrently, only 'PLAIN_TEXT' comments are supported
400INVALID_ARGUMENTInvalid JSON payload received. …
429RESOURCE_EXHAUSTEDQuota exceeded … (monthly plan quota)
503UNAVAILABLEThe service is currently unavailable.

Google client libraries

The googleapis Node client and the Python discovery client build request URLs from a discovery document. Point them at CleanMod's:

https://cleanmod.dev/$discovery/rest?version=v1alpha1

Full examples are in the migration guide.

Limits

  • Comments up to 20 KB.
  • Each successful comments:analyze call counts as one request toward your monthly plan quota (see pricing). Over quota returns HTTP 429 RESOURCE_EXHAUSTED.