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

# Crear reporte

> Create a new report on ChainPatrol for a particular organization

## Descripción general

El endpoint Crear reporte te permite enviar **Assets** (activos digitales: URL, dominios, direcciones de blockchain, etc.) para que el equipo de ChainPatrol los revise. Este endpoint admite envíos masivos y ofrece información detallada de los errores cuando falla la validación.

¿Es tu primera vez con este endpoint? Empieza por [Cómo crear reportes](https://chainpatrol.com/docs/es/external-api/creating-reports.md): una
guía paso a paso de todo el flujo, con ejemplos prácticos.

> [!NOTE]
>
> Este endpoint necesita una clave de API con permiso **Read & write** (lectura y escritura). Una
> clave de solo lectura recibe `403 Forbidden`. Consulta [Permisos de la clave](https://chainpatrol.com/docs/es/external-api/authentication.md#permisos-de-la-clave).

## Adjuntos

`attachmentUrls` acepta URL de cualquier archivo de evidencia, no solo imágenes: los mensajes
`.eml` y `.msg`, los PDF, los documentos y las capturas de pantalla funcionan. Las imágenes se
muestran integradas en el reporte; los demás archivos se listan como evidencia descargable que
nuestro equipo de **Takedowns** (solicitudes de baja de contenido fraudulento) puede reenviar a
un registrador o proveedor de hosting.

Para enviarnos el archivo en sí en lugar de un enlace que tú alojas, súbelo primero con
[Subir archivo adjunto](https://chainpatrol.com/docs/es/external-api/attachment-upload.md) y pasa la URL que devuelve:

```bash theme={null}
# 1. upload the file, get a URL back
curl -X POST 'https://app.chainpatrol.io/api/v2/attachment/upload?fileName=evidence.eml' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  --data-binary '@evidence.eml'

# 2. reference that URL here, in attachmentUrls
```

Los adjuntos pertenecen al reporte en su conjunto y no a un asset individual.

## Respuestas de error

### 422 Unprocessable Content

Se devuelve cuando la solicitud es sintácticamente válida pero contiene errores de validación o assets duplicados. Es el tipo de error más común y ofrece información detallada de errores por asset.

| Tipo de error | Descripción | Solución |
| - | - | - |
| `DUPLICATE_ASSETS` | El mismo asset aparece varias veces en el reporte | Quita los assets duplicados del envío |
| `INVALID_FORMAT` | El formato del asset no es válido | Usa URL, dominios o direcciones de blockchain válidos |
| `ASSET_NOT_FOUND` | No se pudo ubicar ni crear el asset | Verifica el formato del asset y que sea accesible |
| `ASSET_ALREADY_CORRECT` | El asset ya tiene el estado solicitado | No hace falta ninguna acción: el asset ya está en el estado deseado |
| `ALREADY_PENDING_REVIEW` | El asset tiene una **Proposal** (propuesta para bloquear o permitir un asset) pendiente para el estado solicitado | Espera a que se procese la Proposal existente |
| `REPORT_ALREADY_EXISTS` | Ya existe un reporte o una Proposal pendiente para este asset | Revisa los reportes existentes o espera a que se procese |
| `PROCESSING_FAILED` | Ocurrió un error técnico durante el procesamiento del asset | Reintenta la solicitud o contacta a soporte |
| `DOMAIN_NOT_ALLOWED` | El dominio del asset está en la lista de ignorados | El dominio está excluido de los reportes según la política de contenido |
| `VALIDATION_ERROR` | Error de validación genérico | Revisa el formato y los requisitos del asset |

#### Ejemplo: assets duplicados

```json theme={null}
{
  "message": "Report creation failed: Duplicate assets found. 2 asset(s) appear multiple times in the same report.",
  "code": "UNPROCESSABLE_CONTENT",
  "data": {
    "errors": [
      {
        "asset": "scam.example",
        "errorType": "DUPLICATE_ASSETS",
        "message": "This asset appears multiple times in the same report",
        "suggestion": "Remove duplicate assets from your submission - each asset should only appear once per report"
      }
    ]
  }
}
```

#### Ejemplo: varios errores de validación

```json theme={null}
{
  "message": "Report creation failed: 2 of 3 assets are invalid. All assets must be valid to create a report.",
  "code": "UNPROCESSABLE_CONTENT",
  "data": {
    "errors": [
      {
        "asset": "http",
        "errorType": "INVALID_FORMAT",
        "message": "This asset couldn't be processed due to invalid format",
        "suggestion": "Use valid URLs (https://example.com), domains (example.com), or blockchain addresses (eip155:1:0x123...)"
      },
      {
        "asset": "decen-masters.com",
        "errorType": "DOMAIN_NOT_ALLOWED",
        "message": "This domain cannot be reported as it's on the ignore list",
        "suggestion": "This domain is currently excluded from reports based on our content policy. Please reach out to us if you believe this is an error"
      }
    ]
  }
}
```

### 500 Internal Server Error

Se devuelve ante condiciones inesperadas del servidor, incluidos errores de base de datos y otras fallas técnicas. La respuesta usa mensajes seguros y genéricos para no exponer detalles internos del sistema.

#### Respuesta de error estándar

```json theme={null}
{
  "message": "Unable to process your report. Please try again or contact support if the issue persists.",
  "code": "INTERNAL_SERVER_ERROR"
}
```

#### Respuesta de error de base de datos

```json theme={null}
{
  "message": "A database error occurred. This has been reported internally - please contact support@chainpatrol.io for assistance.",
  "code": "INTERNAL_SERVER_ERROR"
}
```

## Buenas prácticas

### Validación de assets

**URL**: Incluye el protocolo completo (`https://` o `http://`)

**Dominios**: Usa nombres de dominio limpios, sin protocolos ni rutas

**Direcciones de blockchain**: Usa el formato EIP-155 para las direcciones de Ethereum

**Evita duplicados**: Cada asset debe aparecer una sola vez por reporte

### Manejo de errores

Revisa siempre el arreglo `data.errors` en las respuestas 422 para ver los detalles por asset

Usa el campo `suggestion` de las respuestas de error para orientar a los usuarios

Implementa una lógica de reintentos con backoff exponencial para los errores 500

### Consejos de rendimiento

Agrupa varios assets en una sola solicitud cuando sea posible

Valida los formatos de los assets del lado del cliente antes de enviarlos

Maneja el límite de solicitudes de forma adecuada

## Solución de problemas

### Problemas comunes

**Errores "INVALID\_FORMAT":**

Asegúrate de que las URL incluyan el protocolo (`https://` o `http://`)

Verifica que los nombres de dominio no incluyan protocolos ni rutas

Comprueba que el formato de la dirección de blockchain coincida con el estándar EIP-155

**Errores "DUPLICATE\_ASSETS":**

Quita las entradas duplicadas del arreglo de assets

Revisa si hay diferencias de mayúsculas y minúsculas

Verifica la normalización de las URL (barras finales, etc.)

**Errores "DOMAIN\_NOT\_ALLOWED":**

El dominio está en la lista de ignorados de ChainPatrol

Escribe a [disputes@chainpatrol.io](mailto:disputes@chainpatrol.io) para disputar esta decisión

Considera reportar URL específicas en lugar del dominio completo

**Errores "ASSET\_ALREADY\_CORRECT":**

El asset ya tiene el estado que estás solicitando

Revisa el estado actual del asset antes de reportarlo

No hace falta ninguna acción: el asset ya está en el estado deseado

### Límite de solicitudes

El endpoint aplica un límite de solicitudes para prevenir abusos. Si recibes errores de límite de solicitudes:

Implementa backoff exponencial en tu lógica de reintentos

Considera agrupar solicitudes para reducir las llamadas a la API

Contacta a soporte si necesitas límites de solicitudes más altos

## Notas

La forma del payload de error es estable en todos los errores 422; revisa `data.errors` para ver los detalles por asset

Proporciona el `organizationSlug` y `assets` válidos para minimizar los errores 500 causados por un estado inválido

Todos los assets deben ser válidos para que se cree el reporte

Solo se puede crear un reporte una vez por dirección de correo electrónico para un asset específico

Si tienes problemas técnicos o preguntas sobre las respuestas de error, escribe a [support@chainpatrol.io](mailto:support@chainpatrol.io) e incluye la respuesta de error completa en tu solicitud.


## OpenAPI

````yaml POST /report/create
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:
  /report/create:
    post:
      tags:
        - report
      summary: Create a report
      description: Create a new report on ChainPatrol for a particular organization
      operationId: reportCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationSlug:
                  type: string
                  description: >-
                    Organization slug used to identify the organization on
                    ChainPatrol
                discordGuildId:
                  type: string
                  description: >-
                    Discord Guild (Server) ID linked to the organization on
                    ChainPatrol
                telegramGroupId:
                  type: string
                  description: Telegram Group ID linked to the organization on ChainPatrol
                title:
                  type: string
                  minLength: 3
                  description: Title of the report
                description:
                  type: string
                  description: Description of the report. Supports markdown
                contactInfo:
                  type: string
                  description: >-
                    Optional reporter contact info. If this value is a phone
                    number, include a country code in E.164 format (e.g.
                    +14155552671).
                attachmentUrls:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: >-
                    URLs of files to attach to the report as evidence. Any file
                    type, not only images: .eml/.msg messages, PDFs, and
                    documents are all supported. Upload a file to POST
                    /attachment/upload to get a URL, or pass a publicly
                    reachable URL you host yourself.
                externalSubmissionLink:
                  type: string
                  format: uri
                  description: Link to the external submission (e.g. Telegram message link)
                userAgent:
                  type: string
                  description: User agent string from the reporter's browser
                referrer:
                  type: string
                  description: Referrer URL from the reporter's browser
                assets:
                  type: array
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: >-
                          Asset content. If providing a phone number, include a
                          country code in E.164 format (e.g. +14155552671).
                      status:
                        type: string
                        enum:
                          - UNKNOWN
                          - ALLOWED
                          - BLOCKED
                        default: BLOCKED
                        description: >-
                          Proposed asset status (defaults to BLOCKED if not
                          provided)
                      reporterConfidence:
                        type: string
                        enum:
                          - HIGH
                          - LOW
                        description: >-
                          Reporter confidence level (applies special handling
                          for trusted reporters and superusers only)
                      brandSlug:
                        type: string
                        minLength: 1
                        description: >-
                          Optional suggested brand slug for this proposed
                          blocked asset
                      enrichments:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                                - content_and_metadata
                                - browser_capture
                                - ownership_and_registration
                                - geolocation_and_ip
                                - dns
                                - tls
                                - tcp
                                - hostname_first_seen
                                - certificate_transparency
                                - post
                                - profile
                                - twitter_followers
                                - cast
                                - farcaster_profile
                                - channel
                                - miniapp
                                - telegram_profile
                                - instagram_profile
                                - facebook_profile
                                - youtube_video
                                - youtube_channel
                                - apple_app_store_listing
                                - google_play_store_listing
                                - mozilla_addon
                                - github_comment
                                - github_repository
                                - github_profile
                                - reddit_subreddit
                                - email_validation
                                - phone_lookup
                                - bilibili_video
                                - bilibili_profile
                                - dailymotion_video
                                - vimeo_video
                                - vimeo_profile
                                - stackblitz_page
                                - leetcode_page
                                - tumblr_blog
                                - tumblr_post
                                - tumblr_community
                                - npm_package
                                - pypi_package
                                - rust_package
                                - linkedin_profile
                                - pump_fun_token
                                - meta_ad
                                - google_ad
                                - adlibrary_ad
                                - contract_deployer
                                - threat_intel
                                - list_membership
                                - threat_score
                              description: Enrichment type
                            source:
                              type: string
                              minLength: 1
                              description: Enrichment source (e.g., extension)
                            output:
                              type: object
                              additionalProperties: {}
                              description: Enrichment output data
                          required:
                            - type
                            - source
                        description: Enrichments to attach to this asset
                    required:
                      - content
                rawAssetsInput:
                  type: string
                externalReporter:
                  type: object
                  properties:
                    avatarUrl:
                      type: string
                      format: uri
                      description: URL of the external avatar
                    platformIdentifier:
                      type: string
                      description: Unique identifier on the external platform
                    platform:
                      type: string
                      description: External platform's name
                    displayName:
                      type: string
                      description: User's public (mutable) display name
                  required:
                    - platformIdentifier
                    - platform
                    - displayName
              required:
                - assets
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                    description: ID of the created report
                  createdAt:
                    type: string
                    description: Date the report was created
                  organization:
                    type: object
                    nullable: true
                    properties:
                      id:
                        type: number
                        description: ID of the organization
                      slug:
                        type: string
                        description: Slug of the organization
                      name:
                        type: string
                        description: Name of the organization
                    required:
                      - id
                      - slug
                      - name
                    description: Organization the report was created for
                required:
                  - id
                  - createdAt
                  - organization
        '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.