Dictionaries API v1

Use https://dictionaries.getbible.net/v1/ as the document root. Every route is a GET of a static JSON file. There are no request bodies, query parameters, or content-negotiated variants. The contract defines no authentication scheme.

API overview · Service documentation · OpenAPI JSON · Builder source · Public support

Quick start#

Fetch the catalog, inspect a dictionary, then retrieve one word:

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/dictionaries.json'

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/metadata.json'

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/G3056.json'

The catalog lists current dictionary identifiers, languages, licenses, entry counts, unique-key counts, Strong's prefixes, and whole-dictionary sizes. Read it at runtime or when refreshing an application cache instead of fixing the current module list in code.

Find a word#

A dictionary's index.json returns an entries array. Each record includes:

Field	Meaning
id	Exact document identifier to use in the entry URL
key	The dictionary's original display key
search	Accent-insensitive lowercase search term
aliases	Optional alternative spellings or keys
occurrence	Optional position for later definitions of a repeated key

The index is sorted by search, which supports in-memory filtering, prefix matching, and binary search. Each result resolves directly to {dictionary}/{id}.json. Do not construct the document ID by uppercasing, slugifying, or normalizing a display name.

This Bash example uses cURL and jq to fetch the first Easton entry whose normalized key is kadesh:

set -euo pipefail

dictionary_index="$(curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/easton/index.json')"

entry_id="$(jq --raw-output --exit-status \
  '[.entries[] | select(.search == "kadesh")][0].id' \
  <<< "$dictionary_index")"

curl --fail --silent --show-error \
  "https://dictionaries.getbible.net/v1/easton/${entry_id}.json"

Repeated keys represent distinct definitions. The first definition keeps the base identifier; later definitions use deterministic suffixes such as --2 and --3. Literal keys may already reserve a suffix, so the suffix itself is not a reliable occurrence counter. Use occurrence and keep all matching index records when showing multiple definitions.

Strong's lexicons#

Strong's entry IDs follow GetBible tokens:

Lexicon	ID rule	Example
Greek	G plus the unpadded number	strongsgreek/G3056.json
Hebrew	H0 plus the unpadded number	strongshebrew/H0430.json

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/G3056.json'

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongshebrew/H0430.json'

Preserve the published token, particularly the Hebrew prefix. A source module's key can have different padding from its public id; for example, an entry may have key: "00430" and id: "H0430".

Entry response#

Required fields are schema, dictionary, language, id, key, occurrence, aliases, and text. Optional see_also and backlinks arrays contain {id, key} pairs in the same dictionary. Optional references contains structured scripture citations.

text is plain text with preserved line and paragraph breaks. For a browser interface, assign it to textContent and use an appropriate whitespace style. Dictionary links and scripture references are separate structured data; they are not HTML hidden inside the definition.

The complete dictionary response contains schema, dictionary, language, name, and an entries array. Each entry is the same document served separately. Its order matches the index.

Scripture references#

A reference has required ref, osis, book, and chapter fields:

Field	Type	Use
ref	string	Canonical reference in the module's language
osis	string	OSIS identifier for the reference anchor
book	integer, 1–83	GetBible book number
chapter	integer, at least 0	Chapter coordinate
verse	optional integer, at least 0	Single verse or first covered verse
verses	optional integer array	All covered verses, including the anchor
text	optional string	Citation exactly as it appears in the definition

If verses exists, it defines coverage. Otherwise verse means one verse. If neither exists, the reference covers the whole chapter. A range crossing chapters is represented by separate chapter references.

Use numeric coordinates with the Bible API, or pass ref to the Query API. Long topical references can exceed the Query API's reference-length limit; split their verse lists into smaller requests when necessary. The metadata's references object records the Bible versification, translation shape, naming translation, and parser tables used during the build.

Offline downloads and integrity#

Check metadata.json.bytes before requesting a whole dictionary. Downloading the entire resource is useful for offline applications; fetching the index once and entries on demand is a lighter starting point for an online interface.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/easton.json' \
  --output easton.json

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/hashes.json' \
  --output dictionary-hashes.json

Verify the exact downloaded bytes with jq and GNU sha256sum:

set -euo pipefail

expected="$(jq --raw-output --exit-status \
  '.files["easton.json"]' dictionary-hashes.json)"
printf '%s  %s\n' "$expected" easton.json | sha256sum --check -

The manifest excludes itself and includes every other generated document. Refresh the manifest together with the files you verify. If a publication changes between requests, fetch a fresh manifest and retry the affected download rather than accepting a mismatch.

Content is byte-stable while a module remains unchanged. Catalog and build records can change between builds. HTTP cache headers, CORS, rate controls, and hosting errors are deployment behavior; the static document contract does not prescribe them.

