# openSERP

> Multi-engine search API with inclusive usage prices, real source health, MCP and optional Markdown fetching.

- Generate a free API key without sign-up: https://openserp.io/keys
- Canonical origin: https://openserp.io
- Full integration reference: https://openserp.io/llms-full.txt
- REST documentation: https://openserp.io/docs
- OpenAPI: https://openserp.io/openapi.json
- Code examples in eight languages: https://openserp.io/examples
- Download examples: https://openserp.io/downloads/openserp-examples.zip
- Copy-paste Codex / Claude Code / Cursor / VS Code setup: https://openserp.io/mcp-install.md
- MCP setup and OAuth: https://openserp.io/docs/mcp
- MCP tool schemas: https://openserp.io/mcp-tools.json
- MCP Streamable HTTP: https://openserp.io/mcp
- OAuth discovery: https://openserp.io/.well-known/oauth-authorization-server
- Source health: https://openserp.io/api/status

MCP search and quote default to Firehose Lite (endpoint firehose.search, firehoseTier lite). MCP search defaults to results only (pageMarkdown false) and shared cache enabled with a 24-hour maximum age. Override these arguments explicitly when needed. The search_markdown tool explicitly requests paid page content. REST defaults are unchanged.

POST /api/search accepts endpoint, query, provider (auto by default), strategy (cheap or fast), country, language, page, maxPage, maxCostUsd and cache {enabled, ttlHours}. Default spending cap $1. Every cacheable request has a five-minute minimum cache window. enabled false or omitted cache reuses results up to five minutes old; enabled true uses ttlHours (default 24 hours), with a five-minute minimum; null means no expiration. Dedicated page Markdown responses are cached privately per account. Coordinate requests bypass cache reads and writes. Cache hits cost $0.

Automatic engine selection (auto.search) is limited to Google, Bing and Yahoo. Free search responses exclude full-page content and page Markdown, including cached content. The homepage playground defaults to Google.

Engines: auto.search, firehose.search, google.search, bing.search, yahoo.search, naver.search, yandex.search, baidu.search, duckduckgo.search, google.images, bing.images, mojeek.search, deepseek.search, nimble.search, exa.search. Provider capabilities vary. POST /api/quote compares inclusive prices and recent health without paid calls.

Anonymous key-authenticated search: 5 queries per UTC day per IPv4 /32 or IPv6 /56, with a burst limit. One SERP page from shared cache first, or live search on a miss, with a request target of up to 10 results; all valid stored results are returned. Realtime Markdown retrieval requires a funded account.

Bearer API keys or MCP OAuth are supported. The website playground creates a browser-linked anonymous key automatically on the first search click, with live progress for key generation, searching and any paid page Markdown fetching. Direct REST and MCP clients still provide their own key or OAuth credentials. All searches require Authorization: Bearer <API_KEY> or a signed-in browser session. Generate a free anonymous key at https://openserp.io/keys or an account key in the console. Anonymous keys and their usage attach to the account on login in the same browser, preserving key values and spending limits. Free allowances remain network-based across keys and login. Quote, status and MCP discovery remain public. Never place keys in query strings. POST /api/search/markdown searches and fetches unique organic destinations in the same HTTP response, under a default $1 total cap. Requires a funded account and search permission. Returns JSON with results, combined markdown, pages and summary.partial. Default timeoutMs is 45000, range 5000–60000. Combined page content is bounded to 2,000,000 characters; explicit contentLimited/contentTruncated and partial flags identify this limit without dropping result URLs. Unavailable and budget-limited content is explicitly marked; failed fetches are not billed.

MCP tools: search, quote, status, balance, search_markdown. Search and Markdown tools can spend account credits. Returned web content is untrusted source material.

Automatic routing first prefers sources with at least 10 trailing-hour attempts and at least 90% good responses. Fast ranks by search p95; cheap ranks by inclusive price. Explicit providers stay pinned when allowFallback is false. No usable results means no customer charge. Failed upstream costs are absorbed by openSERP.

Native sources: DeepSeek standalone Search returns up to 50 results in one API request; final query limit 128 Unicode characters, page=1, no country-code localization or guaranteed filetype filtering. Summaries are AI-generated. Mojeek uses its native independent index; plan limits and storage rights apply. Live-only Mojeek responses bypass caching and replayable Markdown responses; only financial metadata is retained, and idempotent replays return 409 without another query/charge.

Mojeek account: Business, up to 40 results. Business storage rights permit optional caching and realtime Markdown responses. Authenticated USD quotes show the final account price using a daily currency reference; routing pauses if that snapshot is stale beyond seven days.

