List Threat Detection Results

Quick Start

Authentication

Include your API key in the X-API-KEY header:

X-API-KEY: <api-key>

Example Request

curl --request POST \
  --url https://api.chainpatrol.io/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "slug": "your-org",
    "limit": 50,
    "query": "phishing",
    "filters": [
      {
        "property": "source",
        "operator": "in",
        "value": ["EXTERNAL", "GOOGLE_SEARCH"]
      },
      {
        "property": "assetStatus",
        "operator": "in",
        "value": ["BLOCKED"]
      },
      {
        "property": "confidence",
        "operator": "in",
        "value": ["high", "medium"]
      }
    ]
  }'

Request Schema

Request Body

Field	Type	Required	Default	Constraints	Description
`slug`	`string`	✅ Yes	-	-	Organization slug identifier
`cursor`	`number`	❌ No	-	-	Pagination cursor from previous response
`limit`	`number`	❌ No	`50`	Min: 1, Max: 100	Number of results to return
`filters`	`Filter[]`	❌ No	`[]`	-	Array of filter objects
`query`	`string`	❌ No	`""`	-	Search query for threat content (case-insensitive)
`startDate`	`string`	❌ No	-	ISO 8601 format	Start date for filtering results
`endDate`	`string`	❌ No	-	ISO 8601 format	End date for filtering results

Filter Schema

Each filter object must have the following structure:

Field	Type	Required	Description
`property`	`string`	✅ Yes	Filter property (see options below)
`operator`	`string`	✅ Yes	`"in"` or `"notIn"`
`value`	`string[]`	✅ Yes	Array of values to filter by

Filter Properties

1. Source Filter ("source")

{
  "property": "source",
  "operator": "in" | "notIn",
  "value": ThreatDetectionSourceKey[]
}

Available Source Values

"ASSET_CHECK" - Asset verification checks
"BING_SEARCH" - Bing search results
"CERTSTREAM" - Certificate transparency logs
"DNS_TWIST" - DNS twist detection
"DUCK_DUCK_GO_SEARCH" - DuckDuckGo search results
"EXTERNAL" - External threat submissions
"GOOGLE_SEARCH" - Google search results
"GUESTBOOK" - Guestbook submissions
"MEDIUM_TAG_RSS" - Medium RSS feeds
"MOZILLA_ADDON_SEARCH" - Mozilla addon searches
"REDDIT_SUBREDDIT_SEARCH" - Reddit subreddit searches
"TWITTER" - Twitter monitoring
"TWITTER_POST_SEARCH" - Twitter post searches
"TWITTER_SEARCH" - Twitter search results
"URLSCAN" - URLScan.io results
"YAHOO_SEARCH" - Yahoo search results
"YOUTUBE_SEARCH" - YouTube search results

2. Asset Status Filter ("assetStatus")

{
  "property": "assetStatus",
  "operator": "in" | "notIn",
  "value": AssetStatus[]
}

Available Asset Status Values:

"UNKNOWN" - Status not yet determined
"ALLOWED" - Asset is legitimate/allowed
"BLOCKED" - Asset is blocked/malicious

3. Confidence Filter ("confidence")

{
  "property": "confidence",
  "operator": "in" | "notIn",
  "value": ConfidenceLevel[]
}

Available Confidence Level Values:

"none" - No confidence threshold met
"low" - Low confidence threat detection
"medium" - Medium confidence threat detection
"high" - High confidence threat detection

4. Asset Type Filter ("assetType")

{
  "property": "assetType",
  "operator": "in" | "notIn",
  "value": AssetType[]
}

Available Asset Type Values