Build provenance and licensing#

build.json identifies the builder, extractor, contract, build time, catalog source, Bible API, and module count. build-report.json describes compilation health: success means all approved modules built; partial can include successful output and failures. Its retained list identifies previously verified modules kept after their rebuild failed.

Each dictionary's metadata includes the original module, license, copyright details, distribution notes, source page, conversion note, and reference-resolution provenance. Preserve resource-specific attribution and consult these fields when distributing downloaded modules.

Errors and client behavior#

A successful document request returns JSON with HTTP 200. An unknown dictionary, missing entry, or path not present in hashes.json has no document and is described as HTTP 404. The contract does not define a JSON error envelope. Check the HTTP status before parsing the body as JSON; cURL's --fail makes unsuccessful HTTP responses fail the command.

An absent optional link array means no such links were published. A missing entry is not an empty definition. Search the index first and follow its exact identifier.

Import into an API client#

Import the OpenAPI 3.1 JSON by URL in an OpenAPI-compatible client such as Postman. The generated description deliberately has no fixed hostname, and its operation paths already start with /v1. Set the imported client's server or base URL to https://dictionaries.getbible.net, without adding another /v1.

The response schemas are embedded in the specification. They are also available under /v1/schema/ for validation. This guide's endpoint and response reference below is generated from that contract.

Complete endpoint reference#

All paths below are relative to https://dictionaries.getbible.net. Every operation returns JSON for HTTP 200 and describes HTTP 404 for a missing document.

GET /v1/dictionaries.json#

The catalog of every dictionary in the tree.

Every dictionary this tree holds, with its counts and sizes, and the path template of each of its documents relative to v1/.

No parameters.

Response model: dictionary-catalog.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/dictionaries.json'

GET /v1/build.json#

How and when the tree was built.

The builder and extractor versions, the build time, the module catalog the modules were selected from and the Bible API the references were resolved against.

No parameters.

Response model: build.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/build.json'

GET /v1/build-report.json#

The compilation outcome and module failures.

The build status, successfully rebuilt modules, failures with their stage and reason, and previously verified modules retained after a failed rebuild. This snapshot describes compilation; the workflow report also records later publication errors.

No parameters.

Response model: build-report.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/build-report.json'

GET /v1/hashes.json#

The SHA-256 of every other document.

The integrity manifest of the tree: a digest for every other document, which is also the complete list of the paths the tree contains.

No parameters.

Response model: hashes.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/hashes.json'

GET /v1/openapi.json#

This description.

The OpenAPI description of the tree, generated with it.

No parameters.

Response model: JSON object.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/openapi.json'

GET /v1/schema/{document}.json#

The JSON Schema of one document type.

The schemas embedded under components, served beside the data.

Parameter	Type	Required	Meaning
document	string	Yes	The document type. Allowed values: "dictionary-catalog", "dictionary-metadata", "dictionary-index", "dictionary-entry", "dictionary", "build", "build-report", "hashes".

Response model: JSON object.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/schema/dictionary-entry.json'

GET /v1/{dictionary}/metadata.json#

One dictionary's provenance, licence, counts and sizes.

Where the module came from, under which licence, how many words it holds, how large its whole-dictionary document is, and which Bible its references were resolved against.

Parameter	Type	Required	Meaning
dictionary	string	Yes	The dictionary's id, as dictionaries.json lists it. Minimum length: 1.

Response model: dictionary-metadata.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/metadata.json'

GET /v1/{dictionary}/index.json#

Every word of one dictionary.

Every word once, sorted by its accent-insensitive lowercase search term, with the id of the document that holds it.

Parameter	Type	Required	Meaning
dictionary	string	Yes	The dictionary's id, as dictionaries.json lists it. Minimum length: 1.

Response model: dictionary-index.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/index.json'

GET /v1/{dictionary}/{entry}.json#

One word of one dictionary.

The definition, the words it links to and from, and the scripture it cites.

Parameter	Type	Required	Meaning
dictionary	string	Yes	The dictionary's id, as dictionaries.json lists it. Minimum length: 1.
entry	string	Yes	The word's id as index.json lists it: a Strong's token such as G3056 or H0430 in a Strong's lexicon, otherwise a deterministic path-safe id, with --2, --3 and so on for later definitions of a repeated key. Minimum length: 1.

Response model: dictionary-entry.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek/G3056.json'

GET /v1/{dictionary}.json#

The whole dictionary.

Every entry document in index order, each byte-for-byte the document served at its own path. A bulk document: metadata.json states its size.

Parameter	Type	Required	Meaning
dictionary	string	Yes	The dictionary's id, as dictionaries.json lists it. Minimum length: 1.

Response model: dictionary.

