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. The HTTP endpoint itself is locked down; in normal use you never call it directly — the agent's tool call is executed via the relay for you.

GET /v1/web_search

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

Admin-token only. Any other caller — including a regular signed-in user token — receives 401 unauthorized. See Overview & auth for how tokens are presented.

curl -s "https://<relay-host>/v1/web_search?q=rust%20lifetimes" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response shape

{ "results": "<formatted text>" }

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.

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