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

# Agregar assets a la organización

> Batch add multiple assets to your organization's allowlist. Each asset is automatically parsed and classified. Assets are normally approved as ALLOWED; an asset ChainPatrol currently has BLOCKED, and requests from integration organizations, go to manual review instead. Supports optional group assignment and an optional allowlist expiry, for the whole request or per asset.

## Descripción general

Agrega en lote varios assets (**Asset**: activo digital, como una URL, dirección, perfil, app, etc.) a la **Allowlist** (lista de permitidos) de tu organización. Cada asset se analiza automáticamente, se clasifica por tipo y se aprueba con el estado `ALLOWED`. Este endpoint permite agregar hasta 1,000 assets por solicitud, con metadatos opcionales como nombre, descripción y asignación a un grupo.

## Inicio rápido

### Autenticación

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

```bash theme={null}
X-API-KEY: your_api_key_here
```

### Solicitud de ejemplo

```typescript TypeScript theme={null}
const response = await fetch(
  "https://app.chainpatrol.io/api/v2/organization/assets",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY_HERE",
    },
    body: JSON.stringify({
      assets: [
        {
          content: "https://example.com",
          name: "Main Website",
          description: "Our official website",
          groupId: 1,
        },
        {
          content: "0x1234567890abcdef1234567890abcdef12345678",
          name: "Treasury Wallet",
        },
        {
          content: "@ourcompany",
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://app.chainpatrol.io/api/v2/organization/assets",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY_HERE",
    },
    body: JSON.stringify({
      assets: [
        {
          content: "https://example.com",
          name: "Main Website",
          description: "Our official website",
          groupId: 1,
        },
        {
          content: "0x1234567890abcdef1234567890abcdef12345678",
          name: "Treasury Wallet",
        },
        {
          content: "@ourcompany",
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

response = requests.post(
    "https://app.chainpatrol.io/api/v2/organization/assets",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY_HERE",
    },
    json={
        "assets": [
            {
                "content": "https://example.com",
                "name": "Main Website",
                "description": "Our official website",
                "groupId": 1,
            },
            {
                "content": "0x1234567890abcdef1234567890abcdef12345678",
                "name": "Treasury Wallet",
            },
            {
                "content": "@ourcompany",
            },
        ]
    },
)

data = response.json()
print(data)
```

