Bookmarks API v1

Use https://bookmarks.getbible.net/v1/ as the API directory. This is a public, read-only collection of static JSON documents. All eleven operations are GET requests with no request body or query parameters.

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

Discover the catalog#

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

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

The index contains:

Field	Meaning
schema_version	Payload format version, currently 1
catalog_version	Content revision, incremented when the complete catalog checksum changes
checksum	SHA-256 of the exact bytes of all.json
counts.topics	Number of topics
counts.verses	Number of topic-to-verse associations
counts.locales	Number of locale documents
resources	Relative paths and path templates for API resources
locales	Available locale codes

A verse associated with two topics contributes two to counts.verses. This count does not mean distinct scripture verses. Use the index for current counts instead of embedding a fixed catalog size in a client.

Choose a download#

File	Best use
topics.json	Topic picker with English names, colors, and verse counts
topics/{id}.json	One topic with coordinates and available translations
catalog.json	All topics and coordinates without locale documents
all.json	Complete offline collection, including every locale
verses/{book}.json	Related-topic lookup for an entire book
verses/{book}/{chapter}.json	Related-topic lookup for one displayed chapter
locales.json	Discover languages and translation coverage
locales/{locale}.json	Translated topic names for one locale

Topic identifiers and response fields#

Topic IDs are lowercase hyphenated slugs from topics.json. English names, aliases, and translated names are display values, not alternative endpoint addresses.

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

Every individual topic includes:

Field	Type	Meaning
schema_version	integer	Always 1 in v1 documents
id	string	Stable topic slug
name	string	Canonical English display name
color	string	Lowercase six-digit hex color, prefixed with #
aliases	string array	Alternative English display names
default	boolean	Source catalog's default flag
names	object	Available locale codes mapped to translated names, including English
verses	array of triples	Sorted scripture coordinates

The verses member changes shape between resource types: in topics.json, it is an integer count; in individual topics, catalog.json, and all.json, it is an array of coordinates. Do not use a topic-summary parser for full topic documents.

Verse coordinates#

Each coordinate is exactly [book, chapter, verse], with integer values. The book follows the 66-book Protestant canon: Genesis is 1, Exodus 2, Matthew 40, John 43, and Revelation 66. The schema allows book 1–66, chapter 1–150, and verse 1–2,000; chapter validity is also specific to the selected book.

Coordinates have no translation identifier and include no scripture text. They are intended to connect to a Bible translation chosen by the application. Preserve the selected translation's real verse numbering and handle missing verses according to that translation's coverage.

For example, the coordinate [2, 20, 14] can be read by loading Exodus 20:

curl --fail --silent --show-error \
  'https://api.getbible.net/v2/kjv/2/20.json'

Then select verse 14 using the Bible API response format. Coordinate triples are deduplicated within each topic and sorted.

Reverse lookup: verse to topics#

curl --fail --silent --show-error \
  'https://bookmarks.getbible.net/v1/verses/2/20.json'

A published chapter example is:

{
  "schema_version": 1,
  "book": 2,
  "chapter": 20,
  "verses": {
    "6": ["obey-gods-commandments"],
    "12": ["longevity"],
    "14": ["adultery"]
  }
}

Book and chapter fields are integers; chapter and verse object keys are JSON strings. Topic ID arrays are sorted. A missing verse key means no associations for that verse.

A file exists for every canonical book and every valid canonical chapter, including empty chapters. An empty verses object means a valid chapter with no topic associations. A chapter beyond the selected book's chapter count has no file and returns the host's missing-file response.

For all linked topics at Exodus 20:14:

curl --fail --silent --show-error \
  'https://bookmarks.getbible.net/v1/verses/2/20.json' \
  | jq --raw-output '.verses["14"] // [] | .[]'

The book-level response nests the same mapping one level deeper: chapters["20"]["14"].

Localization and English fallback#

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

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

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

Locale codes are lowercase tags from locales.json, such as en, af, and zh-hant. English is generated from canonical topic names and covers the full catalog. Other locales may be partial.

The API does not infer a language from request headers, fill missing translations, or redirect an unavailable locale to English. Implement the fallback in the client:

function topicName(topic, locale) {
  return topic.names?.[locale] ?? topic.names?.en ?? topic.name;
}

