OpenSERP Cloud Quickstart →

OpenSERP comes in two flavors:

  • OpenSERP OSS — you run the open-source server yourself. Free, MIT-licensed.
  • OpenSERP Cloud — OpenSERP runs as a hosted API at https://api.openserp.org.

The search API is intentionally the same across both. Cloud just adds a /v1/ prefix, API-key auth, account credits, usage headers, and hosted operations on top.

Same request shape

OSS

curl "http://localhost:7000/google/search?text=openserp&region=US&limit=5"

Cloud

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

Shared search surface

Capability OSS Cloud
Single-engine web search GET /{engine}/search GET /v1/{engine}/search
Single-engine image search GET /{engine}/image GET /v1/{engine}/image
Multi-engine web search GET /mega/search?mode=balanced|any|fast GET /v1/mega/search?mode=balanced|any|fast
Multi-engine image search GET /mega/image?mode=balanced|any|fast GET /v1/mega/image?mode=balanced|any|fast

Both share the same core search parameters: text, region, lang, limit, start, date, site, file, engines, mode.

And both return the same public envelope:

{
  "query": { "text": "openserp", "engines_requested": ["google"] },
  "meta": { "request_id": "...", "took_ms": 642 },
  "results": [],
  "pagination": { "page": 1, "has_more": false, "next_start": 0 }
}

What Cloud adds

  • Hosted API keys and dashboard key management.
  • Credit billing with no monthly minimum.
  • Usage headers: X-Credits-Used, X-Credits-Remaining, X-Engine-Used.
  • Account and pricing endpoints: GET /v1/me and GET /v1/pricing.
  • User-facing engine status and capability endpoints.
  • Hosted operations, monitoring, and scaling — no infrastructure to run.

When each fits

Choose OSS when Choose Cloud when
You need full control of deployment and infrastructure. You want to integrate search without operating infrastructure.
You have strict internal hosting requirements. You want hosted API keys, credits, and a dashboard.
You are experimenting locally or modifying OpenSERP internals. You are shipping a product, agent, workflow, or pipeline.
You prefer infrastructure cost over per-request API cost. You prefer pay-as-you-go billing and faster setup.

A common pattern is to use both: develop locally against OSS, then point staging or production at Cloud.

One SDK for both

The official SDKs target both backends. Usually only the constructor changes — every other line stays the same.

TypeScript / JavaScript

import { OpenSERP } from "@openserp/sdk";

const oss   = new OpenSERP({ baseUrl: "http://localhost:7000" });
const cloud = new OpenSERP({ apiKey: process.env.OPENSERP_KEY });

const localResults = await oss.search({ engine: "google", text: "openserp" });
const cloudResults = await cloud.search({ engine: "google", text: "openserp" });

Python

import os
from openserp import OpenSERP

oss   = OpenSERP(base_url="http://localhost:7000")
cloud = OpenSERP(api_key=os.environ["OPENSERP_KEY"])

oss_response   = oss.search(engine="google", text="openserp")
cloud_response = cloud.search(engine="google", text="openserp")

Cloud-only SDK methods — me(), pricing(), enginesStatus(), enginesCapabilities() — are available when the client is configured for Cloud.

Migrating from OSS to Cloud

  1. Swap the base URL from http://localhost:7000 (or your OSS host) to https://api.openserp.org/v1.
  2. Add Authorization: Bearer YOUR_API_KEY.
  3. Confirm your response parsing still reads query, meta, results, and pagination — the shape is the same.
  4. Read X-Credits-Used and X-Credits-Remaining for billing and monitoring.
  5. Compare a known query in the Search Playground before switching production traffic.

If you’re using the SDK, steps 1 and 2 collapse into “change the constructor”.

Next