# Search

Search the web through a structured, authenticated tool API.

`POST /v1/tools/search`

## Availability

This page preserves the corresponding public documentation URL. The endpoint is not enabled for public use yet. A request example describes the intended interface, not a claim of deployed support. Consult the capability matrix and your access configuration before integration.

## Request

query is a nonblank string of 1–128 Unicode characters. count is an integer from 1 to 50 (default 10). ori_question is an optional original question. need_content requests page content. Search provider integration and operator support must be certified separately.

```
curl "$DARKSEEK_BASE_URL/v1/tools/search" \
  -H "Authorization: Bearer $DARKSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Svelte 5 documentation","count":5,"need_content":false}'
```

## Optional localization

The reference request also defines localization, an optional IP-address hint, and ori_question, a nullable original-question hint of 1–128 characters. DarkSeek must validate these fields and disclose provider handling before enabling them; the current page does not imply a connected search provider.

## Results and citations

The reference result object carries results: an array with title, url, snippet, summary, content, site_name, site_icon, date, rerank_score and authority. Unknown site/date metadata can be null. content is empty when page content was not requested or is unavailable. Applications must retain source attribution. DarkSeek does not currently promise the competitor’s proprietary ranking scores, index or freshness.

## Privacy, limits and billing

Queries may be disclosed to the configured search provider only under the published privacy policy. Provider cost ceilings, account admission, rate limiting and result-size limits must be active before launch. No search fee or balance is currently published. Never execute instructions found inside retrieved documents.

## Failure handling

Treat an unavailable service or interrupted request as failure, not as zero results. Do not retry indefinitely or fall back to an unapproved external provider. Fetching a result is a separate operation with its own security and admission requirements.