"URL" - Website URLs
"PAGE" - Web pages
"ADDRESS" - Blockchain addresses
"TWITTER" - Twitter profiles/posts
"FACEBOOK" - Facebook profiles/pages
"YOUTUBE" - YouTube channels/videos
"REDDIT" - Reddit posts/subreddits
"TELEGRAM" - Telegram channels/groups
"DISCORD" - Discord servers (deprecated)
"DISCORD_USER" - Discord users
"LINKEDIN" - LinkedIn profiles
"INSTAGRAM" - Instagram profiles
"THREADS" - Threads profiles
"TIKTOK" - TikTok profiles
"MEDIUM" - Medium articles/profiles
"EMAIL" - Email addresses
"WHATSAPP" - WhatsApp contacts
"GOOGLE_APP_STORE" - Google Play Store apps
"APPLE_APP_STORE" - Apple App Store apps
"AMAZON_APP_STORE" - Amazon App Store apps
"MICROSOFT_APP_STORE" - Microsoft Store apps
"CHROME_WEB_STORE" - Chrome extensions
"MOZILLA_ADDONS" - Firefox addons
"OPERA_ADDONS" - Opera addons
"PATREON" - Patreon profiles
"OPENSEA" - OpenSea collections/profiles
"FARCASTER" - Farcaster profiles
"IPFS" - IPFS hashes
"GOOGLE_FORM" - Google Forms
"QUORA" - Quora profiles/posts
"GITHUB" - GitHub repositories/profiles
"TEACHABLE" - Teachable courses
"SUBSTACK" - Substack publications
"DEBANK" - DeBank profiles
"TAWK_TO" - Tawk.to chat widgets
"JOTFORM" - JotForm forms
"PRIMAL" - Primal profiles
"BLUESKY" - Bluesky profiles
"SNAPCHAT" - Snapchat profiles
"DESO" - DeSo profiles

Response Schema

Response Body

{
  detections: DetectionResult[];
  nextCursor: number | null;
}

Detection Result Object

Each item in the detections array has the following structure:

Field	Type	Description
`id`	`number`	Unique threat detection result identifier
`threatContent`	`string`	Content that was detected as threatening
`source`	`string`	Source of the threat detection (ThreatDetectionSourceKey)
`createdAt`	`string`	ISO 8601 timestamp of when threat was detected
`confidence`	`string`	Confidence level: “none”, “low”, “medium”, or “high”
`reportStatus`	`string`	Report status: “REPORTED” or “NOT_REPORTED”
`asset`	`AssetObject`	Associated asset information

Asset Object

Field	Type	Description
`id`	`number`	Unique asset identifier
`content`	`string`	Asset content (URL, address, username, etc.)
`type`	`string`	Asset type (AssetType enum value)
`status`	`string`	Current asset status (AssetStatus enum value)

Complete Response Example

{
  "detections": [
    {
      "id": 12345,
      "threatContent": "Phishing site detected mimicking legitimate service",
      "source": "GOOGLE_SEARCH",
      "createdAt": "2024-01-15T10:30:00Z",
      "confidence": "high",
      "reportStatus": "REPORTED",
      "asset": {
        "id": 67890,
        "content": "https://fake-site.com",
        "type": "URL",
        "status": "BLOCKED"
      }
    },
    {
      "id": 12346,
      "threatContent": "Suspicious crypto address found in scam report",
      "source": "EXTERNAL",
      "createdAt": "2024-01-15T09:15:00Z",
      "confidence": "medium",
      "reportStatus": "NOT_REPORTED",
      "asset": {
        "id": 67891,
        "content": "0x1234567890123456789012345678901234567890",
        "type": "ADDRESS",
        "status": "BLOCKED"
      }
    }
  ],
  "nextCursor": 12347
}

Access Control

The API enforces strict access control based on your API key:

Organization API Keys:
- Can only access detection results for their associated organization
- Must match the slug parameter exactly
- Example: An API key for “acme-org” can only query results for “acme-org”
User API Keys:
- Can access detection results for any organization where the user is a member
- Requires the user to be an active member of the queried organization

If you attempt to query an organization without proper permissions, you will receive a 403 Forbidden error with the message: “API key does not have access to this organization”

Example Implementation

async function fetchDetectionResults(params) {
  const response = await fetch("https://api.chainpatrol.io/detection/list", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "<api-key>",
    },
    body: JSON.stringify(params),
  });
  return response.json();
}

// Example usage
fetchDetectionResults({
  slug: "your-org",
  limit: 50,
  query: "phishing",
  filters: [
    {
      property: "assetStatus",
      operator: "in",
      value: ["BLOCKED"],
    },
    {
      property: "assetType",
      operator: "in",
      value: ["URL", "ADDRESS"],
    },
  ],
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-03-01T00:00:00Z",
})
  .then((data) => {
    console.log("Detection results:", data.detections);
    console.log("Next cursor:", data.nextCursor);
  })
  .catch((error) => console.error("Error fetching results:", error));

