> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar al copiloto de una auditoría

> Responde en lenguaje natural preguntas sobre una auditoría (su mapa, modelo de amenazas, hallazgos, pistas,
invariantes, pruebas, ejecución y revisiones) y puede registrar solicitudes de trabajo. La respuesta es un
stream SSE (`text/event-stream`).

**Cuerpo del pedido (JSON).**
- `message` (obligatorio): la pregunta, de 1 a 4000 caracteres.
- `history`: turnos previos `{role: user|assistant, content}`; se usan los últimos 12.
- `context`: lo que el usuario tiene en pantalla, `{section, selection: {kind, id}}`. Se valida contra la
 auditoría: lo que no existe en ella se ignora.

**Eventos, en este orden.**
- `start` `{audit_id}`: comienzo de la respuesta.
- `token` `{text}`: texto del modelo.
- `tool` `{name, input}` y `tool_result` `{name, audit_id, ok, request?}`: cada herramienta que usó el copiloto.
 `request` aparece cuando registró una solicitud.
- `notice` `{audit_id, notice, detail}`: aviso del sistema. `model_fallback` (se usó el modelo por defecto),
 `truncated` (la respuesta se cortó por longitud) o `empty` (el modelo no devolvió texto).
- `error` `{audit_id, error, detail}`: falla durante la respuesta (`llm_error` o `audit_source_unavailable`).
- `done` `{audit_id}`: fin de la respuesta.

Ni `notice` ni `error` son texto del modelo.

**Qué puede afirmar.** Lo que dice el copiloto no es un hallazgo. Cita los hallazgos por id, con la severidad y
el grado de validación que ya tienen, y las pistas por id como «pista sin probar», sin severidad. Lo que observe
en el código y no sea un hallazgo lo plantea como pregunta. Está acotado a esta auditoría, con el mismo control
de acceso que `GET /v1/audit/{audit_id}/{section}`, y no tiene las herramientas de investigación de
`POST /v1/copilot`.

**Solicitudes.** `request_poc` (una prueba de concepto sobre una pista) y `request_review` (la revisión de una
función del mapa) solo registran una solicitud pendiente, que se consulta en
`GET /v1/audit/{audit_id}/requests`; no ejecutan nada. Se registran como máximo 3 solicitudes nuevas por
mensaje.

**Errores antes del stream.** Con cuerpo `{"error": …, "detail": …}`; en ninguno se consulta al modelo:
- `400 bad_id` o `400 audit_id_mismatch`, como en `GET /v1/audit/{audit_id}`.
- `403 ai_disabled`: la organización desactivó la IA. No se cobra.
- `403 read_only`: el rol es de solo lectura, y las solicitudes escriben.
- `404 not_found`: la auditoría no existe o es de otra organización.
- `422`: `message` vacío o de más de 4000 caracteres.
- `503 llm_not_configured`: el copiloto no está disponible en este momento. `503 audit_source_unavailable`: no
 se pudieron leer los datos de la auditoría.

**Costo:** 40 créditos de base. Algunas operaciones cobran menos si reutilizan un resultado guardado; nunca más.



## OpenAPI

````yaml /openapi.es.json post /v1/audit/{audit_id}/copilot
openapi: 3.1.0
info:
  title: API de blockgence
  description: >-
    La API de **blockgence** da acceso al rastreo de fondos, la atribución de
    entidades y el screening de riesgo

    explicable sobre varias redes, con la evidencia de cada resultado.


    ### Autenticación

    Todas las rutas `/v1/*` requieren una **clave de API**, en el header
    `X-API-Key: <clave>` o en

    `Authorization: Bearer <clave>`. La clave la entrega su organización. Las
    rutas de verificación de evidencia

    (`/v1/evidence/*`) no requieren clave.


    ### Créditos y límites

    Cada plan tiene un **límite de pedidos por minuto** y una **cantidad mensual
    de créditos**. Cada operación indica

    su costo en créditos. **Solo se cobran las respuestas correctas (status
    menor que 400):** una respuesta de error

    queda registrada con 0 créditos. El consumo se consulta en `GET
    /v1/account`.


    ### Datos que no se pudieron leer

    Si la fuente de datos no puede leer lo pedido, la respuesta es `503
    source_unavailable`, sin cobro, con la

    fuente, la red, la consulta, el motivo y si conviene reintentar. Si falla un
    paso intermedio, la respuesta es 200

    y lo declara en `degraded_sources` y en el `coverage_gaps` del nodo o la
    arista: en esos casos, la ausencia de

    datos no significa ausencia de movimientos.


    ### Redes

    `ethereum`, `bsc`, `polygon`, `arbitrum`, `base` y `optimism`; además `tron`
    para rastreo, ficha, fondeo, sondeo

    de redes y transacciones. Qué se puede consultar en cada red se indica en
    `GET /v1/chains`, sin costo. Las redes

    `monero`, `bitcoin`, `litecoin` y `solana` se reconocen en `/screening` y
    `/address`, donde la red se deduce del

    formato de la dirección. Cualquier otra red responde `400`: nunca se
    reemplaza por Ethereum.
  contact:
    name: blockgence
    url: https://www.blockgence.com/
  version: 1.0.0
