dictionaries.getbible.net /v1/
Version v1 of the getBible static API at dictionaries.getbible.net: every resource below this prefix is a file served exactly as published. public, metered · tokens unlimited
Base URL
https://dictionaries.getbible.net/v1/Documents are addressed by their path below the base URL:
curl https://dictionaries.getbible.net/v1/path/to/document.jsonThe machine-readable description of this endpoint is openapi.json.
How to call it
- Allowed file types:
.json. Nothing else exists here. - Methods:
GET,HEAD,OPTIONS. Anything else answers405. The only supported query parameter is the optional_URL change token described below. - CORS is open:
Access-Control-Allow-Origin: *on every response, preflights answer204. - Caching:
Cache-Control: public, max-age=2592000on documents andmax-age=300on.shafiles; every response carries anETag. - Compression: gzip (and brotli where available) on request.
- Health:
GET /healthzanswers{"status":"ok"}.
Optional URL change token
Append ?_=VALUE to give a browser a distinct cache key. The value must contain 1–128 ASCII letters, digits, underscores or hyphens ([A-Za-z0-9_-]{1,128}); timestamps and checksums are supported. Use only one _ parameter, with no other parameters or percent encoding. Empty values, duplicate keys, bare query tokens and other parameter names return 400 with Cache-Control: no-store.
curl 'https://dictionaries.getbible.net/v1/path/to/document.json?_=9f4c2a17'The origin validates and otherwise ignores the value, serving the same file with the same validators, cache lifetime and access requirements. Reuse the value to keep the URL stable; change it to use a different URL. This does not purge old cached URLs or select a content version. Any CDN cache must retain the complete query string to distinguish those URLs.
Access
This endpoint is public and metered. Anonymous callers share a budget per client address; callers with a bearer token are not limited at all.
| Budget (per address) | Value |
|---|---|
| Sustained rate | 50 requests per second, bursts up to 250 |
| Per hour | about 100000 requests |
| Per day | about 1000000 requests |
| Concurrent connections | 100 |
Budgets are enforced as token buckets, so steady traffic under the quota is never touched and bursts above it are slowed with a 429 rather than cut off.
Using a token
Send it as a bearer credential. Tokens never go in the URL.
curl -H "Authorization: Bearer gb..." https://dictionaries.getbible.net/v1/path/to/document.jsonTokens are issued to applications and partners by the getBible team; ask through getBible.net.
Errors
Every error is an RFC 9457 problem document with the media type application/problem+json.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | An unsupported query string, invalid _ value or malformed request was sent. |
| 401 | unauthorized | A bearer token is required and was missing or invalid. |
| 404 | not_found | No such document in this endpoint. |
| 405 | method_not_allowed | Only GET, HEAD and OPTIONS are accepted. |
| 429 | rate_limited | The public budget for your address is used up; a Retry-After header is included. |
| 503 | unavailable | Temporary outage; retry after a moment. |