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:

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:

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.

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:

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 lists request fields, response fields and error codes.