# Web Search

> Real-time web search returning LLM-ready JSON results.

Source: http://localhost:3000/docs/endpoints/search

## Web Search: `POST /v1/search/`

Live web results as clean JSON — titles, URLs, snippets, instant answers. Cost: 1 credit. Available on the free demo.

```bash
curl -X POST https://api.hushsearch.io/v1/search/ \
  -H "X-API-Key: hs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "best open-source vector databases",
  "num_results": 5
}'
```

Real-time web search through private SearXNG metasearch, which queries engines such as Google, Bing and DuckDuckGo and fuses their results. Returns clean, structured results ready for LLM context injection.

## Request

```bash
curl -X POST https://api.hushsearch.io/v1/search/ \
  -H "X-API-Key: hs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best RAG frameworks 2026",
    "num_results": 5,
    "categories": ["general"],
    "time_range": "month"
  }'
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | ✅ | — | The search query |
| `num_results` | integer | | 10 | Max results to return (1–50) |
| `categories` | string[] | | all | Filter: `general`, `news`, `science`, `it` |
| `engines` | string[] | | all | Override engines: `google`, `bing`, `duckduckgo` |
| `time_range` | string | | none | `day`, `week`, `month`, `year` |
| `safe_search` | integer | | 0 | `0` = off, `1` = moderate, `2` = strict |

## Response

```json
{
  "results": [
    {
      "title": "LlamaIndex vs LangChain for RAG in 2026",
      "url": "https://example.com/rag-comparison",
      "snippet": "A comprehensive comparison of the two leading RAG frameworks..."
    }
  ],
  "credits_used": 1,
  "credits_remaining": 499,
  "response_time_ms": 412
}
```

## Python Example

```python

response = requests.post(
    "https://api.hushsearch.io/v1/search/",
    headers={"X-API-Key": "hs_live_..."},
    json={
        "query": "Apple Intelligence API integration guide",
        "num_results": 5,
        "categories": ["general", "it"]
    }
)

data = response.json()
for result in data["results"]:
    print(result["title"], result["url"])
```

## Error Codes

| Code | Meaning |
|---|---|
| `401` | Invalid or missing API key |
| `402` | Insufficient credits |
| `429` | Rate limit exceeded (100 req/min) |
| `503` | Search engine temporarily unavailable |
