API Endpoints¶

Detailed documentation for all Polymathy API endpoints.

Search Endpoint¶

`GET /v1/search`¶

Process a search query, retrieve content from results, and return semantic chunks.

Parameters¶

Parameter	Type	Required	Description
`q`	string	Yes	The search query

Request Example¶

curl "http://localhost:8080/v1/search?q=machine+learning+basics"

Response¶

Returns a JSON object mapping chunk IDs to [url, content] tuples.

{
  "0": ["https://example.com/ml-intro", "Machine learning is a subset of artificial intelligence..."],
  "1": ["https://example.com/ml-intro", "The most common types of machine learning include..."],
  "2": ["https://another-site.com/ml", "Getting started with machine learning requires..."]
}

Response Fields¶

Field	Type	Description
`key`	string	Sequential chunk ID (0, 1, 2, ...)
`value[0]`	string	Source URL where the content was found
`value[1]`	string	The content chunk (approximately 100 words)

Processing Flow¶

sequenceDiagram
    participant C as Client
    participant P as Polymathy
    participant S as SearxNG
    participant PR as Processor

    C->>P: GET /v1/search?q=query
    P->>S: Forward search query
    S-->>P: Return URLs
    loop For each URL (max 10)
        P->>PR: Process URL
        PR-->>P: Return chunks + embeddings
    end
    P-->>C: Return chunk map

Example: Python Client¶

import requests

def search(query: str) -> dict:
    response = requests.get(
        "http://localhost:8080/v1/search",
        params={"q": query}
    )
    response.raise_for_status()
    return response.json()

# Usage
results = search("rust async programming")
for chunk_id, (url, content) in results.items():
    print(f"[{chunk_id}] {url}")
    print(f"    {content[:100]}...")

Example: JavaScript/TypeScript¶

async function search(query: string): Promise<Record<string, [string, string]>> {
  const response = await fetch(
    `http://localhost:8080/v1/search?q=${encodeURIComponent(query)}`
  );

  if (!response.ok) {
    throw new Error(`Search failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const results = await search("web development");
Object.entries(results).forEach(([id, [url, content]]) => {
  console.log(`[${id}] ${url}: ${content.slice(0, 100)}...`);
});

Error Responses¶

Status	Cause	Example
400	Missing query parameter	`{"error": "Missing query parameter 'q'"}`
500	SearxNG unavailable	`{"error": "Failed to fetch search results"}`
500	Processor unavailable	`{"error": "Content processing failed"}`

Rate Limiting¶

Polymathy itself does not implement rate limiting. Rate limits depend on:

Your SearxNG instance configuration
Any reverse proxy settings
The content processor's capacity

Production Deployments

Implement rate limiting at the reverse proxy level for production use.