# OpenSERP Full LLM Context

Last updated: 2026-07-27
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/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/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/serp-api/ - factual SERP API comparison across OpenSERP, SerpAPI, DataForSEO, Zenserp, and Serper.
- 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/tavily/ - Tavily alternative page for SERP-first AI workflows.

## 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. Default web and image order is `google,bing,duckduckgo,yandex,baidu,ecosia`.

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`, `meta.engines_tried`, optional `meta.engines_skipped`, and `X-Engine-Used`.

## 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/comparisons/ and all listed comparison subpages
- https://openserp.org/alternatives/tavily/
- https://openserp.org/blog/multi-engine-rank-tracking/
- https://openserp.org/blog/multi-engine-serp-data-yandex-baidu-bing/
- https://openserp.org/blog/self-hosted-rank-tracker/

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