## Web Search API

The web search endpoint retrieves information from billions of web documents using hybrid search (keyword + vector matching) with optional summaries.

### Endpoint
`POST https://api.langsearch.com/v1/web-search`

### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The search query |
| `count` | integer | No | Number of results to return (default: 10, max: 100) |
| `summary` | boolean | No | Include markdown summaries in results (default: false) |
| `freshness` | string | No | Filter results by freshness (`day`, `week`, `month`, `year`) |

### Response Structure

The API returns an array of search results with:
- `title` - Result title
- `url` - Result URL
- `snippet` - Text excerpt from the page
- `summary` - Markdown formatted summary (if `summary: true` in request)
- `score` - Relevance score

### Example Use Cases

**Current Information Retrieval**
When your LLM needs up-to-date information:

**Multi-Query Research**
Build context from multiple searches:

## Semantic Reranking API

Improve search accuracy by reranking results based on semantic relevance to your query.

### Endpoint
`POST https://api.langsearch.com/v1/rerank`

### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The search query for context |
| `documents` | array | Yes | Array of documents to rerank (each with `title`, `text`, etc.) |
| `model` | string | No | Reranking model (default: `langsearch-rerank-1`) |
| `top_n` | integer | No | Number of top results to return (default: 10) |
| `return_documents` | boolean | No | Include full documents in response (default: false) |

### Example: Reranking Web Search Results

## Building RAG Applications

Combine web search with LLM context for better information retrieval and generation:

import requests
import json
import os

api_key = os.getenv("LANGSEARCH_API_KEY")
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

query = "latest AI developments 2025"
payload = {
    "query": query,
    "count": 5,
    "summary": True
}

response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json=payload
)

results = response.json()
print(json.dumps(results, indent=2))

curl -X POST https://api.langsearch.com/v1/web-search \
  -H "Authorization: Bearer $LANGSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2025",
    "count": 5,
    "summary": true
  }'

# Search for recent developments
response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={
        "query": "Python 3.14 release notes",
        "count": 3,
        "summary": True,
        "freshness": "week"
    }
)

queries = [
    "climate change mitigation strategies",
    "renewable energy trends 2025",
    "carbon capture technology"
]

all_results = []
for query in queries:
    response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={"query": query, "count": 5, "summary": True}
    )
    all_results.extend(response.json())

# Get initial search results
search_response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={"query": "machine learning deployment best practices", "count": 10}
)

search_results = search_response.json()

# Prepare documents for reranking
documents = [
    {"title": r.get("title", ""), "text": r.get("snippet", "")}
    for r in search_results
]

# Rerank for better relevance
rerank_response = requests.post(
    "https://api.langsearch.com/v1/rerank",
    headers=headers,
    json={
        "query": "best practices for deploying ML models in production",
        "documents": documents,
        "top_n": 5
    }
)

reranked = rerank_response.json()

def rag_query(user_question):
    # Step 1: Search the web for relevant information
    search_response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={
            "query": user_question,
            "count": 5,
            "summary": True
        }
    )

    search_results = search_response.json()

    # Step 2: Extract summaries and URLs for context
    context = "\n".join([
        f"- {r['title']}: {r.get('summary', r.get('snippet', ''))}"
        for r in search_results
    ])

    # Step 3: Use with your LLM
    # This is where you'd call your LLM with the context
    rag_context = f"""
Based on recent web search results:

{context}

Answer the user's question: {user_question}
"""

    return rag_context, search_results