Let your agent search
the live web.

curl https://api.trawlia.co/v1/search \
  -H "authorization: Bearer twl_..." \
  -H "content-type: application/json" \
  -d '{
    "query": "latest Python release notes",
    "search_depth": "advanced"
  }'

import os, requests

def web_search(query: str, depth: str = "basic") -> str:
    """Search the live web. Returns ranked pages as Markdown, each with its source URL."""
    res = requests.post(
        "https://api.trawlia.co/v1/search",
        headers={"authorization": f"Bearer {os.environ['TRAWLIA_API_KEY']}"},
        json={"query": query, "search_depth": depth},
        timeout=60,  # advanced depth fetches every result
    )
    res.raise_for_status()
    data = res.json()

    # raise_for_status already separated the cases: 502 means the search could
    # not be served, 429 means it is being paced, and reaching here with an
    # empty list means the search genuinely found nothing.
    if not data["results"]:
        return "No results for that query."

    return "\n\n".join(
        f"## {r['title']}\n{r['url']}\n\n{r['content']}" for r in data["results"]
    )

/** Search the live web. Returns ranked pages as Markdown, each with its source URL. */
export async function webSearch(
  query: string,
  depth: "basic" | "advanced" = "basic",
): Promise<string> {
  const res = await fetch("https://api.trawlia.co/v1/search", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.TRAWLIA_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ query, search_depth: depth }),
  });
  if (!res.ok) throw new Error(`trawlia ${res.status}: ${await res.text()}`);
  const data = await res.json();

  if (data.results.length === 0) return "No results for that query.";

  return data.results
    .map((r: any) => `## ${r.title}\n${r.url}\n\n${r.content}`)
    .join("\n\n");
}