Searpa Documentation on Searpa Docs

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication#

Every API request must carry a valid API key. Keys are issued per user; a request without one gets 401, and a request with a bad or revoked one is rejected.

The API is a self-hosted feature, so keys are issued on your own instance, not on the hosted searpa.eu service.

Getting a key#

On your instance:

In the web UI: Settings → API keys, create a key (optionally name it). The full key is shown once, copy it immediately.
From the command line (admins): python manage.py create_api_key <username> --name "my script", see Issuing API keys.

A key looks like:

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started#

Searpa requires an account, there is no anonymous search. The account itself, though, can be anonymous: only a username and password are needed, no email or personal details are required (an email is optional, and only for password reset, see Your account). On the hosted service, accounts are invite-only during the alpha; on a self-hosted instance the administrator creates them.

Go to your Searpa instance (the hosted service is at searpa.eu).
Click Sign in and enter your username and password.
You land on the search home page.

If you forget your password and added an email to your account, use the Forgot password? link to reset it. Without an email on file a lost password cannot be recovered, see Your account.

Requirements

Mon, 01 Jan 0001 00:00:00 +0000

Requirements#

Runtime#

Component	Notes
A container runtime	Docker or Podman, to run the published image.
PostgreSQL	The application database. Any reasonably recent PostgreSQL (16+) works.
A Brave Search API key	The minimum for useful results, see Search providers. The free tier is enough to start.
Outbound HTTPS	The server calls upstream providers; if you run behind an allowlist, see the provider hosts.

Everything else, the web server, static-file serving and translation-catalog compilation, is built into the image.

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

The fastest way to a running instance is the Docker image. You need a PostgreSQL database and, at minimum, a Brave Search API key.

With Docker#

docker run -p 8000:8000 \
 -e SECRET_KEY=your-long-random-secret \
 -e DATABASE_URL=postgres://user:password@db-host:5432/searpa \
 -e ALLOWED_HOSTS=search.example.com \
 -e BRAVE_API_KEY=your-brave-key \
 -e BRAVE_SUGGEST_API_KEY=your-brave-suggest-key \
 -e MARGINALIA_API_KEY=public \
 searpa

On start the container:

Applies database migrations (a no-op once the schema is current).
Serves the app with gunicorn (2 workers) on port 8000.
Serves its own static files via WhiteNoise (compressed and hashed), no separate web server or CDN required.
Answers a health check at /up.

The translation catalogs and static files are compiled at build time, so there is nothing else to run.

Rate limits

Mon, 01 Jan 0001 00:00:00 +0000

Rate limits#

Each API key has its own budget, enforced by two limits that apply together. A request must satisfy both:

Limit	Default	Purpose
Burst	`60/min`	Short-term cap, protects upstream providers from a runaway client.
Sustained	`5000/day`	Caps total daily volume.

On a self-hosted instance these are configurable with API_THROTTLE_BURST and API_THROTTLE_SUSTAINED, see Configuration.

When you exceed a limit#

Exceeding either limit returns:

HTTP 429 Too Many Requests

{ "detail": "Request was throttled. Expected available in 12 seconds." }

DRF includes a Retry-After hint in the message; back off and retry after the indicated time. A robust client should handle 429 with exponential backoff.

Web search

Mon, 01 Jan 0001 00:00:00 +0000

Web search#

The Web tab is Searpa’s core. It can draw on three independent web indexes and blend whatever you enable into one ranked list.

The three engines#

Engine	What it is
Brave	A large independent web index (also powers Images, News and Videos).
Mojeek	An independent UK search index with its own crawler.
Marginalia	A non-commercial index focused on the small, non-commercial web.

You choose which engines to use in Settings → Engines. Enable just one for a single source, or several to blend them. All three are on by default.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Searpa is configured entirely through environment variables (in production) or a .env file (in development). The repository ships an .env.example documenting every variable; this page is the reference.

Core#

Variable	Purpose	Notes
`SECRET_KEY`	Django secret key	Required in production. Long and random.
`DEBUG`	Debug mode	Keep `False` (the default) in production.
`ALLOWED_HOSTS`	Comma-separated hostnames the app will serve	e.g. `search.example.com`.
`DATABASE_URL`	PostgreSQL connection URL	e.g. `postgres://user:pass@host:5432/searpa`.
`LOG_LEVEL`	Logging verbosity	`DEBUG` / `INFO` / `WARNING` / `ERROR` (default `INFO`).

Search providers#