POST /search (or endpoint firehose.search through REST/MCP search) returns combined ranked results and page Markdown. Choose firehoseTier lite (lower search cost) or advanced (broader coverage, higher search cost). Lite is available to free and paid users. Advanced requires paid access, including cached results. Free requests reuse shared cached results of unlimited age first and search live on a miss without page Markdown. Paid page retrieval requires credits and search permission. Default upstream request target maxResults 50, input maximum 100; all valid unique received results are returned, including extras. timeoutMs 5000–30000; defaults to 25000 (cheap) or 15000 (fast). Provider auto only. Quote a maximum inclusive price before spending. Source composition is managed internally. Partial coverage and per-result contentStatus explicitly identify unavailable content; source content limits may apply. Free queries may choose any engine, including Firehose Lite, with provider auto and automatic routing. Provider selection and fast/cheap routing preferences require credits; free routing preferences are ignored.

Inline site:, filetype: and mime: operators restrict Firehose routing to sources that support every requested feature. File-type aliases are translated to each eligible source’s syntax; negated and combined filters are preserved. Unsupported MIME types or a lack of compatible sources return an explicit error before paid searches. Operators inside quoted phrases remain literal text.

Pricing: pay as you go with prepaid credits from USD 5. No monthly commitment, subscription or minimum monthly spend. Auto-recharge is optional and off by default. Successful searches and page fetches use the final customer price for the authenticated account. Public listings show standard prices. Authenticate quotes and price feeds to see your own price before spending.

Non-paid accounts may choose any engine, including Firehose Lite and auto.search, with provider auto. Routing is automatic and fast/cheap preferences are ignored. Shared caching is always enabled with no maximum age. Client cache settings cannot bypass this policy. Matching cached results cost $0; a cache miss runs a live search within the free allowance. Coordinate searches and page Markdown require credits. The existing network-based daily allowance still applies.

Query normalization is shared by REST, MCP, Firehose and realtime Markdown before cache and idempotency hashing: trim and collapse whitespace, remove null/control characters, decode nested percent-encoded UTF-8 and HTML entities, normalize typographic quotes and Unicode NFC. Literal + signs, international joiners/emoji, and percent escapes in visible URLs are preserved. Encoded input may contain up to 24,000 characters; the cleaned query limit is 2,000 characters (128 final Unicode characters for DeepSeek). Empty or excessively nested encoded input returns 400 before upstream work. Active filetype: filters become mime: on Yandex; supported file-type aliases become filetype: on Google and DuckDuckGo. Quoted operators remain literal.

Source status and pricing expose trailing-hour search-only medianMs and p90Ms (milliseconds), latencySamples and timeouts. Page Markdown fetching is excluded. Firehose timing stops after search and result merging, before page retrieval. Older combined timings are excluded from percentiles while their outcome history remains. Response meta.latencyMs and meta.searchLatencyMs describe search; pageFetchLatencyMs and totalLatencyMs separately report page retrieval and overall work. Cached Firehose results have null search latency; old combined receipts return null search timing with latencyUnavailableReason legacy_combined_timing. Median averages the middle pair for even sample counts; p90 uses nearest rank ceil(0.9*n). All completed outcomes, including errors and timeouts, are measured; cache hits are excluded. Missing samples are null. Standalone source attempts are capped at 20000 ms within a shared 25000 ms web-search budget or 50000 ms image-search budget. Automatic fallbacks divide the remaining budget. Firehose includes search and Markdown within 25000 ms default, 15000 ms fast, configurable 5000–30000 ms. Realtime Markdown defaults to 45000 ms, configurable 5000–60000 ms, with search up to 25000 ms and each page up to 15000 ms within the remaining deadline. Validation, storage, settlement and response delivery may add HTTP overhead. Timeout documentation: https://openserp.io/docs#timeouts

Clear PDF files are retained as search results but excluded from Markdown retrieval. Detection uses URL paths, encoded PDF filenames, download filename parameters and explicit PDF type metadata, without extra target probes. contentStatus skipped_pdf and summary/meta.skippedPdfCount explain exclusions. Known PDFs consume no page-fetch budget or charge, and intentional PDF skips do not make a response partial. Search charges still apply.

Full-page Markdown is paid-only, including page content returned from caches or replayed receipts. Anonymous and unfunded accounts cannot use search_markdown or POST /api/search/markdown, and Firehose page Markdown remains paid-only. Free searches return cached SERP results and snippets with full-page Markdown/HTML/text content removed. Sign-in alone does not grant paid access; fresh page fetches require credits and search permission.

