Every Cloud endpoint is a GET request, returns JSON, and uses the bearer-token auth from Authentication. All paths below are relative to:

https://api.openserp.org

Endpoint map

{engine} for web search is one of: google, bing, yandex, baidu, duckduckgo, duck, ecosia.

{engine} for single-engine image search is one of: google, bing, yandex, baidu, duckduckgo, duck, ecosia.

Single-engine search

curl "https://api.openserp.org/v1/google/search?text=golang&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common parameters

Not every engine honors every filter. lang, date, site, and file are best-effort on engines other than Google.

Response

{
  "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": [
    {
      "rank": 1,
      "title": "The Go Programming Language",
      "url": "https://go.dev/",
      "description": "Go is an open source programming language...",
      "ad": false,
      "engine": "google"
    }
  ]
}

The public Cloud schema is a compact JSON envelope with query, meta, and results. Billable success responses include X-Credits-Used and X-Credits-Remaining.

Megasearch

/v1/mega/search queries several engines and returns one merged, deduplicated result list.

curl "https://api.openserp.org/v1/mega/search?text=golang&engines=google,bing,yandex&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Megasearch-only parameters

Mega endpoints are billed dynamically from the engines/results that successfully return data. Use X-Credits-Used as the source of truth for the final charge.

Any and Fast routing

/v1/any/search and /v1/fast/search return the first successful engine response instead of merging every engine.

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

Any/Fast success responses include meta.engine_used, meta.engines_tried, optional meta.engines_skipped, and the X-Engine-Used header.

Image search

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

Image endpoints return the same query/meta/results envelope. Single-engine image search supports every web engine: google, bing, yandex, baidu, duckduckgo, duck, and ecosia. Use /v1/any/image, /v1/fast/image, or /v1/mega/image for multi-engine image fallback or aggregation.

Image billing is dynamic: ceil(returned_images / 10) credits for single-engine image search, and dynamic per successful engine/result volume for mega image search.

Account and pricing endpoints

GET /v1/me

Returns the account that owns the API key and the live credit balance:

{ "email": "[email protected]", "credits_remaining": 4250 }

GET /v1/pricing

Returns current credit prices. Useful if you want to show “this query will cost N credits” inside your own UI:

{
  "credit_price_usd": 0.02,
  "search": { "credits": 1 },
  "mega_search": { "credits": 1 },
  "image_search": { "credits": 1 },
  "any_search": { "credits": 1 },
  "fast_search": { "credits": 1 },
  "any_image": { "credits": 1 },
  "fast_image": { "credits": 1 }
}

Code samples - full request

A complete request with filters, in each language we recommend.

JavaScript (fetch)

const url = new URL("https://api.openserp.org/v1/fast/search");
url.search = new URLSearchParams({
  text: "openserp api",
  engines: "google,bing",
  limit: "20",
  lang: "EN",
  country: "US",
}).toString();

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.OPENSERP_KEY}` },
});

if (!res.ok) {
  throw new Error(`OpenSERP ${res.status}: ${await res.text()}`);
}

const { results, meta } = await res.json();
console.log(`engine ${meta.engine_used || "n/a"} took ${meta.took_ms}ms - ${results.length} results`);

Python (requests)

import os
import requests

resp = requests.get(
    "https://api.openserp.org/v1/mega/search",
    params={
        "text": "openserp api",
        "engines": "google,bing",
        "limit": 20,
        "country": "US",
    },
    headers={"Authorization": f"Bearer {os.environ['OPENSERP_KEY']}"},
    timeout=30,
)
resp.raise_for_status()

print("credits used:", resp.headers["X-Credits-Used"])
for r in resp.json()["results"]:
    print(r["rank"], r["title"], r["url"])

Go

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "net/url"
    "os"
)

type response struct {
    Results []struct {
        Rank  int    `json:"rank"`
        Title string `json:"title"`
        URL   string `json:"url"`
    } `json:"results"`
}

func main() {
    q := url.Values{
        "text":    {"openserp api"},
        "engines": {"google,bing"},
        "limit":   {"20"},
    }
    req, _ := http.NewRequest("GET", "https://api.openserp.org/v1/any/search?"+q.Encode(), nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENSERP_KEY"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    var out response
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        log.Fatal(err)
    }
    for _, r := range out.Results {
        fmt.Printf("%d  %s  %s\n", r.Rank, r.Title, r.URL)
    }
}

Pagination

Use start to walk past the first page:

# page 1
curl ".../v1/google/search?text=openserp&limit=25&start=0"  -H "Authorization: Bearer ..."
# page 2
curl ".../v1/google/search?text=openserp&limit=25&start=25" -H "Authorization: Bearer ..."

Each page is a separate billable request. Check Pricing and credits before paginating large result sets.