List suspected threats for organization

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "slug": "<string>",
  "cursor": 123,
  "limit": 50,
  "filters": [],
  "query": "",
  "minScore": 0.5,
  "maxScore": 0.5,
  "includeTotal": false,
  "startDate": "<string>",
  "endDate": "<string>"
}
'

import requests

url = "https://app.chainpatrol.io/api/v2/detection/list"

payload = {
    "slug": "<string>",
    "cursor": 123,
    "limit": 50,
    "filters": [],
    "query": "",
    "minScore": 0.5,
    "maxScore": 0.5,
    "includeTotal": False,
    "startDate": "<string>",
    "endDate": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slug: '<string>',
    cursor: 123,
    limit: 50,
    filters: [],
    query: '',
    minScore: 0.5,
    maxScore: 0.5,
    includeTotal: false,
    startDate: '<string>',
    endDate: '<string>'
  })
};

fetch('https://app.chainpatrol.io/api/v2/detection/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.chainpatrol.io/api/v2/detection/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'cursor' => 123,
    'limit' => 50,
    'filters' => [
        
    ],
    'query' => '',
    'minScore' => 0.5,
    'maxScore' => 0.5,
    'includeTotal' => false,
    'startDate' => '<string>',
    'endDate' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.chainpatrol.io/api/v2/detection/list"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.chainpatrol.io/api/v2/detection/list")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chainpatrol.io/api/v2/detection/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "detections": [
    {
      "id": 123,
      "threatContent": "<string>",
      "source": "meta_ads_search",
      "createdAt": "<string>",
      "confidence": "none",
      "score": 123,
      "reason": "<string>",
      "configId": 123,
      "reportedAt": "<string>",
      "brands": [
        {
          "id": 123,
          "name": "<string>",
          "slug": "<string>"
        }
      ],
      "reportStatus": "REPORTED",
      "asset": {
        "id": 123,
        "content": "<string>",
        "type": "URL",
        "status": "UNKNOWN",
        "pendingStatus": "UNKNOWN"
      }
    }
  ],
  "nextCursor": 123,
  "total": 123
}

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

Threat Detection

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.

POST

detection

list

List suspected threats for organization

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "slug": "<string>",
  "cursor": 123,
  "limit": 50,
  "filters": [],
  "query": "",
  "minScore": 0.5,
  "maxScore": 0.5,
  "includeTotal": false,
  "startDate": "<string>",
  "endDate": "<string>"
}
'

import requests

url = "https://app.chainpatrol.io/api/v2/detection/list"

payload = {
    "slug": "<string>",
    "cursor": 123,
    "limit": 50,
    "filters": [],
    "query": "",
    "minScore": 0.5,
    "maxScore": 0.5,
    "includeTotal": False,
    "startDate": "<string>",
    "endDate": "<string>"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slug: '<string>',
    cursor: 123,
    limit: 50,
    filters: [],
    query: '',
    minScore: 0.5,
    maxScore: 0.5,
    includeTotal: false,
    startDate: '<string>',
    endDate: '<string>'
  })
};

fetch('https://app.chainpatrol.io/api/v2/detection/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.chainpatrol.io/api/v2/detection/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slug' => '<string>',
    'cursor' => 123,
    'limit' => 50,
    'filters' => [
        
    ],
    'query' => '',
    'minScore' => 0.5,
    'maxScore' => 0.5,
    'includeTotal' => false,
    'startDate' => '<string>',
    'endDate' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.chainpatrol.io/api/v2/detection/list"

	payload := strings.NewReader("{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.chainpatrol.io/api/v2/detection/list")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chainpatrol.io/api/v2/detection/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slug\": \"<string>\",\n  \"cursor\": 123,\n  \"limit\": 50,\n  \"filters\": [],\n  \"query\": \"\",\n  \"minScore\": 0.5,\n  \"maxScore\": 0.5,\n  \"includeTotal\": false,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "detections": [
    {
      "id": 123,
      "threatContent": "<string>",
      "source": "meta_ads_search",
      "createdAt": "<string>",
      "confidence": "none",
      "score": 123,
      "reason": "<string>",
      "configId": 123,
      "reportedAt": "<string>",
      "brands": [
        {
          "id": 123,
          "name": "<string>",
          "slug": "<string>"
        }
      ],
      "reportStatus": "REPORTED",
      "asset": {
        "id": 123,
        "content": "<string>",
        "type": "URL",
        "status": "UNKNOWN",
        "pendingStatus": "UNKNOWN"
      }
    }
  ],
  "nextCursor": 123,
  "total": 123
}

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

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:

X-API-KEY: <api-key>

Example Request

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/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	-	-	`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

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")

{
  "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
"YANDEX_IMAGE_SEARCH" - Yandex reverse image search results for your brand imagery
"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 suspected threat
"medium" - Medium-confidence suspected threat
"high" - High-confidence suspected threat

4. Block Status Filter ("blockStatus")

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

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

{
  "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; // 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

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

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <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 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.

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.

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.
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.
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"] }.

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.

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": "<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`.

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": "<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:

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”
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

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": "<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));

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<DetectionListResponse> {
  const response = await fetch("https://app.chainpatrol.io/api/v2/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,
  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));

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 support@chainpatrol.io to get an API key for your use.

Body

application/json

slug

string

required

Organization slug

cursor

number

Pass the nextCursor from the previous response to fetch the next page. Omit it for the first page.

limit

number

default:50

Number of results per page, between 1 and 1000. Defaults to 50.

Required range: 1 <= x <= 1000

filters

object[]

Filters to apply to the results

Show child attributes

query

string

default:""

Search query for threat content

minScore

number

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.

Required range: 0 <= x <= 1

maxScore

number

Only return suspected threats whose raw score is at most this value (inclusive, 0-1). Must not be below minScore.

Required range: 0 <= x <= 1

includeTotal

boolean

default:false

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

string

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

string

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.

Response

Successful response

detections

object[]

required

Show child attributes

nextCursor

number

total

number

How many suspected threats match the filters, search and date range across all pages, regardless of cursor. Present only when includeTotal is true.

Getting Started

Assets

Reports

Disputes

Webhooks

Organization Brands

Organization Assets

Organization Asset Groups

Organization Reports

Threat Detection

Dark Web

Takedowns

Metrics

Account & Access

Operations

Staff

Healthchecks

List Suspected Threats

Overview

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

Counting and Score Cut-offs

Fetching only new suspected threats

Access Control

Example Implementation

Authorizations

Body

Response

​Overview

​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

​Counting and Score Cut-offs

​Pagination and Incremental Sync

​Fetching only new suspected threats

​Access Control

​Example Implementation

Authorizations

Body

Response

Overview

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

Counting and Score Cut-offs

Pagination and Incremental Sync

Fetching only new suspected threats

Access Control

Example Implementation