These keys decide which engines, media tabs and knowledge cards are available. A provider with no key is simply hidden (not shown as broken). Full details on Search providers.

Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Conventions#

Shared query parameters#

The search endpoints accept a common set of parameters. Each maps to an option the website keeps in its preferences cookie, here they’re explicit in the URL.

Parameter	Applies to	Values	Default
`q`	all search endpoints	The query string (required)	—
`engine`	web, images, news, videos, cards	`brave`, `mojeek`, `marginalia`, or `all`; comma/space-separate several	`all`
`safe`	web, images, news, videos, cards	`on` / `off` (`off`, `false`, `0`, `no` all mean off)	`on`
`lang`	most endpoints	A language code, e.g. `en`, `fr`	empty (auto)
`page`	web, images, news, videos	Page number, `1`–`50`	`1`
`date`	web, news, videos	Time range: `d` (day), `w` (week), `m` (month), `y` (year)	none

Notes:

Search tabs

Mon, 01 Jan 0001 00:00:00 +0000

Search tabs#

Besides the Web tab, Searpa has dedicated tabs for images, news, videos, maps and translation. Each runs your query against sources suited to that kind of content. A tab only appears when the instance has the provider it needs configured.

Images#

Image results come from the Brave image index, blended with Pixabay where it is enabled. Results are shown as a thumbnail grid.

Click any image to open a lightbox (much like Google Images):

Instant answers

Mon, 01 Jan 0001 00:00:00 +0000

Instant answers#

For common utility queries, Searpa shows an instant answer right at the top of the web results, so you get the answer without clicking through. This is in the spirit of DuckDuckGo’s instant answers.

Almost every instant answer is computed locally on the server, with no third party involved and nothing about your query sent anywhere.

What you can ask#

Category	Example queries
Calculator	`2+2`, `sqrt(16)*3`, `15% of 200`
Unit conversion	`5 km to miles`, `100 f to c`, `2 cups to ml`
Base conversion	`0xff in decimal`, `255 in binary`
Colour	`#4f46e5`, `rgb(255,128,0)`, `color picker`
World clock	`time in tokyo`, `what time is it in new york`
QR code	`qr code https://example.com`
Hash / UUID	`md5 hello`, `sha256 of test`, `uuid`
Password	`password generator`, `strong password`
Unix time	`unix timestamp`, `1700000000 to date`
Encode / decode	`base64 encode hi`, `url decode foo%20bar`
JSON / Regex	`json formatter`, `regex tester`
HTTP / Ports	`http 404`, `port 443`
Randomisers	`roll 2d6`, `flip a coin`, `random number 1-100`
Timer	`timer 5 minutes`, `stopwatch`
What’s my IP	`what's my ip`

Multilingual triggers#

Instant answers fire in seven languages, English, French, German, Spanish, Italian, Portuguese and Dutch. For example, all of these work:

Search endpoints

Mon, 01 Jan 0001 00:00:00 +0000

Search endpoints#

The bread-and-butter endpoints: web, image, news and video search, plus the “similar images” helper. All take the shared parameters (q, engine, safe, lang, page, date).

Web search#

GET /api/v1/web/?q=...

curl -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
 "https://search.example.com/api/v1/web/?q=climate&engine=all&lang=en&date=w"

{
 "query": "climate",
 "tab": "web",
 "page": 1,
 "engine": ["brave", "mojeek", "marginalia"],
 "correction": "",
 "results": [
 {
 "title": "Climate change",
 "url": "https://example.org/climate",
 "description": "...",
 "display_url": "example.org",
 "favicon_url": "https://...",
 "age": "2 days ago",
 "source": "all",
 "source_label": "Brave, Mojeek, Marginalia",
 "sitelinks": []
 }
 ]
}

source / source_label — which engine(s) returned the result. brave / mojeek / marginalia for a single engine, or both / all for cross-engine agreement (source_label is the readable form).
correction — a suggested spelling correction, or "".

Image search#

GET /api/v1/images/?q=...

{
 "query": "golden retriever",
 "tab": "images",
 "page": 1,
 "engine": ["brave"],
 "results": [
 {
 "title": "...",
 "url": "https://example.com/page",
 "source": "example.com",
 "thumbnail": "https://.../thumb.jpg"
 }
 ]
}

Similar images#

Mirrors the website’s lightbox “similar images” grid, an image search seeded from an opened image’s caption.

Search providers

Mon, 01 Jan 0001 00:00:00 +0000

Search providers#

Searpa blends results from several independent providers. Which tabs and cards appear depends on which keys you set. A provider with no key is hidden, the affected tab or card simply doesn’t show, rather than displaying an error.

