Perspective API shuts down on December 31, 2026.Switch by changing one URL

Checks

A check tells you whether a message is spam. It can also score toxicity, self-harm, sexual content and personal details. Spamgone uses AI to judge each message, together with the context you send and signals from your own traffic.

Check a message

POST /v1/checks
Authorization: Bearer sg_live_...
{
  "text": "Turn $250 into $5,000 in 7 days. DM me on Telegram",
  "context": {
    "content_type": "message",
    "author": {
      "id": "user_8412",
      "created_at": "2026-11-14T07:58:00Z",
      "verified": false,
      "role": "member"
    },
    "recipient": { "id": "user_17", "is_contact": false }
  },
  "checks": ["spam", "toxicity"]
}
Field Type Required Description
text string yes The message, 1 to 10,000 characters.
context.content_type string no message, comment, post, profile, username, review or other.
context.author.id string no Your ID for the author. Used for rules and sending-pattern signals, never sent to the AI model.
context.author.created_at string no When the author's account was created, as an ISO 8601 date and time.
context.author.verified boolean no Whether you have verified the author.
context.author.role string no The author's role, such as member, staff, officer or admin. Staff sending the same announcement to many people isn't treated as spam for that alone.
context.recipient.id string no Your ID for the recipient.
context.recipient.is_contact boolean no Whether the recipient knows the author.
checks string[] no ["spam"] by default. Add toxicity, self_harm, sexual or pii for those scores. Spam always runs.

Unknown fields are rejected with validation_error, naming the field.

Response

{
  "object": "check",
  "id": "8f6f1c9e-0f0e-4c55-9a31-5d1d1e7f2b10",
  "spam": {
    "score": 0.97,
    "action": "block",
    "category": "scam",
    "reasons": [
      "Looks like a scam: promises money, prizes or easy returns",
      "Sent by an account created 2 hours ago"
    ]
  },
  "toxicity": {
    "score": 0.04,
    "labels": {
      "insult": 0.02,
      "threat": 0.01,
      "identity_attack": 0.01,
      "profanity": 0.01,
      "severe_toxicity": 0.01
    }
  },
  "cached": false,
  "test": false,
  "created_at": "2026-11-14T09:58:12Z"
}
Field Description
spam.score How likely the message is spam, from 0 to 1.
spam.action What to do: block, review or allow, from your thresholds.
spam.category scam, phishing, promotion, adult, malware, other_spam, or none for allowed messages.
spam.reasons Up to five short reasons in plain language. They never quote the message.
toxicity Only when you asked for it: an overall score and a score for each of insult, threat, identity_attack, profanity and severe_toxicity, each from 0 to 1.
self_harm Only when you asked for it. See Other checks.
sexual Only when you asked for it. See Other checks.
pii Only when you asked for it, with exact matches. See Other checks.
cached true when an identical recent check was reused. It still counts toward your usage.
test true for checks made with a test key.

Other checks

Add any of toxicity, self_harm, sexual and pii to checks. Each comes back as an object with a score and labels, each from 0 to 1. They don't change spam.action, so you decide what to do with them. A message counts as one check, whatever you ask for.

Check Labels score
toxicity insult, threat, identity_attack, profanity, severe_toxicity Overall toxicity, judged itself
self_harm intent: the author may want to hurt or kill themselves. encouragement: urges, praises or explains self-harm, suicide or disordered eating, including telling someone to kill themselves. The highest label
sexual explicit: describes sexual acts or genitals in detail. solicitation: asks for or offers sexual content, services, nude photos or meetups. minors: sexualizes someone under 18. The highest label
pii contact: phone numbers, email addresses and messaging or social handles, including disguised ones. address: a home or street address. financial: card and bank details. government_id: passport and ID numbers. The highest label

Recovery stories, worry about a friend, news and figures of speech such as "this exam is killing me" score low for self_harm. Flirting, romance and sex education score low for sexual.

{
  "text": "Text me at jane.doe@example.com or +359 88 123 4567",
  "checks": ["spam", "pii"]
}
{
  "object": "check",
  "spam": {
    "score": 0.04,
    "action": "allow",
    "category": "none",
    "reasons": []
  },
  "pii": {
    "score": 0.97,
    "labels": {
      "contact": 0.97,
      "address": 0.02,
      "financial": 0.01,
      "government_id": 0.01
    },
    "matches": [
      { "type": "email", "text": "jane.doe@example.com" },
      { "type": "phone", "text": "+359 88 123 4567" }
    ]
  }
}

