> ## 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 de la organización

> List every asset your organization has reported, with the lifecycle state of each investigation: report opened, escalated, blocklisted, takedown submitted, takedown completed. Built for threat-intel platforms that poll for changes and upsert on asset ID. Supports pagination.

## Descripción general

Lista todos los **assets** (activos digitales: URL, direcciones, perfiles, apps, etc.) reportados para tu organización, ya sea por tu equipo o por ChainPatrol, junto con
el estado en que se encuentra cada uno: todavía en investigación, escalado a ti, bloqueado o
permitido, y qué tan avanzado va su **takedown** (solicitud de baja de contenido fraudulento).

Úsalo para mantener una plataforma de inteligencia de amenazas, un SIEM o un sistema de tickets sincronizado con
ChainPatrol. Recórrelo página por página una vez para hacer la carga inicial (backfill); después consulta periódicamente con `updatedSince` y
haz un upsert de cada fila usando `id`.

Para listar solo las amenazas confirmadas que se bloquearon en un rango de fechas, usa
[`/threats/list`](https://chainpatrol.com/docs/es/external-api/threats-list). Para listar las detecciones sin confirmar, usa
[`/detection/list`](https://chainpatrol.com/docs/es/external-api/detection-list).

## Inicio rápido

### Autenticación

Incluye tu clave de API en el encabezado `X-API-KEY`. Las claves de API de organización determinan la
organización a partir de la clave, así que `slug` es opcional para ellas.

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

### Solicitud de ejemplo

```bash theme={null}
curl --request GET \
  --url 'https://app.chainpatrol.io/api/v2/organization/threats?updatedSince=2026-11-01T00:00:00Z&per_page=500' \
  --header 'X-API-KEY: <api-key>'
```

## Parámetros de consulta

| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
| - | - | - | - | - |
| `slug` | `string` | ❌ No | - | Slug de la organización. Solo se necesita cuando tus credenciales tienen acceso a más de una organización. |
| `updatedSince` | `string` | ❌ No | - | Marca de tiempo ISO 8601. Solo las amenazas cuyo asset, reportes o takedown cambiaron en ese momento o después. Omítelo para la carga inicial (backfill). |
| `assetType` | `AssetType` | ❌ No | - | Solo las amenazas de este tipo de asset. |
| `per_page` | `number` | ❌ No | `100` | Amenazas por página, de 1 a 1000. |
| `next_page` | `string` | ❌ No | - | El valor de `next_page` de la respuesta anterior. |

## Estados del ciclo de vida

`state` resume los reportes de cada asset y la decisión que se tomó sobre él:

| `state` | Significado |
| - | - |
| `investigating` | Hay un reporte abierto y ChainPatrol lo está revisando. |
| `escalated` | Hay un reporte abierto y está a la espera de una decisión de tu organización. |
| `blocked` | El asset está en la **Blocklist** (lista de bloqueo). |
| `allowed` | El asset está en la **Allowlist** (lista de permitidos). |
| `closed` | Se revisaron todos los reportes y no se bloqueó nada. |

Una decisión sobre el asset prevalece sobre los reportes abiertos: una vez que está bloqueado o permitido,
`state` se queda ahí aunque alguien lo vuelva a reportar. Un asset que fue escalado,
decidido y luego reportado otra vez vuelve a `investigating`.

Las marcas de tiempo de cada amenaza:

* `firstReportedAt`: el primer reporte para tu organización.
* `escalatedAt`: la primera vez que el asset se escaló a tu organización, o
  `null` si nunca se escaló.
* `blockedAt`: cuándo se bloqueó el asset, o `null`.
* `takedown`: `null` hasta que se abre un takedown. `submittedAt` es la primera vez que
  se presentó ante un proveedor, y `completedAt` la primera vez que se completó. Si
  el sitio vuelve a aparecer, el takedown se reabre: `status` vuelve a `IN_PROGRESS` mientras que
  `completedAt` conserva la primera finalización. Vigila `status` para detectar reapariciones.
* `updatedAt`: el cambio más reciente en el asset, sus reportes o su takedown. Este es
  el valor contra el que se compara `updatedSince`.

## Consultar cambios periódicamente

1. **Carga inicial (backfill).** Llama sin `updatedSince` y sigue `next_page` hasta que sea
   `null`. Anota la hora en que empezaste.
2. **Consulta periódica (polling).** Envía `updatedSince` con un valor unos minutos anterior al inicio de tu última
   sincronización exitosa, y sigue `next_page` hasta que sea `null`, manteniendo el mismo
   `updatedSince` en cada página. Haz un upsert de cada amenaza usando `id`.
3. **Avanza.** Usa la hora de inicio de esta sincronización como marca de referencia (watermark) para la siguiente.

> [!WARNING]
>
> Superpón tus ventanas de tiempo por unos minutos. De lo contrario, un cambio escrito mientras se ejecuta una solicitud
> puede quedar entre dos consultas. La superposición vuelve a enviar algunas amenazas que
> ya tienes, algo que un upsert absorbe.

Las páginas se ordenan por el `id` del asset, de forma ascendente, y el cursor es el último `id` devuelto,
así que los assets reportados a mitad de la sincronización quedan en páginas posteriores en lugar de desplazar las anteriores. Una
página puede contener menos amenazas que `per_page` mientras `next_page` todavía tiene un valor; continúa
hasta que `next_page` sea `null`.

```javascript theme={null}
async function syncThreats(apiKey, updatedSince) {
  const threats = [];
  let nextPage = null;

  do {
    const params = new URLSearchParams({ per_page: "1000" });
    if (updatedSince) params.set("updatedSince", updatedSince);
    if (nextPage) params.set("next_page", nextPage);

    const response = await fetch(
      `https://app.chainpatrol.io/api/v2/organization/threats?${params}`,
      { headers: { "X-API-KEY": apiKey } },
    );
    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    const page = await response.json();
    threats.push(...page.threats);
    nextPage = page.next_page;
  } while (nextPage);

  return threats;
}
```


## OpenAPI

````yaml GET /organization/threats
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:
  /organization/threats:
    get:
      tags:
        - organization
      summary: List organization threats
      description: >-
        List every asset your organization has reported, with the lifecycle
        state of each investigation: report opened, escalated, blocklisted,
        takedown submitted, takedown completed. Built for threat-intel platforms
        that poll for changes and upsert on asset ID. Supports pagination.
      operationId: organizationThreatsList
      parameters:
        - in: query
          name: slug
          schema:
            type: string
        - in: query
          name: updatedSince
          schema:
            type: string
        - in: query
          name: assetType
          schema:
            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
        - in: query
          name: per_page
          description: The number of threats to return per page (max 1000)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            description: The number of threats to return per page (max 1000)
        - in: query
          name: next_page
          description: Cursor for fetching the next page of results
          schema:
            type: string
            nullable: true
            description: Cursor for fetching the next page of results
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  threats:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Asset ID
                        content:
                          type: string
                          description: Asset content (URL, handle, email, etc.)
                        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
                        status:
                          type: string
                          enum:
                            - UNKNOWN
                            - ALLOWED
                            - BLOCKED
                          description: Raw asset status
                        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.
                        state:
                          type: string
                          enum:
                            - investigating
                            - escalated
                            - blocked
                            - allowed
                            - closed
                          description: >-
                            Lifecycle stage: `investigating` (a report is open
                            and under review), `escalated` (an open report has
                            been passed to the organization for a decision),
                            `blocked` (confirmed malicious), `allowed`
                            (confirmed benign / false positive), `closed` (every
                            report reviewed, asset neither blocked nor allowed).
                            `escalated` reflects an escalation that is still
                            open, not one that was decided and followed by a new
                            report. A threat confirmed malicious while
                            protection is not active reports `closed` with
                            `pendingStatus` set to `BLOCKED` — check
                            `pendingStatus` before treating `closed` as benign.
                        livenessStatus:
                          type: string
                          enum:
                            - UNKNOWN
                            - ALIVE
                            - DEAD
                          description: >-
                            Whether the threat is currently reachable (`ALIVE`),
                            gone (`DEAD`), or unchecked (`UNKNOWN`)
                        brands:
                          type: array
                          items:
                            type: object
                            properties:
                              slug:
                                type: string
                                description: Brand slug
                              name:
                                type: string
                                description: Brand name
                            required:
                              - slug
                              - name
                          description: >-
                            The brands of yours this threat was reported
                            against. Empty when no report named one.
                        firstReportedAt:
                          type: string
                          description: >-
                            When this organization first filed a report against
                            the asset
                        escalatedAt:
                          type: string
                          nullable: true
                          description: >-
                            When the asset was *first* escalated to this
                            organization for a decision, or null if it never
                            was. This is escalation history, not current state:
                            an asset escalated once and later reported again
                            reports `escalated_at` alongside a `state` of
                            `investigating`. Read `state` to know whether
                            anything is waiting on you right now.
                        blockedAt:
                          type: string
                          nullable: true
                          description: >-
                            When the asset was blocklisted, or null if it has
                            not been. For a threat whose `pendingStatus` is
                            `BLOCKED`, this is when the block was confirmed; it
                            is not enforced until protection is activated.
                        takedown:
                          type: object
                          nullable: true
                          properties:
                            status:
                              type: string
                              enum:
                                - TODO
                                - IN_PROGRESS
                                - COMPLETED
                                - CANCELLED
                                - PENDING_RETRACTION
                                - RETRACTION_SENT
                                - RETRACTED
                                - PENDING_INPUT
                                - PENDING_EVIDENCE
                              description: Current takedown status
                            submittedAt:
                              type: string
                              nullable: true
                              description: >-
                                When the first takedown request was submitted to
                                a provider, or null if nothing has been
                                submitted yet
                            completedAt:
                              type: string
                              nullable: true
                              description: >-
                                When the takedown was marked completed, or null
                                if it has not been
                          required:
                            - status
                            - submittedAt
                            - completedAt
                          description: Takedown progress, or null if no takedown was opened
                        detailsUrl:
                          type: string
                          description: >-
                            Deep link to the asset's reports and takedowns in
                            the ChainPatrol app
                        updatedAt:
                          type: string
                          description: >-
                            The most recent change to anything in this record —
                            the asset, its reports, its takedown or that
                            takedown's tasks. Matches what `updatedSince`
                            filters on. To derive your next watermark, drain
                            every page until `next_page` is null and take the
                            highest value across the whole sweep: results are
                            ordered by asset ID, not by this field, so a later
                            page can carry an earlier timestamp and a per-page
                            watermark would skip it.
                      required:
                        - id
                        - content
                        - type
                        - status
                        - pendingStatus
                        - state
                        - livenessStatus
                        - brands
                        - firstReportedAt
                        - escalatedAt
                        - blockedAt
                        - takedown
                        - detailsUrl
                        - updatedAt
                  next_page:
                    type: string
                    nullable: true
                    description: >-
                      Cursor for fetching the next page of results, or null on
                      the last page. Drain it to null before advancing your
                      `updatedSince` watermark — see `updatedAt`.
                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'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '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.NOT_FOUND:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Not found
        code:
          type: string
          description: The error code
          example: NOT_FOUND
        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: Not found error (404)
      description: The error information
      example:
        code: NOT_FOUND
        message: Not found
        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.