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

# Listar amenazas

> List threats for an organization using API key authentication

## Inicio rápido

### Autenticación

Incluye tu clave de API en el encabezado `X-API-KEY`:

```bash theme={null}
X-API-KEY: <api-key>
```

### Solicitud de ejemplo

```bash theme={null}
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": "phishing",
    "assetType": ["URL", "ADDRESS"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "per_page": 50,
    "sorting": [
      {
        "key": "blockedAt",
        "direction": "desc"
      }
    ]
  }'
```

## Esquema de la solicitud

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Valor predeterminado | Restricciones | Descripción |
| - | - | - | - | - | - |
| `query` | `string` | ❌ No | - | - | Consulta de búsqueda para filtrar amenazas por contenido |
| `startDate` | `string` | ❌ No | hace 1 día | Formato YYYY-MM-DD | Fecha de inicio para filtrar amenazas (inclusive) |
| `endDate` | `string` | ❌ No | hoy | Formato YYYY-MM-DD | Fecha de fin para filtrar amenazas (inclusive) |
| `assetType` | `AssetType[]` | ❌ No | - | - | Arreglo de tipos de **asset** (activo digital: URL, dirección, perfil, app, etc.) por los que filtrar |
| `sorting` | `SortingConfig[]` | ❌ No | `[{key: "id", direction: "asc"}]` | - | Arreglo de configuraciones de ordenamiento |
| `per_page` | `number` | ❌ No | `10` | Mín.: 1, Máx.: 100 | Cantidad de amenazas que se devuelven por página |
| `next_page` | `string` | ❌ No | - | Entero positivo | Cursor para obtener la siguiente página de resultados |
| `includePending` | `boolean` | ❌ No | `false` | - | Devuelve también los bloqueos pendientes (ver más abajo) |

> [!WARNING]
>
> Sin `startDate` ni `endDate`, este endpoint devuelve solo las amenazas bloqueadas en
> el **último día**. Ambas fechas filtran por `blockedAt`. Para listar todas las amenazas confirmadas,
> envía un `startDate` antiguo, como `"2020-01-01"`.

### Bloqueos pendientes

Si la protección no está activa para tu organización, ChainPatrol igual revisa lo que
encuentra, pero las amenazas confirmadas quedan en espera como **Pending Blocked** en lugar de
aplicarse en la **Blocklist** (lista de bloqueo). De forma predeterminada se excluyen, porque este endpoint alimenta
a los consumidores de la Blocklist. Establece `includePending: true` para incluirlas. Se devuelven con
`pendingStatus: "BLOCKED"`, y su `blockedAt` indica cuándo se confirmó el bloqueo.

### Configuración de ordenamiento

Cada objeto de ordenamiento debe tener la siguiente estructura:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `key` | `string` | ✅ Sí | Campo por el que se ordena (ver las opciones más abajo) |
| `direction` | `"asc"` \| `"desc"` | ✅ Sí | Dirección del ordenamiento |

#### Campos de ordenamiento disponibles

* `"id"` - Ordena por ID de la amenaza
* `"blockedAt"` - Ordena por el momento en que se bloqueó el asset
* `"content"` - Ordena por contenido de la amenaza
* `"type"` - Ordena por tipo de asset

### Filtro por tipo de asset

El parámetro `assetType` acepta un arreglo de tipos de asset por los que filtrar:

> [accordion] Valores de tipo de asset disponibles
>
> * `"URL"` - URL de sitios web
> * `"PAGE"` - Páginas web
> * `"ADDRESS"` - Direcciones de blockchain
> * `"LINKEDIN"` - Perfiles de LinkedIn
> * `"TWITTER"` - Perfiles/publicaciones de Twitter
> * `"FACEBOOK"` - Perfiles/páginas de Facebook
> * `"YOUTUBE"` - Canales/videos de YouTube
> * `"REDDIT"` - Publicaciones/subreddits de Reddit
> * `"TELEGRAM"` - Canales/grupos de Telegram
> * `"GOOGLE_APP_STORE"` - Apps de Google Play Store
> * `"APPLE_APP_STORE"` - Apps de Apple App Store
> * `"AMAZON_APP_STORE"` - Apps de Amazon App Store
> * `"MICROSOFT_APP_STORE"` - Apps de Microsoft Store
> * `"TIKTOK"` - Perfiles de TikTok
> * `"INSTAGRAM"` - Perfiles de Instagram
> * `"THREADS"` - Perfiles de Threads
> * `"MEDIUM"` - Artículos/perfiles de Medium
> * `"CHROME_WEB_STORE"` - Extensiones de Chrome
> * `"MOZILLA_ADDONS"` - Complementos de Firefox
> * `"OPERA_ADDONS"` - Complementos de Opera
> * `"EMAIL"` - Direcciones de correo electrónico
> * `"PATREON"` - Perfiles de Patreon
> * `"OPENSEA"` - Colecciones/perfiles de OpenSea
> * `"FARCASTER"` - Perfiles de Farcaster
> * `"IPFS"` - Hashes de IPFS
> * `"GOOGLE_FORM"` - Formularios de Google Forms
> * `"WHATSAPP"` - Contactos de WhatsApp
> * `"DISCORD_USER"` - Usuarios de Discord
> * `"QUORA"` - Perfiles/publicaciones de Quora
> * `"GITHUB"` - Repositorios/perfiles de GitHub
> * `"TEACHABLE"` - Cursos de Teachable
> * `"SUBSTACK"` - Publicaciones de Substack
> * `"DEBANK"` - Perfiles de DeBank
> * `"TAWK_TO"` - Widgets de chat de Tawk.to
> * `"JOTFORM"` - Formularios de JotForm
> * `"PRIMAL"` - Perfiles de Primal
> * `"BLUESKY"` - Perfiles de Bluesky
> * `"SNAPCHAT"` - Perfiles de Snapchat
> * `"DESO"` - Perfiles de DeSo
> * `"PINTEREST"` - Perfiles/pines de Pinterest

