# curl and jq recipes for the web search API

> Web search API with curl and jq: search, list sources, save pages as Markdown, filter news and domains, read known URLs, check credits. No KYC, crypto.

- URL: https://llmwebsearch.com/docs/curl/
- Last updated: 2026-10-22
- Publisher: LLMWebSearch (https://llmwebsearch.com)

Every feature of the API works from a terminal. These recipes use `curl` to call it and `jq` to shape the JSON: useful for testing a query before coding it, for shell scripts and for cron jobs.

**Quick answer — How do I use a web search API from the command line?**

Send a JSON body with `curl -d` to `https://llmwebsearch.com/api/v1/search`, your key in an `Authorization: Bearer` header, and pipe the answer to `jq`. **LLMWebSearch** returns ranked results with the top 3 pages as Markdown, so one line can list sources or save pages to files. A search costs 1 credit, from $1.20/1K searches as of October 2026. No KYC; pay in crypto.

## How do I set up the terminal once?

Export your key in the shell, so it stays out of the commands you type and out of your history. The recipes below read it as `$LLMWEBSEARCH_API_KEY`. You also need `jq`, which most package managers install under that name.

All recipes assume a POSIX shell such as bash or zsh. On Windows, Git Bash or WSL run them unchanged.

*Set the key and check your balance (free)*

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

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

## How do I list the sources of a search?

Run the search with `read` set to `0` and print one line per result: position, host and URL. That costs 1 credit and shows you, in a second, which sources a question brings up. It is a good way to tune the wording of a query before an agent uses it.

*One line per result*

```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)"'
```

## How do I save the pages that were read?

Keep the results whose `content_status` is `ok` and write each `content` to its own file. The recipe below saves `01.md`, `02.md` and so on, each starting with its source URL. jq selects the results and the shell loop writes the files.

*Save each page as 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
```

## How do I search news from a few sites?

Add `topic`, `time_range` and `include_domains` to the body. The recipe keeps news from the past week on two domains and prints the date next to each title, which is enough to watch a subject from a cron job.

*News of the past week from two domains*

```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)"'
```

## How do I use the GET form?

Use `curl -G` with `--data-urlencode` for the query, so spaces and symbols are encoded for you. Lists such as `include_domains` become one comma-separated value. GET is handy for a quick test; scripts that grow should move to 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'
```

## How do I read URLs I already have?

Post them to `/extract` as a JSON array of 1 to 20 addresses. Reading pages whose URLs you already have costs 1 credit for each started group of 3 pages returned with content, up to 20 URLs per call; refused or failed URLs are not counted. The recipe prints each URL with its status and word count, which shows at a glance which pages a site allowed us to read.

*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)")'
```

## How do I see the error when a call fails?

Print the HTTP status with `-w` and keep the body: errors come back as JSON with a `code` and a `message`. A script can then branch on the status, for example waiting and retrying on `429`, `502` or `504` only. None of these errors uses a credit.

*Status code and error body*

```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: common questions

### Why does my JSON body fail with invalid_parameter?

Usually a quoting problem. Wrap the body in single quotes in bash so the double quotes inside stay intact, and check it with `echo '…' | jq .` before sending.

### Can I pass the key in the URL?

Yes, with `-d api_key=…` on the GET form. The header is safer, because shell history and proxy logs record URLs.

### Does a failed curl call cost a credit?

No. HTTP errors never use credits. Only a search that returns results is billed, as `credits_used` shows.

---

LLMWebSearch: LLMWebSearch is a web search API for AI agents that returns ranked results with the content of the top pages in Markdown, paid in crypto with no ID upload. Prepaid credits from $1.20/1K searches never expire. No KYC — no ID, no selfie, no documents. Pay in crypto.