```bash cURL theme={null}
curl -X POST 'https://app.chainpatrol.io/api/v2/organization/assets' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "assets": [
      {
        "content": "https://example.com",
        "name": "Main Website",
        "description": "Our official website",
        "groupId": 1
      },
      {
        "content": "0x1234567890abcdef1234567890abcdef12345678",
        "name": "Treasury Wallet"
      },
      {
        "content": "@ourcompany"
      }
    ]
  }'
```

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| assets | array | Sí | Arreglo de assets para agregar (máximo 1,000 por solicitud) |
| assets\[].content | string | Sí | Contenido del asset: URL, dirección de blockchain, handle (nombre de usuario) de redes sociales, correo electrónico, dominio, etc. |
| assets\[].name | string | No | Nombre visible del asset. Útil para identificar los assets en tu **Dashboard** (panel principal). |
| assets\[].description | string | No | Descripción que da contexto sobre el propósito o el uso del asset. |
| assets\[].groupId | number | No | ID del grupo al que se asignará el asset. Debe ser un grupo válido que pertenezca a tu organización. |
| assets\[].expiresAt | string | No | Vencimiento en la allowlist para este asset, como fecha y hora ISO 8601 en el futuro. Tiene prioridad sobre el `expiresAt` de la solicitud. |
| expiresAt | string | No | Vencimiento en la allowlist para todos los assets de la solicitud, como fecha y hora ISO 8601 en el futuro. Consulta [Definir un vencimiento al agregar](#definir-un-vencimiento-al-agregar). |

### Definir un vencimiento al agregar

A los assets que solo deben permanecer por un tiempo, como el sitio de un socio, se les puede asignar un [vencimiento en la allowlist](https://chainpatrol.com/docs/es/concepts/allowlist.md#vencimiento) en la misma solicitud. Define `expiresAt` en la solicitud para aplicar una misma fecha a todos los assets, o en un asset para darle su propia fecha. La fecha propia de un asset tiene prioridad sobre la de la solicitud.

```json theme={null}
{
  "expiresAt": "2027-04-30T23:59:59Z",
  "assets": [
    { "content": "https://partner-one.example" },
    { "content": "https://partner-two.example", "expiresAt": "2026-12-31T23:59:59Z" }
  ]
}
```

* El vencimiento solo se define en los assets que se agregaron. Los assets que no se pudieron agregar no reciben ninguno.
* Cada fecha debe estar en el futuro. Si alguna no lo está, la solicitud devuelve `400` y no se agrega nada.
* Para cambiar un vencimiento más adelante, usa [Definir vencimiento de assets de la organización](https://chainpatrol.com/docs/es/external-api/organization-assets-expiry.md).

### Tipos de asset admitidos

El endpoint detecta y clasifica automáticamente los siguientes tipos de asset:

* **URL** - URL completas con protocolo (p. ej., `https://example.com`)
* **ADDRESS** - Direcciones de blockchain (p. ej., direcciones de Ethereum o Bitcoin)
* **PAGE** - Identificadores de páginas web
* **DISCORD** - Identificadores de servidores o canales de Discord
* **TELEGRAM** - Identificadores de canales o grupos de Telegram
* **TWITTER** - Handles de Twitter/X (p. ej., `@username`)
* **INSTAGRAM** - Handles de Instagram
* **MEDIUM** - Identificadores de publicaciones o usuarios de Medium
* **GITHUB** - Identificadores de repositorios o usuarios de GitHub
* **YOUTUBE** - Identificadores de canales de YouTube
* **LINKEDIN** - Identificadores de perfiles de LinkedIn
* **TWITCH** - Identificadores de canales de Twitch
* **TIKTOK** - Identificadores de handles de TikTok
* **EMAIL** - Direcciones de correo electrónico

## Respuesta

### Respuesta exitosa

```json theme={null}
{
  "results": [
    {
      "content": "https://example.com",
      "success": true,
      "id": 12345
    },
    {
      "content": "0x1234567890abcdef1234567890abcdef12345678",
      "success": true,
      "id": 12346
    },
    {
      "content": "@ourcompany",
      "success": true,
      "id": 12347
    }
  ],
  "successCount": 3,
  "errorCount": 0
}
```

### Respuesta con éxito parcial

Cuando algunos assets se agregan correctamente y otros fallan:

```json theme={null}
{
  "results": [
    {
      "content": "https://example.com",
      "success": true,
      "id": 12345
    },
    {
      "content": "invalid-content",
      "success": false,
      "error": "Invalid asset format"
    },
    {
      "content": "https://existing.com",
      "success": false,
      "error": "Asset already exists in organization"
    }
  ],
  "successCount": 1,
  "errorCount": 2
}
```

### Campos de la respuesta

| Campo | Tipo | Descripción |
| - | - | - |
| results | array | Arreglo de objetos de resultado, uno por cada asset enviado |
| results\[].content | string | El contenido del asset que se envió |
| results\[].success | boolean | Indica si el asset se agregó correctamente |
| results\[].id | number | ID del asset (solo está presente cuando success es true) |
| results\[].error | string | Mensaje de error (solo está presente cuando success es false) |
| results\[].expiresAt | string \| null | El vencimiento en la allowlist guardado para el asset, o `null` cuando no se definió ninguno (solo está presente cuando success es true) |
| successCount | number | Cantidad total de assets agregados correctamente |
| errorCount | number | Cantidad total de assets que no se pudieron agregar |

## Respuestas de error

### 400 Bad Request

Se devuelve cuando la solicitud está mal formada o supera los límites:

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Maximum 1000 assets allowed per request"
  }
}
```

### 401 Unauthorized

Se devuelve cuando falta la clave de API, no es válida o no tiene acceso a la organización:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key with organization access required"
  }
}
```

### 404 Not Found

Se devuelve cuando un ID de grupo especificado no existe:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Group with ID 999 not found"
  }
}
```

## Mensajes de error comunes

| Mensaje de error | Causa | Solución |
| - | - | - |
| Invalid asset format | No se reconoce el formato del contenido del asset | Verifica que el formato del asset coincida con un tipo admitido |
| Asset already exists in organization | Asset duplicado en tu organización | El asset ya está en tu allowlist; no necesitas hacer nada |
| Maximum 1000 assets allowed per request | La solicitud contiene más de 1,000 assets | Divídela en varias solicitudes |
| Group with ID {id} not found | ID de grupo no válido | Usa un ID de grupo válido de tu organización |
| Content is required | Falta el campo `content` | Proporciona el campo `content` para cada asset |
| Invalid group ID | El formato del ID de grupo no es válido | Proporciona un ID de grupo numérico válido |

## Buenas prácticas

### Operaciones en lote

* **Maximiza el rendimiento**: usa el límite completo de 1,000 assets por solicitud cuando hagas importaciones masivas
* **Maneja los fallos parciales**: revisa siempre tanto `successCount` como `errorCount` en las respuestas
* **Reintenta los assets fallidos**: extrae de los resultados los assets que fallaron y reinténtalos con los datos corregidos

### Formato de los assets

* **URL**: incluye el protocolo (`https://` o `http://`)
  * ✅ `https://example.com`
  * ❌ `example.com` (se interpretará como dominio, no como URL)