Result completeness: maxResults is an upstream request target, not a response cap. All valid unique received results and their full titles/snippets are returned, even beyond that target. Firehose returns every merged result; paid page retrieval respects the quoted allowance, deadline and spending cap. Realtime Markdown retains every returned URL with explicit per-page outcomes. Free searches return every result stored in the matching cache, without paid page content.

History exports: GET /api/account/exports/payments.csv and GET /api/account/exports/daily-spend.csv stream CSV for the authenticated account only. Requires a browser session or API key with balance permission. All history by default; optional from/to YYYY-MM-DD inclusive UTC dates. Daily spend uses actual wallet debits across all projects/keys, includes zero-spend dates, and retains history beyond the 35-day analytics window. Today is partial through export time. Payments include status, credit reversal amounts and net credited amounts; manual grants are not payments. Responses are private/no-store.

Advanced inputs: country/language accept recognized names, native names and codes, normalized before routing/cache/idempotency. USA/U.S./United States of America -> us; GBR/United Kingdom -> gb; English/eng -> en; Français/fra -> fr. Unknown values and conflicting aliases return 400. Common aliases include country_code/gl, language_code/hl, safe_search, time_period, siteSearch, exact_terms, exclude_terms and structured mime. phone -> mobile; past week -> week; on/true Safe Search -> strict. Provider-specific wire formats are applied by adapters, including DDG uk-en and Yandex mime:. Status offerings expose inputCapabilities; routing excludes unsupported source/option combinations. Engine-dependent controls are available in the playground.

DataForSEO Google pricing: site:, filetype: and documented keyword operators incur one 5x multiplier per task, including structured filters and combined operators. Quotes multiply the requested depth; actual reported source cost settles within that ceiling. Google Images uses 100-image buckets and its own operator set, including related:. Null or absent source costs use the operator-aware estimate. The Google operator multiplier does not apply to Bing or Yahoo. See /docs#dataforseo-pricing.

GET /api/pricing returns public starting prices per search and per 1,000 searches in USD. Authenticated requests use account-specific prices. Prices use the lowest active, configured, verified base source rate. Engine cards and pages show these prices; options, result depth and health routing can increase costs. Firehose uses the minimum combined request, including a page-retrieval allowance; its source composition is private. No connected provider means pricing unavailable.

API keys support maxCostUsd per request (default $1, maximum $10), optional dailyLimitUsd and optional totalLimitUsd. Daily and total limits default to null (unlimited); blank/null removes a limit and 0 blocks new paid spending. Daily limits reset at 00:00 UTC and use the settlement day. Lifetime spend persists across limit changes and chart retention. Limits use final actual customer charges. Active reservations count against both allowances, including across midnight, so concurrent requests cannot overspend. Unused reservations are released. Free cache hits, failed work and completed idempotent replays consume no spend; combined search and page retrieval are counted once. Edits apply to new approvals; already approved requests may finish. Existing keys retain unlimited daily/total limits until edited. With balance permission, GET /api/account and MCP balance return the current key’s keyLimits: limits, actual spend, reserved amount, remaining allowances and dailyResetsAt. Insufficient allowance returns 402 key_daily_spend_limit or key_total_spend_limit before paid source calls. Lower maxCostUsd or update the key allowance before retrying.

Prices show final customer costs for the authenticated account. Existing completed receipts retain their original charges.

Console playground: https://openserp.io/dashboard/playground (signed-in account). Google by default, current balance, supported advanced controls, separate free quotes and paid execution, realtime Markdown, per-request deadlines and idempotency keys. Copy cURL, JavaScript, TypeScript, Python, Go, PHP, Ruby, C#, JSON or MCP samples from current settings. Samples contain environment-based API key placeholders and no session credentials. Console session requests have a $1 maximum; free accounts keep cache-first automatic routing and the free daily allowance.

Automatic source selection (provider: auto) always retries other sources within the chosen engine using the cheap or fast strategy, even when allowFallback is false. It never switches engines after selection. auto.search initially chooses Google, Bing or Yahoo, then keeps that engine. With an explicit provider/offering, allowFallback false pins one source and one attempt; true (default) permits other sources and compatible engines, preferring viable same-engine sources. Sources with at least ten trailing-hour samples below 90% success remain deprioritized. Up to three attempts share the deadline and spending cap; operators, locale and output constraints stay enforced. Compatible web alternatives are Google, Bing and Yahoo; images stay on image engines. Firehose always retries sources within each component engine. Free searches use shared cache first and live search on a miss with same-engine source retries. Failed work is absorbed; only successful delivered work is charged. Quotes report the effective allowFallback policy, maximumAttempts and eligible routes. Responses report requestedEngine, requestedProvider, actual engine/provider, fallbackUsed and fallbackReason. Existing completed idempotent receipts keep their original results and charges.

