Multi-Engine Web Search via POST /v1/search

SIRS is Piramyd’s self-hosted multi-engine search service, powered by SearXNG. Submit a natural-language or keyword query and receive ranked results with titles, snippets, source engines, relevance scores, and publication dates. Set include_content: true to concurrently scrape each result via CROWD, attaching full page markdown directly to each result object — useful when you want enriched context without a separate scrape call.

When you need full page content alongside search results, prefer POST /v1/crowd/search — it uses Firecrawl’s native search-and-scrape pipeline in a single optimized call, rather than performing parallel scrapes after the fact.

Endpoint

POST https://api.piramyd.cloud/v1/search

Authentication: Authorization: Bearer sk-<key>

Request Parameters

string

required

The search query to run across all configured engines.

integer

default:"5"

Maximum number of results to return. Accepted range: 1–20.

boolean

default:"false"

When true, each result is enriched with a full_content field containing the full page markdown, fetched concurrently via CROWD (Firecrawl).

string

default:"auto"

BCP-47 language code to filter results (e.g. "en", "pt") or "auto" to let SIRS infer from the query.

string

default:"general"

Search category. One of: general, news, science, it, social media, videos, music, files, images, map.

integer

default:"30"

Maximum time in seconds to wait for upstream engines to respond. Accepted range: 5–60.

Response

array

Array of ranked search result objects.

Show result object fields

string

Page title as returned by the search engine.

string

Canonical URL of the result.

string

Snippet or description extracted by the search engine.

string[]

List of engines that returned this result (e.g. ["google", "bing"]).

number

Relevance score assigned by SIRS (0–1, higher is more relevant).

string

ISO 8601 publication date, if available.

string

The category this result was retrieved under.

string

Full page markdown content fetched via CROWD. Only present when include_content: true.

string[]

Query suggestions returned by the search engines.

string[]

Spelling corrections suggested for the query, if any.

integer

Number of results returned in this response.

string

The original query string as received by the API.

Code Example

import httpx

PIRAMYD_KEY = "sk-YOUR_KEY"
BASE = "https://api.piramyd.cloud/v1"
HEADERS = {"Authorization": f"Bearer {PIRAMYD_KEY}"}

resp = httpx.post(
    f"{BASE}/search",
    headers=HEADERS,
    json={
        "text_query": "latest breakthroughs in protein folding 2025",
        "limit": 5,
        "include_content": False,
        "language": "en",
        "categories": "science",
        "timeout_seconds": 30,
    },
)

data = resp.json()
print(f"Query: {data['query']}")
print(f"Results: {data['number_of_results']}")

for result in data["results"]:
    print(f"\n[{result['score']:.2f}] {result['title']}")
    print(f"  URL: {result['url']}")
    print(f"  Engines: {', '.join(result['engines'])}")
    print(f"  Snippet: {result['content'][:120]}...")

{
  "text_query": "latest breakthroughs in protein folding 2025",
  "limit": 5,
  "include_content": false,
  "language": "en",
  "categories": "science",
  "timeout_seconds": 30
}

{
  "results": [
    {
      "title": "AlphaFold 3 — Nature",
      "url": "https://www.nature.com/articles/s41586-024-07487-w",
      "content": "Google DeepMind's AlphaFold 3 predicts...",
      "engines": ["google", "bing"],
      "score": 0.97,
      "publishedDate": "2024-05-08T00:00:00Z",
      "category": "science"
    }
  ],
  "suggestions": ["protein structure prediction"],
  "corrections": [],
  "number_of_results": 5,
  "query": "latest breakthroughs in protein folding 2025"
}

Errors

Error code	HTTP status	Description
`search_timeout`	504	SIRS did not respond within `timeout_seconds`. Retry with backoff or increase the timeout.
`search_upstream_error`	502	An upstream search engine returned an error. Retry with backoff.
`search_unavailable`	502	The SIRS service is temporarily unavailable. Retry with backoff.
`search_internal_error`	500	Unexpected internal error. Retry with backoff.

All error responses follow the standard Piramyd error shape: { "error": { "message": "...", "type": "...", "code": "..." } }. Retry 502, 504, and 500 with exponential backoff (base 1 s, max 8 s, with jitter). Respect Retry-After on 429.

Inference

Models

Web Intelligence

Account

Multi-Engine Web Search via POST /v1/search — SIRS

Endpoint

Request Parameters

Response

Code Example

Errors

​Endpoint

​Request Parameters

​Response

​Code Example

​Errors

Endpoint

Request Parameters

Response

Code Example

Errors