Reference — ShildMatrix Docs

GET /status/

Simple health check. Confirms the API is reachable and your API key is valid.

Auth: X-API-Key header (API key only — JWT is not accepted).

GET

/status/

Health check for your API key.

Example request

curl --request GET \
  --url 'http://localhost:8000/api/v1/status/' \
  --header 'accept: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'

Example response

{
  "success": true,
  "status": "ok",
  "datasets": {
    "disposable_domains": {
      "count": 167611,
      "version": "2026-09-03"
    },
    "free_providers": {
      "version": "2026-07-01"
    },
    "role_prefixes": {
      "version": "2026-07-01"
    }
  }
}

Status response

Always returns this exact shape:

{
  "success": true,
  "status": "ok",
  "datasets": {
    "disposable_domains": { "count": 167611, "version": "2026-09-03" },
    "free_providers": { "version": "2026-07-01" },
    "role_prefixes": { "version": "2026-07-01" }
  }
}

Field	Type	Description
`success`	boolean	Always `true` on success
`status`	string	Always `"ok"` when the API is healthy
`datasets`	object	Loaded list datasets: entry counts and file versions

POST /check/

Validate an email address and optionally an IP address in real time.

Auth: X-API-Key, or JWT Bearer with api_key_id in the body (dashboard playground).

Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email address to validate
`ip`	string	No	Client IP address — stored and echoed with the result; IP intelligence is coming soon
`api_key_id`	string	No*	Required when authenticating with JWT (dashboard playground). Must match the `X-API-Key` when both are sent.

POST

/check/

Real-time email and IP validation with risk scoring.

Example request

curl --request POST \
  --url 'http://localhost:8000/api/v1/check/' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{"email":"[email protected]","ip":"203.0.113.42"}'

Example response

{
  "success": true,
  "id": "log_01hxyzexample000000000000",
  "email": "[email protected]",
  "ip": "203.0.113.42",
  "decision": "block",
  "risk_score": 85,
  "signals": {
    "disposable_email": true,
    "mx_valid": true,
    "free_provider": false
  },
  "reasons": ["Disposable email domain detected"],
  "created_at": "2026-07-07T12:00:00.000000+00:00"
}

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success
`id`	string	Prefixed log id (e.g. `log_…`)
`email`	string	Email that was checked
`ip`	string \| null	IP that was checked
`decision`	string	Risk decision (see below)
`risk_score`	number	Risk score from 0–100
`signals`	object	Boolean flags for detected risk signals
`reasons`	string	Human-readable explanations
`created_at`	string	ISO 8601 timestamp

Decision values

The decision field can contain the following values:

"allow" — Low risk (score under 30), safe to proceed
"challenge" — Elevated risk (score 30–54), consider extra verification (CAPTCHA, OTP)
"review" — Medium risk (score 55–79), manual review recommended
"block" — High risk (score 80+), should be rejected

Signals

The signals object reports detected risk factors:

Signal	Description
`disposable_email`	Email uses a known disposable domain
`mx_valid`	Domain has MX records (`false` if none found)
`free_provider`	Email uses a free consumer provider

Signups with decision: "block" should be rejected. Consider challenging "challenge" and reviewing "review" for enhanced security.

Error codes

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid API key / JWT
`403`	API key does not have permission (inactive or not owned)
`429`	Monthly usage limit exceeded

429 response body

{
  "error": "Monthly usage limit exceeded",
  "checks_used": 5000,
  "checks_limit": 5000,
  "upgrade_url": "/api/v1/billing/subscription/"
}