List Threats

List threats

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/threats/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "query": "<string>",
  "startDate": "<string>",
  "endDate": "<string>",
  "assetType": [],
  "sorting": [
    {
      "key": "<string>"
    }
  ],
  "per_page": 10,
  "next_page": "<string>"
}
'

import requests

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

payload = {
    "query": "<string>",
    "startDate": "<string>",
    "endDate": "<string>",
    "assetType": [],
    "sorting": [{ "key": "<string>" }],
    "per_page": 10,
    "next_page": "<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({
    query: '<string>',
    startDate: '<string>',
    endDate: '<string>',
    assetType: [],
    sorting: [{key: '<string>'}],
    per_page: 10,
    next_page: '<string>'
  })
};

fetch('https://app.chainpatrol.io/api/v2/threats/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/threats/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([
    'query' => '<string>',
    'startDate' => '<string>',
    'endDate' => '<string>',
    'assetType' => [
        
    ],
    'sorting' => [
        [
                'key' => '<string>'
        ]
    ],
    'per_page' => 10,
    'next_page' => '<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/threats/list"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<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/threats/list")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chainpatrol.io/api/v2/threats/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  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<string>\"\n}"

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

{
  "threats": [
    {
      "id": 123,
      "content": "<string>",
      "blockedAt": "<string>"
    }
  ],
  "next_page": "<string>"
}

{
  "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": []
}

POST

threats

list

List threats

curl --request POST \
  --url https://app.chainpatrol.io/api/v2/threats/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "query": "<string>",
  "startDate": "<string>",
  "endDate": "<string>",
  "assetType": [],
  "sorting": [
    {
      "key": "<string>"
    }
  ],
  "per_page": 10,
  "next_page": "<string>"
}
'

import requests

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

payload = {
    "query": "<string>",
    "startDate": "<string>",
    "endDate": "<string>",
    "assetType": [],
    "sorting": [{ "key": "<string>" }],
    "per_page": 10,
    "next_page": "<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({
    query: '<string>',
    startDate: '<string>',
    endDate: '<string>',
    assetType: [],
    sorting: [{key: '<string>'}],
    per_page: 10,
    next_page: '<string>'
  })
};

