> ## 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 Threats > List threats for an organization using API key authentication ## 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://api.chainpatrol.io/threats/list \ --header 'Content-Type: application/json' \ --header 'X-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: * `"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 ```typescript theme={null} { 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 ```json theme={null} { "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 JavaScript theme={null} async function fetchThreats(params) { const response = await fetch("https://api.chainpatrol.io/threats/list", { method: "POST", headers: { "Content-Type": "application/json", "X-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)); ``` ```typescript TypeScript theme={null} 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 { const response = await fetch("https://api.chainpatrol.io/threats/list", { method: "POST", headers: { "Content-Type": "application/json", "X-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)); ``` ## OpenAPI ````yaml POST /threats/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 externalDocs: url: https://chainpatrol.com/docs paths: /threats/list: post: tags: - threats summary: List threats description: List threats for an organization using API key authentication operationId: threatsList requestBody: required: true content: application/json: schema: type: object properties: query: type: string startDate: type: string endDate: type: string assetType: 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 sorting: type: array items: type: object properties: key: type: string direction: type: string enum: - asc - desc required: - key - direction per_page: type: integer minimum: 1 maximum: 100 default: 10 next_page: type: string nullable: true responses: '200': description: Successful response content: application/json: schema: type: object properties: threats: type: array items: 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 blockedAt: type: string required: - id - content - type - blockedAt next_page: type: string nullable: true required: - threats '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. ````