Search

POST

Run a web search and get clean, ranked results in a single API call.

The Search API returns a ranked list of web results (title, URL, and a short description snippet) for a query. It's a lightweight building block for grounding LLM responses, gathering sources, or feeding a downstream pipeline. For LLM-ready results that are scored for relevance and optionally enriched with full-page content, see the Web Search API.

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/search/web

Basic example

A simple search request.

curl -X POST https://api.greenpt.ai/v1/tools/search/web \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "renewable energy storage"
  }'

const response = await fetch(
  'https://api.greenpt.ai/v1/tools/search/web',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'renewable energy storage',
    }),
  },
);

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

import requests

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

payload = {
  "query": "renewable energy storage"
}
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

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

print(response.json())

Advanced example

Control the number of results, paginate, and bias results toward a language/region.

curl -X POST https://api.greenpt.ai/v1/tools/search/web \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "renewable energy storage",
    "maxResults": 10,
    "page": 1,
    "country": "de-DE"
  }'

const response = await fetch(
  'https://api.greenpt.ai/v1/tools/search/web',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'renewable energy storage',
      maxResults: 10,
      page: 1,
      country: 'de-DE',
    }),
  },
);

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

import requests

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

payload = {
  "query": "renewable energy storage",
  "maxResults": 10,
  "page": 1,
  "country": "de-DE"
}
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 (1–500 characters).
`maxResults`	integer	No	Maximum number of results to return (1–50). Default: `20`.
`page`	integer	No	Result page number (≥ 1). Default: `1`.
`country`	string	No	Language/region code such as `"en"` or `"de-DE"`. Biases results toward that language/region.

Note on country: this value is used as a language/region bias, not a strict country filter. Use an [ISO 639-1] language code ("en") optionally with an [ISO 3166-1] region ("de-DE").

Response format

{
  "results": [
    {
      "url": "https://example.com/article",
      "title": "Article Title",
      "description": "A short snippet describing the result.",
      "position": 1,
      "favicon": "https://www.google.com/s2/favicons?domain=example.com&sz=32"
    }
  ]
}

Field	Type	Description
`url`	string	The result URL.
`title`	string	The result title.
`description`	string	A short snippet of the page content.
`position`	integer	The result's rank (starting at 1).
`favicon`	string	Favicon URL for the result's domain (when available).

Use cases

LLM grounding: fetch fresh sources to ground model responses.
Research: gather a ranked list of links for a topic.
Pipelines: feed URLs into the Scraper API for full content.