API Reference

Access all dictionaries through a simple REST API. All responses use a consistent JSON envelope.

Response Format

{
  "ok": true,
  "data": { ... },
  "meta": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "took_ms": 12
  }
}

Authentication

All API requests require an API key passed via the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://shobdo.dev/api/v1/search?q=hello

Endpoints

GET/api/v1/search

Search across all dictionaries.

Parameter	Type	Required	Description
q	string	Required	Search query
lang	string	Optional	Language filter (e.g. "en", "en-de")
source	string	Optional	Dictionary ID filter (e.g. "oxf_ode")
limit	integer	Optional	Results per page (default: 20, max: 100)
offset	integer	Optional	Pagination offset (default: 0)

GET/api/v1/entry/:source/:id

Get a full entry from a specific dictionary.

Parameter	Type	Required	Description
source	string	Required	Dictionary ID
id	string	Required	Entry ID

GET/api/v1/audio/:source/:lexid

Get pronunciation audio for an entry.

Parameter	Type	Required	Description
source	string	Required	Dictionary ID
lexid	string	Required	Entry/lexical ID

Code Examples

cURL

curl "https://shobdo.dev/api/v1/search?q=ubiquitous&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  "https://shobdo.dev/api/v1/search?q=hello",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { data, meta } = await res.json();
console.log(`Found ${meta.total} results in ${meta.took_ms}ms`);

Python (requests)

import requests

resp = requests.get(
    "https://shobdo.dev/api/v1/search",
    params={"q": "hello", "lang": "en-de"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = resp.json()
for entry in data["data"]:
    print(f"{entry['word']}: {entry['preview']}")