api · v1

¶ Documentation

Everything you need to read, paginate, and search 6 public-domain translations of the Bible: clean JSON, predictable URLs.

Quickstart

1Create an account: you'll get an API key immediately.
2Send the key as a Bearer token: Authorization: Bearer {YOUR_KEY}
3Hit any of the endpoints below. The free tier allows 30 requests / minute and 2,500 / month — see pricing for higher limits.

Authentication

All endpoints require a Bearer token. Tokens are issued from the dashboard and never expire (you revoke when needed).

# All requests look like this
curl https://versemark.dev/api/v1/bibles \
  -H "Authorization: Bearer versemark_pk_..."

v. ❋ try it now

Playground

Live calls to the API. Your key is stored in this browser only: never sent anywhere except your own request.

api key

endpoint

translation

book (osis)

chapter

verse

query

reference text

theme slug

translations (csv)

radius

limit

/api/v1/bibles/kjv/John/3/16

code snippet

curl ...

response -

// Hit "Send →" to make a request.

GET

/v1/bibles

List all available translations.

{
  "data": [
    {
      "code": "kjv",
      "name": "King James Version",
      "language": "en",
      "license": "public-domain",
      "year_published": 1611
    }
  ]
}

GET

/v1/books

All 66 books with OSIS IDs, abbreviations, and chapter counts. Use these osis_id values in chapter/verse paths.

GET

/v1/bibles/{translation}/{book}/{chapter}

Returns every verse in a chapter, ordered. {book} accepts OSIS IDs (Gen, Ps, John) and full names (Genesis, Psalms).

GET /v1/bibles/kjv/Ps/23

{
  "data": {
    "translation": "kjv",
    "book": "Ps",
    "chapter": 23,
    "verse_count": 6,
    "verses": [
      { "verse": 1, "text": "The LORD is my shepherd..." }
    ]
  }
}

GET

/v1/bibles/{translation}/{book}/{chapter}/{verse}

A single verse. The cheapest, fastest endpoint we offer.

vii. ❋ cross-references

GET

/v1/bibles/{translation}/{book}/{chapter}/{verse}/refs

For any verse, return cross-referenced passages from the Treasury of Scripture Knowledge + community votes (340k+ links). Sorted by votes, descending. Includes a preview of the linked verse in the requested translation.

GET /v1/bibles/kjv/John/3/16/refs?limit=3

{
  "meta": { "source": { "reference": "John 3:16", "text": "For God so loved..." } },
  "data": [
    {
      "reference": "Romans 5:8",
      "votes": 962,
      "preview": "But God commendeth his love toward us..."
    }
  ]
}

Add ?min_votes=10 to filter low-confidence links. Source: openbible.info (CC-BY).

GET

/v1/search

FTS5 full-text search with porter stemming and relevance ranking.

param

type

notes

string · required

2–200 chars. Stems automatically.

translation

string · optional

e.g. kjv. Defaults to all.

limit

int · optional

1–100. Default 25.

x. ❋ treasury search

GET

/v1/search/treasury

Concept search using the Treasury of Scripture Knowledge cross-reference graph as the semantic backbone. No neural model, no API key, no extra cost: just 200 years of curated theological consensus, indexed.

how

Each verse is given a TF-IDF "concept fingerprint" blended with the TF-IDF of its top cross-references, weighted by votes.

why

Searching "comfort in suffering" finds Isa 40:1 and 2 Cor 1:4 even though scoring on raw text alone wouldn't rank them this high.

trade-off

Bound to the corpus vocabulary. Words not in the KJV ("anxiety") won't match: try the synonyms the KJV actually uses ("careful," "troubled").

GET /v1/search/treasury?q=comfort+in+suffering&limit=3

{
  "meta": { "index": "treasury" },
  "data": [
    { "reference": "Isaiah 66:13", "score": 0.628, "text": "As one whom his mother comforteth..." },
    { "reference": "Isaiah 40:1", "score": 0.583, "text": "Comfort ye, comfort ye my people..." },
    { "reference": "2 Corinthians 1:4", "score": 0.580, "text": "Who comforteth us in all our tribulation..." }
  ]
}

Index built over the KJV (31k verses, 1.7M fingerprint rows). Results map to your chosen translation by reference. Source data: Treasury of Scripture Knowledge (CC-BY).

viii. ✦ semantic search

GET · beta · self-hosted

/v1/search/semantic

Vector search using whatever embedding provider you configure. Returns verses by meaning, not keyword. Treasury Search handles the common case for free; this is the optional neural-quality upgrade.

i. huggingface

Free tier, hosted, rate-limited.

# sign up: huggingface.co
# then in .env:
EMBEDDING_PROVIDER=huggingface
HUGGINGFACE_API_KEY=hf_...

ii. openai

Best quality, ~$0.02 one-time.

# in .env:
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...

After configuring a provider, run:

php artisan bible:embed # uses your configured provider

GET /v1/search/semantic?q=verses+about+forgiveness&limit=5

{
  "meta": { "model": "hf:sentence-transformers/all-MiniLM-L6-v2" },
  "data": [
    { "reference": "Matthew 6:14", "score": 0.6234, "text": "For if ye forgive men..." }
  ]
}

Embeddings are computed once over the KJV; results map to your chosen translation by reference. Score is cosine similarity (0–1, higher is closer). Each provider stores its embeddings under a distinct model key, so you can keep multiple providers' embeddings side-by-side.

ix. ¶ reference parser

GET / POST

/v1/parse

Turn a free-form reference like "Jn 3:16-18" or "1 Cor 13:4-7" into a structured {book, chapter, verse_start, verse_end}. Add ?expand=1 to also receive the actual verses.

