PHP SDK

Official PHP client for the KireiFilter spam detection API.

Quick start

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

Generate an API token in Settings.

Install the SDK and call check().

Install packagist.org/packages/ramlev/kireifilter

$ composer require ramlev/kireifilter

Setup + first check

use Ramlev\Kireifilter\KireifilterClient;

$client = new KireifilterClient('kf_live_your_token');

$result = $client->check(
    type:    'comment',
    content: 'Buy cheap meds now!!!',
);

if ($result->isSpam) {
    // block or queue for review
}

Authentication

Pass your API token as the only constructor argument. The SDK attaches it as a Bearer token on every request automatically.

Authorization: Bearer <your-api-token>

Generate tokens in Settings → API token. Tokens can be revoked at any time. A 401 response throws AuthException.

check()

Submit a single item for spam classification.

Example

$result = $client->check(
    type:     'comment',
    content:  'Win a free iPhone — click here now!!!',
    metadata: [
        'ip'     => '203.0.113.42',
        'author' => 'john',
    ],
);

if ($result->isSpam) {
    // $result->score     → float, e.g. 0.92
    // $result->reasons   → ['Spam keywords detected', ...]
    // $result->id        → int, server-side record ID
    // $result->checkedAt → DateTimeImmutable
}

Throws

AuthException	Invalid or missing API token (HTTP 401)
QuotaExceedException	Monthly quota exhausted (HTTP 429, body has `resetsAt`)
KireifilterException	Validation errors (422), burst rate limit (429), and any other API or network error

checkBatch()

Submit up to 25 items in a single request. Returns an array of SpamCheckResult in the same order as the input. More than 25 items throws \InvalidArgumentException before any HTTP call.

Example

$results = $client->checkBatch([
    ['type' => 'comment', 'content' => 'First post!'],
    ['type' => 'comment', 'content' => 'Buy followers cheap!'],
    ['type' => 'email',   'content' => $emailBody, 'metadata' => ['from' => 'a@b.com']],
]);

foreach ($results as $i => $result) {
    // $result->isSpam, $result->score, $result->reasons
}

quota()

Fetch current quota usage without consuming a check. Returns the decoded JSON response as an associative array.

Example

$quota = $client->quota();

$quota['plan'];       // "free" | "starter" | "pro" | "max"
$quota['billing'];    // "monthly" | "yearly"
$quota['limit'];      // int — total checks this period
$quota['used'];       // int — checks consumed so far
$quota['remaining'];  // int — checks still available
$quota['resetsAt'];   // ISO-8601 string — next reset

Request fields

Both type and content are required. Pass extra context in metadata to enable additional detection layers.

Field	Type	Required	Values / notes
type	string	required	`comment` · `email` · `email_address`
content	string	required	The text to classify
metadata	array	optional	See table below

Metadata keys

Key	Relevant for	Notes
ip	comment · email	IPv4 or IPv6 of the submitter. Enables RBL and IP reputation checks.
author	comment	Display name or username of the commenter.
url	comment	URL of the page or post where the comment was submitted.
from	email	The `From:` header value.
subject	email	The email subject line.
envelope_from	email	SMTP MAIL FROM address. Required for SPF checks.
dkim_signature	email	Full `DKIM-Signature:` header. Required for DKIM verification.

Response

check() returns a SpamCheckResult. All values are exposed as public readonly properties — access them directly, no getters.

Property	Type	Description
$result->isSpam	bool	`true` when score ≥ 0.5
$result->score	float	Spam probability — `0.0` (clean) to `1.0` (definite spam)
$result->reasons	string[]	Detection signals that fired, e.g. `"Spam keywords detected"`
$result->id	int	Server-side record ID for this check
$result->checkedAt	DateTimeImmutable	When the check was performed

To inspect remaining quota, call $client->quota() — it does not consume a check.

Exceptions

All SDK exceptions extend Ramlev\Kireifilter\Exception\KireifilterException, which itself extends \RuntimeException. Catch the base class to handle any SDK error.

Exception	When	Extras
AuthException	HTTP 401 — token missing or invalid	—
QuotaExceedException	HTTP 429 — monthly quota exhausted	`$e->resetsAt` → `?DateTimeImmutable`
KireifilterException	Validation (422), burst rate limit (429 without body), other HTTP / network errors	`$e->getCode()` · `$e->getMessage()`

Exception handling

use Ramlev\Kireifilter\Exception\AuthException;
use Ramlev\Kireifilter\Exception\KireifilterException;
use Ramlev\Kireifilter\Exception\QuotaExceedException;

try {
    $result = $client->check(type: 'comment', content: $text);

} catch (AuthException $e) {
    // invalid or missing API token

} catch (QuotaExceedException $e) {
    // $e->resetsAt — when the quota refills

} catch (KireifilterException $e) {
    // validation, burst rate limit, network, or any other API error
    // $e->getCode() holds the HTTP status
}

Interactive API explorer

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

Open API docs