List Threats

List threats for an organization using API key authentication

POST /threats/list

List threats

cURL

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": [
    "URL"
  ],
  "sorting": [
    {
      "key": "<string>",
      "direction": "asc"
    }
  ],
  "per_page": 10,
  "next_page": "<string>"
}
'

200

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

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:

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

2. 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

JavaScript

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

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 [e-mail] to get an API key for your use.

Body

application/json

query · string

startDate · string

endDate · string

assetType · enum<string>[]

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

sorting · object[]

Show child attributes

per_page · integer · default: 10

Required range: 1 <= x <= 100

next_page · string | null

Response

200

application/json

Successful response

threats · object[] · required

Show child attributes

next_page · string | null