> ## Documentation Index > Fetch the complete documentation index at: https://chainpatrol.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Suspected Threats > List suspected threats for an organization using API key authentication, newest first. A suspected threat is an unconfirmed result of automated threat detection; use the `blockStatus` filter to find the ones confirmed as threats. Returns human-readable confidence levels (none, low, medium, high) and report status. Supports filtering by source, confidence level, raw score range, asset status, asset type and creation time, plus search. Pages hold up to 1000 results: pass `nextCursor` back as `cursor` until it is absent, set `includeTotal` to get the number of matching suspected threats without paging, and use `startDate` to fetch only suspected threats created since your last sync. ## Overview Lists your organization's **suspected threats**: assets that ChainPatrol's automated detection flagged. A suspected threat is not confirmed until it is reviewed and blocked. Use the `blockStatus` filter below to select the ones that have since been confirmed. The API keeps the detection name: the endpoint is `/detection/list`, results come back in the `detections` array, and each item is a detection result. ## Quick Start ### Authentication Include your API key in the `X-API-KEY` header: ```bash theme={null} X-API-KEY: ``` ### Example Request ```bash theme={null} curl --request POST \ --url https://app.chainpatrol.io/api/v2/detection/list \ --header 'Content-Type: application/json' \ --header 'X-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 | - | - | `nextCursor` from the previous response | | `limit` | `number` | ❌ No | `50` | Min: 1, Max: 1000 | Number of results per page | | `filters` | `Filter[]` | ❌ No | `[]` | - | Array of filter objects | | `query` | `string` | ❌ No | `""` | - | Search query for threat content (case-insensitive) | | `startDate` | `string` | ❌ No | - | ISO 8601 format | Only suspected threats created at or after this time | | `endDate` | `string` | ❌ No | - | ISO 8601 format | Only suspected threats created at or before this time | | `minScore` | `number` | ❌ No | - | 0–1, inclusive | Only suspected threats whose raw `score` is at least this | | `maxScore` | `number` | ❌ No | - | 0–1, inclusive | Only suspected threats whose raw `score` is at most this | | `includeTotal` | `boolean` | ❌ No | `false` | - | Also return `total`, the match count across pages | > [!WARNING] > > `startDate` and `endDate` filter on when the **suspected threat** was created, not > on when the asset was first seen, reported or blocked. Leave both out when you want > every suspected threat: a date window silently drops older history, which reads as > missing results rather than as a filter. ### 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"`)** ```typescript theme={null} { "property": "source", "operator": "in" | "notIn", "value": ThreatDetectionSourceKey[] } ``` > [accordion] 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 > * `"YANDEX_IMAGE_SEARCH"` - Yandex reverse image search results for your brand imagery > * `"YOUTUBE_SEARCH"` - YouTube search results **2. Asset Status Filter (`"assetStatus"`)** ```typescript theme={null} { "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"`)** ```typescript theme={null} { "property": "confidence", "operator": "in" | "notIn", "value": ConfidenceLevel[] } ``` **Available Confidence Level Values:** * `"none"` - No confidence threshold met * `"low"` - Low-confidence suspected threat * `"medium"` - Medium-confidence suspected threat * `"high"` - High-confidence suspected threat **4. Block Status Filter (`"blockStatus"`)** ```typescript theme={null} { "property": "blockStatus", "operator": "in" | "notIn", "value": ("blocked" | "pending")[] } ``` Selects suspected threats whose asset has since become a **confirmed threat**: * `"blocked"` - the asset is on the blocklist (`asset.status` is `"BLOCKED"`) * `"pending"` - the asset was confirmed malicious but is not enforced yet, because protection is not active for your organization (`asset.pendingStatus` is `"BLOCKED"`). The ChainPatrol app labels these **Pending Blocked**. Pass both values to get every confirmed threat, the way the app counts them. The `assetStatus` filter only sees `asset.status`, so `assetStatus: ["BLOCKED"]` leaves pending blocks out. **5. Deleted Filter (`"deleted"`)** ```typescript theme={null} { "property": "deleted", "operator": "in" | "notIn", "value": ["deleted"] } ``` Deleted suspected threats are **included by default**. Add `{ "property": "deleted", "operator": "notIn", "value": ["deleted"] }` to leave them out, or use `"in"` to return only deleted ones. **6. Asset Type Filter (`"assetType"`)** ```typescript theme={null} { "property": "assetType", "operator": "in" | "notIn", "value": AssetType[] } ``` > [accordion] 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 ```typescript theme={null} { detections: DetectionResult[]; nextCursor?: number; // omitted on the last page total?: number; // only when includeTotal is true } ``` ### Detection Result Object Each item in the `detections` array is one suspected threat, with the following structure: | Field | Type | Description | | - | - | - | | `id` | `number` | Unique threat detection result identifier | | `threatContent` | `string` | Content that was detected as threatening | | `source` | `string` | Detection source that found it (ThreatDetectionSourceKey) | | `createdAt` | `string` | ISO 8601 timestamp of when it was detected | | `confidence` | `string` | Confidence level: "none", "low", "medium", or "high" | | `score` | `number` | Raw model score (0–1) that `confidence` is bucketed from | | `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) | | `pendingStatus` | `string \| null` | A reviewed status that has not taken effect yet. `"BLOCKED"` means confirmed malicious but not enforced because protection is not active ("Pending Blocked"). `null` when nothing is pending. | ### Complete Response Example ```json theme={null} { "detections": [ { "id": 12345, "threatContent": "Phishing site detected mimicking legitimate service", "source": "GOOGLE_SEARCH", "createdAt": "2024-01-15T10:30:00Z", "confidence": "high", "score": 0.97, "reportStatus": "REPORTED", "asset": { "id": 67890, "content": "https://fake-site.com", "type": "URL", "status": "BLOCKED", "pendingStatus": null } }, { "id": 12346, "threatContent": "Suspicious crypto address found in scam report", "source": "EXTERNAL", "createdAt": "2024-01-15T09:15:00Z", "confidence": "medium", "score": 0.71, "reportStatus": "NOT_REPORTED", "asset": { "id": 67891, "content": "0x1234567890123456789012345678901234567890", "type": "ADDRESS", "status": "UNKNOWN", "pendingStatus": "BLOCKED" } } ], "nextCursor": 12347 } ``` ## Counting and Score Cut-offs To count suspected threats without paging through them, send `includeTotal: true`. The response then carries `total`: how many suspected threats match your filters, search and date range across all pages. It is counted before the cursor is applied, so every page of a sweep reports the same number. It costs an extra count query, so ask for it on the first page rather than on every page. `confidence` is bucketed from `score` using your organization's own thresholds, so `"high"` does not mean a fixed score. For a fixed cut-off such as "over 80%", use `minScore` (and optionally `maxScore`) instead: ```bash theme={null} curl --request POST \ --url https://app.chainpatrol.io/api/v2/detection/list \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: ' \ --data '{ "slug": "your-org", "limit": 10, "minScore": 0.8, "includeTotal": true, "filters": [ { "property": "deleted", "operator": "notIn", "value": ["deleted"] } ] }' ``` `minScore` greater than `maxScore` is rejected with a `400`. See [Evaluating suspected threats](https://chainpatrol.com/docs/external-api/evaluating-detections.md) for the questions people usually ask when they first look at this data, and the request that answers each one. ## Pagination and Incremental Sync Suspected threats are returned newest first. There is no single-call export: an organization can hold hundreds of thousands of suspected threats, far more than fit in one response. Page through them instead: * Set `limit` up to **1000**. * Pass the `nextCursor` from each response back as `cursor`. * Stop when a response has no `nextCursor`. > [!NOTE] > > Responses are capped at 4MB. A page that would exceed it fails with a `413` > error instead of being cut short. Retry with a smaller `limit`. A 1000-row page > is usually well under 1MB. ### Fetching only new suspected threats After an initial full sync, use `startDate` so each run only fetches what was created since the previous one. For 1,000–10,000 new suspected threats a day, that is a handful of 1000-row pages. 1. Record the time the sync starts, and send it as `endDate`. Suspected threats created while you are paging land at the front of the newest-first order, so without a fixed `endDate` they would be skipped. The next run picks them up instead. 2. Set `startDate` to the previous run's start time, minus a few minutes of overlap. A suspected threat can take a few seconds to become visible after its `createdAt`, and the overlap catches it. 3. Page until `nextCursor` is absent, and de-duplicate by `id`. The overlap means some suspected threats come back in two runs. Deleted suspected threats are included unless you add `{ "property": "deleted", "operator": "notIn", "value": ["deleted"] }` to `filters`. To fetch only suspected fake domains, add `{ "property": "assetType", "operator": "in", "value": ["URL"] }`. > [!WARNING] > > A `startDate` sync only returns suspected threats *created* in the window. If a > suspected threat is reported or deleted after you fetched it, the next incremental run > will not return it again. Run a periodic full sync (for example, daily) if you > need those changes. ```javascript JavaScript theme={null} async function fetchDetections({ slug, startDate, endDate, filters = [] }) { const detections = new Map(); let cursor; do { const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", { method: "POST", headers: { "Content-Type": "application/json", "X-API-KEY": "", }, body: JSON.stringify({ slug, limit: 1000, filters, ...(startDate ? { startDate } : {}), ...(endDate ? { endDate } : {}), ...(cursor ? { cursor } : {}), }), }); if (!response.ok) { throw new Error(`detection/list failed: ${response.status}`); } const data = await response.json(); for (const detection of data.detections) { detections.set(detection.id, detection); } cursor = data.nextCursor; } while (cursor); return [...detections.values()]; } // Incremental run: everything created since the previous run started. const OVERLAP_MS = 5 * 60 * 1000; const syncStartedAt = new Date(); const previousSyncStartedAt = new Date("2026-09-24T00:00:00Z"); // load from your store const newDetections = await fetchDetections({ slug: "your-org", startDate: new Date(previousSyncStartedAt.getTime() - OVERLAP_MS).toISOString(), endDate: syncStartedAt.toISOString(), filters: [{ property: "assetType", operator: "in", value: ["URL"] }], }); // Save `syncStartedAt` as the next run's `previousSyncStartedAt`. ``` ```python Python theme={null} from datetime import datetime, timedelta, timezone import requests def fetch_detections(slug, start_date=None, end_date=None, filters=None): detections = {} cursor = None while True: body = {"slug": slug, "limit": 1000, "filters": filters or []} if start_date: body["startDate"] = start_date.isoformat() if end_date: body["endDate"] = end_date.isoformat() if cursor: body["cursor"] = cursor response = requests.post( "https://app.chainpatrol.io/api/v2/detection/list", headers={"Content-Type": "application/json", "X-API-KEY": ""}, json=body, ) response.raise_for_status() data = response.json() for detection in data["detections"]: detections[detection["id"]] = detection cursor = data.get("nextCursor") if not cursor: break return list(detections.values()) # Incremental run: everything created since the previous run started. sync_started_at = datetime.now(timezone.utc) previous_sync_started_at = datetime(2026, 9, 24, tzinfo=timezone.utc) # load from your store new_detections = fetch_detections( "your-org", start_date=previous_sync_started_at - timedelta(minutes=5), end_date=sync_started_at, filters=[{"property": "assetType", "operator": "in", "value": ["URL"]}], ) # Save `sync_started_at` as the next run's `previous_sync_started_at`. ``` ## Access Control The API enforces strict access control based on your API key: 1. **Organization API Keys**: * Can only access suspected threats for their associated organization * Must match the `slug` parameter exactly * Example: An API key for "acme-org" can only query results for "acme-org" 2. **User API Keys**: * Can access suspected threats 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 ```javascript JavaScript theme={null} async function fetchDetectionResults(params) { const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", { method: "POST", headers: { "Content-Type": "application/json", "X-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)); ``` ```typescript TypeScript theme={null} interface DetectionFilter { property: | "source" | "assetStatus" | "blockStatus" | "deleted" | "assetType" | "confidence"; operator: "in" | "notIn"; value: string[]; } interface DetectionListParams { slug: string; cursor?: number; limit?: number; filters?: DetectionFilter[]; query?: string; startDate?: string; endDate?: string; minScore?: number; maxScore?: number; includeTotal?: boolean; } interface AssetObject { id: number; content: string; type: string; status: string; pendingStatus: string | null; } interface DetectionResult { id: number; threatContent: string; source: string; createdAt: string; confidence: "none" | "low" | "medium" | "high"; score: number; reportStatus: "REPORTED" | "NOT_REPORTED"; asset: AssetObject; } interface DetectionListResponse { detections: DetectionResult[]; nextCursor?: number; total?: number; } async function fetchDetectionResults( params: DetectionListParams ): Promise { const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", { method: "POST", headers: { "Content-Type": "application/json", "X-API-KEY": "", }, body: JSON.stringify(params), }); return response.json(); } // Example usage fetchDetectionResults({ slug: "your-org", limit: 50, filters: [ { property: "source", operator: "in", value: ["GOOGLE_SEARCH", "EXTERNAL"], }, { property: "assetStatus", operator: "in", value: ["BLOCKED"], }, ], }) .then((data) => { console.log(`Found ${data.detections.length} detection results`); data.detections.forEach((item) => { console.log(`Threat: ${item.threatContent}`); console.log(`Asset: ${item.asset.content} (${item.asset.type})`); console.log(`Status: ${item.asset.status}`); console.log(`Confidence: ${item.confidence}`); console.log(`Report Status: ${item.reportStatus}`); console.log("---"); }); if (data.nextCursor) { console.log("More results available with cursor:", data.nextCursor); } }) .catch((error) => console.error("Error fetching results:", error)); ``` ## OpenAPI ````yaml POST /detection/list openapi: 3.0.3 info: title: ChainPatrol External API - OpenAPI 3.0 description: ChainPatrol External API documentation version: 2.0.0 servers: - url: https://app.chainpatrol.io/api/v2 security: [] tags: - name: asset - name: report - name: dark-web externalDocs: url: https://chainpatrol.com/docs paths: /detection/list: post: tags: - detection summary: List suspected threats for organization description: >- List suspected threats for an organization using API key authentication, newest first. A suspected threat is an unconfirmed result of automated threat detection; use the `blockStatus` filter to find the ones confirmed as threats. Returns human-readable confidence levels (none, low, medium, high) and report status. Supports filtering by source, confidence level, raw score range, asset status, asset type and creation time, plus search. Pages hold up to 1000 results: pass `nextCursor` back as `cursor` until it is absent, set `includeTotal` to get the number of matching suspected threats without paging, and use `startDate` to fetch only suspected threats created since your last sync. operationId: detectionList requestBody: required: true content: application/json: schema: type: object properties: slug: type: string description: Organization slug cursor: type: number description: >- Pass the `nextCursor` from the previous response to fetch the next page. Omit it for the first page. limit: type: number minimum: 1 maximum: 1000 default: 50 description: >- Number of results per page, between 1 and 1000. Defaults to 50. filters: type: array items: oneOf: - type: object properties: property: type: string enum: - source operator: type: string enum: - in - notIn value: type: array items: type: string enum: - meta_ads_search - telegram_channels_search - telegram_user_search - telegram_channels_search_vetric - telegram_user_search_vetric - facebook_page_search_vetric - facebook_user_search_vetric - facebook_post_search_vetric - instagram_account_search_vetric - twitter_search_vetric - linkedin_people_search_vetric - linkedin_company_search_vetric - meta_ads_search_vetric - tik_tok_video_search - tik_tok_user_search - tik_tok_user_search_vetric - tik_tok_video_search_vetric - blocklist - apple_app_store - google_ads_search - google_ads_transparency_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 - twitter_username_monitor - urlscan - urlscan_hostname_search - youtube_search - google_play_search - dexscreener_search - blocked_ip_scan - blocked_bilibili_suggested - grok_post_search - grok_user_search - google_lens_image_search - yandex_search - yandex_image_search - linkedin_employee_detection - linkedin_post_search - linkedin_company_search - bing_ads_search - tik_tok_ads_search - adlibrary_ads_search - dnsdb - daily_motion_search - watchlist - github_search - pump_fun_token_search - dnsdb_watched_parents - ct_log_search - ranger required: - property - operator - value - type: object properties: property: type: string enum: - confidence operator: type: string enum: - in - notIn value: type: array items: type: string enum: - none - low - medium - high required: - property - operator - value - type: object properties: property: type: string enum: - liveness operator: type: string enum: - in - notIn value: type: array items: type: string enum: - UNKNOWN - ALIVE - DEAD required: - property - operator - value - type: object properties: property: type: string enum: - watchlist operator: type: string enum: - in - notIn value: type: array items: type: string enum: - ENABLED - DISABLED required: - property - operator - value - type: object properties: property: type: string enum: - assetStatus operator: type: string enum: - in - notIn value: type: array items: type: string enum: - UNKNOWN - ALLOWED - BLOCKED required: - property - operator - value - type: object properties: property: type: string enum: - blockStatus operator: type: string enum: - in - notIn value: type: array items: type: string enum: - blocked - pending required: - property - operator - value description: >- Filter by whether the asset is a confirmed threat. `blocked` matches assets on the blocklist (`asset.status` is `BLOCKED`); `pending` matches assets confirmed malicious but not yet enforced because protection is not active (`asset.pendingStatus` is `BLOCKED`). Pass both to get every confirmed threat, the way the ChainPatrol app counts them. - type: object properties: property: type: string enum: - reported operator: type: string enum: - in - notIn value: type: array items: type: string enum: - reported - not_reported required: - property - operator - value - type: object properties: property: type: string enum: - assetType operator: type: string enum: - in - notIn value: type: array items: type: string enum: - 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 - BASENAME - BILIBILI_TV - VIMEO - DAILYMOTION - PHONE_NUMBER - SLACK - CALENDLY - NGROK - RARIBLE - RUST_PACKAGE - FLATHUB - VIDLII - VEVIOZ - ISSUU - SOUNDCLOUD - ZAPPER - REDNOTE - SAMSUNG_APP_STORE - HUAWEI_APP_STORE - XIAOMI_APP_STORE - TENCENT_APP_STORE - OPPO_APP_STORE - VIVO_APP_STORE - F_DROID - GOOGLE_AD - BING_AD - TWITCH - BEHANCE - ZORA - META_AD - SIGNAL - DEVIANTART - BANDCAMP - ARCHIVE_ORG - FIVE_HUNDRED_PX - LUMA - SMARTMONEYMATCH - APK_GOLD - GLASSDOOR - PUMP_FUN - TUMBLR - MASTODON required: - property - operator - value - type: object properties: property: type: string enum: - brand operator: type: string enum: - in - notIn value: type: array items: type: number required: - property - operator - value - type: object properties: property: type: string enum: - deleted operator: type: string enum: - in - notIn value: type: array items: type: string enum: - deleted required: - property - operator - value - type: object properties: property: type: string enum: - countryCode operator: type: string enum: - in - notIn value: type: array items: type: string minLength: 2 maxLength: 2 required: - property - operator - value default: [] description: Filters to apply to the results query: type: string default: '' description: Search query for threat content minScore: type: number minimum: 0 maximum: 1 description: >- Only return suspected threats whose raw `score` is at least this value (inclusive, 0-1). Use this rather than the `confidence` filter when you need a fixed cut-off such as 0.8: `confidence` buckets depend on your organization's thresholds. maxScore: type: number minimum: 0 maximum: 1 description: >- Only return suspected threats whose raw `score` is at most this value (inclusive, 0-1). Must not be below `minScore`. includeTotal: type: boolean default: false description: >- Also return `total`: how many suspected threats match the filters, search and date range across all pages. Costs an extra count query, so request it on the first page of a sweep rather than every page. startDate: type: string description: >- Only return suspected threats created at or after this time (inclusive). For incremental syncs, pass the time your previous sync started minus a few minutes of overlap, and de-duplicate by `id`. endDate: type: string description: >- Only return suspected threats created at or before this time (inclusive). Pin it to the time a sync starts so every page of that sync sees the same result set. required: - slug responses: '200': description: Successful response content: application/json: schema: type: object properties: detections: type: array items: type: object properties: id: type: number threatContent: type: string source: anyOf: - type: string enum: - meta_ads_search - telegram_channels_search - telegram_user_search - telegram_channels_search_vetric - telegram_user_search_vetric - facebook_page_search_vetric - facebook_user_search_vetric - facebook_post_search_vetric - instagram_account_search_vetric - twitter_search_vetric - linkedin_people_search_vetric - linkedin_company_search_vetric - meta_ads_search_vetric - tik_tok_video_search - tik_tok_user_search - tik_tok_user_search_vetric - tik_tok_video_search_vetric - blocklist - apple_app_store - google_ads_search - google_ads_transparency_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 - twitter_username_monitor - urlscan - urlscan_hostname_search - youtube_search - google_play_search - dexscreener_search - blocked_ip_scan - blocked_bilibili_suggested - grok_post_search - grok_user_search - google_lens_image_search - yandex_search - yandex_image_search - linkedin_employee_detection - linkedin_post_search - linkedin_company_search - bing_ads_search - tik_tok_ads_search - adlibrary_ads_search - dnsdb - daily_motion_search - watchlist - github_search - pump_fun_token_search - dnsdb_watched_parents - ct_log_search - ranger - type: string description: >- Detection source key. Usually one of the current source keys, but suspected threats from a retired source keep their original key, so treat unknown values as valid. createdAt: type: string confidence: type: string enum: - none - low - medium - high score: type: number description: >- Raw model score (0-1). `confidence` is derived by bucketing this into low/medium/high using the org's thresholds; use this when the buckets are too coarse. reason: type: string description: >- Free-text explanation of why this was flagged as a suspected threat (e.g. 'matches brand-name typo squat', 'TLS cert issued by known lookalike CA'). Read this before deciding what to do with a hit. configId: type: number description: >- ID of the `ThreatDetectionConfig` that produced this hit. Combine with `run_chainpatrol listDetectionConfigs` to drill back into the config. reportedAt: type: string nullable: true description: >- When the suspected threat was reported (transitioned to REPORTED status). `null` when it hasn't been reported yet — `reportStatus` reflects the same information as a categorical. brands: type: array items: type: object properties: id: type: number name: type: string slug: type: string required: - id - name - slug description: >- Brands the suspected threat was associated with. Empty when it was not linked to any brand at classification time. reportStatus: type: string enum: - REPORTED - NOT_REPORTED asset: type: object properties: id: type: number content: type: string type: type: string enum: - 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 - BASENAME - BILIBILI_TV - VIMEO - DAILYMOTION - PHONE_NUMBER - SLACK - CALENDLY - NGROK - RARIBLE - RUST_PACKAGE - FLATHUB - VIDLII - VEVIOZ - ISSUU - SOUNDCLOUD - ZAPPER - REDNOTE - SAMSUNG_APP_STORE - HUAWEI_APP_STORE - XIAOMI_APP_STORE - TENCENT_APP_STORE - OPPO_APP_STORE - VIVO_APP_STORE - F_DROID - GOOGLE_AD - BING_AD - TWITCH - BEHANCE - ZORA - META_AD - SIGNAL - DEVIANTART - BANDCAMP - ARCHIVE_ORG - FIVE_HUNDRED_PX - LUMA - SMARTMONEYMATCH - APK_GOLD - GLASSDOOR - PUMP_FUN - TUMBLR - MASTODON status: type: string enum: - UNKNOWN - ALLOWED - BLOCKED pendingStatus: type: string nullable: true enum: - UNKNOWN - ALLOWED - BLOCKED - null description: >- A reviewed status that has not taken effect yet, or null when nothing is pending. `BLOCKED` here means the asset was confirmed malicious but is not enforced on the blocklist because protection is not active for your organization — shown as "Pending Blocked" in the ChainPatrol app. It becomes `status` once protection is activated. required: - id - content - type - status - pendingStatus required: - id - threatContent - source - createdAt - confidence - score - reason - configId - reportedAt - brands - reportStatus - asset nextCursor: type: number total: type: number description: >- How many suspected threats match the filters, search and date range across all pages, regardless of `cursor`. Present only when `includeTotal` is true. required: - detections '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - ApiKey: [] components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Invalid input data code: type: string description: The error code example: BAD_REQUEST issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Authorization not provided code: type: string description: The error code example: UNAUTHORIZED issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] error.FORBIDDEN: type: object properties: message: type: string description: The error message example: Insufficient access code: type: string description: The error code example: FORBIDDEN issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: ApiKey: type: apiKey in: header name: X-API-KEY description: >- Your API key. This is required by most endpoints to access our API programatically. Reach out to us at [support@chainpatrol.io](mailto:support@chainpatrol.io?subject=Re:%20API%20Key%20for%20SDK&body=Company:%20%0AName:%20%0APurpose:%20) to get an API key for your use. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.