## Esquema de la respuesta

### Cuerpo de la respuesta

```typescript theme={null}
{
  threats: ThreatResult[];
  next_page: string | null;
}
```

### Objeto de resultado de amenaza

Cada elemento del arreglo `threats` tiene la siguiente estructura:

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | `number` | Identificador único de la amenaza |
| `content` | `string` | Contenido de la amenaza (URL, dirección, nombre de usuario, etc.) |
| `type` | `string` | Tipo de asset (valor del enum AssetType) |
| `blockedAt` | `string` | Marca de tiempo ISO 8601 del momento en que se bloqueó el asset |
| `pendingStatus` | `string \| null` | `"BLOCKED"` para un bloqueo pendiente (solo se devuelve con `includePending`); de lo contrario, `null` |

### Ejemplo de respuesta completa

```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"
}
```

## Control de acceso

La API aplica un control de acceso estricto según tu clave de API:

1. **Claves de API de organización**:

   * Solo pueden acceder a las amenazas de su organización asociada
   * Devuelven solo las amenazas que fueron bloqueadas por la organización
   * Ejemplo: una clave de API de "acme-org" solo puede consultar las amenazas bloqueadas por "acme-org"

2. **Claves de API de usuario**:
   * Pueden acceder a las amenazas de cualquier organización de la que el usuario sea miembro
   * Requieren que el usuario sea un miembro activo de la organización consultada

Si intentas acceder a las amenazas sin los permisos adecuados, recibirás un error 401 Unauthorized con el mensaje: "Valid API key required"

## Comportamiento predeterminado

* **Rango de fechas**: Si no se proporciona `startDate` ni `endDate`, la API devuelve de forma predeterminada las amenazas del último día. Si solo se envía `startDate`, `endDate` toma como valor predeterminado el momento actual; si solo se envía `endDate`, `startDate` toma como valor predeterminado un día antes de esa fecha
* **Bloqueos pendientes**: Se excluyen a menos que `includePending` sea `true`
* **Paginación**: Si no se proporciona `next_page`, devuelve la primera página de resultados
* **Ordenamiento**: De forma predeterminada ordena por `id` en orden ascendente
* **Tamaño de página**: De forma predeterminada son 10 resultados por página (máx. 100)

## Implementación de ejemplo

```javascript JavaScript theme={null}
async function fetchThreats(params) {
  const response = await fetch("https://app.chainpatrol.io/api/v2/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));
```

```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;
  includePending?: boolean;
}

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

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

async function fetchThreats(
  params: ThreatListParams
): Promise<ThreatListResponse> {
  const response = await fetch("https://app.chainpatrol.io/api/v2/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));
```


## 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
  - name: dark-web
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
                  description: Search query to filter threats by content
                startDate:
                  type: string
                  description: >-
                    The start date to list threats from. This should be in the
                    format `YYYY-MM-DD` and is inclusive.
                endDate:
                  type: string
                  description: >-
                    The end date to list threats to. This should be in the
                    format `YYYY-MM-DD` and is inclusive.
                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
                      - LUMA
                      - SMARTMONEYMATCH
                      - APK_GOLD
                      - GLASSDOOR
                      - PUMP_FUN
                      - TUMBLR
                      - MASTODON
                  description: Filter by asset types
                includePending:
                  type: boolean
                  default: false
                  description: >-
                    Also return threats confirmed malicious but not yet enforced
                    because protection is not active for your organization
                    (shown as "Pending Blocked" in the ChainPatrol app). These
                    carry `pendingStatus: BLOCKED`. Defaults to false, which
                    returns only assets on the blocklist.
                sorting:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Field to sort by
                      direction:
                        type: string
                        enum:
                          - asc
                          - desc
                        description: Sort direction
                    required:
                      - key
                      - direction
                  description: Sorting configuration
                per_page:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 10
                  description: The number of threats to return per page
                next_page:
                  type: string
                  nullable: true
                  description: Cursor for fetching the next page of results
              description: >-
                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](https://moment.github.io/luxon/#/parsing) 

                for parsing the dates.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  threats:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Threat ID
                        content:
                          type: string
                          description: Threat content
                        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
                            - LUMA
                            - SMARTMONEYMATCH
                            - APK_GOLD
                            - GLASSDOOR
                            - PUMP_FUN
                            - TUMBLR
                            - MASTODON
                          description: Asset type
                        livenessStatus:
                          type: string
                          nullable: true
                          enum:
                            - UNKNOWN
                            - ALIVE
                            - DEAD
                            - null
                          description: >-
                            Whether the blocked threat is currently reachable
                            (`ALIVE`), gone (`DEAD`), or unchecked (`UNKNOWN`).
                            Use to filter out dead threats without a second
                            call.
                        blockedAt:
                          type: string
                          description: When the asset was blocked
                        pendingStatus:
                          type: string
                          nullable: true
                          enum:
                            - UNKNOWN
                            - ALLOWED
                            - BLOCKED
                            - null
                          description: >-
                            A reviewed status that has not taken effect yet, or
                            null when nothing is pending. `BLOCKED` here means
                            the asset was confirmed malicious but is not
                            enforced on the blocklist because protection is not
                            active for your organization — shown as "Pending
                            Blocked" in the ChainPatrol app. It becomes `status`
                            once protection is activated.
                      required:
                        - id
                        - content
                        - type
                        - livenessStatus
                        - blockedAt
                        - pendingStatus
                  next_page:
                    type: string
                    nullable: true
                    description: Cursor for fetching the next page of results
                required:
                  - threats
                description: Successful operation
        '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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.