API 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:

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.

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 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.

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:

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.

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.

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.)

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:

API on Searpa Docs

Authentication

Authentication#

Getting a key#

Rate limits

Rate limits#

When you exceed a limit#

Conventions

Conventions#

Shared query parameters#

Search endpoints

Search endpoints#

Web search#

Image search#

Similar images#

Maps

Maps#

Geocode a place name#

Reverse geocode coordinates#

Translate

Translate#

Translate text#

List available languages#

Instant & cards

Instant answers & knowledge cards#

Instant answers#

Meta endpoints

Meta endpoints#

Suggestions#

Provider status#

Errors

Errors#

Status codes#

Error bodies#

Validation errors (400)#

Validation errors (`400`)#