# 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_...
```

```json
{
  "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

```json
{
  "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](#other-checks).                                                                                                   |
| `sexual`        | Only when you asked for it. See [Other checks](#other-checks).                                                                                                   |
| `pii`           | Only when you asked for it, with exact `matches`. See [Other checks](#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`.

```json
{
  "text": "Text me at jane.doe@example.com or +359 88 123 4567",
  "checks": ["spam", "pii"]
}
```

```json
{
  "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`. |