* **Direcciones de blockchain**: usa el formato de dirección completo
  * ✅ `0x1234567890abcdef1234567890abcdef12345678`
* **Handles de redes sociales**: incluye el símbolo `@` para Twitter y otras plataformas sociales
  * ✅ `@username`
  * ✅ `username` (también funciona)

### Metadatos

* **Nombres**: usa nombres descriptivos para identificarlos más fácilmente en tu dashboard
* **Descripciones**: agrega contexto sobre el propósito del asset, sobre todo en el caso de direcciones y URL
* **Grupos**: organiza los assets por tipo, proyecto o propósito mediante grupos

### Manejo de errores

* Revisa el arreglo `results` para conocer el estado de éxito o fallo de cada asset
* Usa `successCount` y `errorCount` para los informes agregados
* Registra los assets fallidos con sus mensajes de error para depurar
* Implementa una lógica de reintento para los assets fallidos después de corregir los problemas

## Casos de uso

### Importar desde una hoja de cálculo

```typescript theme={null}
import * as fs from "fs";
import * as csv from "csv-parse/sync";

async function importFromCSV(filePath: string) {
  const fileContent = fs.readFileSync(filePath, "utf-8");
  const records = csv.parse(fileContent, {
    columns: true,
    skip_empty_lines: true,
  });

  // Process in batches of 1000
  for (let i = 0; i < records.length; i += 1000) {
    const batch = records.slice(i, i + 1000);
    const assets = batch.map((row) => ({
      content: row.content,
      name: row.name,
      description: row.description,
      groupId: row.groupId ? parseInt(row.groupId) : undefined,
    }));

    const response = await fetch(
      "https://app.chainpatrol.io/api/v2/organization/assets",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.API_KEY,
        },
        body: JSON.stringify({ assets }),
      }
    );

    const result = await response.json();
    console.log(
      `Batch ${i / 1000 + 1}: ${result.successCount} succeeded, ${
        result.errorCount
      } failed`
    );

    // Log failures
    result.results
      .filter((r) => !r.success)
      .forEach((r) => console.error(`Failed: ${r.content} - ${r.error}`));
  }
}
```

### Agregar varios tipos de asset

