KireiFilter
Sign in Create account

Documentation

Everything you need to integrate KireiFilter into your stack.

Quick start

1

Create an account — free plan included, no card required.

2

Generate an API token in Settings.

3

Send a POST request — get a spam score back in milliseconds.

quickstart.sh 
curl -X POST \
  https://kireifilter.net/api/v1/spam-check \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "comment", "content": "Buy cheap meds now!!! Click here"}'

Authentication

All requests must include a Bearer token in the Authorization header.

Authorization: Bearer <your-api-token>

Generate tokens in Settings → API token. Tokens can be revoked at any time.

Endpoint

Method URL Description
POST /api/v1/spam-check Submit content for spam classification
POST /api/v1/spam-check/batch Submit up to 25 items in a single request
GET /api/v1/quota Check remaining request quota for current period

Batch

Submit up to 25 items in one request. All items are validated before any check runs; quota is only consumed when the full batch succeeds.

Request

POST /api/v1/spam-check/batch
{
  "items": [
    { "type": "comment", "content": "Buy cheap meds now!", "metadata": { "ip": "203.0.113.1" } },
    { "type": "email",   "content": "Hello, just checking in." }
  ]
}

Response

200 OK
{
  "results": [
    { "index": 0, "id": 101, "isSpam": true,  "score": 0.92, "reasons": ["Spam keywords detected"], "checkedAt": "2026-03-14T10:00:00+00:00" },
    { "index": 1, "id": 102, "isSpam": false, "score": 0.02, "reasons": [],                               "checkedAt": "2026-03-14T10:00:00+00:00" }
  ]
}

Sending more than 25 items returns 400 Bad Request.

Request fields

Send JSON. Both type and content are required. Pass extra context in metadata to improve accuracy.

Field Type Required Description
type string required Content type — comment or email
content string required The text to classify (comment body, email body, etc.)
metadata object optional Extra context. For comments: ip, author, url. For emails: from, subject, ip, envelope_from, dkim_signature — passing the last two enables SPF/DKIM detection.

Response fields

Field Type Description
id integer Unique identifier for this check
isSpam boolean true if score ≥ 0.5
score float Spam probability from 0.0 (clean) to 1.0 (definite spam)
reasons string[] Detection signals that contributed to the score
checkedAt string ISO 8601 timestamp of when the check was run
200 OK
{
  "id": 42,
  "isSpam": true,
  "score": 0.85,
  "reasons": ["Spam keywords detected"],
  "checkedAt": "2026-03-03T12:00:00+00:00"
}

Errors

Status Meaning
400 Malformed request body, empty items array, or batch exceeds 25 items
401 Missing or invalid API token
422 Validation failed — content is missing or empty
429 Two distinct causes:
  • Quota exhausted — body contains resetsAt; no Retry-After header. Upgrade your plan or wait for the next billing period.
  • Burst rate limit — body contains "Too many requests"; Retry-After header is present. Slow down and retry after the indicated delay.
500 Internal server error

Examples

curl -X POST \
  https://kireifilter.net/api/v1/spam-check \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "comment",
    "content": "Win a free iPhone — click here now!!!",
    "metadata": { "ip": "203.0.113.42", "author": "john" }
  }'
$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://kireifilter.net/api/v1/spam-check', [
        'type'     => 'comment',
        'content'  => 'Win a free iPhone — click here now!!!',
        'metadata' => ['ip' => '203.0.113.42', 'author' => 'john'],
    ]);

$isSpam = $response->json('isSpam'); // true
$score  = $response->json('score');  // 0.85
import requests

resp = requests.post(
    "https://kireifilter.net/api/v1/spam-check",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "type": "comment",
        "content": "Win a free iPhone — click here now!!!",
        "metadata": {"ip": "203.0.113.42", "author": "john"},
    },
)

data = resp.json()
print(data["isSpam"], data["score"])  # True 0.85
const res = await fetch('https://kireifilter.net/api/v1/spam-check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'comment',
    content: 'Win a free iPhone — click here now!!!',
    metadata: { ip: '203.0.113.42', author: 'john' },
  }),
});

const { isSpam, score } = await res.json();
console.log(isSpam, score); // true 0.85
# Request
curl -X POST \
  https://kireifilter.net/api/v1/spam-check/batch \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "comment", "content": "Buy cheap meds now!", "metadata": { "ip": "203.0.113.1" } },
      { "type": "email",   "content": "Hello, just checking in." }
    ]
  }'

# Response
{
  "results": [
    { "index": 0, "id": 101, "isSpam": true,  "score": 0.92, "reasons": ["Spam keywords detected"], "checkedAt": "2026-03-14T10:00:00+00:00" },
    { "index": 1, "id": 102, "isSpam": false, "score": 0.02, "reasons": [],                               "checkedAt": "2026-03-14T10:00:00+00:00" }
  ]
}

Interactive API explorer

Try requests directly in the browser with the full OpenAPI reference.

Open API docs