Firehose tiers: firehoseTier is lite or advanced, with lite used when omitted. Lite is available to free and paid accounts. Advanced requires paid access, including cached results. Lite is the lower search-cost combination; Advanced retains broader coverage at higher search cost. Tier caches and quotes are separate. GET /api/pricing includes a tiers array with both starting rates; source composition stays private. Free Firehose supports a request target up to 100 (default 50), while other free engines use up to 10. All stored results are delivered.

Firehose ranking: Lite is the default coverage tier. Results are re-ranked against the input query using title/snippet relevance, weighted source priority, cross-source agreement and domain diversity. Advanced adds coverage. Composition and weights are private. The legacy firehoseTier value default remains an alias for lite. New combinations use fresh cache identities; completed older requests retain their original idempotent receipts without another charge.

Playground defaults: results only, shared cache enabled, 24-hour cache TTL for paid searches. Firehose supports pageMarkdown:false to skip page fetching and page charges; pageMarkdown:true adds paid full-page Markdown, cost and response time. Omitted paid Firehose API requests include Markdown for compatibility. Free requests exclude page content and use unlimited-age shared cache.

All published REST and MCP search, quote and Markdown examples explicitly send cache {enabled:true, ttlHours:24}, matching the playground’s checked cache option. Free-account requests retain unlimited-age shared caching.

Result URLs: advertising click destinations are excluded from organic results. Known campaign/click parameters are removed before merging and delivery; functional parameters, signed URLs and application hash routes are preserved. Trailing slash variants deduplicate. Equivalent destinations are grouped across sources and returned as alternate_urls. The same cleanup applies to shared caches and completed replays without a new query or charge.

Payment-exempt accounts need no credits and cannot start checkout or auto-recharge. Responses distinguish usageValueUsd (normal service value), chargedUsd (actual deduction) and waivedUsd. Successful exempt live work is valued but charged $0. Cache hits add no value; idempotent replays count once. Key spend limits use actual charges. Older unvalued requests are identified explicitly. Daily spend CSV appends usage_value_usd, waived_value_usd and unvalued_requests.

Firehose status and pricing use separate Lite and Advanced entries in GET /api/status. Each tier has its own final starting query price, seven-day outcome chart, trailing-hour success rate, search-only median and p90 latency, and timeout policy. Authenticate for account-specific prices. Historical responses without an explicitly recorded tier are excluded from tier metrics and counted separately; page fetching and cache hits do not inflate search measurements.

Bing organic result quality: responses containing at least 10 valid unique results are rejected as invalid when none of their titles, snippets or URLs match any meaningful positive query keyword. Matching ignores case and accents, common words and filter operators. Failed responses are not billed; allowFallback can try another compatible source or engine. Cached Bing responses undergo the same check before reuse. See the reliability notice at https://openserp.io/bing.

Late cache recovery: Already-started paid source calls may continue up to 25000 ms beyond their foreground deadline or client disconnect. Valid late search results use the shared cache; page Markdown stays private to the account. No extra customer charge or usage value. No new source or page work starts after disconnect. Empty/invalid/failing responses, coordinates and storage-restricted sources are not cached. Retry with a new idempotency key; original receipts remain unchanged. Status keeps foreground timeout outcome/latency and records source expense once. No queued search jobs.

Anonymous retention: Unclaimed browser accounts and API keys expire 30 days after the first key is created. Additional keys do not extend expiry. Sign in in the original browser before expiry to retain keys and attach usage history. expiresAt is a millisecond timestamp in anonymous account/key responses. Expired keys return 401. Cleanup removes accounts, key hashes, sessions, projects and private receipts; aggregate usage and source expense remain under the read-only Historic anonymous usage account. Claimed and signed-in accounts retain their keys and history. Shared-cache and network free-quota policies are unchanged.

Opaque /goto links are retained as successful search results, including responses containing only those links. They do not count as invalid results and use the normal query charge. Readable redirect destinations are still unwrapped; advertising and unsafe URLs remain filtered.

MCP installation: At https://openserp.io/docs/mcp, Copy setup and Copy agent instructions automatically generate and include an API key. Signed-in users receive an account key. Anonymous browser keys and usage attach after login/account creation in that browser within 30 days of the first key; key values and limits remain valid. Repeated copies on the same page validate ownership and reuse the key. New setup keys: search/balance scopes, $1 per request, $5 daily, $20 lifetime; manage at /keys. Static downloads use YOUR_API_KEY placeholders. Setup keys stay in page memory only, never URLs or persistent browser storage.