Search

Returns current web results for a query: title, link, and a text excerpt when available. Use them with any model or app, for example to give a model current information. Use Answer instead when you want a written answer.

POSThttps://api.freetheai.org/v1/search

Request

curl

curl https://api.freetheai.org/v1/search \
  -H "Authorization: Bearer $FTAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "vitepress local search", "num_results": 5}'

Python

import os
import requests

response = requests.post(
    "https://api.freetheai.org/v1/search",
    headers={"Authorization": f"Bearer {os.environ['FTAI_KEY']}"},
    json={"query": "vitepress local search", "num_results": 5},
    timeout=60,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["title"], result["url"])

TypeScript

type SearchResult = { title: string; url: string; text?: string; publishedDate?: string }

const response = await fetch('https://api.freetheai.org/v1/search', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.FTAI_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'vitepress local search', num_results: 5 }),
})
if (!response.ok) throw new Error((await response.json()).error?.message)
const { results } = (await response.json()) as { results: SearchResult[] }
for (const r of results) console.log(r.title, r.url)

Body parameters

Parameter	Type	Description
query	string, required	What to search for, up to 1,024 characters. Short keyword queries work best.
num_results	integer	How many results to return, 1 to 25. Default 10.

Response

{
  "query": "vitepress local search",
  "results": [
    {
      "title": "Search | VitePress",
      "url": "https://vitepress.dev/reference/default-theme-search",
      "text": "VitePress supports fuzzy full-text search using an in-browser index...",
      "publishedDate": "2025-01-20",
      "score": 0.82,
      "highlights": ["...in-browser index thanks to minisearch..."]
    }
  ],
  "suggestions": [],
  "daily_used": 3,
  "daily_limit": 50
}

Field	Type	Description
query	string	The query that was searched.
results[].title	string	Page title.
results[].url	string	Page link.
results[].text	string	A text excerpt from the page, when available.
results[].highlights	array of strings	Short relevant passages, when available.
results[].publishedDate	string	Publication date, when known.
results[].score	number	Relevance score, when available.
suggestions	array of strings	Related queries, when available.
daily_used	integer	Searches used today, including this one.
daily_limit	integer	Your account's daily web-search allowance.

The daily_limit value in the example is only an illustration; read it from the response.

Limits

• Every call counts against one daily web-search allowance shared with /v1/answer. It is separate from your free requests and resets at 00:00 UTC.
• Identical queries within an hour return the same results.

Errors

Status	Meaning
400	The query is missing or too long.
401	Missing or invalid API key.
429	The daily web-search allowance is used up. It resets at 00:00 UTC.
502	No results could be fetched right now. Try again shortly.