servers:
  - url: https://app.blockgence.com
    description: Producción
security: []
tags:
  - name: Plataforma
    description: >-
      Qué redes hay, qué se puede consultar en cada una, con qué fuentes y con
      qué metodología. Sin costo.
  - name: Rastreo
    description: >-
      Rastreo del flujo de fondos y lecturas de una dirección o una transacción:
      grafo en los dos sentidos con consistencia temporal, fondeo, contrapartes,
      puentes, swaps, mezcladores, etiquetas y datos on-chain.
  - name: Screening
    description: >-
      Screening de riesgo de una dirección, con una recomendación (allow, review
      o block), sus razones y sus fuentes.
  - name: Contratos
    description: Inspección de contratos y simulación de una transacción antes de firmarla.
  - name: Tokens
    description: >-
      Ficha de un token, con su emisor, su suministro, sus tenedores y sus
      señales de riesgo.
  - name: Compromiso
    description: >-
      Vector de compromiso de una billetera robada, es decir, cómo se perdió el
      control de los fondos.
  - name: Incidentes
    description: >-
      Respuesta a incidentes de víctimas, hackeos y estafas: playbook, pedidos
      de congelamiento a emisores, post-mortem y entregables.
  - name: Copiloto
    description: >-
      Copiloto de investigación con IA, que responde en lenguaje natural y cita
      la evidencia (streaming SSE).
  - name: Casos
    description: >-
      Casos de investigación para guardar, compartir y exportar, con su
      evidencia, su actividad y sus anotaciones.
  - name: Permisos
    description: >-
      Aprobaciones, delegaciones y firmas que dan acceso a los fondos de una
      dirección (ERC-20, Permit2 y EIP-7702).
  - name: Guard
    description: >-
      Vigilancia de billeteras y protocolos, con alertas por webhook y por
      correo.
  - name: Travel Rule
    description: >-
      Travel Rule sin conexión con terceros: desafío de titularidad,
      contraparte, conciliación y validación de mensajes IVMS101.
  - name: Auditoría
    description: >-
      Auditoría de smart contracts, con el estado, los hallazgos y la evidencia
      de cada auditoría.
  - name: Evidencia
    description: >-
      Verificación de la evidencia sellada, con la clave pública de firma y los
      sellos de tiempo. No requiere clave de API ni cobra.
  - name: Monero
    description: >-
      Ficha pública de una transacción de Monero y verificación de una prueba de
      pago. Monero no publica remitentes ni montos, por lo que no se rastrea.
  - name: Cuenta
    description: Consumo y límites de su clave de API.
  - name: Íconos
    description: Logos de entidades para mostrar grafos en su propia interfaz. Sin costo.
  - name: Servicio
    description: Estado del servicio.