GET /v1/parse?text=1+Cor+13:4-7&expand=1

{
  "data": {
    "input": "1 Cor 13:4-7",
    "book": "1 Corinthians",
    "osis_id": "1Cor",
    "chapter": 13,
    "verse_start": 4,
    "verse_end": 7,
    "reference": "1 Corinthians 13:4-7",
    "verses": [ ... ]
  }
}

Handles abbreviations (Jn, Mt, 1 Cor, II Tim), Roman numerals, missing colons, en-dashes, and cross-chapter ranges (Gen 1:1-2:4).

xi. ⁂ side by side

GET

/v1/compare/{book}/{chapter}/{verse}

Same verse across all six translations in one call. Optional ?translations=kjv,asv,web to limit.

GET

/v1/bibles/{translation}/{book}/{chapter}/{verse}/context

A verse plus its surrounding verses (default radius=3, max 10). Useful for showing scripture in its passage.

GET

/v1/verse-of-the-day

A curated rotating verse, deterministic by UTC date. Cached until midnight UTC. 122-verse cycle of canonical / encouraging passages.

GET

/v1/verses/random

Random verse from the chosen translation. no-store caching so every call gets a fresh draw.

xii. ❦ curated themes

GET

/v1/themes · /v1/themes/{slug}

Hand-curated topical index. Each theme maps to canonical KJV references that scholars and pastors traditionally cite for the topic. Currently: love · anxiety · forgiveness · faith · hope · comfort · wisdom · marriage · money · work · prayer · fear · identity · salvation.

GET /v1/themes/anxiety?translation=kjv

{
  "meta": { "name": "Anxiety", "count": 14 },
  "data": [
    { "reference": "Philippians 4:6", "text": "Be careful for nothing..." },
    { "reference": "1 Peter 5:7", "text": "Casting all your care upon him..." }
  ]
}

GET · public

/api/health

Service status, DB latency, and counts of verses / cross-references / fingerprints / embeddings. Public (no auth required) for monitoring tools.

xiii. § caching

Caching

Bible text never changes, so almost every endpoint returns aggressive cache headers:

header

value

notes

ETag

"<content-hash>"

Send back as If-None-Match for 304 Not Modified.

Cache-Control

public, max-age=86400, immutable

CDN-friendly. /verses/random overrides to no-store.

X-RateLimit-*

Limit / Remaining

Standard throttling headers from Laravel.

vi. ❦ the canon

Book IDs

Use these in the {book} path segment. Aliases like "Genesis" work too.

Genesis Gen

Exodus Exod

Leviticus Lev

Numbers Num

Deuteronomy Deut

Joshua Josh

Judges Judg

Ruth Ruth

1 Samuel 1Sam

2 Samuel 2Sam

1 Kings 1Kgs

2 Kings 2Kgs

1 Chronicles 1Chr

2 Chronicles 2Chr

Ezra Ezra

Nehemiah Neh

Esther Esth

Job Job

Psalms Ps

Proverbs Prov

Ecclesiastes Eccl

Song of Solomon Song

Isaiah Isa

Jeremiah Jer

Lamentations Lam

Ezekiel Ezek

Daniel Dan

Hosea Hos

Joel Joel

Amos Amos

Obadiah Obad

Jonah Jonah

Micah Mic

Nahum Nah

Habakkuk Hab

Zephaniah Zeph

Haggai Hag

Zechariah Zech

Malachi Mal

Matthew Matt

Mark Mark

Luke Luke

John John

Acts Acts

Romans Rom

1 Corinthians 1Cor

2 Corinthians 2Cor

Galatians Gal

Ephesians Eph

Philippians Phil

Colossians Col

1 Thessalonians 1Thess

2 Thessalonians 2Thess

1 Timothy 1Tim

2 Timothy 2Tim

Titus Titus

Philemon Phlm

Hebrews Heb

James Jas

1 Peter 1Pet

2 Peter 2Pet

1 John 1John

2 John 2John

3 John 3John

Jude Jude

Revelation Rev

Errors

Standard HTTP status codes. The body is always JSON with at least an error or message field.

401Missing or invalid Bearer token.

404Translation, book, or verse not found.

422Validation error (e.g. q missing on /search).

429Rate limit exceeded: wait, then retry.

Rate limits

Rate limits are scoped to your authenticated user and set by your plan: 30 / min on Free, 600 / min on Indie, 2,000 / min on Pro. Anonymous traffic (no key) is capped at 20 / minute by IP. Free is also capped at 2,500 requests per calendar month — see pricing for full limits.

vii. ❦ credits & licensing

Credits & licensing

Versemark stands on decades of scholarship released freely to the world. The data behind every endpoint is public-domain or openly licensed; we list our sources here so you can verify, attribute, and trust what you're building on.

Translations

All six translations are in the public domain, drawn from openly licensed biblical text compilations.

King James Version kjv · 1611 Public domain

Young's Literal Translation ylt · 1862 Public domain

Darby Bible darby · 1889 Public domain

American Standard Version asv · 1901 Public domain

World English Bible web · 2000 Public-domain dedication

New Heart English Bible nheb · 2010 Public-domain dedication

Note for UK users: the King James Version remains under perpetual Crown copyright in the United Kingdom, where reproduction is reserved to the Crown's patentee (Cambridge University Press). It is in the public domain everywhere else.

Cross-references

The /refs endpoint is built from the OpenBible.info cross-reference dataset, a community-voted refinement of the Treasury of Scripture Knowledge, used here under CC BY 4.0. If you redistribute Versemark's cross-reference data, please credit OpenBible.info.

Synonym expansion

Treasury and semantic search use Grady Ward's Moby Thesaurus II, released to the public domain via Project Gutenberg.