fetch('https://app.chainpatrol.io/api/v2/threats/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/threats/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([
    'query' => '<string>',
    'startDate' => '<string>',
    'endDate' => '<string>',
    'assetType' => [
        
    ],
    'sorting' => [
        [
                'key' => '<string>'
        ]
    ],
    'per_page' => 10,
    'next_page' => '<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/threats/list"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<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/threats/list")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.chainpatrol.io/api/v2/threats/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  \"query\": \"<string>\",\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"assetType\": [],\n  \"sorting\": [\n    {\n      \"key\": \"<string>\"\n    }\n  ],\n  \"per_page\": 10,\n  \"next_page\": \"<string>\"\n}"

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

{
  "threats": [
    {
      "id": 123,
      "content": "<string>",
      "blockedAt": "<string>"
    }
  ],
  "next_page": "<string>"
}

{
  "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": []
}

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/threats/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "query": "phishing",
    "assetType": ["URL", "ADDRESS"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "per_page": 50,
    "sorting": [
      {
        "key": "blockedAt",
        "direction": "desc"
      }
    ]
  }'

Request Schema

Request Body

Field	Type	Required	Default	Constraints	Description
`query`	`string`	❌ No	-	-	Search query to filter threats by content
`startDate`	`string`	❌ No	1 day ago	YYYY-MM-DD format	Start date for filtering threats (inclusive)
`endDate`	`string`	❌ No	today	YYYY-MM-DD format	End date for filtering threats (inclusive)
`assetType`	`AssetType[]`	❌ No	-	-	Array of asset types to filter by
`sorting`	`SortingConfig[]`	❌ No	`[{key: "id", direction: "asc"}]`	-	Array of sorting configurations
`per_page`	`number`	❌ No	`10`	Min: 1, Max: 100	Number of threats to return per page
`next_page`	`string`	❌ No	-	Positive integer	Cursor for fetching the next page of results

Sorting Configuration

Each sorting object must have the following structure:

Field	Type	Required	Description
`key`	`string`	✅ Yes	Field to sort by (see options below)
`direction`	`"asc"` \| `"desc"`	✅ Yes	Sort direction

Available Sort Fields

"id" - Sort by threat ID
"blockedAt" - Sort by when the asset was blocked
"content" - Sort by threat content
"type" - Sort by asset type

Asset Type Filter

The assetType parameter accepts an array of asset types to filter by:

Available Asset Type Values

"URL" - Website URLs
"PAGE" - Web pages
"ADDRESS" - Blockchain addresses
"LINKEDIN" - LinkedIn profiles
"TWITTER" - Twitter profiles/posts
"FACEBOOK" - Facebook profiles/pages
"YOUTUBE" - YouTube channels/videos
"REDDIT" - Reddit posts/subreddits
"TELEGRAM" - Telegram channels/groups
"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
"TIKTOK" - TikTok profiles
"INSTAGRAM" - Instagram profiles
"THREADS" - Threads profiles
"MEDIUM" - Medium articles/profiles
"CHROME_WEB_STORE" - Chrome extensions
"MOZILLA_ADDONS" - Firefox addons
"OPERA_ADDONS" - Opera addons
"EMAIL" - Email addresses
"PATREON" - Patreon profiles
"OPENSEA" - OpenSea collections/profiles
"FARCASTER" - Farcaster profiles
"IPFS" - IPFS hashes
"GOOGLE_FORM" - Google Forms
"WHATSAPP" - WhatsApp contacts
"DISCORD_USER" - Discord users
"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
"PINTEREST" - Pinterest profiles/pins

Response Schema

Response Body

{
  threats: ThreatResult[];
  next_page: string | null;
}

Threat Result Object

Each item in the threats array has the following structure:

Field	Type	Description
`id`	`number`	Unique threat identifier
`content`	`string`	Threat content (URL, address, username, etc.)
`type`	`string`	Asset type (AssetType enum value)
`blockedAt`	`string`	ISO 8601 timestamp of when asset was blocked

Complete Response Example

{
  "threats": [
    {
      "id": 12345,
      "content": "https://fake-site.com",
      "type": "URL",
      "blockedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": 12346,
      "content": "eip155:1:0x1234567890123456789012345678901234567890",
      "type": "ADDRESS",
      "blockedAt": "2024-01-15T09:15:00.000Z"
    },
    {
      "id": 12347,
      "content": "twitter.com/fake_account",
      "type": "TWITTER",
      "blockedAt": "2024-01-15T08:45:00.000Z"
    }
  ],
  "next_page": "12348"
}

Access Control

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

Organization API Keys:
- Can only access threats for their associated organization
- Returns only threats that were blocked by the organization
- Example: An API key for “acme-org” can only query threats blocked by “acme-org”
User API Keys:
- Can access 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 access threats without proper permissions, you will receive a 401 Unauthorized error with the message: “Valid API key required”

Default Behavior

Date Range: If no startDate or endDate is provided, the API defaults to returning threats from the last 1 day
Pagination: If no next_page is provided, returns the first page of results
Sorting: Defaults to sorting by id in ascending order
Page Size: Defaults to 10 results per page (max 100)

Example Implementation

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

// Example usage
fetchThreats({
  query: "phishing",
  assetType: ["URL", "ADDRESS"],
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  per_page: 50,
  sorting: [
    {
      key: "blockedAt",
      direction: "desc",
    },
  ],
})
  .then((data) => {
    console.log("Threats found:", data.threats.length);
    data.threats.forEach((threat) => {
      console.log(`ID: ${threat.id}`);
      console.log(`Content: ${threat.content}`);
      console.log(`Type: ${threat.type}`);
      console.log(`Blocked At: ${threat.blockedAt}`);
      console.log("---");
    });

    if (data.next_page) {
      console.log("More results available with next_page:", data.next_page);
    }
  })
  .catch((error) => console.error("Error fetching threats:", error));

interface SortingConfig {
  key: "id" | "blockedAt" | "content" | "type";
  direction: "asc" | "desc";
}

interface ThreatListParams {
  query?: string;
  startDate?: string;
  endDate?: string;
  assetType?: string[];
  sorting?: SortingConfig[];
  per_page?: number;
  next_page?: string;
}

interface ThreatResult {
  id: number;
  content: string;
  type: string;
  blockedAt: string;
}

interface ThreatListResponse {
  threats: ThreatResult[];
  next_page: string | null;
}

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

// Example usage with pagination
async function getAllThreats(params: ThreatListParams) {
  const allThreats: ThreatResult[] = [];
  let nextPage: string | null = null;

  do {
    const response = await fetchThreats({
      ...params,
      next_page: nextPage || undefined,
    });

    allThreats.push(...response.threats);
    nextPage = response.next_page;
  } while (nextPage);

  return allThreats;
}

// Get all URL threats from the last week
getAllThreats({
  assetType: ["URL"],
  startDate: "2024-01-01",
  endDate: "2024-01-07",
  per_page: 100,
})
  .then((threats) => {
    console.log(`Found ${threats.length} URL threats in the last week`);
  })
  .catch((error) => console.error("Error fetching all threats:", 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

List threats request body

Defaults to getting all threats in the last 1 day.

You can also choose a startDate and endDate for the range of threat updates, most timestamp formats should work, we use Luxon for parsing the dates.

query

string

Search query to filter threats by content

startDate

string

The start date to list threats from. This should be in the format YYYY-MM-DD and is inclusive.

endDate

string

The end date to list threats to. This should be in the format YYYY-MM-DD and is inclusive.

assetType

enum<string>[]

Filter by asset types

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,

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

sorting

object[]

Sorting configuration

Show child attributes

per_page

integer

default:10

The number of threats to return per page

Required range: 1 <= x <= 100

next_page

string | null

Cursor for fetching the next page of results

Response

Successful response

Successful operation

threats

object[]

required

Show child attributes

next_page

string | null

Cursor for fetching the next page of results

⌘I

External API

Assets

Blocklist Sync

Organization Assets

Organization Asset Groups

Organization Brands

Reports

Organization Reports

Threats

Disputes

Takedowns

Organization Metrics

Operations

Healthchecks

Account & Access

Webhooks

Quick Start

Authentication

Example Request

Request Schema

Request Body

Sorting Configuration

Available Sort Fields

Asset Type Filter

Response Schema

Response Body

Threat Result Object

Complete Response Example

Access Control

Default Behavior

Example Implementation

Authorizations

Body

Response

​Quick Start

​Authentication

​Example Request

​Request Schema

​Request Body

​Sorting Configuration

​Available Sort Fields

​Asset Type Filter

​Response Schema

​Response Body

​Threat Result Object

​Complete Response Example

​Access Control

​Default Behavior

​Example Implementation

Authorizations

Body

Response

Quick Start

Authentication

Example Request

Request Schema

Request Body

Sorting Configuration

Available Sort Fields

Asset Type Filter

Response Schema

Response Body

Threat Result Object

Complete Response Example

Access Control

Default Behavior

Example Implementation