Every Cloud endpoint is a JSON API under:

https://api.openserp.org

Search endpoints are GET requests and require the bearer auth from Authentication. The official SDKs call these same endpoints for you — when an example is shown for both, pick whichever fits your codebase.

Endpoint map

Supported engines: google, bing, yandex, baidu, duckduckgo (alias duck), ecosia.

Single-engine web search

Use this when you know which engine you want.

JavaScript SDK

const response = await client.search({
  engine: "google",
  text: "golang",
  limit: 10,
  region: "US",
  lang: "EN",
});

for (const r of response.results) {
  console.log(r.rank, r.title, r.url);
}

Python SDK

response = client.search(engine="google", text="golang", limit=10, region="US", lang="EN")

for r in response.results:
    print(r.rank, r.title, r.url)

HTTP

curl "https://api.openserp.org/v1/google/search?text=golang&limit=10&region=US&lang=EN" \
  -H "Authorization: Bearer $OPENSERP_KEY"

Common search parameters

Not every engine supports every filter — treat lang, date, site, and file as best-effort outside Google.

Response envelope

Search responses always use the same query, meta, results, pagination shape:

{
  "query": { "text": "golang", "engines_requested": ["google"] },
  "meta": {
    "request_id": "019dc6c1-da45-706e-a57c-d671fa2862ee",
    "requested_at": "2026-05-12T18:30:00Z",
    "took_ms": 642
  },
  "results": [
    {
      "id": "google-1",
      "rank": 1,
      "type": "organic",
      "title": "The Go Programming Language",
      "url": "https://go.dev/",
      "display_url": "go.dev",
      "snippet": "Go is an open source programming language.",
      "domain": "go.dev",
      "position": { "absolute": 1 },
      "engine": "google"
    }
  ],
  "pagination": { "page": 1, "has_more": true, "next_start": 10 }
}

Web result fields include title, url, snippet, domain, type, position, and engine. Image results use the same envelope and add image-specific fields described below.

Multi-engine web search

Use mode=balanced for broader coverage with one deduplicated list.

JavaScript SDK

const response = await client.megaSearch({
  text: "openserp api",
  engines: ["google", "bing", "duckduckgo"],
  limit: 20,
  region: "US",
});

console.log(response.results.length, "merged results");
console.log("credits used:", client.lastResponse?.credits?.used);

HTTP

curl "https://api.openserp.org/v1/mega/search?text=openserp+api&mode=balanced&engines=google,bing,duckduckgo&limit=20&region=US" \
  -H "Authorization: Bearer $OPENSERP_KEY"

Mega parameters

Mega endpoints are billed dynamically from the engines and result volume that successfully return data. Use X-Credits-Used (or client.lastResponse?.credits?.used) as the source of truth.

Any and Fast routing

These modes return one successful response and bill a predictable 1 credit. Use them when you want resilience without merged coverage.

JavaScript SDK

const fast = await client.fastSearch({
  text: "golang",
  engines: ["google", "bing", "duckduckgo"],
  limit: 10,
});
console.log("served by:", client.lastResponse?.engineUsed);

const any = await client.anySearch({
  text: "golang",
  engines: ["google", "bing", "duckduckgo"],
  limit: 10,
});
console.log("served by:", client.lastResponse?.engineUsed);

HTTP

curl "https://api.openserp.org/v1/mega/search?text=golang&mode=fast&engines=google,bing,duckduckgo&limit=10" \
  -H "Authorization: Bearer $OPENSERP_KEY"

Any/Fast success responses include meta.engine_used, meta.engines_tried, and the X-Engine-Used header. If every requested engine fails, the response is 502 and isn’t charged — see Errors & rate limits.

Image search

Image endpoints accept the same parameters as web search (text, limit, start, region, lang, site, file, date).

Single-engine

const images = await client.image({
  engine: "bing",
  text: "golang logo",
  limit: 10,
});

for (const img of images.results) {
  console.log(img.title, img.image_url, `${img.width}x${img.height}`);
}

curl "https://api.openserp.org/v1/bing/image?text=golang+logo&limit=10" \
  -H "Authorization: Bearer $OPENSERP_KEY"

Multi-engine

const merged = await client.megaImage({
  text: "golang logo",
  engines: ["bing", "google"],
  limit: 20,
});

const fastImg = await client.fastImage({
  text: "golang logo",
  engines: ["bing", "google"],
  limit: 10,
});

const anyImg = await client.anyImage({
  text: "golang logo",
  engines: ["bing", "google"],
  limit: 10,
});

Image result fields

Image results extend the standard envelope with:

Pagination

Use start to request later result pages:

async function paginate(text: string, perPage = 25, pages = 3) {
  const all = [];
  for (let i = 0; i < pages; i += 1) {
    const page = await client.search({
      engine: "google",
      text,
      limit: perPage,
      start: i * perPage,
    });
    all.push(...page.results);
    if (!page.pagination?.has_more) break;
  }
  return all;
}

const results = await paginate("openserp");
console.log(results.length);

Each page is a separate billable request. Watch X-Credits-Used and X-Credits-Remaining on long pagination jobs.

Account and capability endpoints

These endpoints are free to call.

GET /v1/me

The account associated with the API key and the current credit balance.

const account = await client.me();
console.log(account.email, account.credits_remaining);

{ "email": "you@example.com", "credits_remaining": 4250 }

GET /v1/pricing

Live credit pricing. Fetch it from your own app when you want to display expected cost without hardcoding values.

const pricing = await client.pricing();
console.log(pricing.credit_price_usd, pricing.search.credits);

See Pricing & credits for the full response shape and what counts as billable.

GET /v1/engines/status

User-facing operational status and recent latency signals.

const status = await client.enginesStatus();
console.log(status);

{
  "engines": {
    "google": { "status": "operational", "latency_ms": 420 },
    "yandex": { "status": "loaded", "latency_ms": 710 },
    "baidu": { "status": "unknown" }
  }
}

Status values:

• operational — engine has delivered results recently.
• loaded — engine is available but hasn’t served recent traffic.
• down — currently unavailable.
• unknown — no recent health signal.

GET /v1/engines/capabilities

Currently supported web and image capabilities.

const caps = await client.enginesCapabilities();
console.log(caps.engines?.google);

{
  "engines": {
    "google": { "web": true, "image": true }
  },
  "modes": {
    "any": { "web": true, "image": true },
    "fast": { "web": true, "image": true },
    "mega": { "web": true, "image": true }
  }
}

Response telemetry

Every billable response includes:

Next

• Errors & rate limits — retry behavior and failure handling.
• OSS vs Cloud — how Cloud differs from the self-hosted server.