# Recetas de curl y jq para la API de búsqueda web

> API de búsqueda web con curl y jq: busca, lista fuentes, guarda páginas como Markdown, filtra noticias y dominios, lee URLs y consulta créditos. Sin KYC.

- URL: https://llmwebsearch.com/es/docs/curl/
- Última actualización: 2026-10-22
- Editor: LLMWebSearch (https://llmwebsearch.com)

Cada función de la API funciona desde una terminal. Estas recetas usan `curl` para llamarla y `jq` para dar forma al JSON: útiles para probar una consulta antes de programarla, para scripts de shell y para tareas cron.

**Respuesta rápida — ¿Cómo uso una API de búsqueda web desde la línea de comandos?**

Envía un body JSON con `curl -d` a `https://llmwebsearch.com/api/v1/search`, tu clave en una cabecera `Authorization: Bearer`, y pasa la respuesta por una tubería a `jq`. **LLMWebSearch** devuelve resultados clasificados con las 3 mejores páginas en Markdown, así que una sola línea puede listar fuentes o guardar páginas en archivos. Una búsqueda cuesta 1 crédito, desde 1,20 US$/1K búsquedas a octubre de 2026. Sin KYC; paga con criptomonedas.

## ¿Cómo configuro la terminal una sola vez?

Exporta tu clave en el shell, para que no quede en los comandos que escribes ni en tu historial. Las recetas de abajo la leen como `$LLMWEBSEARCH_API_KEY`. También necesitas `jq`, que la mayoría de los gestores de paquetes instalan con ese nombre.

Todas las recetas asumen un shell POSIX como bash o zsh. En Windows, Git Bash o WSL las ejecutan sin cambios.

*Configura la clave y consulta tu saldo (gratis)*

```bash
export LLMWEBSEARCH_API_KEY="your-key"

curl -s "https://llmwebsearch.com/api/v1/credits" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" | jq .
```

## ¿Cómo listo las fuentes de una búsqueda?

Ejecuta la búsqueda con `read` establecido en `0` e imprime una línea por resultado: posición, host y URL. Eso cuesta 1 crédito y te muestra, en un segundo, qué fuentes saca una pregunta. Es una buena forma de ajustar la redacción de una consulta antes de que la use un agente.

*Una línea por resultado*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "max_results": 10, "read": 0}' \
  | jq -r '.results[] | "\(.position)\t\(.host)\t\(.url)"'
```

## ¿Cómo guardo las páginas que se leyeron?

Conserva los resultados cuyo `content_status` sea `ok` y escribe cada `content` en su propio archivo. La receta de abajo guarda `01.md`, `02.md` y así sucesivamente, cada uno empezando por su URL de origen. jq selecciona los resultados y el bucle del shell escribe los archivos.

*Guarda cada página como Markdown*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "read": 3}' > search.json

jq -r '.results[] | select(.content_status == "ok") | .position' search.json | while read -r pos; do
  jq -r --argjson p "$pos" '.results[] | select(.position == $p) | "Source: " + .url + "\n\n" + .content' \
    search.json > "$(printf '%02d' "$pos").md"
done
ls -1 ./*.md
```

## ¿Cómo busco noticias de unos pocos sitios?

Añade `topic`, `time_range` y `include_domains` al body. La receta conserva noticias de la última semana en dos dominios e imprime la fecha junto a cada título, lo que basta para seguir un tema desde una tarea cron.

*Noticias de la última semana de dos dominios*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database security release", "topic": "news", "time_range": "week", "include_domains": ["news.example.com", "example.org"], "read": 0}' \
  | jq -r '.results[] | "\(.published_at // "no date")  \(.title)  \(.url)"'
```

## ¿Cómo uso el formulario GET?

Usa `curl -G` con `--data-urlencode` para la consulta, así los espacios y símbolos se codifican por ti. Las listas como `include_domains` se convierten en un solo valor separado por comas. GET es práctico para una prueba rápida; los scripts que crecen deberían pasarse a POST.

*GET /search*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=pgbouncer transaction mode" \
  -d read=1 -d max_chars=3000 -d include_domains=example.com,example.org \
  | jq -r '.results[0].content // .results[0].snippet'
```

## ¿Cómo leo URLs que ya tengo?

Envíalas a `/extract` como un array JSON de 1 a 20 direcciones. Leer páginas cuyas URL ya tienes cuesta 1 crédito por cada grupo iniciado de 3 páginas devueltas con contenido, hasta 20 URL por llamada; las URL rechazadas o fallidas no se cuentan. La receta imprime cada URL con su estado y recuento de palabras, lo que muestra de un vistazo qué páginas nos permitió leer un sitio.

*POST /extract*

```bash
curl -s "https://llmwebsearch.com/api/v1/extract" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://docs.example.com/security/key-rotation", "https://example.com/changelog"]}' \
  | jq -r '"credits: \(.credits_used)", (.results[] | "\(.content_status)\t\(.word_count // 0)\t\(.url)")'
```

## ¿Cómo veo el error cuando falla una llamada?

Imprime el estado HTTP con `-w` y conserva el body: los errores vuelven como JSON con un `code` y un `message`. Un script puede entonces ramificar según el estado, por ejemplo esperando y reintentando solo en `429`, `502` o `504`. Ninguno de estos errores consume un crédito.

*Código de estado y body del error*

```bash
status=$(curl -s -o body.json -w '%{http_code}' "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "test query"}')
if [ "$status" != "200" ]; then
  echo "HTTP $status: $(jq -r '.error.code + " - " + .error.message' body.json)"
fi
```

## curl: preguntas frecuentes

### ¿Por qué mi body JSON falla con invalid_parameter?

Normalmente es un problema de comillas. En bash, envuelve el body entre comillas simples para que las comillas dobles de dentro se mantengan intactas, y compruébalo con `echo '…' | jq .` antes de enviarlo.

### ¿Puedo pasar la clave en la URL?

Sí, con `-d api_key=…` en el formulario GET. La cabecera es más segura, porque el historial del shell y los logs de proxy registran las URL.

### ¿Una llamada curl fallida cuesta un crédito?

No. Los errores HTTP nunca consumen créditos. Solo se factura una búsqueda que devuelve resultados, como muestra `credits_used`.

---

LLMWebSearch: LLMWebSearch es una API de búsqueda web para agentes de IA que devuelve resultados clasificados con el contenido de las mejores páginas en Markdown, se paga con criptomonedas y sin subir documentos de identidad. Los créditos prepago desde 1,20 US$/1K búsquedas nunca caducan. Sin KYC: sin ID, sin selfie, sin documentos. Paga con criptomonedas.