search.getbible.net /v2/
The getBible search endpoint: give it words, get the verses that contain them. public, metered · tokens unlimited API v2
Routes
GET https://search.getbible.net/v2/{translation}/{search string}
GET https://search.getbible.net/v2/{translation}?q={search string}
GET https://search.getbible.net/v2?q={search string}&translation={translation}
POST https://search.getbible.net/v2/{translation}/{search string} (query parameters and/or JSON)
POST https://search.getbible.net/v2/{translation} (query parameters and/or JSON)
POST https://search.getbible.net/v2 (JSON body with translation)The search string is the last path segment when present. /v2/{search string} without a translation redirects to kjv. GET takes filters from the URL query string. POST accepts the same query parameters, a JSON body, or both; a body is optional when the URL contains the search text. GET bodies are not read. When the same value appears in more than one place, the path wins, then the query string, then the body, then the endpoint's defaults.
curl https://search.getbible.net/v2/kjv/faith%20hope
curl "https://search.getbible.net/v2/kjv/faith%20hope?words=all&scope=new_testament&limit=25"
curl -X POST -H "Content-Type: application/json" \
-d '{"q":"faith hope","scope":"new_testament","limit":25}' https://search.getbible.net/v2/kjvA search string that is a scripture reference, such as John 3:16, returns that scripture without applying full-text filters; the query.kind field says which happened.
Filters
Every filter is optional. The defaults below apply to managed deployments; explicit URL or JSON values override defaults, including false and 0. The q parameter supplies the search text when absent from the path, and translation defaults to kjv when absent from the path. POST fields set to null leave lower-priority values unchanged.
| Parameter | Values | Default |
|---|---|---|
words | all, any, phrase | all |
match | whole_word, substring | whole_word |
case_sensitive | true, false | false |
scope | bible, old_testament, new_testament, deuterocanon | bible |
book (repeatable) / books (comma list) | Book names or numbers; both forms are combined (up to 83 selections) | all books |
diacritics | fold, exact | fold |
exclude (repeatable) | Up to 32 words that must not occur (100 characters each) | none |
proximity | 0 to 100 intervening words (with words=all) | none |
sort | canonical, relevance | canonical |
limit | 1 to 100 | 100 |
offset | 0 to 10000 | 0 |
Unknown parameters, repeated non-repeatable parameters, and values out of range answer 400. Matching is derived from the writing system of the text and the search string, so a bare search string works in every translation; the machine-readable description is in openapi.json.
Response
A JSON envelope with three members: query (normalised criteria, kind, translation, sha, exact total, pagination, cache state and cost), results (the same chapter-keyed scripture object the query endpoint returns) and matches (the ordered verses with score, occurrences and matched terms). Reference results omit full-text criteria, pagination, cache/cost details, scores, occurrences and matched terms. Public GET responses carry Cache-Control: public, max-age=2592000 and an ETag. Token-protected endpoints use private, no-store; POST responses are never cached.
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://search.getbible.net/v2/kjv/faith%20hopeTokens are issued to applications and partners by the getBible team; ask through getbible.net.
Documentation pages, openapi.json, GET /healthz and GET /readyz are available without a token. Token checks apply to API data requests.
Errors
Every error is an RFC 9457 problem document (application/problem+json); the detail field carries the message.
| Status | Code | Meaning |
|---|---|---|
| 400 | missing_search | No search string in the path, the q parameter or the body. |
| 400 | invalid_search, invalid_body, unknown_parameter, repeated_parameter, request_limit | The filters are invalid or over their limits. |
| 401 | unauthorized | A bearer token is required and was missing or invalid. |
| 404 | translation_not_found | No such translation. |
| 404 | unknown_version | Only v2 is served here. |
| 415 | unsupported_media_type | A POST body that is not JSON. |
| 429 | rate_limited | The public budget for your address is used up. |
| 503 | busy, search_timeout, repository_unavailable, readiness_failed | Temporary; retry after the Retry-After seconds. |
Health
GET /healthz answers when the service is up; GET /readyz reads a verse from the default translation. Deployment additionally runs GET /probez through the private service socket to verify the search corpus. The deployment probe is not exposed through the public web server. A failed readiness or deployment check answers 503 with a problem document and Retry-After. Alias redirects use 301 for GET and 308 for POST, preserving JSON bodies and query parameters.