Web Search

Search the web and get LLM-ready, relevance-filtered results, with optional full-page content.

POST

Search the web and get LLM-ready, relevance-filtered results, with optional full-page content.

The Web Search API runs a two-tier pipeline designed to return content that's ready to hand straight to an LLM:

Tier 1: snippet scoring. Results from the search index are scored for relevance against your query. If the top snippets are relevant enough, they are returned as-is (fast, no scraping).
Tier 2: full-page enrichment. When snippets aren't strong enough, the most relevant pages are scraped, chunked, and scored, and the most relevant passages are returned per result as relevant_content within a character budget.

If you just need raw ranked links, use the lighter Search API instead.

Authentication

All requests require an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API endpoint

POST https://api.greenpt.ai/v1/tools/websearch

Basic example

curl -X POST https://api.greenpt.ai/v1/tools/websearch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do solid-state batteries work"
  }'

const response = await fetch(
  'https://api.greenpt.ai/v1/tools/websearch',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'how do solid-state batteries work',
    }),
  },
);

const result = await response.json();
console.log(result);

import requests

url = "https://api.greenpt.ai/v1/tools/websearch"

payload = {
  "query": "how do solid-state batteries work"
}
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Advanced example

Force full-page fetching and bias toward a language/region.

curl -X POST https://api.greenpt.ai/v1/tools/websearch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do solid-state batteries work",
    "count": 8,
    "force_fetch": true,
    "language": "en"
  }'

const response = await fetch(
  'https://api.greenpt.ai/v1/tools/websearch',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'how do solid-state batteries work',
      count: 8,
      force_fetch: true,
      language: 'en',
    }),
  },
);

const result = await response.json();
console.log(result);

import requests

url = "https://api.greenpt.ai/v1/tools/websearch"

payload = {
  "query": "how do solid-state batteries work",
  "count": 8,
  "force_fetch": True,
  "language": "en"
}
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query. Unsupported operators (`site:`, `inurl:`, `filetype:`, etc.) are stripped before searching.
`count`	integer	No	Number of index results to consider (1–20). Default: `5`. See the note below; it is not a guaranteed output size.
`force_fetch`	boolean	No	Skip the Tier 1 snippet short-circuit and always scrape full pages (Tier 2). Default: `false`.
`language`	string	No	Language/region code such as `"en"` or `"de-DE"`. Biases results toward that language/region.

Note on result counts: count controls how many index results are considered, not how many you get back. In Tier 1, up to count snippet results may be returned. When Tier 2 runs (low snippet relevance or force_fetch: true), the number of enriched results is capped independently of count, so you may receive fewer items.

Response format

{
  "note": "Full page content has been fetched, analyzed, and filtered for relevance. Use this content to answer the user.",
  "results": [
    {
      "title": "Result Title",
      "link": "https://example.com/article",
      "snippet": "A short snippet describing the result.",
      "relevant_content": "The most relevant passages extracted from the page..."
    }
  ]
}

Field	Type	Description
`note`	string	Guidance describing what the `results` contain (snippets only vs. fetched full-page content).
`results`	array	The ranked, relevance-filtered results.
`results[].title`	string	The result title.
`results[].link`	string	The result URL.
`results[].snippet`	string	A short snippet of the page content.
`results[].relevant_content`	string	The most relevant extracted passages. Present only when full-page content was fetched (Tier 2).

Use cases

RAG / LLM grounding: get relevance-filtered, LLM-ready content in one call.
Question answering: fetch and rank the passages most relevant to a query.
Research assistants: gather sources with the key passages already extracted.