Reference

GET/status

Get the status of your API key and subscription.

Example request

curl --request GET \
  --url https://www.chat-flow.app/api/sentinel/v1/status \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

Response

{
  "status": "active",
  "api_key": {
    "name": "Production Key"
  },
  "subscription": {
    "plan": "shield",
    "status": "active"
  }
}

GET/check

Check the risk level of an email address, domain, or IP address.

Query parameters

Parameter	Type	Description
`email`	string	Email address to check
`domain`	string	Domain to check
`ip`	string	IP address to check

At least one of email, domain, or ip must be provided.

Example request

curl --request GET \
  --url 'https://www.chat-flow.app/api/sentinel/v1/[email protected]' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

Response

{
  "risk_level": "high",
  "risk_score": 85,
  "recommendation": "block",
  "matched_categories": ["disposable_email", "spam_domain"],
  "details": {
    "is_disposable": true,
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": false,
    "is_whitelisted": false,
    "is_blacklisted": false
  }
}

Risk Levels

The risk_level field can contain the following values:

high - High risk, should be blocked
medium - Medium risk, recommended to challenge or review
low - Low risk, allow with caution
none - No risk detected

Recommendations

The recommendation field provides suggested actions:

allow - Safe to allow
allow_with_caution - Allow but monitor
challenge - Require additional verification
block - Block the request

Users with "high" risk level should be blocked. We recommend requiring additional verification for users with "medium" risk level.

POST/submit

Submit a threat report to the community database for review.

Body parameters

Parameter	Type	Description
`value`*	string	The email, domain, or IP to report
`entry_type`*	string	One of: "email", "domain", "ip"
`reason`*	string	Description of why this is a threat (min 10 characters)

Example request

curl --request POST \
  --url https://www.chat-flow.app/api/sentinel/v1/submit \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '{
    "value": "[email protected]",
    "entry_type": "email",
    "reason": "Spam account used for fraudulent signups"
  }'

Example response

Response

{
  "success": true,
  "submission": {
    "id": 12345,
    "value": "[email protected]",
    "entry_type": "email",
    "status": "pending",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

GET/lists

Retrieve your custom whitelist and blacklist entries.

Query parameters

Parameter	Type	Description	Default
`type`	string	Filter by list type: "whitelist" or "blacklist"	all

Example response

Response

{
  "whitelist": [
    {
      "id": 1,
      "value": "[email protected]",
      "entry_type": "email",
      "reason": "Verified partner account",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "blacklist": [
    {
      "id": 2,
      "value": "spam-domain.xyz",
      "entry_type": "domain",
      "reason": "Known spam domain",
      "created_at": "2026-01-14T08:00:00Z"
    }
  ]
}

POST/lists

Add a new entry to your whitelist or blacklist.

Body parameters

Parameter	Type	Description
`value`*	string	The email, domain, or IP to add
`entry_type`*	string	One of: "email", "domain", "ip"
`list_type`*	string	One of: "whitelist", "blacklist"
`reason`	string	Optional reason for adding this entry

Example response

Response

{
  "success": true,
  "entry": {
    "id": 3,
    "value": "[email protected]",
    "entry_type": "email",
    "list_type": "whitelist",
    "reason": "Verified partner",
    "created_at": "2026-01-16T09:00:00Z"
  }
}

DELETE/lists

Remove an entry from your whitelist or blacklist.

Query parameters

Parameter	Type	Description
`id`*	number	The ID of the entry to remove

Example response

Response

{
  "success": true,
  "message": "Entry removed successfully"
}

Auth Providers