API reference
Two endpoints: one searches the web, one reads pages. Both take JSON and return JSON. Field names match Tavily's, so an app that used Tavily swaps one function.
Authentication
Send your app's key as a bearer token on every request. Each app has its own key, issued by hand. Requests go to https://truffler.dev.
Authorization: Bearer <key>Errors
A failed request returns a status code and a JSON body with an error message.
| Status | When |
|---|---|
| 400 | The body is missing a field, or a value is out of range. |
| 401 | The key is missing or wrong. |
{
"error": "..."
}Search
POST /api/v1/searchThe same query and options within 24 hours come from cache.Searches Google. Basic depth returns each result's title, address, snippet and date. Advanced depth also reads the top results and returns the passages that best match the query as content, in place of the snippet.
Request body
querystringRequired- What to search for.
maxResultsnumber, 1 to 20Default 5- How many results to return.
depth"basic" or "advanced"Default "basic"- Basic returns Google's snippet for each result. Advanced also reads the top results and returns the passages that best match the query instead.
includeDomainsstring[]Optional- Only return results from these domains.
Response
querystring- The query you sent.
results[].titlestring- The page's title.
results[].urlstring- The page's address.
results[].contentstring- Google's snippet, or with advanced depth, the passages that best match the query.
results[].published_datestring or null- The page's date, when Google has one.
results[].scorenumber- How well the result matches the query. Higher is better.
response_timenumber- Seconds the request took.
curl https://truffler.dev/api/v1/search \
-H "Authorization: Bearer $TRUFFLER_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"aurora forecast iceland","maxResults":2,"depth":"advanced"}'{
"query": "aurora forecast iceland",
"results": [
{
"title": "Aurora forecast | Icelandic Met Office",
"url": "https://en.vedur.is/weather/forecasts/aurora/",
"content": "The aurora forecast shows expected cloud cover and auroral activity for the next three nights. Clear skies matter as much as activity.",
"published_date": null,
"score": 0.91
},
{
"title": "Aurora - Wikipedia",
"url": "https://en.wikipedia.org/wiki/Aurora",
"content": "Auroras are most often seen in high-latitude regions such as Iceland, between September and April, when nights are long and dark.",
"published_date": "2026-11-02",
"score": 0.84
}
],
"response_time": 1.42
}Extract
POST /api/v1/extractA page read in the last 7 days comes from cache.Reads each page and returns its main text as markdown, with its title, date, images and links. Each address is read with a plain fetch first, and with a headless browser if that fails. Private and internal addresses are refused.
Request body
urlsstring[], 1 to 20Required- The pages to read.
Response
results[].urlstring- The address you sent.
results[].titlestring- The page's title.
results[].publisherstring or null- The site's name, when the page gives one.
results[].published_datestring or null- The page's date, when it has one.
results[].raw_contentstring- The page's main text, as markdown.
results[].image_urlstring or null- The page's main image.
results[].images{ url, alt }[]- Images on the page, with their alt text.
results[].links{ url, text }[]- Links on the page, with their text.
results[].youtube_idsstring[]- YouTube videos on the page.
results[].extractor"readability" or "browser"- Which step read the page.
failed_results{ url, error }[]- Pages that couldn't be read, and why.
response_timenumber- Seconds the request took.
curl https://truffler.dev/api/v1/extract \
-H "Authorization: Bearer $TRUFFLER_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://en.wikipedia.org/wiki/Aurora","http://10.0.0.5/admin"]}'{
"results": [
{
"url": "https://en.wikipedia.org/wiki/Aurora",
"title": "Aurora",
"publisher": "Wikipedia",
"published_date": null,
"raw_content": "# Aurora\n\nAn aurora is a natural light display in Earth's sky, seen mostly in high-latitude regions...",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/a/aa/Polarlicht_2.jpg",
"images": [
{
"url": "https://upload.wikimedia.org/wikipedia/commons/a/aa/Polarlicht_2.jpg",
"alt": "Aurora over a frozen lake"
}
],
"links": [
{
"url": "https://en.wikipedia.org/wiki/Magnetosphere",
"text": "magnetosphere"
}
],
"youtube_ids": [],
"extractor": "readability"
}
],
"failed_results": [
{
"url": "http://10.0.0.5/admin",
"error": "Private and internal addresses are refused."
}
],
"response_time": 0.86
}