Skip to content

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.

Header
Authorization: Bearer <key>

Errors

A failed request returns a status code and a JSON body with an error message.

StatusWhen
400The body is missing a field, or a value is out of range.
401The key is missing or wrong.
Error body
{
  "error": "..."
}

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.
Request
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"]}'
Response
{
  "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
}