curl --fail --silent --show-error \
  'https://dictionaries.getbible.net/v1/strongsgreek.json'

Complete response field reference#

The tables preserve the generated OpenAPI field names, types, required fields, and constraints. Nested required fields are required when their containing object is present. Fields marked optional may be omitted. JSON Schemas in the linked specification provide the complete machine-readable contract.

dictionary-catalog#

Every dictionary in one v1 tree, with the path template of each of its documents relative to the tree root. The catalog and build.json are the only documents that carry the build time.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-dictionaries-catalog-v1".
version	number	Yes	Constant: 1.
generated_at	string	Yes	Format: date-time.
base_url	string	Yes	Minimum length: 1.
metadata_url_template	string	Yes	Constant: "{dictionary}/metadata.json".
index_url_template	string	Yes	Constant: "{dictionary}/index.json".
dictionary_url_template	string	Yes	Constant: "{dictionary}.json".
entry_url_template	string	Yes	Constant: "{dictionary}/{entry}.json".
module_count	integer	Yes	Minimum: 0.
dictionaries	array	Yes
dictionaries[].id	string	Yes	Minimum length: 1.
dictionaries[].name	string	Yes	Minimum length: 1.
dictionaries[].language	string	Yes	Minimum length: 2.
dictionaries[].license	string	Yes
dictionaries[].entry_count	integer	Yes	Minimum: 0.
dictionaries[].unique_key_count	integer	Yes	Minimum: 0.
dictionaries[].strong_prefix	string, null	Yes	Allowed values: "G", "H", null.
dictionaries[].bytes	integer	Yes	Minimum: 0.

dictionary-metadata#

One dictionary's provenance, licence, counts and sizes. bytes is the size of the whole-dictionary document.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-dictionary-metadata-v1".
id	string	Yes	Minimum length: 1.
module	string	Yes	The source module's own name. Minimum length: 1.
name	string	Yes	Minimum length: 1.
language	string	Yes	Minimum length: 2.
version	string	Yes
license	string	Yes
driver	string	Yes
source_type	string	Yes
entry_count	integer	Yes	Minimum: 0.
unique_key_count	integer	Yes	Minimum: 0.
strong_prefix	string, null	Yes	Allowed values: "G", "H", null.
bytes	integer	Yes	Minimum: 0.
index_url	string	Yes	Constant: "index.json".
entry_url_template	string	Yes	Constant: "{entry}.json".
source	string	Yes	Constant: "CrossWire SWORD".
source_module_url	string	Yes	The module's own page at its source. Minimum length: 1.
text_source	string	Yes
copyright	string	Yes
copyright_holder	string	Yes
copyright_contact	object	Yes	No additional fields.
copyright_contact.name	string	Yes
copyright_contact.email	string	Yes
copyright_contact.address	string	Yes
distribution_notes	string	Yes
about	string	Yes
conversion_note	string	Yes	Minimum length: 1.
references	object	Yes	Which Bible the module's scripture references were resolved against: the API, the versification, the translations whose shape decided which chapters and verses exist, the translation whose book names ref uses, and the librarian and alias tables that resolved the spellings. No additional fields.
references.api	string	Yes	Constant: "getbible-v2".
references.versification	string	Yes
references.translations	array	Yes
references.names	string, null	Yes
references.language	string	Yes
references.librarian	array	Yes
references.aliases	array	Yes

dictionary-index#

Every word in one dictionary, sorted by the accent-insensitive lowercase search term. One fetch is enough to search a dictionary in any direction; the word itself is then at entry_url_template with the record's id.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-dictionary-index-v1".
dictionary	string	Yes	Minimum length: 1.
language	string	Yes	Minimum length: 2.
name	string	Yes	Minimum length: 1.
entry_url_template	string	Yes	Constant: "{entry}.json".
entry_count	integer	Yes	Minimum: 0.
unique_key_count	integer	Yes	Minimum: 0.
entries	array	Yes
entries[].id	string	Yes	Minimum length: 1.
entries[].key	string	Yes	Minimum length: 1.
entries[].search	string	Yes	Minimum length: 1.
entries[].aliases	array	No	Minimum items: 1.
entries[].occurrence	integer	No	Minimum: 2.

dictionary-entry#

