Skip to content
MelMel
API > API reference

Web search

The relay's web-search endpoint.

The relay performs web searches server-side so the agent's web_search tool works without any search API key on your machine. In normal use you never call it directly — the agent's tool call is executed by Mel's server for you.

GET /v1/web_search

GET /v1/web_search?q=<urlencoded query>

Requires a signed-in, active account. Each plan has a daily number of searches, counted per UTC day; see Billing & usage. See Overview & auth for how tokens are presented.

curl -s "https://<relay-host>/v1/web_search?q=rust%20lifetimes" \
  -H "Authorization: Bearer $TOKEN"
  • 401 {"error": "unauthorized"} — signed out.
  • 429 {"error": "web_search_daily_limit"} — the plan's daily searches are spent.

Response shape

{ "results": "<formatted text>", "provider": "tavily" }

provider names the search engine that answered.

results is a single preformatted string, not an array. Each result contributes its title, url, and snippet to the text block. If you are parsing programmatically, treat it as opaque display text — there is no structured per-result JSON on this endpoint.

Errors follow the shared shape from Overview & auth: {"error": "<machine_code>", "message": "<human text>"} with a matching HTTP status.

GET /v1/web_fetch

GET /v1/web_fetch?url=<urlencoded url>

Fetches one page on Mel's server and returns its readable text: 200 {"text": "<extracted text>"}, capped at 24 KB. Same sign-in and the same daily counter as /v1/web_search. A failure (HTTP status, timeout, no readable content) comes back as a <web_fetch: …> note inside text, not as an error status. Addresses inside private networks are refused, on every hop of a redirect.

How the agent uses it

In an agent conversation, the model requests a search by emitting a web_search tool call during agent streaming:

{"name": "web_search", "parameters": {"type": "object", "required": ["query"],
  "properties": {"query": {"type": "string"}}}}

The client executes the call and returns the formatted result string as a role:"tool" message on the next leg — the same round-trip every tool uses (see Tool definitions). The streamed transcript then renders the result list inline.

Related