# Search API

API de búsqueda web para apps y agentes: search, extract, crawl, map y pedidos en paralelo, cobrados del saldo de la empresa.

Fuente: https://ardumaker.com/docs/search-api/

- Categoría: Inteligencia artificial y agentes
- Estado: Disponible
- Requisitos: Un token de Search API de la empresa (lo crea un admin); Medio de pago activo y al menos 20 EUR de saldo para crear el token; La empresa al día con los pagos para usarlo
- Herramientas MCP (Solo leen): `listar_tokens_search_api`, `ver_token_search_api`, `ver_costos_operaciones_search_api`
- Herramientas MCP (Escriben o modifican): `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api`

## ¿Qué permite hacer?

- **search**: buscar en la web y recibir resultados con título, URL, contenido y puntaje, opcionalmente con una respuesta resumida.
- **extract**: traer el contenido de una o varias URL en Markdown o texto.
- **crawl**: recorrer un sitio desde una URL, con profundidad y amplitud configurables, y extraer su contenido.
- **map**: listar las URL de un sitio sin extraer contenido.
- **multiple**: correr hasta 10 de los anteriores en paralelo y recibir las respuestas en el mismo orden.

## ¿Cuándo conviene usarlo?

- Darle a un agente de IA acceso a información actual de la web.
- Alimentar una base de conocimiento con el contenido de un sitio.
- Pagar la búsqueda desde el saldo de la empresa sin contratar otro proveedor.

## ¿Cómo funciona en ArduMaker?

1. La aplicación hace `POST` a `https://api.ardumaker.com/api/v1/searchapi/<operación>/` con el token en el header `Authorization` (el valor del token, sin prefijo).
2. ArduMaker valida el token: tiene que existir, estar activo y la empresa no tiene que estar suspendida por pagos pendientes.
3. Se reenvía el pedido a un proveedor de búsqueda externo con los parámetros recibidos y se devuelve su respuesta.
4. Se suma el costo de la operación al token (con la comisión de la empresa). Cuando lo acumulado sin registrar llega a 1 EUR, se descuenta del saldo de la empresa.

```bash
curl -X POST https://api.ardumaker.com/api/v1/searchapi/search/ \
  -H "Authorization: $SEARCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "novedades de energía solar", "max_results": 5, "include_answer": true}'
```

### Cómo se calcula el costo

| Operación | Unidad de cobro |
| --- | --- |
| search | Por pedido; `search_depth: advanced` cuesta más |
| extract | Por URL; `extract_depth: advanced` cuesta más |
| crawl | Por cada 5 páginas del `limit` pedido (50 por defecto); `advanced` cuesta más |
| map | Por cada 10 páginas del `limit` pedido; con `instructions`, el doble |

Los precios vigentes se consultan sin autenticación en `GET /api/v1/searchapi/pricing/` y pueden cambiar. Un pedido que llega al proveedor se cobra aunque el proveedor responda con error; uno rechazado antes (sin `query` o sin `url`) no.

## ¿Qué cambia realmente?

- En el token: contadores de pedidos y costo, totales y de las ventanas de 24 horas, 7 días y 30 días.
- En el historial de la empresa: un consumo cada vez que lo acumulado llega a 1 EUR, y lo pendiente al revocar el token.
- Si la empresa queda pendiente de verificación de identidad, sus tokens se pausan hasta que se verifique.

## Parámetros principales

| Operación | Campo obligatorio | Algunos opcionales |
| --- | --- | --- |
| `search` | `query` | `search_depth`, `max_results`, `topic`, `time_range`, `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains` |
| `extract` | `urls` | `query`, `extract_depth`, `format`, `include_images` |
| `crawl` | `url` | `instructions`, `max_depth`, `max_breadth`, `limit`, `select_paths`, `exclude_paths`, `allow_external` |
| `map` | `url` | `instructions`, `max_depth`, `max_breadth`, `limit`, `allow_external` |
| `multiple` | `requests` | Cada elemento lleva `type` y los campos de su operación |

Los parámetros opcionales se reenvían tal cual al proveedor.

## Esquema

**Un pedido de búsqueda**

```text
Tu app o agente (token en Authorization)
  ↓
Search API (valida token y estado de pagos)
  ↓
Proveedor de búsqueda (search, extract, crawl o map)
  ↓
Costo (se suma al token; se registra cada 1 EUR)
```

## Resultado esperado

- La respuesta es la del proveedor: `results`, y según la operación `answer`, `failed_results`, `base_url` y `response_time`.
- `multiple` devuelve una respuesta por pedido, en el mismo orden; los que fallan van con su error.
- `ver_costos_operaciones_search_api` muestra el gasto de todos los tokens activos (total y de 24 horas, 7 y 30 días) y los precios por operación.

## Errores y resolución

| Respuesta | Causa | Qué hacer |
| --- | --- | --- |
| 403 `authorization_token_required` | Falta el header `Authorization` | Mandar el token |
| 403 `invalid_or_inactive_token` | Token inexistente, revocado o pausado | Revisar el token o reactivarlo |
| 402 `service_suspended_due_to_pending_payment` | La empresa tiene pagos pendientes | Regularizar el saldo |
| 400 `query is required` / `url is required` / `urls is required` | Falta el campo obligatorio (no se cobra) | Completar el pedido |
| 400 más de 10 pedidos | `multiple` acepta hasta 10 | Partir en varias llamadas |
| 424 `no_tavily_api_keys` | El proveedor no está disponible en este momento | Reintentar más tarde |
| `proveedor_de_busqueda_fallo` | El proveedor falló al responder | Reintentar; se cobra igual |

## Relación con MCP

La búsqueda en sí se usa por HTTP con el token, no por MCP. Por MCP (perfiles `/mcp` e `/mcp/infra`) se administran los tokens:

- Lectura: `listar_tokens_search_api`, `ver_token_search_api`, `ver_costos_operaciones_search_api` (nunca devuelven el token).
- Escritura, solo admin: `crear_token_search_api` (devuelve el token una sola vez; acepta `idempotency_key`), `reactivar_token_search_api`.
- Destructiva y reversible, solo admin: `revocar_token_search_api` (registra el costo pendiente).

Referencia en [/mcp/docs](https://ardumaker.com/mcp/docs) y ejemplos en [/mcp/ia](https://ardumaker.com/mcp/ia).

## Funciones relacionadas

- [Router IA](https://ardumaker.com/docs/router-ia/)
- [Claves de IA](https://ardumaker.com/docs/claves-ia/)
- [Saldo por empresa](https://ardumaker.com/docs/saldo-por-empresa/)
- [Consumo de servicios](https://ardumaker.com/docs/consumo-de-servicios/)