commentaries.getbible.net

A getBible static API: every resource is a file served exactly as published. public, metered · tokens unlimited

Endpoints

Every path starts with a version segment. Each endpoint is an independent tree with its own documentation page, changing on its own schedule.

Machine-readable index of the endpoints and their OpenAPI documents: versions.json.

How to call it

Plain HTTPS GET requests, from any origin. Responses are JSON, plus .sha and .txt files as plain text. Request bodies are not used. The only supported query parameter is the optional _ URL change token described below.

curl https://commentaries.getbible.net/v1/path/to/document.json

• Allowed file types: .json.
• Methods: GET, HEAD, OPTIONS. Anything else answers 405.
• CORS is open: Access-Control-Allow-Origin: * on every response, preflights answer 204.
• Caching: Cache-Control: public, max-age=2592000 on documents and max-age=300 on .sha files; every response carries an ETag, so conditional requests answer 304.
• Compression: gzip (and brotli where available) on request.
• Health: GET /healthz answers {"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://commentaries.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.

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://commentaries.getbible.net/v1/path/to/document.json

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

{"type":"https://getbible.net/problems/not-found","title":"Not Found","status":404,"code":"not_found","detail":"No such resource on this API. ...","instance":"urn:request:..."}