All upstream calls happen server-side; keys are never exposed to the browser.

This page is the overview of which key enables what. For step-by-step signup instructions for each provider, see Getting API keys.

Getting API keys

Mon, 01 Jan 0001 00:00:00 +0000

Getting API keys#

Step-by-step guides for obtaining each provider’s key. None are required to boot Searpa, but at least one web engine (Brave is the easiest) is needed for useful results. Each provider you skip simply hides its tab or card, see Search providers for what each one enables.

Once you have a key, set the matching environment variable (see Configuration) and restart the app.

All of these have a free tier that is generous enough for a personal or small-team instance, Searpa caches aggressively and only calls the paid card APIs when a query actually matches. The shared keys (public for Marginalia, anonymous Stack Exchange) need no signup at all.

Knowledge cards

Mon, 01 Jan 0001 00:00:00 +0000

Knowledge cards#

When your web search (first page) is about a well-known subject, Searpa shows up to three knowledge cards beside the results, a quick summary so you often don’t need to click through at all.

The cards#

Card	Source	Shows
Wikipedia	Wikipedia	A summary, image and link for the subject. This is the anchor card, it also helps detect what the other cards should show.
Film / TV	TMDB	Details for a movie or TV show: poster, rating, year, overview.
Places	TripAdvisor	A restaurant, hotel or attraction: rating, address (which links to the map) and a link.
Q&A	Stack Exchange	The top question and answer for a technical query.

How they’re chosen#

Searpa only shows a card when your query genuinely matches that kind of subject:

Maps

Mon, 01 Jan 0001 00:00:00 +0000

Maps#

Geocode a place name or reverse-geocode a coordinate pair, using OpenStreetMap’s Nominatim. No provider key is required.

GET /api/v1/maps/

Geocode a place name#

GET /api/v1/maps/?q=<place>&limit=<n>&lang=<code>

q — the place or address to look up (required in this mode).
limit — max results, 1–50 (default 10).
lang — preferred language for names.

curl -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
 "https://search.example.com/api/v1/maps/?q=Eiffel+Tower&limit=1"

{
 "query": "Eiffel Tower",
 "places": [
 {
 "name": "Eiffel Tower",
 "display_name": "Eiffel Tower, Paris, France",
 "lat": 48.8584,
 "lon": 2.2945,
 "category": "tourism",
 "type": "attraction",
 "addresstype": "tourism",
 "importance": 0.82,
 "embed_url": "https://www.openstreetmap.org/export/embed.html?...",
 "mini_embed_url": "https://...",
 "osm_url": "https://www.openstreetmap.org/...",
 "directions_url": "https://www.openstreetmap.org/directions?...",
 "geo_uri": "geo:48.8584,2.2945"
 }
 ]
}

Reverse geocode coordinates#

Pass lat and lon instead of q:

Bangs

Mon, 01 Jan 0001 00:00:00 +0000

Bangs#

Bangs are !shortcuts you type in the search box to send a query straight to another site or to a different Searpa tab. Searpa understands the widely-used DuckDuckGo-style bang vocabulary, thousands of sites, plus a few of its own.

The bang definitions come from Kagi’s open-source bangs repository, the same community-maintained !bang list Kagi publishes. Self-hosters refresh it with make bangs, see Maintenance.

A bang can sit anywhere in the query, the rest of the text is the search terms.

Translate

Mon, 01 Jan 0001 00:00:00 +0000

Translate#

Translate text between languages, powered by the instance’s LibreTranslate. This endpoint accepts GET or POST, use POST to keep long text out of the URL and logs.

GET /api/v1/translate/
POST /api/v1/translate/

Translate text#

Parameter	Required	Meaning
`q` (or `text`)	yes	The text to translate
`target`	yes	Target language code (e.g. `fr`)
`source`	no	Source language code; defaults to `auto` (detect)

# GET
curl -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
 "https://search.example.com/api/v1/translate/?q=hello&target=fr"

# POST (better for long text)
curl -X POST -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
 -d "q=hello world" -d "target=fr" \
 "https://search.example.com/api/v1/translate/"

{
 "source": "auto",
 "target": "fr",
 "translated_text": "bonjour le monde",
 "detected_lang": "en"
}

detected_lang is filled only when source was auto (otherwise empty).
If translation isn’t configured on the instance, the endpoint returns 503 with {"detail": "Translation is unavailable or not configured on this deployment."}.

List available languages#

GET /api/v1/translate/languages/

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "fr", "name": "French" }
 ]
}