For a locale document, use locale.topics[topic.id] ?? topic.name. In the locale list, name is always present and may be null. In an individual locale document, an unrecorded language name is omitted.

The all.json.locales member contains locale documents keyed by locale. The aggregate topics array contains topic metadata and verse coordinates; an individual topic additionally assembles the available translations in names.

Offline use, catalog versions, and checksums#

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

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

Verify with jq and GNU sha256sum:

set -euo pipefail

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

index.json.checksum also describes the exact all.json bytes, including formatting and final newline. catalog_version increases when that content checksum changes. A documentation-only update can change openapi.json without incrementing the catalog version.

checksums.json.files maps relative paths to SHA-256 hashes for all generated files except itself, including index.json and openapi.json. Compare hashes before refreshing large cached resources. Fetch content and its manifest from a consistent publication; if a deployment changes between requests, refetch and verify again.

The files themselves are deterministic for identical inputs. HTTP cache headers, CORS, and host-specific limits are not prescribed by the generated contract.

Errors and access#

The published API has no authentication system or write endpoint. A token is not part of these public GET requests. Contributions are managed through source control.

Unknown topic IDs, deleted topics, unavailable locale codes, invalid books, and out-of-range chapter paths have no generated file. The OpenAPI contract describes 404 without a JSON error envelope; the hosting server controls the body. Check HTTP status before parsing.

A missing topic is different from a valid topic with no linked verses. A valid chapter with no associations returns HTTP 200 and an empty map. Treat these cases separately in the interface.

Import the OpenAPI description#

Import the OpenAPI 3.1.1 JSON by URL into a compatible client such as Postman. The specification uses servers[0].url: "./", resolving against its own published directory. Operation paths are relative to that directory and do not repeat /v1.

When importing a downloaded file or pasting the specification, explicitly set the base/server URL to https://bookmarks.getbible.net/v1/. Local files do not identify the production host.

Response schemas use JSON Schema Draft 2020-12 and are embedded with local references. Some examples are embedded; larger examples use relative externalValue links to complete published JSON. Those example links need the published base URL or a local copy of the generated files.

Contribute to the shared catalog#

The bookmark builder owns the reviewed sources:

Source	Purpose
data/topics.json	IDs, English names, colors, aliases, and default flags
data/links/{topic}.json	Verse coordinates for one topic
data/locales/{locale}.json	Translated topic names

A source change is validated and rebuilt into static output. Changes are reviewed through GitHub; the generated API accepts no POST, PATCH, or DELETE requests. See the source data rules and contribution guide for topic creation, renaming, translation, and bundle import.

Deletion removes a topic from generated documents at the next build; it is not retained as an alias or tombstone. Keep application caches synchronized through the index checksum and catalog version.

Complete endpoint reference#

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

GET /index.json#

Discover the catalogue and resource paths.

Resource paths are relative to this directory. counts.verses counts topic-to-verse associations, not distinct verses. checksum is the SHA-256 of the exact all.json bytes. catalog_version increments when that content checksum changes; documentation-only changes do not increment it. schema_version describes the payload format.

No parameters.

Response model: Index.

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

GET /all.json#

Download the complete catalogue and all translations.

Contains all topic metadata and verse coordinates, plus every locale's names. This is the content document hashed by index.json. No Scripture text is included.

No parameters.

Response model: All.

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

GET /catalog.json#

Download every topic with its verse coordinates.

The same topics array as all.json, without locale documents. Verse coordinates are translation-independent [book, chapter, verse] triples in the 66-book Protestant canon, sorted without duplicates within a topic. No Scripture text is included.

No parameters.

Response model: Catalog.

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

GET /topics.json#

List topics with verse counts.

Topic summaries use an integer verses count instead of the coordinate arrays returned by catalog.json and individual topic files. Use the stable id to request a topic. Names and aliases are English display text, not alternative URL identifiers.

No parameters.

Response model: Topics.

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

GET /topics/{id}.json#

Read one topic and its translated names.

Returns metadata, all verse coordinates, and names keyed by the locales that translate this topic. English (en) is always included. For a missing translation the client should display the English name. Deleted or unknown topic ids have no file.

Parameter	Type	Required	Meaning
id	string	Yes	Exact topic id from topics.json. Aliases and display names are not URL ids. Maximum length: 80. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.

