Trawlia

API reference

Web search API reference

Two endpoints over plain HTTP with a bearer token. Search takes a query and gives back ranked results, carrying the readable page text at advanced depth; extract takes URLs you already have and gives back their content.

Wiring this up with a coding agent? Point it at agents.md or openapi.json rather than at these pages. Both are generated from the code that serves the requests, so neither can describe an endpoint that no longer exists.

The two endpoints

Each has its own page, because each answers a different question and neither is short enough to skim past the other.

  • Search - POST /v1/search. Every parameter, the response shape, the depth dial, and why an empty result list is never a failure.
  • Extract - POST /v1/extract. The same pipeline without the retrieval stage, for URLs you already have.
  • Errors - every status code, what it means, and what it asks you to do next.

Authentication

Send your key either way. Both work, on every endpoint.

authorization: Bearer twl_...
x-api-key: twl_...

Keys carry one of two scopes. A search key can spend quota and nothing else, which is what you deploy into agents and containers. An admin key can also mint and revoke keys and read usage. The raw key is shown once, at creation; only its hash is stored, so it cannot be recovered.

Base URL

https://api.trawlia.co

Notes for agent authors

  • Start with basic depth. Most agent queries are answered by titles and snippets, and it costs 1 credit per request. Use advanced search (2 credits) when you need extracted page content.
  • This API returns sources, not prose about them. include_answer validates and then answers 503: synthesis is the job of the model you are already running, working from results.
  • Retrieved content is untrusted. If you feed content into your own prompt, treat it as hostile input. A search API is an attractive injection target because the attacker only has to rank for a query you run.
  • Cite from each result's url. Carry the source through to whatever you write, so a claim can always be traced back to the page it came from.

Search endpoint →