feat(docs): add search API docs

README.md

@@ -12,6 +12,7 @@
   - [Non-Docker Installation](#non-docker-installation)
   - [Ollama Connection Errors](#ollama-connection-errors)
 - [Using as a Search Engine](#using-as-a-search-engine)
+- [Using Perplexica's API](#using-perplexicas-api)
 - [One-Click Deployment](#one-click-deployment)
 - [Upcoming Features](#upcoming-features)
 - [Support Us](#support-us)
@@ -45,6 +46,7 @@ Want to know more about its architecture and how it works? You can read it [here
   - **Wolfram Alpha Search Mode:** Answers queries that need calculations or data analysis using Wolfram Alpha.
   - **Reddit Search Mode:** Searches Reddit for discussions and opinions related to the query.
 - **Current Information:** Some search tools might give you outdated info because they use data from crawling bots and convert them into embeddings and store them in a index. Unlike them, Perplexica uses SearxNG, a metasearch engine to get the results and rerank and get the most relevant source out of it, ensuring you always get the latest information without the overhead of daily data updates.
+- **API**: Integrate Perplexica into your existing applications and make use of its capibilities.
 
 It has many more features like image and video search. Some of the planned features are mentioned in [upcoming features](#upcoming-features).
 
@@ -125,6 +127,12 @@ If you wish to use Perplexica as an alternative to traditional search engines li
 3. Add a new site search with the following URL: `http://localhost:3000/?q=%s`. Replace `localhost` with your IP address or domain name, and `3000` with the port number if Perplexica is not hosted locally.
 4. Click the add button. Now, you can use Perplexica directly from your browser's search bar.
 
+## Using Perplexica's API
+
+Perplexica also provides an API for developers looking to integrate its powerful search engine into their own applications. You can run searches, customize models, and get results tailored to your needs.
+
+For more details, check out the full documentation [here](https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/API/SEARCH.md).
+
 ## One-Click Deployment
 
 [![Deploy to RepoCloud](https://d16t0pc4846x52.cloudfront.net/deploylobe.svg)](https://repocloud.io/details/?app_id=267)
@@ -135,6 +143,7 @@ If you wish to use Perplexica as an alternative to traditional search engines li
 - [x] Adding support for local LLMs
 - [x] History Saving features
 - [x] Introducing various Focus Modes
+- [x] Adding API support
 - [ ] Finalizing Copilot Mode
 - [ ] Adding Discover
 

docs/API/SEARCH.md

@@ -0,0 +1,105 @@
+# Perplexica Search API Documentation
+
+## Overview
+
+Perplexica’s Search API makes it easy to use our AI-powered search engine. You can run different types of searches, pick the models you want to use, and get the most recent info. Follow the following headings to learn more about Perplexica's search API.
+
+## Endpoint
+
+### **POST** `/api/search`
+
+### Request
+
+The API accepts a JSON object in the request body, where you define the focus mode, chat models, embedding models, and your query.
+
+#### Request Body Structure
+
+```json
+{
+  "chatModel": {
+    "provider": "openai",
+    "model": "gpt-4o-mini"
+  },
+  "embeddingModel": {
+    "provider": "openai",
+    "model": "text-embedding-3-large"
+  },
+  "focusMode": "webSearch",
+  "query": "What is Perplexica",
+  "history": []
+}
+```
+
+### Request Parameters
+
+- **`chatModel`** (object, optional): Defines the chat model to be used for the query.
+
+  - `provider`: Specifies the provider for the chat model (e.g., `openai`, `ollama`).
+  - `model`: The specific model from the chosen provider (e.g., `gpt-4o-mini`).
+  - Optional fields for custom OpenAI configuration:
+    - `customOpenAIBaseURL`: If you’re using a custom OpenAI instance, provide the base URL.
+    - `customOpenAIKey`: The API key for a custom OpenAI instance.
+
+- **`embeddingModel`** (object, optional): Defines the embedding model for similarity-based searching.
+
+  - `provider`: The provider for the embedding model (e.g., `openai`).
+  - `model`: The specific embedding model (e.g., `text-embedding-3-large`).
+
+- **`focusMode`** (string, required): Specifies which focus mode to use. Available modes:
+
+  - `webSearch`, `academicSearch`, `writingAssistant`, `wolframAlphaSearch`, `youtubeSearch`, `redditSearch`.
+
+- **`query`** (string, required): The search query or question.
+
+- **`history`** (array, optional): An array of message pairs representing the conversation history. Each pair consists of a role (either 'human' or 'assistant') and the message content. This allows the system to use the context of the conversation to refine results. Example:
+  ```json
+  [
+    ["human", "What is Perplexica?"],
+    ["assistant", "Perplexica is an AI-powered search engine..."]
+  ]
+  ```
+
+### Response
+
+The response from the API includes both the final message and the sources used to generate that message.
+
+#### Example Response
+
+```json
+{
+	"message": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online. Here are some key features and characteristics of Perplexica:\n\n- **AI-Powered Technology**: It utilizes advanced machine learning algorithms to not only retrieve information but also to understand the context and intent behind user queries, providing more relevant results [1][5].\n\n- **Open-Source**: Being open-source, Perplexica offers flexibility and transparency, allowing users to explore its functionalities without the constraints of proprietary software [3][10].",
+	"sources": [
+		{
+			"pageContent": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online.",
+			"metadata": {
+				"title": "What is Perplexica, and how does it function as an AI-powered search ...",
+				"url": "https://askai.glarity.app/search/What-is-Perplexica--and-how-does-it-function-as-an-AI-powered-search-engine"
+			}
+		},
+		{
+			"pageContent": "Perplexica is an open-source AI-powered search tool that dives deep into the internet to find precise answers.",
+			"metadata": {
+				"title": "Sahar Mor's Post",
+				"url": "https://www.linkedin.com/posts/sahar-mor_a-new-open-source-project-called-perplexica-activity-7204489745668694016-ncja"
+			}
+		}
+        ....
+	]
+}
+```
+
+### Fields in the Response
+
+- **`message`** (string): The search result, generated based on the query and focus mode.
+- **`sources`** (array): A list of sources that were used to generate the search result. Each source includes:
+  - `pageContent`: A snippet of the relevant content from the source.
+  - `metadata`: Metadata about the source, including:
+    - `title`: The title of the webpage.
+    - `url`: The URL of the webpage.
+
+### Error Handling
+
+If an error occurs during the search process, the API will return an appropriate error message with an HTTP status code.
+
+- **400**: If the request is malformed or missing required fields (e.g., no focus mode or query).
+- **500**: If an internal server error occurs during the search.