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

# Researcher con IA

> Usa el motor de análisis con IA de Shimli para procesar archivos y generar insights.

**Researcher** es el motor de análisis con IA de Shimli. Sube archivos (PDFs, imágenes, audio, video, URLs) y obtén análisis estructurados, no solo resúmenes.

## Modelos disponibles

| Modelo      | Velocidad | Profundidad | Cuándo usar                                           |
| ----------- | --------- | ----------- | ----------------------------------------------------- |
| `fast`      | Rápido    | Básico      | Análisis rápido de documentos cortos                  |
| `balance`   | Medio     | Equilibrado | Caso general, la mejor relación velocidad/profundidad |
| `analytics` | Lento     | Profundo    | Análisis complejo de datos extensos                   |

## Tipos de archivo soportados

| `type`     | Extensiones               |
| ---------- | ------------------------- |
| `document` | PDF, DOCX, TXT, CSV, XLSX |
| `photo`    | JPG, PNG, WEBP            |
| `audio`    | MP3, WAV, M4A             |
| `video`    | MP4, MOV, WEBM            |
| `url`      | Cualquier URL pública     |

## Crear una investigación (draft)

```bash theme={null}
curl -X POST "https://api.shimli.app/v1/researcher?token=TOKEN_SHIMLI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Análisis de estados financieros Q2",
    "description": "Extraer KPIs principales y tendencias",
    "model": "balance",
    "type": "ID_POLITIC",
    "files": [
      {
        "url": "https://ejemplo.com/estados-q2.pdf",
        "name": "Estados_Financieros_Q2.pdf",
        "type": "document"
      }
    ]
  }'
```

## Ejecutar la investigación

Una vez creado el draft, ejecútalo:

```bash theme={null}
curl -X PUT "https://api.shimli.app/v1/researcher/ID_RESEARCHER?token=TOKEN_SHIMLI" \
  -H "Content-Type: application/json" \
  -d '{ "status": 1 }'
```

## Añadir archivos a una investigación existente

```bash theme={null}
curl -X PATCH "https://api.shimli.app/v1/researcher/ID_RESEARCHER?token=TOKEN_SHIMLI" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "url": "https://ejemplo.com/analisis-complementario.xlsx",
        "name": "Analisis_Complementario.xlsx",
        "type": "document"
      },
      {
        "url": "https://ejemplo.com/grafico.png",
        "name": "Grafico_Ventas.png",
        "type": "photo"
      }
    ]
  }'
```

## Consultar el estado y resultado

<Steps>
  <Step title="Lista tus investigaciones">
    ```bash theme={null}
    curl "https://api.shimli.app/v1/researcher?token=TOKEN_SHIMLI&page=1&limit=10"
    ```
  </Step>

  <Step title="Obtén el detalle de una investigación">
    ```bash theme={null}
    curl "https://api.shimli.app/v1/researcher/ID_RESEARCHER?token=TOKEN_SHIMLI&fields=name,status,description,type,model,files,process,updated,progress,output,output_format"
    ```
  </Step>
</Steps>

## Campos disponibles en la consulta

Puedes especificar qué campos quieres con el parámetro `fields`:

| Campo           | Descripción                                 |
| --------------- | ------------------------------------------- |
| `name`          | Nombre de la investigación                  |
| `status`        | Estado actual (draft, running, done, error) |
| `description`   | Descripción                                 |
| `type`          | ID de política                              |
| `model`         | Modelo usado (fast, balance, analytics)     |
| `files`         | Lista de archivos                           |
| `process`       | Proceso interno                             |
| `updated`       | Última actualización                        |
| `progress`      | Progreso (0-100)                            |
| `output`        | Resultado del análisis                      |
| `output_format` | Formato del resultado                       |

## Búsqueda

Puedes buscar investigaciones por nombre:

```bash theme={null}
curl "https://api.shimli.app/v1/researcher?token=TOKEN_SHIMLI&search=financieros"
```

<Callout type="info">
  El campo `output` contiene el análisis generado por la IA. El formato depende de la política usada (`type`), pero típicamente es texto estructurado o JSON.
</Callout>

## Referencia

* [List Researcher](/api-reference/researcher/list)
* [Get Researcher](/api-reference/researcher/get)
* [Create Draft](/api-reference/researcher/create-draft)
* [Run Researcher](/api-reference/researcher/run)
* [Add Files](/api-reference/researcher/add-files)