yacy_search_server/help/yacy/search.md

page, help, title, package, access, kind, backend_java

page	help	title	package	access	kind	backend_java
htroot/yacy/search.html	help/yacy/search.md	search	machine-api-peer	peer-service	peer-endpoint	source/net/yacy/htroot/yacy/search.java

search

Purpose

search is a machine-oriented search endpoint.

Use it when the caller needs search data without the full browser interface.

What You Can Do Here

• Run a machine-oriented search request.
• Choose query, count, resource, and filter parameters explicitly.
• Use the returned data in tools that do not need the full browser result page.

Page Architecture

This is a compact endpoint-style page. Its behavior is driven mainly by request parameters and the selected response template, so callers should send only the fields needed for the specific query or peer-service action.

Correct Use

Call the endpoint as a protocol surface. Use exact parameter names and encoded values, authenticate when required, and inspect the response before relying on it. Avoid sending browser-only submit buttons unless the backend explicitly requires the action key.

Access And Safety

This is a peer-service endpoint for YaCy peer communication, not a normal editing page.

Behind a reverse proxy, YaCy accepts X-Real-IP as the effective client and routing address only when the proxy socket IP matches server.reverseProxy.trusted and the header contains one valid IPv4 or IPv6 address. Otherwise YaCy uses the socket IP. Authentication and access control always use the socket IP. The proxy must overwrite, not pass through, any client-supplied X-Real-IP value.

Automation And API

Page backend: source/net/yacy/htroot/yacy/search.java.

Endpoint	Method	Access	Backend
/yacy/search.html	GET or POST	peer-service	source/net/yacy/htroot/yacy/search.java

Parameter Guide

The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default.

Parameter	Meaning and valid values	Care
collection	Collection name. Use it to group crawled or imported documents and to search or manage that group later.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
constraint	Encoded YaCy bitfield constraint. Leave it empty unless you are replaying a URL generated by YaCy itself.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
contentdom	Content domain filter. Common values are all, text, image, audio, video, and app; use it to ask for web pages, media, or application documents deliberately.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
count	SRU-style result count. It is an alternative to maximumRecords on search endpoints.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
filter	Filter text or expression used to narrow the displayed records.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
iam	Twelve-character enhanced-Base64 seed hash of the requesting YaCy peer. When it identifies a known peer, YaCy uses it for search-statistics attribution so peers sharing an address behind NAT remain distinguishable.	This is attribution metadata, not an independent authentication credential. Missing, malformed, or unknown hashes fall back to the effective request client IP.
language	Interface language. Values are browser for the browser-preferred language, default for English, or a language code such as de, fr, es, zh, ja, or ko.	Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result.
query	Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
sitehost	Host or domain scope.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
strictContentDom	When true, YaCy enforces the selected content domain more strictly instead of using it mainly for presentation.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
time	Date/time value for filtering, display, or scheduling.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
timezoneOffset	Client timezone offset in minutes. YaCy uses it for date display or schedule calculations.	Read-only request context for date handling.

Example request shape:

GET or POST /yacy/search.html?iam=...&language=...&query=...&contentdom=...&abstracts=...&author=...

What To Expect

Expect a compact service response rather than a teaching interface. The response may be XML, RSS, JSON-like text, plain text, or a small HTML template depending on the endpoint.

Related Pages

• Related protocol work usually continues through the calling tool, the peer endpoint family under /yacy/, or the API page that consumes this response.