yacy_search_server/help/yacysearch.md

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

page	help	title	package	access	kind	backend_java
htroot/yacysearch.html	help/yacysearch.md	Search Page	core-search-public	mixed	search-page	source/net/yacy/htroot/yacysearch.java

Search Page

Purpose

The Search Page is the main result page. It turns a query into local or distributed search results and carries the parameters that define result count, content type, language, pagination, and verification behavior.

Use it to understand how a browser search maps to an API-style request.

What You Can Do Here

• Search the local YaCy index, or the YaCy network when the peer is configured for global search.
• Choose query, result type, collection, and verification options according to the information need.
• Page through results, restrict results to a URL pattern, request a content type such as images or text, and choose how fresh snippets must be.
• When authenticated, perform result actions such as deleting a reference, recommending a result, bookmarking it, or sending a URL to a blacklist.

Page Architecture

Public search pages turn request parameters into result lists, previews, snippets, feeds, or integration fragments. They are mostly read-oriented, but some result actions can bookmark, recommend, blacklist, or delete references when authenticated.

Control	Meaning	Values or examples
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.	Search terms, for example climate data or a more specific phrase.
Enter	Browser submit button. Omit it from direct API calls; YaCy uses the query and filter parameters, not the button label, to run the search.	Browser-generated submit value only.

Correct Use

For a normal search, send only query and the options that express the user intent: maximumRecords for result count, resource for local versus network search, contentdom for text or media, and urlmaskfilter when the user asks to search inside a site. Start with verify=iffresh when freshness matters; use cacheonly only when the user explicitly wants stored snippets without refetching.

Do not send result-action parameters such as deleteref, bookmarkref, or blacklisturl as part of an ordinary search. Those parameters change state and require an exact result reference from a prior response.

Access And Safety

The page may be visible, but the backend performs authentication checks for protected actions.

Protected related endpoint(s): /yacysearch.html.

Backend checks: built-in administrator authentication for protected search features and all state-changing result actions.

Automation And API

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

Endpoint	Method	Access	Backend
/yacysearch.html	GET	mixed	source/net/yacy/htroot/yacysearch.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. Low-level generated parameters are omitted when they are only meaningful inside the rendered YaCy form.

Parameter	Meaning and valid values	Care
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.
auth	Requests authentication-aware behavior when the endpoint supports user-specific or protected actions.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
callback	JSONP callback name for legacy script clients. Leave empty for normal HTML or JSON-style use.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
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.
deleteref	URL hash/reference selected for deletion from results. Use only with administrator intent and an exact known reference.	Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target.
focus	Browser presentation flag controlling whether the search input receives focus.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
indexof	Interprets the query as an index-of style request when supported.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
lr	Language filter, usually a two-letter code such as de, fr, or en when the page supports language-restricted search.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
maximumRecords	Maximum number of results to return on one page. Use a modest value for interactive use; larger values are for controlled scripts.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
nav	Navigator/facet selection for search results. all requests the normal set; narrower values reduce displayed facets.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
offset	Zero-based result offset for pagination.	Read-only pagination control. Use 0 for the first page and increase by the result count for later pages.
prefermaskfilter	Regular-expression URL preference. Matching results are favored without excluding all others.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
recommendref	URL hash/reference selected for recommendation.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
resortCachedResults	Requests resorting of a cached search event instead of starting a fully fresh result event.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
resource	Search source. local searches this peer index; global may use the YaCy network when the peer and configuration allow it.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
resource-switch	Browser control for switching between local and global search. For direct calls use resource=local or resource=global.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
rows	Rows requested by API-style clients. It is another result-count alias on search endpoints.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
search	Alternative search text parameter accepted by some search endpoints; prefer query on browser search pages unless reproducing an existing URL.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.
startRecord	First result record for pagination; accepted as an alternative to offset on search endpoints.	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.
timezoneOffset	Client timezone offset in minutes. YaCy uses it for date display or schedule calculations.	Read-only context for date handling; it does not by itself change the index.
urlmaskfilter	Regular-expression URL filter for search results. Use .* for no restriction; use a precise host/path expression to search inside a site or section.	Controls the scope or format of the result. Prefer the narrowest value that answers the request.
verify	Snippet/cache verification strategy. Typical values are iffresh, ifexist, cacheonly, nocache, and false; choose according to whether freshness or speed matters more.	Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default.

Example request shape:

GET /yacysearch.html?query=climate+data&maximumRecords=10&resource=local&contentdom=text&verify=iffresh

What To Expect

The response is an HTML result page. It contains result entries, navigators/facets when enabled, and hidden references used by authenticated result actions. If a query returns too little, first check whether the crawler has indexed the relevant site and whether urlmaskfilter, collection, or contentdom narrowed the request too far.

Related Pages

• Status.html