```typescript theme={null}
const assets = [
  // URLs
  {
    content: "https://our-website.com",
    name: "Main Website",
    groupId: 1,
  },
  {
    content: "https://docs.our-website.com",
    name: "Documentation",
    groupId: 1,
  },
  // Blockchain addresses
  {
    content: "0x1234567890abcdef1234567890abcdef12345678",
    name: "Treasury Wallet",
    groupId: 2,
  },
  {
    content: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    name: "Staking Contract",
    groupId: 2,
  },
  // Social media
  {
    content: "@ourcompany",
    name: "Official Twitter",
    groupId: 3,
  },
  {
    content: "ourcompany",
    name: "Discord Server",
    description: "Official Discord community",
    groupId: 3,
  },
];

const response = await fetch(
  "https://app.chainpatrol.io/api/v2/organization/assets",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "YOUR_API_KEY_HERE",
    },
    body: JSON.stringify({ assets }),
  }
);
```

## Notas

* Los assets se analizan y se clasifican por tipo automáticamente
* Todos los assets agregados correctamente reciben el estado `ALLOWED`
* Los assets duplicados (que ya están en tu organización) fallarán con el error correspondiente
* El endpoint devuelve un éxito parcial: algunos assets pueden agregarse correctamente mientras otros fallan
* La organización se determina automáticamente a partir de tu clave de API
* Los ID de grupo deben pertenecer a tu organización
* La validación de los assets ocurre durante el procesamiento; los formatos no válidos se informarán en los resultados


## OpenAPI

````yaml POST /organization/assets
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/assets:
    post:
      tags:
        - organization
      summary: Add assets to organization allowlist
      description: >-
        Batch add multiple assets to your organization's allowlist. Each asset
        is automatically parsed and classified. Assets are normally approved as
        ALLOWED; an asset ChainPatrol currently has BLOCKED, and requests from
        integration organizations, go to manual review instead. Supports
        optional group assignment and an optional allowlist expiry, for the
        whole request or per asset.
      operationId: organizationAssetsAdd
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assets:
                  type: array
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: Asset content (URL, address, handle, etc.)
                      name:
                        type: string
                        description: Optional display name for the asset
                      description:
                        type: string
                        description: Optional description for the asset
                      groupId:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                        description: Optional group ID to assign the asset to
                      expiresAt:
                        type: string
                        format: date-time
                        description: >-
                          Optional allowlist expiry for this asset, as an ISO
                          8601 date-time in the future. Overrides the request's
                          `expiresAt`.
                    required:
                      - content
                  minItems: 1
                  maxItems: 1000
                  description: Array of assets to add (max 1000 per request)
                expiresAt:
                  type: string
                  format: date-time
                  description: >-
                    Optional allowlist expiry for every asset in the request, as
                    an ISO 8601 date-time in the future (e.g.
                    `2027-04-30T23:59:59Z`). After it passes, the assets stay on
                    your organization for a 14-day grace period, then are
                    removed from it; their status does not change. An asset's
                    own `expiresAt` overrides this.
              required:
                - assets
              description: >-
                Add assets to organization allowlist


                Batch add multiple assets to your organization's allowlist. 

                Each asset will be automatically parsed and classified.

                Assets are normally auto-approved as ALLOWED. Two cases go to
                manual review

                instead: an asset ChainPatrol currently has BLOCKED, because
                allowlisting one

                is an unblock, and requests from integration organizations. The
                response still

                reports each asset as added; the status change follows once a
                reviewer

                approves it.

                Pass `expiresAt` to give the assets an allowlist expiry, for
                example for a partner's site.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        content:
                          type: string
                          description: Asset content
                        success:
                          type: boolean
                          description: Whether the asset was added successfully
                        id:
                          type: number
                          description: Asset ID if successful
                        error:
                          type: string
                          description: Error message if failed
                        expiresAt:
                          type: string
                          nullable: true
                          description: >-
                            The allowlist expiry saved for the asset, or `null`
                            when none was set. Present only for added assets.
                      required:
                        - content
                        - success
                    description: Results for each asset
                  successCount:
                    type: number
                    description: Number of assets successfully added
                  errorCount:
                    type: number
                    description: Number of assets that failed to add
                required:
                  - results
                  - successCount
                  - errorCount
                description: Batch add operation results
        '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.