Introduction — ShildMatrix Docs

API endpoint

The API is available at the following base endpoint:

http://localhost:8000/api/v1/

API key

All validation endpoints require a valid API key in the X-API-Key header. See the authentication guide for details on obtaining and using your 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"
    }
  }
}

Response format

All successful responses include a success field set to true along with endpoint-specific data.

If the request fails, the response includes an error field with a human-readable message and an appropriate HTTP status code.

Validation response fields

Field	Type	Description
`decision`	string	`allow`, `challenge`, `review`, or `block`
`risk_score`	number	Risk score from 0–100
`signals`	object	Boolean flags for detected risk signals
`reasons`	array	Human-readable explanations (e.g. `"Disposable email domain detected"`)

Rate limits

API requests are rate-limited based on your subscription tier. When you exceed your monthly quota, the API returns 429 Too Many Requests.