paths:
  /v1/audit/{audit_id}/copilot:
    post:
      tags:
        - Auditoría
      summary: Consultar al copiloto de una auditoría
      description: >-
        Responde en lenguaje natural preguntas sobre una auditoría (su mapa,
        modelo de amenazas, hallazgos, pistas,

        invariantes, pruebas, ejecución y revisiones) y puede registrar
        solicitudes de trabajo. La respuesta es un

        stream SSE (`text/event-stream`).


        **Cuerpo del pedido (JSON).**

        - `message` (obligatorio): la pregunta, de 1 a 4000 caracteres.

        - `history`: turnos previos `{role: user|assistant, content}`; se usan
        los últimos 12.

        - `context`: lo que el usuario tiene en pantalla, `{section, selection:
        {kind, id}}`. Se valida contra la
         auditoría: lo que no existe en ella se ignora.

        **Eventos, en este orden.**

        - `start` `{audit_id}`: comienzo de la respuesta.

        - `token` `{text}`: texto del modelo.

        - `tool` `{name, input}` y `tool_result` `{name, audit_id, ok,
        request?}`: cada herramienta que usó el copiloto.
         `request` aparece cuando registró una solicitud.
        - `notice` `{audit_id, notice, detail}`: aviso del sistema.
        `model_fallback` (se usó el modelo por defecto),
         `truncated` (la respuesta se cortó por longitud) o `empty` (el modelo no devolvió texto).
        - `error` `{audit_id, error, detail}`: falla durante la respuesta
        (`llm_error` o `audit_source_unavailable`).

        - `done` `{audit_id}`: fin de la respuesta.


        Ni `notice` ni `error` son texto del modelo.


        **Qué puede afirmar.** Lo que dice el copiloto no es un hallazgo. Cita
        los hallazgos por id, con la severidad y

        el grado de validación que ya tienen, y las pistas por id como «pista
        sin probar», sin severidad. Lo que observe

        en el código y no sea un hallazgo lo plantea como pregunta. Está acotado
        a esta auditoría, con el mismo control

        de acceso que `GET /v1/audit/{audit_id}/{section}`, y no tiene las
        herramientas de investigación de

        `POST /v1/copilot`.


        **Solicitudes.** `request_poc` (una prueba de concepto sobre una pista)
        y `request_review` (la revisión de una

        función del mapa) solo registran una solicitud pendiente, que se
        consulta en

        `GET /v1/audit/{audit_id}/requests`; no ejecutan nada. Se registran como
        máximo 3 solicitudes nuevas por

        mensaje.


        **Errores antes del stream.** Con cuerpo `{"error": …, "detail": …}`; en
        ninguno se consulta al modelo:

        - `400 bad_id` o `400 audit_id_mismatch`, como en `GET
        /v1/audit/{audit_id}`.

        - `403 ai_disabled`: la organización desactivó la IA. No se cobra.

        - `403 read_only`: el rol es de solo lectura, y las solicitudes
        escriben.

        - `404 not_found`: la auditoría no existe o es de otra organización.

        - `422`: `message` vacío o de más de 4000 caracteres.

        - `503 llm_not_configured`: el copiloto no está disponible en este
        momento. `503 audit_source_unavailable`: no
         se pudieron leer los datos de la auditoría.

        **Costo:** 40 créditos de base. Algunas operaciones cobran menos si
        reutilizan un resultado guardado; nunca más.
      operationId: copilot_v1_audit__audit_id__copilot_post
      parameters:
        - name: audit_id
          in: path
          required: true
          schema:
            type: string
            title: Audit Id
          description: >-
            Id de la auditoría: minúsculas, dígitos, `_` y `-`, de 1 a 64
            caracteres, como los que lista `GET /v1/audit`.
        - name: X-Audit-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Audit-Id
          description: >-
            Id de la auditoría que el cliente cree estar leyendo, opcional. Si
            no coincide con el `audit_id` de la ruta, la respuesta es `400
            audit_id_mismatch` y no se lee nada.
        - name: X-Case-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Case-Id
          description: >-
            Caso activo, opcional: el token de un caso que usted puede ver. La
            consulta queda registrada en ese caso y usa también sus etiquetas
            propias. Un caso que no existe, se borró o ya no está compartido con
            usted responde `400 case_unavailable` y la consulta no se hace, sin
            cobro.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditCopilotRequest'
      responses:
        '200':
          description: >-
            Stream SSE (`text/event-stream`) con los eventos `start`, `token`,
            `tool`, `tool_result`, `notice`, `error` y `done`.
          content:
            application/json:
              schema: {}
        '401':
          description: Falta la clave de API, o es inválida o revocada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Se agotaron los créditos del mes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            El pedido no tiene la forma esperada; `detail` indica qué campo
            corregir.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Se superó el límite de pedidos por minuto. Reintente después de los
            segundos que indica `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    AuditCopilotRequest:
      properties:
        message:
          type: string
          maxLength: 4000
          minLength: 1
          title: Message
          description: La pregunta del usuario.
        history:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 40
          title: History
          description: >-
            Turnos previos `{role: user|assistant, content}` de esta
            conversación (se usan los últimos 12).
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
          description: >-
            La pantalla: `{section, selection: {kind: finding|lead|proof, id}}`.
            Se valida contra la auditoría: lo que no existe en ella se ignora.
      type: object
      required:
        - message
      title: AuditCopilotRequest
    Error:
      type: object
      title: Error
      description: >-
        Forma común de los errores: un `detail` legible y, en muchos casos, un
        `error` con un código estable para reconocerlo sin interpretar el texto.
      properties:
        detail:
          type: string
          description: Qué ocurrió, en una frase.
        error:
          type: string
          description: Código estable del error, cuando lo tiene.
      required:
        - detail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Su clave de API en el header `X-API-Key`.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        La misma clave de API en `Authorization: Bearer <clave>`, como
        alternativa a `X-API-Key`.

````

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