API Structure

The API has three main routes:

• / : Home page
• /search : Main route for interacting with the software and performing web searches
• /docs : Documentation automatically generated by FastAPI

Search

The search endpoint accepts the following input parameters:

Parameter	Description	Data Type	Notes
q	Search query (required)	String	User’s search text. Max length: 1900 characters (default: longer input is truncated)
engines	Active search engines	String or List	One or more engines from different categories. Default: all engines
enabled_plugins	Active plugins	String or List	One or more plugins (both pre and post types). Default: all plugins
time_range	Time range filter	String	Expected values: hour, day, week, month, year
language	Filter results by language	String	Language code such as en, ar, etc.
limit	Maximum number of results	Integer	Limits the number of returned results
pageno	Page number	Integer	Page number of search results (default is 1)
seafesearch	Explicit content filter	Integer (0,1,2)	0: off, 1: moderate, 2: strict
country	Filter results by country	String	Country code such as US
categories	Search categories	String	Expected values: general (default), images, videos, news, books, maps, shaping, other
api_mode	API output mode	String	Values: merged (default), normal, stream

---

Parameter Details

1. q (required)

   The main search query text entered by the user.

2. engines

   Active search engines. Can include one or multiple engines from different categories. Defaults to all engines if not specified.

3. enabled_plugins

   Active plugins including both pre and post types. Defaults to all plugins.

4. time_range

   Filters results by time. Valid values:
   hour, day, week, month, year

5. language

   Filters results by language; expects language codes like en, ar, etc.

6. limit

   Limits the maximum number of results returned.

7. pageno

   Page number of search results; defaults to 1.

8. seafesearch

   Explicit content filter levels:

   • 0: off
   • 1: moderate
   • 2: strict

9. country

   Filters results based on the specified country code.

10. categories

    Search within specific categories:
    general (default), images, videos, news, books, maps, shaping, other

11. api_mode

    Different API output modes:

• merged (default):
  Results from all active search engines are merged and the total number of results is limited.

{
  "number_of_results": 0,
  "results": {
    "<index>": {
      "title": "str",
      "url": "str",
      "content": "str",
      "engine": ["str"]  // or just "str"
    }
  },
  "pre_plugins": {
    "<plugin_name>": "Any"
  },
  "post_plugins": {
    "<plugin_name>": "Any"
  }
}

<index> is a numeric counter from 0 up to x.

• normal: Raw results from each engine are returned separately without merging.

{
  "number_of_results": 0,
  "results": {
    "<engine_name>": {
      "results": [
        {
          "title": "str",
          "url": "str",
          "content": "str"
        }
      ],
      "metadata": {
        "page": "int (optional)",
        "category": "str (optional)",
        "status": "str (optional)"
      }
    }
  },
  "pre_plugins": {
    "<plugin_name>": "Any"
  },
  "post_plugins": {
    "<plugin_name>": "Any"
  }
}

• stream: A more dynamic mode where results from each engine are sent separately and incrementally in multiple JSON lines.

Example output:

{"type": "engine_result", "name": "<engine_name>", "result": {"error": "error...", "metadata": {"status": "failed"}}}
{"type": "engine_result", "name": "<engine_name>", "result": {"results": [{"title": "", "url": "", "content": ""},]}}
{"type": "number_of_results", "data": 0}
{"type": "done", "data": "[DONE]"}

Each line is a separate JSON object. After all engines send their results, a summary with the number of results and a final done message are sent.

---

Important Notes

Some parameters may not be supported by all engines. Unsupported values by any engine will be ignored.