Response model: Topic.

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

GET /verses/{book}.json#

Find topics associated with verses in a book.

A file exists for each of the 66 books. chapters maps chapter-number strings to verse-number strings to sorted topic-id arrays. Only linked chapters and verses appear in the maps. An empty chapters object means no associations in the book.

Parameter	Type	Required	Meaning
book	integer	Yes	Book number in the 66-book Protestant canon, without leading zeros. | Book | Name | Chapters | |---|---|---| | 1 | Genesis | 50 | | 2 | Exodus | 40 | | 3 | Leviticus | 27 | | 4 | Numbers | 36 | | 5 | Deuteronomy | 34 | | 6 | Joshua | 24 | | 7 | Judges | 21 | | 8 | Ruth | 4 | | 9 | 1 Samuel | 31 | | 10 | 2 Samuel | 24 | | 11 | 1 Kings | 22 | | 12 | 2 Kings | 25 | | 13 | 1 Chronicles | 29 | | 14 | 2 Chronicles | 36 | | 15 | Ezra | 10 | | 16 | Nehemiah | 13 | | 17 | Esther | 10 | | 18 | Job | 42 | | 19 | Psalms | 150 | | 20 | Proverbs | 31 | | 21 | Ecclesiastes | 12 | | 22 | Song of Solomon | 8 | | 23 | Isaiah | 66 | | 24 | Jeremiah | 52 | | 25 | Lamentations | 5 | | 26 | Ezekiel | 48 | | 27 | Daniel | 12 | | 28 | Hosea | 14 | | 29 | Joel | 3 | | 30 | Amos | 9 | | 31 | Obadiah | 1 | | 32 | Jonah | 4 | | 33 | Micah | 7 | | 34 | Nahum | 3 | | 35 | Habakkuk | 3 | | 36 | Zephaniah | 3 | | 37 | Haggai | 2 | | 38 | Zechariah | 14 | | 39 | Malachi | 4 | | 40 | Matthew | 28 | | 41 | Mark | 16 | | 42 | Luke | 24 | | 43 | John | 21 | | 44 | Acts | 28 | | 45 | Romans | 16 | | 46 | 1 Corinthians | 16 | | 47 | 2 Corinthians | 13 | | 48 | Galatians | 6 | | 49 | Ephesians | 6 | | 50 | Philippians | 4 | | 51 | Colossians | 4 | | 52 | 1 Thessalonians | 5 | | 53 | 2 Thessalonians | 3 | | 54 | 1 Timothy | 6 | | 55 | 2 Timothy | 4 | | 56 | Titus | 3 | | 57 | Philemon | 1 | | 58 | Hebrews | 13 | | 59 | James | 5 | | 60 | 1 Peter | 5 | | 61 | 2 Peter | 3 | | 62 | 1 John | 5 | | 63 | 2 John | 1 | | 64 | 3 John | 1 | | 65 | Jude | 1 | | 66 | Revelation | 22 | Minimum: 1. Maximum: 66.

Response model: Book.

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

GET /verses/{book}/{chapter}.json#

Find topics associated with verses in a chapter.

Every valid canonical chapter has a file, even when verses is empty. Keys are verse numbers as strings; values are sorted topic-id arrays. A missing verse key means no associations. A chapter beyond the selected book's chapter count has no file.

