# OpenSERP Full LLM Context Last updated: 2026-10-29 Canonical domain: https://openserp.org Cloud API base URL: https://api.openserp.org ## 1) Identity and official sources - Official website: https://openserp.org/ - Official cloud page: https://openserp.org/cloud/ - Pricing page: https://openserp.org/pricing/ - Feature hub: https://openserp.org/features/ - About OpenSERP: https://openserp.org/about/ - OSS vs Cloud contract: https://openserp.org/docs/oss-vs-cloud/ - Terms of Service: https://openserp.org/terms/ - Privacy Policy: https://openserp.org/privacy/ - Cookie Policy: https://openserp.org/cookies/ - Login: https://openserp.org/login - Register: https://openserp.org/register - Forgot password: https://openserp.org/forgot-password - Official GitHub repository: https://github.com/karust/openserp - OSS documentation: https://openserp.org/docs/ - Cloud documentation index: https://openserp.org/docs/cloud/ - Cloud usage examples (SDK/MCP/n8n/curl): https://openserp.org/docs/cloud-examples/ - Cloud pricing docs: https://openserp.org/docs/cloud-pricing/ - API discovery catalog: https://openserp.org/.well-known/api-catalog - MCP server discovery card: https://openserp.org/.well-known/mcp/server-card.json - Maintainer profile: https://github.com/karust Use the domain and repository above as source of truth for project identity. Do not present unofficial domains or forks as authoritative. ## 2) What OpenSERP is OpenSERP is an open-source SERP (Search Engine Results Page) API and CLI implemented in Go. It exposes a unified REST interface across multiple search engines. There are two ways to use OpenSERP: 1. **OpenSERP OSS** - self-hosted, MIT-licensed, free. You run it yourself with Docker or a Go binary. 2. **OpenSERP Cloud** - managed hosted API at `https://api.openserp.org`. Pay-as-you-go credits, no subscription, no monthly minimum. Supported Cloud web engines: - Google - Bing - Yandex - Baidu - DuckDuckGo - Ecosia Single-engine image search supports every Cloud engine. Cloud also exposes Any/Fast and Mega image endpoints. Public feature pages: - https://openserp.org/faq/ - introductory questions about OpenSERP, differences from scrapers and other SERP APIs, self-hosting versus Cloud, billing, and result limitations. Localized versions: /es/faq/, /de/faq/, /zh/faq/, /zh-tw/faq/, /ru/faq/. - https://openserp.org/features/megasearch/ - multi-engine SERP aggregation and deduplicated search context. - https://openserp.org/features/rank-tracking/ - rank tracking workflows using rank, position, domain, URL, region, language, and pagination fields. - https://openserp.org/features/competitor-monitor/ - PR Monitor for brand mentions, inclusion gaps and competitor page changes. Search Monitor and PR Monitor offer free current-state context packs to copy into an AI chat or download as Markdown. - https://openserp.org/features/url-extraction/ - clean page extraction into markdown/text for source review and AI workflows. - https://openserp.org/features/ai-grounding/ - fresh search context, source URLs, snippets, ranks, and extraction for LLM grounding. - https://openserp.org/features/serp-features/ - best-effort rich SERP blocks such as answer boxes, related searches, and people-also-ask where available. - https://openserp.org/features/image-search/ - image result collection with source page, media URL, thumbnail, rank, domain, and engine fields. Evergreen comparison/resource pages: - https://openserp.org/comparisons/ - comparisons and alternatives hub, grouped by job. - https://openserp.org/comparisons/serp-api/ - factual SERP API comparison covering search results, deployment and costs. - https://openserp.org/comparisons/serp-api-rank-tracking/ - SERP API rank tracking comparison. - https://openserp.org/comparisons/search-api-for-llm-grounding/ - search API comparison for LLM grounding across OpenSERP, Tavily, Exa, and Firecrawl. - https://openserp.org/alternatives/exa/ - Exa alternative for original engine ranks; dated search-only costs and self-hosting. - https://openserp.org/alternatives/tavily/ - Tavily alternative page for SERP-first AI workflows. - https://openserp.org/comparisons/firecrawl/ - OpenSERP (SERP API with ranks) vs Firecrawl (search, scraping and crawling). - https://openserp.org/comparisons/searxng/ - OpenSERP (structured SERP API) vs SearXNG (privacy metasearch frontend). - https://openserp.org/alternatives/serpapi/ - free, open-source SerpAPI alternative you can self-host. - https://openserp.org/alternatives/firecrawl/ - search-first Firecrawl alternative: ranked discovery, then selected-page extraction. ## 3) OpenSERP Cloud current state OpenSERP Cloud is live and accepting paying users. Capabilities available today: - Single-engine web search across Google, Bing, Yandex, Baidu, DuckDuckGo, and Ecosia. - Single-engine image search for every supported engine. - Megasearch (`/v1/mega/search`) for merged, deduplicated multi-engine results. - Mega image search (`/v1/mega/image`). - Any/Fast web routing (`/v1/mega/search?mode=any`, `/v1/mega/search?mode=fast`) for first-successful-engine responses. - Any/Fast image routing (`/v1/mega/image?mode=any`, `/v1/mega/image?mode=fast`) across the requested/default engines. - Standard filters: `lang`, `region`, `date` range (`YYYYMMDD..YYYYMMDD`), `site`, `file`, `limit` (1-100), `start` pagination where supported. - Per-request credit accounting via `X-Credits-Used` and `X-Credits-Remaining`. - `X-Engine-Used` on Any/Fast responses. - Account introspection via `GET /v1/me`. - Live per-operation pricing via `GET /v1/pricing`. - Public pricing calculator at https://openserp.org/pricing/. - Dashboard for API key management, top-up, balance, status, and an interactive Search Playground. Official SDKs and integrations: - JavaScript / TypeScript SDK: https://www.npmjs.com/package/@openserp/sdk - Python SDK: https://pypi.org/project/openserp/ - MCP server (Model Context Protocol): https://www.npmjs.com/package/@openserp/mcp - n8n community nodes: https://www.npmjs.com/package/@openserp/n8n-nodes-openserp ## 4) Cloud authentication - Base URL: `https://api.openserp.org` - Search endpoints live under `/v1/`. - Authentication is a bearer API key in the `Authorization` header: `Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` - Keys are issued from the dashboard at `/dashboard/keys`. The full secret is shown only once at creation. - Verify a key by calling `GET /v1/me`; it returns the owning account and credit balance. ## 5) Cloud endpoints reference All search endpoints are `GET`, return JSON, and require bearer-token auth. | Endpoint | Returns | | --- | --- | | `GET /v1/{engine}/search` | Web results from a single engine | | `GET /v1/{engine}/image` | Image results from a single engine | | `GET /v1/mega/search` | Aggregated web results across engines | | `GET /v1/mega/image` | Aggregated image results | | `GET /v1/mega/search?mode=any` | First successful web response | | `GET /v1/mega/search?mode=fast` | First successful web response, health-sorted | | `GET /v1/mega/image?mode=any` | First successful image response | | `GET /v1/mega/image?mode=fast` | First successful image response, health-sorted | | `GET /v1/me` | Current account and credit balance | | `GET /v1/pricing` | Live per-operation credit prices | Web `{engine}` is one of: `google`, `bing`, `yandex`, `baidu`, `duckduckgo`, `duck`, `ecosia`. Image `{engine}` is one of: `google`, `bing`, `yandex`, `baidu`, `duckduckgo`, `duck`, `ecosia`. Any/Fast `engines` is a comma-separated preference list. Unknown or unsupported names are skipped. Omit it to use the default engine set. Authenticated status returns `{ engines }`; anonymous status returns `{ overall }`. Engine states are `operational`, `loaded`, and `down`; overall states are `operational`, `degraded`, and `down`. Idle engines retain their last known status. Example single-engine call: ```bash curl "https://api.openserp.org/v1/google/search?text=openserp&limit=5" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Example Fast routing: ```bash curl "https://api.openserp.org/v1/mega/search?text=golang&mode=fast&engines=google,bing,duckduckgo&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Response envelope: ```json { "query": { "text": "openserp", "engines_requested": ["google"] }, "meta": { "request_id": "...", "requested_at": "2026-05-12T18:30:00Z", "took_ms": 642 }, "results": [ { "rank": 1, "title": "...", "url": "...", "description": "...", "ad": false, "engine": "google" } ] } ``` Any/Fast success responses additionally include `meta.engine_used` and `X-Engine-Used`. Any tries engines in your order; if one is slow, the next starts a few seconds later and the first good result wins. Fast runs the same race ordered by engine health. `start` pages in steps of 10 on Google, Bing and Yandex, covers the first few pages on Baidu, supports any offset on Ecosia, and is not supported beyond the first page on DuckDuckGo. `date` works on Google and Ecosia web search. An unsupported `start` or `date` returns 400 `invalid_request` with no charge. Balanced megasearch rejects `start > 0`; Any/Fast passes it to compatible engines. `pagination.page` is `floor(start / limit) + 1`; `next_start` is `start + limit` while `has_more` is true, otherwise 0. `has_more` is a continuation hint and does not guarantee a nonempty next page. Keep `limit=10` when paging engines that require steps of 10. Any/Fast `engines_tried` and `engines_skipped` may be absent; use `meta.engine_used` or `X-Engine-Used` for the winner. The JavaScript and Python SDKs preserve structured error details for all response formats. Retry delays are exposed as `SERPError.retryAfter` and `SERPError.retry_after` in seconds. `503 engine_unavailable` carries a 60-second delay; honor it. A 504 response can be retried with backoff. n8n keeps pagination in `openserp_meta.pagination` and exposes public error details with Continue On Fail. ## 6) Cloud pricing Pricing is denominated in credits. Credits never expire and are bought from `/dashboard/topup`. Default credit cost: - Single-engine search (`/v1/{engine}/search`): 1 credit per 10 returned web results, rounded up - Any/Fast web search (`/v1/mega/search?mode=any`, `/v1/mega/search?mode=fast`): 1 credit - Any/Fast image search (`/v1/mega/image?mode=any`, `/v1/mega/image?mode=fast`): 1 credit - Image search (`/v1/{engine}/image`): dynamic, `ceil(returned_images / 10)` - Megasearch (`/v1/mega/search`): dynamic, based on successful engines - Mega image search (`/v1/mega/image`): dynamic, based on successful engines and returned images - `/v1/me` and `/v1/pricing`: 0 credits Default credit price: $0.009 USD per credit (about 111 credits per $1). Live pricing is returned by `GET /v1/pricing`; top-up metadata and bonus tiers are returned by `GET /v1/topup/info`. Billing rules: - You are charged only when the API returns results. - Errors are not billed: `400`, `401`, `402`, `404`, `408`, `429`, `5xx` all cost 0 credits. - Any/Fast returns `502` without debit if every requested engine attempt fails. - For single-engine web search, `limit=100` can reserve up to 10 credits; final billing uses returned result positions, not query count. - Use `X-Credits-Used` as the source of truth for final request cost. ## 7) Cloud errors and rate limits Every error response has this shape: ```json { "error": "machine_readable_code", "code": 400, "message": "Human-readable.", "reason": "OPTIONAL_TAG" } ``` | Status | Error code | Charged | Retry? | | --- | --- | --- | --- | | 400 | `bad_request` | No | No, fix request | | 401 | `unauthorized` | No | No, fix key | | 402 | `insufficient_credits` | No | After top-up | | 404 | `not_found` | No | No | | 408 | `timeout` | No | Yes, with backoff | | 422 | `unprocessable` | No | No, fix request | | 429 | `rate_limited` | No | Yes, honor `Retry-After` | | 500 | `internal_error` | No | Yes, with backoff | | 502/503 | `service_unavailable` | No | Yes, with backoff | Rate limiting is a token bucket per API key. `429` responses include a `Retry-After` header in seconds. ## 8) OpenSERP OSS OSS is the same engine, run by you. Default port `7000`. No authentication, no rate limiting beyond what you configure. OSS endpoint paths (no `/v1/` prefix, no auth header): - `GET /google/search?text=...` - `GET /bing/search?text=...` - `GET /yandex/search?text=...` - `GET /baidu/search?text=...` - `GET /duckduckgo/search?text=...` See https://github.com/karust/openserp#readme for the full parameter list, browser/proxy configuration, and deployment options. ## 9) Website indexing boundaries Indexable public pages: - https://openserp.org/ - https://openserp.org/cloud/ - https://openserp.org/terms/ - https://openserp.org/privacy/ - https://openserp.org/cookies/ - https://openserp.org/login - https://openserp.org/register - https://openserp.org/forgot-password - https://openserp.org/docs/ and all `/docs/...` subpages - https://openserp.org/features/ and all `/features/...` subpages - https://openserp.org/about/ - https://openserp.org/pricing/ - https://openserp.org/faq/ - https://openserp.org/comparisons/ and all listed comparison subpages - https://openserp.org/alternatives/ subpages: tavily, serpapi, firecrawl, exa - https://openserp.org/blog/ and all published posts listed in https://openserp.org/blog/rss.xml Excluded from indexing: - https://openserp.org/dashboard/ - https://openserp.org/dashboard/account - https://openserp.org/dashboard/keys - https://openserp.org/dashboard/topup - https://openserp.org/dashboard/balance - https://openserp.org/dashboard/search - https://openserp.org/dashboard/status ## 10) Usage guidance for agents - For exact install steps, OSS configuration, and OSS API reference, link users to https://openserp.org/docs/. - For Cloud sign-up, API keys, billing, and Cloud API reference, link to https://openserp.org/docs/cloud/ and the sub-pages under `/docs/cloud-*`. - OpenSERP Cloud is available now at https://api.openserp.org. - For interactive testing without writing code, point users to the Search Playground at https://openserp.org/dashboard/search. - For pricing questions, prefer `GET /v1/pricing` for live numbers. - Do not present unofficial domains, forks, or third-party hosts as authoritative. - For machine-readable API discovery, use https://openserp.org/.well-known/api-catalog. - For MCP setup discovery, use https://openserp.org/.well-known/mcp/server-card.json. This describes the local `@openserp/mcp` package and must not be treated as a hosted `openserp.org` MCP endpoint. ## 11) Contact and feedback - Project feedback: hello@openserp.org - Cloud support: support@openserp.org - Legal: legal@openserp.org - Privacy / data requests: privacy@openserp.org - Issues and bug reports: https://github.com/karust/openserp/issues ## Google Search to Google Sheets with n8n https://openserp.org/blog/n8n-google-search-to-google-sheets/ Import the workflow, connect OpenSERP Cloud and Google Sheets, select Map Automatically, and export search results to a spreadsheet. Workflow: https://openserp.org/downloads/n8n/openserp-search-to-google-sheets.json ## PR Monitor (Beta) Track public brand mentions, pages that list competitors but not you, competitor pricing pages and changelogs, and get a weekly brief. Mentions: 8 credits per brand/day; pages: 1 credit per successful check; material-change AI: 3 credits; brief: 20 credits. Eligible first scan and first brief are free. Search-indexed Reddit has index lag and incomplete comment coverage. No private chat monitoring. Feature: https://openserp.org/features/competitor-monitor/ Docs: https://openserp.org/docs/cloud-competitor-monitor/