---
title: "Run a web search"
method: POST
path: "/v1/web/search"
tags: ["Web"]
---

# Run a web search

`POST /v1/web/search`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/web/search`
- Auth: HTTP bearer

Routes the `query` through the configured web search provider. Optional
`site` filter, `time_range` (day/week/month/year), and `safe_search`
controls. Returns ranked results with title, URL, and snippet.

## Request body

- WebSearchRequest
  - `query` string, required
  - `limit` integer: Max results to return. Default 10.
  - `site` string: Restrict to a domain (e.g. `news.ycombinator.com`).
  - `time_range` 'day' | 'week' | 'month' | 'year'
  - `safe_search` string

## Response `200`

Search results

- WebSearchResponse
  - `query` string
  - `provider` string: Provider that served the request.
  - `results` object[], required
    - `title` string
    - `url` string
    - `snippet` string

## Other responses

- `400`: Invalid request
- `502`: Provider parse or upstream error
- `503`: Web search adapter not initialized

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)