Parameter	Type	Required	Meaning
book	integer	Yes	Book number in the 66-book Protestant canon, without leading zeros. | Book | Name | Chapters | |---|---|---| | 1 | Genesis | 50 | | 2 | Exodus | 40 | | 3 | Leviticus | 27 | | 4 | Numbers | 36 | | 5 | Deuteronomy | 34 | | 6 | Joshua | 24 | | 7 | Judges | 21 | | 8 | Ruth | 4 | | 9 | 1 Samuel | 31 | | 10 | 2 Samuel | 24 | | 11 | 1 Kings | 22 | | 12 | 2 Kings | 25 | | 13 | 1 Chronicles | 29 | | 14 | 2 Chronicles | 36 | | 15 | Ezra | 10 | | 16 | Nehemiah | 13 | | 17 | Esther | 10 | | 18 | Job | 42 | | 19 | Psalms | 150 | | 20 | Proverbs | 31 | | 21 | Ecclesiastes | 12 | | 22 | Song of Solomon | 8 | | 23 | Isaiah | 66 | | 24 | Jeremiah | 52 | | 25 | Lamentations | 5 | | 26 | Ezekiel | 48 | | 27 | Daniel | 12 | | 28 | Hosea | 14 | | 29 | Joel | 3 | | 30 | Amos | 9 | | 31 | Obadiah | 1 | | 32 | Jonah | 4 | | 33 | Micah | 7 | | 34 | Nahum | 3 | | 35 | Habakkuk | 3 | | 36 | Zephaniah | 3 | | 37 | Haggai | 2 | | 38 | Zechariah | 14 | | 39 | Malachi | 4 | | 40 | Matthew | 28 | | 41 | Mark | 16 | | 42 | Luke | 24 | | 43 | John | 21 | | 44 | Acts | 28 | | 45 | Romans | 16 | | 46 | 1 Corinthians | 16 | | 47 | 2 Corinthians | 13 | | 48 | Galatians | 6 | | 49 | Ephesians | 6 | | 50 | Philippians | 4 | | 51 | Colossians | 4 | | 52 | 1 Thessalonians | 5 | | 53 | 2 Thessalonians | 3 | | 54 | 1 Timothy | 6 | | 55 | 2 Timothy | 4 | | 56 | Titus | 3 | | 57 | Philemon | 1 | | 58 | Hebrews | 13 | | 59 | James | 5 | | 60 | 1 Peter | 5 | | 61 | 2 Peter | 3 | | 62 | 1 John | 5 | | 63 | 2 John | 1 | | 64 | 3 John | 1 | | 65 | Jude | 1 | | 66 | Revelation | 22 | Minimum: 1. Maximum: 66.
chapter	integer	Yes	Chapter number without leading zeros. Must not exceed the selected book's chapter count (see the book parameter table); 150 is only the maximum across all books. Minimum: 1. Maximum: 150.

Response model: Chapter.

curl --fail --silent --show-error \
  'https://bookmarks.getbible.net/v1/verses/43/1.json'

GET /locales.json#

List available locales and translation coverage.

Each entry gives the locale code, its English language name (null if unrecorded), and the number of topic names translated. English (en) is always complete; other locales may translate only part of the catalogue.

No parameters.

Response model: Locales.

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

GET /locales/{locale}.json#

Read topic names for one locale.

topics maps stable topic ids to translated names. name is omitted when no language name is recorded. en is derived from the English topic names and is always present. Other locales may be partial. Clients must implement English fallback; requesting an unavailable locale does not automatically return English.

Parameter	Type	Required	Meaning
locale	string	Yes	Exact lowercase locale code from locales.json, such as en or zh-hant. Unsupported locales do not fall back automatically. Maximum length: 16. Pattern: ^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$.

Response model: Locale.

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

GET /checksums.json#

Read SHA-256 hashes for the generated files.

files maps relative paths to SHA-256 hashes of the exact published bytes. Includes index.json and openapi.json; excludes checksums.json itself to avoid self-reference. Use this manifest to verify downloads from the same build.

No parameters.

Response model: Checksums.

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

GET /openapi.json#

Read this OpenAPI description.

Generated with the API on every build. Describes the available GET routes, path parameters, response schemas and examples. Response schemas are embedded with local references so schema resolution does not require another download.

No parameters.

Response model: JSON object.

curl --fail --silent --show-error \
  'https://bookmarks.getbible.net/v1/openapi.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.

Index#

Discovery document. checksum is the SHA-256 of all.json; catalog_version increments whenever that checksum changes between published builds.

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
catalog_version	integer	Yes	Minimum: 1.
checksum	string	Yes	Pattern: ^[0-9a-f]{64}$.
counts	object	Yes	No additional fields.
counts.topics	integer	Yes	Minimum: 0.
counts.verses	integer	Yes	Minimum: 0.
counts.locales	integer	Yes	Minimum: 0.
resources	object	Yes
resources.{key}	string	—
locales	array	Yes

All#

