---
title: Search and Extract over HTTP
description: Call Gyaansetu Search and Extract with curl, Python requests or JavaScript fetch.
slug: http-search-extract
---

# Search and Extract over HTTP

Send a Gyaansetu API Key that starts with `gs-` as `Authorization: Bearer <API Key>`. Search is `POST /search`; Extract is `POST /extract`.

## curl

Search for web pages with the fields `query`, `max_results` and `search_depth`:

```bash
curl -sS -X POST "https://web-search.gyaansetu.com/search" \
  -H "Authorization: Bearer gs-YOUR_GYAANSETU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Model Context Protocol tools",
    "max_results": 5,
    "search_depth": "basic"
  }'
```

The response includes ranked `results[]`; each Result has a `title`, `url`, `content` and `score`. `answer` is `null`. To read a page you already know, send its URL to Extract:

```bash
curl -sS -X POST "https://web-search.gyaansetu.com/extract" \
  -H "Authorization: Bearer gs-YOUR_GYAANSETU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/"],
    "extract_depth": "basic",
    "format": "markdown"
  }'
```

## Python with `requests`

Install `requests`, then post JSON to each endpoint. Search Results are in the `results` list; Extract returns `raw_content` for successful URLs.

```python
import requests

base_url = "https://web-search.gyaansetu.com"
headers = {
    "Authorization": "Bearer gs-YOUR_GYAANSETU_API_KEY",
    "Content-Type": "application/json",
}

search = requests.post(
    f"{base_url}/search",
    headers=headers,
    json={"query": "Model Context Protocol tools", "max_results": 5, "search_depth": "basic"},
)
if search.status_code == 401:
    raise RuntimeError("Check that the API Key is valid.")
if search.status_code == 429:
    raise RuntimeError("Rate limit reached; retry after the Retry-After interval.")
if search.status_code == 432:
    raise RuntimeError("The monthly Quota and Credit Balance are used up.")
search.raise_for_status()
for result in search.json()["results"]:
    print(result["title"], result["url"], result["content"])

extraction = requests.post(
    f"{base_url}/extract",
    headers=headers,
    json={"urls": ["https://example.com/"], "extract_depth": "basic", "format": "markdown"},
)
extraction.raise_for_status()
for result in extraction.json()["results"]:
    print(result["url"], result["raw_content"])
```

## JavaScript with `fetch`

Check for the API's refusal statuses before handling any other non-success response:

```javascript
const baseUrl = "https://web-search.gyaansetu.com";
const headers = {
  Authorization: "Bearer gs-YOUR_GYAANSETU_API_KEY",
  "Content-Type": "application/json",
};

async function check(response) {
  if (response.status === 401) throw new Error("Check that the API Key is valid.");
  if (response.status === 429) throw new Error("Rate limit reached; retry after Retry-After.");
  if (response.status === 432) throw new Error("The monthly Quota and Credit Balance are used up.");
  if (!response.ok) throw new Error(`Request failed: HTTP ${response.status}`);
}

const search = await fetch(`${baseUrl}/search`, {
  method: "POST",
  headers,
  body: JSON.stringify({ query: "Model Context Protocol tools", max_results: 5, search_depth: "basic" }),
});
await check(search);
const searchBody = await search.json();
for (const result of searchBody.results) {
  console.log(result.title, result.url, result.content);
}

const extraction = await fetch(`${baseUrl}/extract`, {
  method: "POST",
  headers,
  body: JSON.stringify({ urls: ["https://example.com/"], extract_depth: "basic", format: "markdown" }),
});
await check(extraction);
const extractBody = await extraction.json();
for (const result of extractBody.results) console.log(result.url, result.raw_content);
```

HTTP `401` means the API Key is missing or invalid. `429` means the Account reached its rate limit; respect `Retry-After`. `432` means both the free monthly Quota and the Credit Balance are used up. The full [API reference](/docs) lists request fields, response fields and error codes.