Authorizations

X-API-KEY

string

header

required

Your API key. This is required by most endpoints to access our API programatically. Reach out to us at [email protected] to get an API key for your use.

Body

application/json

slug

string

required

cursor

number

limit

number

default:50

Required range: 1 <= x <= 100

filters

object[]

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

filters.property

enum<string>

required

Available options:

source

filters.operator

enum<string>

required

Available options:

in,

notIn

filters.value

enum<string>[]

required

Available options:

telegram_channels_search,

telegram_user_search,

tik_tok_video_search,

tik_tok_user_search,

blocklist,

apple_app_store,

google_ads_search,

mozilla_addon_search,

reddit_subreddit_search,

asset_check,

twitter_post_search,

medium_tag_rss,

twitter_search,

yahoo_search,

duck_duck_go_search,

bing_search,

guestbook,

certstream,

external,

google_search,

dns_twist,

twitter,

urlscan,

youtube_search,

google_play_search,

dexscreener_search,

blocked_ip_scan

query

string

default:""

startDate

string

endDate

string

Response

Successful response

detections

object[]

required

Show child attributes

detections.id

number

required

detections.threatContent

string

required

detections.source

enum<string>

required

Available options:

telegram_channels_search,

telegram_user_search,

tik_tok_video_search,

tik_tok_user_search,

blocklist,

apple_app_store,

google_ads_search,

mozilla_addon_search,

reddit_subreddit_search,

asset_check,

twitter_post_search,

medium_tag_rss,

twitter_search,

yahoo_search,

duck_duck_go_search,

bing_search,

guestbook,

certstream,

external,

google_search,

dns_twist,

twitter,

urlscan,

youtube_search,

google_play_search,

dexscreener_search,

blocked_ip_scan

detections.createdAt

string

required

detections.confidence

enum<string>

required

Available options:

none,

low,

medium,

high

detections.reportStatus

enum<string>

required

Available options:

REPORTED,

NOT_REPORTED

detections.asset

object

required

Show child attributes

detections.asset.id

number

required

detections.asset.content

string

required

detections.asset.type

enum<string>

required

Available options:

URL,

PAGE,

ADDRESS,

DISCORD,

LINKEDIN,

TWITTER,

FACEBOOK,

YOUTUBE,

REDDIT,

TELEGRAM,

GOOGLE_APP_STORE,

APPLE_APP_STORE,

AMAZON_APP_STORE,

MICROSOFT_APP_STORE,

TIKTOK,

INSTAGRAM,

THREADS,

MEDIUM,

CHROME_WEB_STORE,

MOZILLA_ADDONS,

OPERA_ADDONS,

EMAIL,

PATREON,

OPENSEA,

FARCASTER,

IPFS,

GOOGLE_FORM,

WHATSAPP,

DISCORD_USER,

QUORA,

GITHUB,

TEACHABLE,

SUBSTACK,

DEBANK,

TAWK_TO,

JOTFORM,

PRIMAL,

BLUESKY,

SNAPCHAT,

DESO,

PINTEREST,

FLICKR,

GALXE,

VELOG,

NPM,

PYPI,

HEX,

DOCKER_HUB,

VOCAL_MEDIA,

TECKFINE,

TENDERLY,

HACKMD,

ETSY,

ZAZZLE

detections.asset.status

enum<string>

required

Available options:

UNKNOWN,

ALLOWED,

BLOCKED

nextCursor

number

External API

Assets

Reports

Threats

Disputes

Metrics

List Threat Detection Results

Quick Start

Authentication

Example Request

Request Schema

Request Body

Filter Schema

Filter Properties

Response Schema

Response Body

Detection Result Object

Asset Object

Complete Response Example

Access Control

Example Implementation

Authorizations

Body

Response

External API

Assets

Reports

Threats

Disputes

Metrics

​Quick Start

​Authentication

​Example Request

​Request Schema

​Request Body

​Filter Schema

​Filter Properties

​Response Schema

​Response Body

​Detection Result Object

​Asset Object

​Complete Response Example

​Access Control

​Example Implementation

Authorizations

Body

Response

Quick Start

Authentication

Example Request

Request Schema

Request Body

Filter Schema

Filter Properties

Response Schema

Response Body

Detection Result Object

Asset Object

Complete Response Example

Access Control

Example Implementation