Exact personal details

pii.matches lists the exact values found by fixed patterns, in reading order, so you can hide them by replacing each text in the message:

  • email: email addresses.
  • phone: phone numbers with + or 00 in front, with a leading 0 as in most of Europe, or in the North American format, such as (415) 555-2671.
  • payment_card: 13 to 19 digits that pass the card checksum (Luhn).
  • iban: IBANs with the right length for their country and a valid checksum.
  • ip_address: IPv4 addresses.

The labels come from the AI model and also catch details that patterns can't, such as "zero eight eight" written out in words or "name at gmail dot com". Matches are copies of your message, so we don't store them: history shows them only while it keeps the text, webhooks never include them, and MCP returns only their type.

Handling self-harm and content involving minors

  • A high self_harm.labels.intent means a person may be at risk. Don't just delete the message. Show support resources, such as a local crisis line, and let a trained person follow up. Treat encouragement like other harmful content.
  • Treat sexual.labels.minors at 0.5 or above as serious. Remove the content, and follow the reporting rules that apply to your service, such as reporting to NCMEC in the US. We test this label for false alarms on everyday mentions of children. We don't create test content that sexualizes minors, so we don't publish an accuracy figure for it.

Actions and thresholds

The action follows your thresholds: block at or above the block threshold (0.8 by default), review at or above the review threshold (0.5 by default), and allow below. You can set different thresholds per content type. Change them with PATCH /v1/settings.

Community description

Describe your community in up to 500 characters, for example "A community app for university clubs and sports teams". It is part of every check, so talk that is normal for your community, like club fees in a sports app, isn't flagged. Set it with PATCH /v1/settings and community_description.

Rules

Allow and block lists for domains, phrases and author IDs apply before any AI check, so a match costs no model call. The block list wins over the allow list.

  • GET /v1/rules, POST /v1/rules with list (allow or block), kind (domain, phrase or author) and value, and DELETE /v1/rules/{id}.
  • A domain rule matches that domain and its subdomains. A phrase rule ignores case and extra spaces.

Batches

POST /v1/checks/batch takes { "items": [...] } with up to 100 check requests and returns a result for each, in order. A bad item returns an error object in its own slot and doesn't stop the others. Each successful item counts as one check.

History and feedback

  • GET /v1/checks lists checks, newest first, with action, category, source, test, api_key_id, created_after and created_before filters and cursor pagination. GET /v1/checks/{id} returns one check.
  • Message text is kept for your plan's history period, or the retention you set with text_retention_days (0 keeps none). After that, text is null.
  • POST /v1/checks/{id}/feedback with verdict (spam or not_spam), an optional note, and an optional rule to add to your lists.

Deleting checks

  • DELETE /v1/checks/{id} deletes one check and its feedback at once.
  • POST /v1/checks/delete with author_id deletes every check whose context.author.id is that ID, for an end user who asks to be forgotten. The response says how many were deleted.

Caching

An identical message with the same context and the same checks from the same team reuses the verdict for 24 hours. Changing your rules, thresholds or community description means a fresh verdict next time.

Test mode

Test keys (sg_test_) never call the AI model and are never counted:

Text contains Result
spamgone_test_block block, score 0.99
spamgone_test_review review, score 0.65
spamgone_test_toxic High toxicity scores, when requested
spamgone_test_self_harm High self-harm scores, when requested
spamgone_test_sexual High sexual-content scores, when requested
spamgone_test_pii High personal-details scores, when requested
anything else allow, score 0.01

Personal-detail matches are found in test mode too, since they don't need the AI model.

Perspective API compatibility

POST /v1alpha1/comments:analyze accepts Perspective's request body (comment.text, requestedAttributes, languages, doNotStore, clientToken, spanAnnotations) with the key as ?key= or a bearer token, and answers in Perspective's response shape. Supported attributes: TOXICITY, SEVERE_TOXICITY, IDENTITY_ATTACK, INSULT, PROFANITY, THREAT, SEXUALLY_EXPLICIT and SPAM. Others fail with Perspective's 400 INVALID_ARGUMENT. doNotStore: true means the text is never stored. POST /v1alpha1/comments:suggestscore records your suggested scores as feedback.

Errors

name Status Meaning
validation_error 422 A field is missing or invalid. The message names it.
text_too_long 422 text is longer than 10,000 characters.
model_unavailable 503 Checks are briefly unavailable. Wait for retry-after.