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+or00in front, with a leading0as 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.intentmeans 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. Treatencouragementlike other harmful content. - Treat
sexual.labels.minorsat 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/ruleswithlist(alloworblock),kind(domain,phraseorauthor) andvalue, andDELETE /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/checkslists checks, newest first, withaction,category,source,test,api_key_id,created_afterandcreated_beforefilters 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,textisnull. POST /v1/checks/{id}/feedbackwithverdict(spamornot_spam), an optionalnote, and an optionalruleto add to your lists.
Deleting checks
DELETE /v1/checks/{id}deletes one check and its feedback at once.POST /v1/checks/deletewithauthor_iddeletes every check whosecontext.author.idis 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. |