Get Started

Create an API key

Sign in to your ShildMatrix dashboard and navigate to Settings → API Keys.

Click Generate API Key and give it a descriptive name (e.g. "Production" or "Staging").

Copy your key

Copy the generated key immediately — it is only shown once. You can revoke and recreate keys at any time from the dashboard.

Make a test request

Use your new key to verify the API is working:

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

{
  "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"
    }
  }
}

If everything is set up correctly, you should receive a response with "status": "ok".

Validate an email

Once your key works, try a validation check:

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"}'

{
  "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"
}

Next steps

• Read the full API Reference for all endpoints
• Try requests interactively in the API Playground
• Review authentication for security best practices