One word of one dictionary. see_also lists the words this entry points at; backlinks lists the words that point back.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-dictionary-entry-v1".
dictionary	string	Yes	Minimum length: 1.
language	string	Yes	Minimum length: 2.
id	string	Yes	Minimum length: 1.
key	string	Yes	Minimum length: 1.
occurrence	integer	Yes	Minimum: 1.
aliases	array	Yes	Minimum items: 1.
text	string	Yes
see_also	links	No	See dictionary-entry/$defs/links.
backlinks	links	No	See dictionary-entry/$defs/links.
references	array	No
references[].text	string	No	Minimum length: 1.
references[].ref	string	Yes	Minimum length: 1.
references[].osis	string	Yes	Minimum length: 1.
references[].book	integer	Yes	Minimum: 1. Maximum: 83.
references[].chapter	integer	Yes	Minimum: 0.
references[].verse	integer	No	Minimum: 0.
references[].verses	array	No	Every verse this reference covers, including verse. Absent when it covers only verse. Minimum items: 2. Items are unique.

dictionary-entry: links#

Field	Type	Required	Meaning and constraints
id	string	Yes	Minimum length: 1.
key	string	Yes	Minimum length: 1.

dictionary#

One complete dictionary in index order. Each member of entries is byte-for-byte the document served at {dictionary}/{entry}.json. This is a bulk document for offline clients; metadata.json publishes its size in bytes.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-dictionary-v1".
dictionary	string	Yes	Minimum length: 1.
language	string	Yes	Minimum length: 2.
name	string	Yes	Minimum length: 1.
entries	array	Yes
entries[]	dictionary-entry	—	See dictionary-entry.

build#

How and when one v1 tree was built: the builder and extractor, the catalog the modules were selected from and the Bible API the references were resolved against.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-build-v1".
builder	string	Yes	Constant: "v1_study_builder".
builder_version	string	Yes	Minimum length: 1.
extractor	string	Yes	Constant: "getbiblesword".
extractor_version	string	Yes	Minimum length: 1.
extractor_contract	string	Yes	Minimum length: 1.
api_version	number	Yes	Constant: 1.
resource	enum	Yes	Allowed values: "commentaries", "dictionaries".
generated_at	string	Yes	Format: date-time.
catalog_url	string	Yes	Minimum length: 1.
bible_api	string	Yes	Minimum length: 1.
module_count	integer	Yes	Minimum: 0.

build-report#

Compilation status and actionable diagnostics for one build. A published snapshot is captured before repository publication; the workflow report is updated with later publication errors. Successfully rebuilt modules and retained previous modules are listed separately.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-build-report-v1".
status	enum	Yes	Running is an in-progress checkpoint. Success means all approved modules built; partial means usable output exists with reported failures. Failed means the run could not complete safely. Publication failures are recorded in the workflow report. Allowed values: "running", "success", "partial", "failed".
started_at	string	Yes	Format: date-time.
completed_at	string, null	Yes	Format: date-time.
requested_resource	enum	Yes	Allowed values: "all", "commentaries", "dictionaries".
catalog_url	string	Yes	Minimum length: 1.
built	object	Yes	No additional fields.
built.commentaries	array	Yes
built.dictionaries	array	Yes
skipped	array	Yes
skipped[]	moduleIssue	—	See build-report/$defs/moduleIssue.
failed	array	Yes
failed[]	moduleFailure	—	See build-report/$defs/moduleFailure.
retained	array	Yes	Failed modules whose prior verified documents remain in the published tree.
retained[]	moduleIssue	—	See build-report/$defs/moduleIssue.
errors	array	Yes
errors[].stage	string	Yes	Minimum length: 1.
errors[].error_type	string	Yes	Minimum length: 1.
errors[].reason	string	Yes
errors[].resource	enum	No	Allowed values: "commentaries", "dictionaries".
diagnostics	object	Yes
diagnostics.{key}	array	—
storage	object	Yes
storage.{key}	object	—
commits	object	Yes
commits.{key}	string, null	—

build-report: moduleIssue#

Field	Type	Required	Meaning and constraints
resource	enum	Yes	Allowed values: "commentaries", "dictionaries".
module	string	Yes	Minimum length: 1.
reason	string	Yes

build-report: moduleFailure#

Field	Type	Required	Meaning and constraints
resource	enum	Yes	Allowed values: "commentaries", "dictionaries".
module	string	Yes	Minimum length: 1.
reason	string	Yes
stage	string	Yes	Minimum length: 1.
error_type	string	Yes	Minimum length: 1.

hashes#

The SHA-256 of every other document in one v1 tree, keyed by path relative to the tree root; also the complete list of the paths the tree contains.

Field	Type	Required	Meaning and constraints
schema	string	Yes	Constant: "getbible-hashes-v1".
algorithm	string	Yes	Constant: "sha256".
files	object	Yes
files.{key}	string	—	Pattern: ^[0-9a-f]{64}$.

Sources#

• Published dictionaries OpenAPI specification
• Generated dictionaries data repository
• Study builder contracts and implementation guide

Complete contract reference#

Open the complete endpoint and schema reference for every operation, parameter, response and component model in the published OpenAPI contract.