From b896b8af3c5606d111438e9d953991c5e5580099 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:15:03 +0000 Subject: [PATCH 1/2] docs: document expanded response fields for takedowns, detections, reports, and assets --- external-api/asset-list.mdx | 10 ++++++ external-api/asset-search.mdx | 4 +-- external-api/detection-list.mdx | 33 +++++++++++++----- external-api/organization-reports-list.mdx | 34 +++++++++++++------ external-api/takedowns-list.mdx | 12 +++++++ external-api/threats-list.mdx | 17 ++++++---- .../instance-methods/asset-list.mdx | 24 +++++++++++++ 7 files changed, 107 insertions(+), 27 deletions(-) diff --git a/external-api/asset-list.mdx b/external-api/asset-list.mdx index fd99d5c..0b65159 100644 --- a/external-api/asset-list.mdx +++ b/external-api/asset-list.mdx @@ -13,6 +13,16 @@ Include your API key in the `X-API-KEY` header: X-API-KEY: ``` +## Response fields + +Each entry in the `assets` array includes: + +- **`id`** — the asset's unique numeric identifier. Use this to reference the asset in follow-up calls to endpoints like `POST /asset/search`. +- **`livenessStatus`** — whether the asset is currently reachable (`ALIVE`), gone (`DEAD`), or has never been checked (`UNKNOWN`). `null` when liveness has never been evaluated. Use this to skip dead assets without an extra call. +- **`blockedAt`** — ISO 8601 timestamp of when the asset transitioned to `BLOCKED`. `null` for non-blocked assets or for blocks that predate this field. Distinct from `updatedAt`, which changes on any mutation. + +Existing fields (`content`, `type`, `status`, `watchStatus`, `updatedAt`) are unchanged. + ## Sync Strategy and Removals diff --git a/external-api/asset-search.mdx b/external-api/asset-search.mdx index af5f5fc..a686853 100644 --- a/external-api/asset-search.mdx +++ b/external-api/asset-search.mdx @@ -7,9 +7,9 @@ openapi: "POST /asset/search" The Asset Search endpoint returns a single result with four main parts: -- **asset** - The matched asset: its `id`, `content`, `type`, `status`, `watchStatus`, and timestamps (`createdAt`, `updatedAt`). +- **asset** - The matched asset: its `id`, `content`, `type`, `status`, `watchStatus`, `livenessStatus` (whether the asset is currently `ALIVE`, `DEAD`, or `UNKNOWN`, `null` when it hasn't been checked), `blockedAt` (when the asset transitioned to `BLOCKED`, `null` for non-blocked assets), and timestamps (`createdAt`, `updatedAt`). - **reports** - List of reports linked to the asset, each with `id`, `title`, `status`, and `createdAt`. -- **takedown** - Takedown metadata (`id`, `status`, timestamps) plus a **tasks** array. Each task has `type`, `status`, `retractionStatus`, the associated `takedownProvider` name, submission/retraction timestamps, and an optional `externalId` for the provider's tracking ID. [Learn more about takedown tasks](../general/concepts#takedown-tasks). +- **takedown** - Takedown metadata (`id`, `status`, timestamps) plus a **tasks** array. Each task has `type`, `status`, `retractionStatus`, the associated `takedownProvider` name, submission/retraction timestamps, and an optional `externalId` for the provider's tracking ID. [Learn more about takedown tasks](/general/concepts#takedown-tasks). - **blockedBy** - List of platforms currently consuming (blocking) the asset. Each entry has a `consumer` slug (e.g. `metamask`, `google-safe-browsing`, `quad9`), the platform's display `name`, and a `consumedAt` timestamp indicating when the platform started blocking the asset. ## Quick Start diff --git a/external-api/detection-list.mdx b/external-api/detection-list.mdx index a1a4e83..db424c7 100644 --- a/external-api/detection-list.mdx +++ b/external-api/detection-list.mdx @@ -205,15 +205,20 @@ Each filter object must have the following structure: Each item in the `detections` array has the following structure: -| Field | Type | Description | -| --------------- | ------------- | --------------------------------------------------------- | -| `id` | `number` | Unique threat detection result identifier | -| `threatContent` | `string` | Content that was detected as threatening | -| `source` | `string` | Source of the threat detection (ThreatDetectionSourceKey) | -| `createdAt` | `string` | ISO 8601 timestamp of when threat was detected | -| `confidence` | `string` | Confidence level: "none", "low", "medium", or "high" | -| `reportStatus` | `string` | Report status: "REPORTED" or "NOT_REPORTED" | -| `asset` | `AssetObject` | Associated asset information | +| Field | Type | Description | +| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `number` | Unique threat detection result identifier | +| `threatContent` | `string` | Content that was detected as threatening | +| `source` | `string` | Source of the threat detection (ThreatDetectionSourceKey) | +| `createdAt` | `string` | ISO 8601 timestamp of when threat was detected | +| `confidence` | `string` | Confidence level: `"none"`, `"low"`, `"medium"`, or `"high"`. Bucketed from `score` using your organization's thresholds. | +| `score` | `number` | Raw model score in the range `0`–`1`. Use this when you need a finer-grained signal than the bucketed `confidence`. | +| `reason` | `string \| null` | Free-text explanation of why the detection fired (for example, `"matches brand-name typo squat"` or `"TLS cert issued by known lookalike CA"`). Read this before deciding how to act on a hit. | +| `configId` | `number \| null` | ID of the `ThreatDetectionConfig` that produced the hit. Pair with `GET /detection-configs/list` to look up the originating config. | +| `reportStatus` | `string` | Report status: `"REPORTED"` or `"NOT_REPORTED"` | +| `reportedAt` | `string \| null` | ISO 8601 timestamp of the transition to `REPORTED`. `null` when the detection has not been reported. | +| `brands` | `Brand[]` | Brand associations for the detection (each entry has at least `id`, `name`, and `slug`). Empty array when no brand match is available. | +| `asset` | `AssetObject` | Associated asset information | ### Asset Object @@ -235,7 +240,12 @@ Each item in the `detections` array has the following structure: "source": "GOOGLE_SEARCH", "createdAt": "2024-01-15T10:30:00Z", "confidence": "high", + "score": 0.94, + "reason": "Matches brand-name typo squat", + "configId": 42, "reportStatus": "REPORTED", + "reportedAt": "2024-01-15T10:32:00Z", + "brands": [{ "id": 7, "name": "Acme", "slug": "acme" }], "asset": { "id": 67890, "content": "https://fake-site.com", @@ -249,7 +259,12 @@ Each item in the `detections` array has the following structure: "source": "EXTERNAL", "createdAt": "2024-01-15T09:15:00Z", "confidence": "medium", + "score": 0.62, + "reason": null, + "configId": null, "reportStatus": "NOT_REPORTED", + "reportedAt": null, + "brands": [], "asset": { "id": 67891, "content": "0x1234567890123456789012345678901234567890", diff --git a/external-api/organization-reports-list.mdx b/external-api/organization-reports-list.mdx index d95e54a..cf291e3 100644 --- a/external-api/organization-reports-list.mdx +++ b/external-api/organization-reports-list.mdx @@ -111,7 +111,13 @@ curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?limit=50' \ "reason": "phishing", "createdAt": "2024-01-15T10:30:00.000Z" } - ] + ], + "slaDueAt": "2024-01-16T10:30:00.000Z", + "externalSubmissionLink": "https://discord.com/channels/123/456/789", + "duplicateOfId": null, + "imageDisplay": "PREVIEW", + "favoritedAt": null, + "attachments": [] } ], "cursor": "next_page_cursor_string" @@ -120,15 +126,23 @@ curl -X GET 'https://app.chainpatrol.io/api/v2/organization/reports?limit=50' \ ### Response Fields -| Field | Type | Description | -| -------------------------- | ------ | ------------------------------------------------------------------------ | -| reports | array | Array of report objects for your organization | -| reports[].id | string | Unique identifier for the report | -| reports[].createdAt | string | ISO 8601 timestamp when the report was created | -| reports[].status | string | Overall status of the report (PENDING, APPROVED, REJECTED) | -| reports[].assets | array | Array of assets included in the report | -| reports[].proposals | array | Array of proposals associated with the report | -| cursor | string | Cursor for the next page of results (undefined if no more results) | +| Field | Type | Description | +| ---------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| reports | array | Array of report objects for your organization | +| reports[].id | string | Unique identifier for the report | +| reports[].createdAt | string | ISO 8601 timestamp when the report was created | +| reports[].status | string | Overall status of the report (PENDING, APPROVED, REJECTED) | +| reports[].assets | array | Array of assets included in the report | +| reports[].proposals | array | Array of proposals associated with the report. Each proposal exposes its nested `asset.scans[]` metadata for callers that need scan history alongside the proposal. | +| reports[].slaDueAt | string \| null | ISO 8601 SLA deadline for the report. Use this to identify reports that are late without making a second healthcheck call. | +| reports[].externalSubmissionLink | string \| null | Original external source URL (for example, a Discord message, X/Twitter post, or forwarded webform) when the report was submitted from a third-party surface. | +| reports[].duplicateOfId | string \| null | ID of the canonical report when this report is a duplicate. Group reports by this field to dedupe counts. | +| reports[].imageDisplay | string | How the report's images should be displayed in downstream UIs. | +| reports[].favoritedAt | string \| null | ISO 8601 timestamp when the report was favorited by a reviewer. `null` when it isn't favorited. | +| reports[].attachments | array | Attachments uploaded with the report (screenshots, evidence files, etc.). | +| cursor | string | Cursor for the next page of results (undefined if no more results) | + +All new fields are additive — existing integrations continue to work unchanged. ## Pagination diff --git a/external-api/takedowns-list.mdx b/external-api/takedowns-list.mdx index 778be22..f4a813d 100644 --- a/external-api/takedowns-list.mdx +++ b/external-api/takedowns-list.mdx @@ -14,6 +14,18 @@ openapi: "POST /takedowns/list" pagination feature as described below. +## Response fields + +Each entry in the `takedowns` array includes: + +- **`externalId`** (nullable) — the vendor's own reference for the takedown (for example, a CleanDNS report ID or a registrar ticket number). Use this to reconcile takedowns with your own systems and with reports pulled from the takedown provider directly. +- **`hasFilingDelay`** / **`hasLivenessCheckDelay`** — boolean flags set by ChainPatrol staff that mark takedowns held up in filing or liveness verification. Use them to explain slow takedowns without needing internal context. +- **`domainRegistrar`**, **`hostingProvider`**, **`tldRegistrar`** — `{ id, name }` objects (nullable) describing the entities responsible for the asset being taken down. These are exposed at the takedown level and are distinct from the per-task `takedownProvider` on `tasks[]`. +- **`asset.livenessStatus`** — whether the asset is currently reachable (`ALIVE`), gone (`DEAD`), or hasn't been checked (`UNKNOWN`). `null` when liveness has never been evaluated. +- **`asset.blockedAt`** — timestamp when the asset transitioned to `BLOCKED`. `null` for non-blocked assets or blocks that predate the field. + +All fields are additive — existing integrations continue to work unchanged. + ## Pagination To use pagination, include the `per_page` and `next_page` parameters in your request: diff --git a/external-api/threats-list.mdx b/external-api/threats-list.mdx index 3f3a2c6..cd3bdfb 100644 --- a/external-api/threats-list.mdx +++ b/external-api/threats-list.mdx @@ -129,12 +129,13 @@ The `assetType` parameter accepts an array of asset types to filter by: 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 | +| Field | Type | Description | +| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `number` | Unique threat identifier | +| `content` | `string` | Threat content (URL, address, username, etc.) | +| `type` | `string` | Asset type (AssetType enum value) | +| `livenessStatus` | `string \| null` | Whether the threat is currently reachable (`ALIVE`), gone (`DEAD`), or has never been checked (`UNKNOWN`). `null` when liveness has never been evaluated. Use this to filter out dead threats without a follow-up call. | +| `blockedAt` | `string` | ISO 8601 timestamp of when asset was blocked | ### Complete Response Example @@ -145,18 +146,21 @@ Each item in the `threats` array has the following structure: "id": 12345, "content": "https://fake-site.com", "type": "URL", + "livenessStatus": "ALIVE", "blockedAt": "2024-01-15T10:30:00.000Z" }, { "id": 12346, "content": "eip155:1:0x1234567890123456789012345678901234567890", "type": "ADDRESS", + "livenessStatus": null, "blockedAt": "2024-01-15T09:15:00.000Z" }, { "id": 12347, "content": "twitter.com/fake_account", "type": "TWITTER", + "livenessStatus": "DEAD", "blockedAt": "2024-01-15T08:45:00.000Z" } ], @@ -255,6 +259,7 @@ interface ThreatResult { id: number; content: string; type: string; + livenessStatus: "UNKNOWN" | "ALIVE" | "DEAD" | null; blockedAt: string; } diff --git a/sdk/chainpatrol-client/instance-methods/asset-list.mdx b/sdk/chainpatrol-client/instance-methods/asset-list.mdx index 38045c2..7d34105 100644 --- a/sdk/chainpatrol-client/instance-methods/asset-list.mdx +++ b/sdk/chainpatrol-client/instance-methods/asset-list.mdx @@ -54,6 +54,10 @@ client.asset.list(request: AssetListInput): Promise Array of asset objects matching the filter criteria. + + Unique numeric identifier for the asset. Use it to reference the asset in follow-up calls such as `asset.search`. + + The type of the asset: `URL`, `PAGE`, or `ADDRESS`. @@ -68,6 +72,18 @@ client.asset.list(request: AssetListInput): Promise The threat status: `UNKNOWN`, `ALLOWED`, or `BLOCKED`. + + Whether ChainPatrol is actively monitoring the asset: `ENABLED` or `DISABLED`. + + + + Whether the asset is currently reachable (`ALIVE`), gone (`DEAD`), or has never been checked (`UNKNOWN`). `null` when liveness has never been evaluated. Use this to filter out dead assets without an extra request. + + + + ISO 8601 timestamp of when the asset transitioned to `BLOCKED`. `null` for non-blocked assets or for blocks that predate this field. Distinct from `updatedAt`, which changes on any mutation. + + ISO timestamp when the asset was last updated. @@ -145,15 +161,23 @@ result.assets.forEach(asset => { { "assets": [ { + "id": 90123, "type": "URL", "content": "phishing-site.com", "status": "BLOCKED", + "watchStatus": "ENABLED", + "livenessStatus": "ALIVE", + "blockedAt": "2023-06-15T10:30:00.000Z", "updatedAt": "2023-06-15T10:30:00.000Z" }, { + "id": 90124, "type": "URL", "content": "scam-airdrop.net", "status": "BLOCKED", + "watchStatus": "ENABLED", + "livenessStatus": "DEAD", + "blockedAt": "2023-06-14T15:45:00.000Z", "updatedAt": "2023-06-14T15:45:00.000Z" } ] From e609a11eb3f139ade21e42a8fd203a50ff6ca26a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:17:38 +0000 Subject: [PATCH 2/2] docs: expand asset.list SDK description for SEO --- sdk/chainpatrol-client/instance-methods/asset-list.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/chainpatrol-client/instance-methods/asset-list.mdx b/sdk/chainpatrol-client/instance-methods/asset-list.mdx index 7d34105..39d2236 100644 --- a/sdk/chainpatrol-client/instance-methods/asset-list.mdx +++ b/sdk/chainpatrol-client/instance-methods/asset-list.mdx @@ -1,6 +1,6 @@ --- title: "asset.list" -description: "Retrieve lists of assets with filtering options" +description: "Retrieve paginated lists of ChainPatrol assets filtered by type, status, and date range, including watch status, liveness, and blocked-at timestamps." --- The `asset.list` method allows you to retrieve bulk lists of assets that ChainPatrol has reviewed, with powerful filtering options by type, status, and date range. This method is ideal for bulk analysis and reporting.