v1/all.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
topics	array	Yes
topics[].id	string	Yes	Maximum length: 80. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.
topics[].name	string	Yes	Maximum length: 80. Pattern: ^[A-Za-z0-9][A-Za-z0-9 &'():?-]*[A-Za-z0-9)]$.
topics[].color	string	Yes	Pattern: ^#[0-9a-f]{6}$.
topics[].aliases	array	Yes	Maximum items: 20. Items are unique.
topics[].default	boolean	Yes
topics[].verses	array	Yes	Maximum items: 100000.
topics[].verses[][0]	integer	Yes	Minimum: 1. Maximum: 66.
topics[].verses[][1]	integer	Yes	Minimum: 1. Maximum: 150.
topics[].verses[][2]	integer	Yes	Minimum: 1. Maximum: 2000.
locales	object	Yes
locales.{key}	Locale	—	See Locale.

Catalog#

v1/catalog.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
topics	array	Yes
topics[].id	string	Yes	Maximum length: 80. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.
topics[].name	string	Yes	Maximum length: 80. Pattern: ^[A-Za-z0-9][A-Za-z0-9 &'():?-]*[A-Za-z0-9)]$.
topics[].color	string	Yes	Pattern: ^#[0-9a-f]{6}$.
topics[].aliases	array	Yes	Maximum items: 20. Items are unique.
topics[].default	boolean	Yes
topics[].verses	array	Yes	Maximum items: 100000.
topics[].verses[][0]	integer	Yes	Minimum: 1. Maximum: 66.
topics[].verses[][1]	integer	Yes	Minimum: 1. Maximum: 150.
topics[].verses[][2]	integer	Yes	Minimum: 1. Maximum: 2000.

Topics#

v1/topics.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
topics	array	Yes
topics[].id	string	Yes	Maximum length: 80. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.
topics[].name	string	Yes	Maximum length: 80. Pattern: ^[A-Za-z0-9][A-Za-z0-9 &'():?-]*[A-Za-z0-9)]$.
topics[].color	string	Yes	Pattern: ^#[0-9a-f]{6}$.
topics[].aliases	array	Yes	Maximum items: 20. Items are unique.
topics[].default	boolean	Yes
topics[].verses	integer	Yes	Minimum: 0.

Topic#

v1/topics/.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
id	string	Yes	Maximum length: 80. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.
name	string	Yes	Maximum length: 80. Pattern: ^[A-Za-z0-9][A-Za-z0-9 &'():?-]*[A-Za-z0-9)]$.
color	string	Yes	Pattern: ^#[0-9a-f]{6}$.
aliases	array	Yes	Maximum items: 20. Items are unique.
default	boolean	Yes
names	object	Yes
names.{key}	string	—	Minimum length: 1. Maximum length: 120.
verses	array	Yes	Maximum items: 100000.
verses[][0]	integer	Yes	Minimum: 1. Maximum: 66.
verses[][1]	integer	Yes	Minimum: 1. Maximum: 150.
verses[][2]	integer	Yes	Minimum: 1. Maximum: 2000.

Book#

v1/verses/.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
book	integer	Yes	Minimum: 1. Maximum: 66.
chapters	object	Yes
chapters.{key}	object	—

Chapter#

v1/verses//.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
book	integer	Yes	Minimum: 1. Maximum: 66.
chapter	integer	Yes	Minimum: 1. Maximum: 150.
verses	object	Yes
verses.{key}	array	—	Minimum items: 1.

Locales#

v1/locales.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
locales	array	Yes
locales[].code	string	Yes	Maximum length: 16. Pattern: ^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$.
locales[].name	string, null	Yes	Maximum length: 80.
locales[].topics	integer	Yes	Minimum: 0.

Locale#

Translated topic names for one locale (data/locales/.json and v1/locales/.json)

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
locale	string	Yes	Maximum length: 16. Pattern: ^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$.
name	string	No	Minimum length: 1. Maximum length: 80.
topics	object	Yes
topics.{key}	string	—	Minimum length: 1. Maximum length: 120.

Checksums#

v1/checksums.json

Field	Type	Required	Meaning and constraints
schema_version	number	Yes	Constant: 1.
files	object	Yes
files.{key}	string	—	Pattern: ^[0-9a-f]{64}$.

Sources#

• Published bookmarks OpenAPI specification
• Generated bookmarks data repository
• Bookmark builder API documentation
• Bookmark builder architecture and contribution documentation

Complete contract reference#

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