The list reflects whatever the connected LibreTranslate instance offers, see Translation for the self-hosting side.

Translation

Mon, 01 Jan 0001 00:00:00 +0000

Translation (LibreTranslate)#

The Translate tab is powered by LibreTranslate, an open-source, self-hostable machine-translation server. Searpa calls it server-side, no third-party translation service is involved.

Enabling the tab#

Point Searpa at a LibreTranslate instance with LIBRETRANSLATE_URL:

LIBRETRANSLATE_URL=http://libretranslate:5000

Set it and the Translate tab (and its setting) appear, with whatever languages that instance offers.
Leave it unset and the Translate tab and its setting are disabled entirely.

Running LibreTranslate#

The development stack starts a local LibreTranslate automatically (make up brings one up at http://localhost:5000). For production, run your own, for example:

Instant & cards

Mon, 01 Jan 0001 00:00:00 +0000

Instant answers & knowledge cards#

These two endpoints mirror the website’s inline answers and side panels. Because their content varies by answer type and provider, they return provider-shaped JSON rather than a fixed per-field schema, treat the structures as data and read the fields you need.

Instant answers#

GET /api/v1/instant/?q=...

Returns the instant answer for a utility query (maths, unit/base/colour conversion, weather, currency, world clock, hashes, QR, “what’s my IP”, …), or null when the query isn’t one Searpa answers inline.

Settings

Mon, 01 Jan 0001 00:00:00 +0000

Settings#

Open Settings from the home page or the menu to tailor Searpa to you. Your preferences sync to your account automatically and are restored on any device you sign in on. They are also stored in your browser, so they apply even before you sign in.

What you can change#

Setting	Options	Default
Engines	Any mix of Brave / Mojeek / Marginalia	All enabled
Safe search	On / Off	On
Search language	Auto, or one of the seven UI languages	Auto (your browser)
Interface language	Auto, or one of the seven UI languages	Auto
Theme	System / Light / Dark	System
Open links	Same tab / New tab	Same tab
Proxy images	On / Off	Off
Lazy-load knowledge cards	On / Off	On
Data sources	Per-provider on/off toggles	All enabled

Engines#

Pick which web indexes Searpa queries and blends, see Web search. This is also where you manage your blocked sites and custom bangs.

Users & access

Mon, 01 Jan 0001 00:00:00 +0000

Users & access#

Searpa is login-only with no public registration, so as the administrator you control who has an account. This is what keeps an instance private to your users.

Creating accounts#

Create users with Django’s standard management command:

# Docker
docker exec -it <container> python manage.py createsuperuser

# From source
make superuser

createsuperuser makes an admin account; for ordinary users you can create them the same way (or from the Django admin once you have a superuser). Each account needs a username and password; an email is optional (see below).

API keys

Mon, 01 Jan 0001 00:00:00 +0000

API keys#

Users access the public API with per-user API keys. Users can manage their own keys in the web UI (Settings → API keys), and you can manage them from the command line.

How keys are stored#

A key looks like searpa_sk_<prefix>.<secret>:

The prefix (8 characters) is stored in the clear for fast lookup.
Only a SHA-256 hash of the secret is stored, never the secret itself.

So a key’s full value is shown exactly once, at creation, and cannot be recovered afterwards, only revoked.

Meta endpoints

Mon, 01 Jan 0001 00:00:00 +0000

Meta endpoints#

Helpers for autocomplete, provider health, key introspection and endpoint discovery. The root, status/ and key/ don’t count toward your monthly search usage (they still count against the raw rate limit).

Suggestions#

Search-bar autocomplete suggestions for a query. (Counts as a search.)

GET /api/v1/suggest/?q=...

curl -H "Authorization: Api-Key searpa_sk_<prefix>.<secret>" \
 "https://search.example.com/api/v1/suggest/?q=clim"

{
 "query": "clim",
 "suggestions": ["climate", "climate change", "climbing"]
}

Provider status#

Current up/down status of each configured upstream provider, the data behind the /status page. (Does not count toward usage.)

Your account

Mon, 01 Jan 0001 00:00:00 +0000

Your account#

Signing in#

Searpa is login-only, every search happens under your account, and there is no public sign-up form. On the hosted service, accounts are invite-only during the alpha; on a self-hosted instance the administrator creates accounts.

Your account can be anonymous: it needs only a username and password, with no email or other personal details. There is no anonymous search (you’re always signed in), but the account behind it need not identify you.

Errors

Mon, 01 Jan 0001 00:00:00 +0000

Errors#

The API uses standard HTTP status codes and returns a JSON body describing the problem.

Status codes#

Code	Meaning	Typical cause
`200`	OK	Successful request.
`400`	Bad request	A bad parameter, e.g. a missing `q`, a non-integer `page`, or an unknown `engine`.
`401`	Unauthorized	No API key sent (or no recognised auth header).
`403`	Forbidden	Key belongs to a disabled account.
`429`	Too many requests	A rate limit was exceeded.
`503`	Service unavailable	A dependent service isn’t configured, e.g. translation when LibreTranslate is unset.

Error bodies#

Validation errors (`400`)#

Field-keyed messages:

Maintenance

Mon, 01 Jan 0001 00:00:00 +0000

Maintenance#

Searpa needs little ongoing care, but a few management commands keep it tidy and current. Run them on a schedule (a cron job, a systemd timer, or your orchestrator’s scheduled-task feature). Run each inside the container (docker exec <container> python manage.py …) or via make / uv run from source.

Scheduled tasks#

Command	What it does	Suggested schedule
`clear_expired_cache`	Deletes expired search-result cache rows	Daily
`check_provider_health`	Probes providers with a free health endpoint so `/status` stays current, without spending paid quota	Every ~10 minutes
`refresh_currency`	Refreshes cached exchange rates and prunes the instant-answer cache	Daily (optional, also self-refreshes on demand)

A cron example:

Privacy

Mon, 01 Jan 0001 00:00:00 +0000

Privacy#

Searpa is built to be a private alternative to surveillance-funded search. Here is what that means in practice.

What Searpa does not do#

No tracking. Searpa does not follow you around the web or across sessions to build a profile.
No ads. There is no advertising, so there is no incentive to profile you.
No selling data. Your searches are not a product sold to anyone.

How your queries are handled#

Searches run server-side. Searpa talks to upstream providers (Brave, Mojeek, Marginalia and the rest) on your behalf, so those providers don’t see your browser or IP, they see Searpa’s server.
Provider API keys never reach your browser. All upstream calls happen on the server.
Image proxying (optional, in Settings) routes thumbnails through the Searpa server so source sites don’t see your browser either.
Results are briefly cached on the server to keep things fast and reduce load on providers; the cache is keyed to the query, not to you.

Your data#

Your settings sync to your account so they follow you across devices. You can export or delete them.
Your email, if you add one, is used only for password reset, see Your account.

Where it’s run#

The hosted service is operated in the European Union under European privacy law. Because the search engine is open source, anyone can audit how it works, or run their own copy and be the only operator who ever touches their data.

Production notes

Mon, 01 Jan 0001 00:00:00 +0000

Production notes#

A few things worth knowing when you run Searpa for real users.

The image#

Serves the app with gunicorn (2 workers) on port 8000.
Serves its own static files via WhiteNoise, compressed and hashed, so you don’t need a separate static-file server or CDN.
Compiles translation catalogs and collects static files at build time.
Runs database migrations on start.

Reverse proxy and TLS#

Put a TLS-terminating reverse proxy in front (Caddy, nginx, Traefik, …) and forward to port 8000. Set:

Searpa Documentation on Searpa Docs

Authentication

Authentication#

Getting a key#

Getting started

Getting started#

Sign in#

Requirements

Requirements#

Runtime#

Quick start

Quick start#

With Docker#

Rate limits

Rate limits#

When you exceed a limit#

Web search

Web search#

The three engines#

Configuration

Configuration#

Core#

Search providers#

Conventions

Conventions#

Shared query parameters#

Search tabs

Search tabs#

Images#

Instant answers

Instant answers#

What you can ask#

Multilingual triggers#

Search endpoints

Search endpoints#

Web search#

Image search#

Similar images#

Search providers

Search providers#

Getting API keys

Getting API keys#

Knowledge cards

Knowledge cards#

The cards#

How they’re chosen#

Maps

Maps#

Geocode a place name#

Reverse geocode coordinates#

Bangs

Bangs#

Translate

Translate#

Translate text#

List available languages#

Translation

Translation (LibreTranslate)#

Enabling the tab#

Running LibreTranslate#

Instant & cards

Instant answers & knowledge cards#

Instant answers#

Settings

Settings#

What you can change#

Engines#

Users & access

Users & access#

Creating accounts#

API keys

API keys#

How keys are stored#

Meta endpoints

Meta endpoints#

Suggestions#

Provider status#

Your account

Your account#

Signing in#

Validation errors (`400`)#