Read-only, keyless, exact

Five GET endpoints over an immutable corpus. No API key. Responses are cacheable for a year and carry an ETag, every verse carries its SHA-256, and every error is application/problem+json with a fixed vocabulary.

Conventions

Base URL https://harness.talk/api/v1. Machine description at /openapi.json (OpenAPI 3.1) and /agents/tools.json (JSON Schema tool manifest — identical to the MCP tools).
Data responses: Cache-Control: public, max-age=31536000, immutable and an ETag. Search responses are cached for a day.
Errors: RFC 9457 application/problem+json. title is the stable code; type links to its definition on /agents/protocol.
Rate limit: a soft per-IP courtesy limit. If you need the whole corpus, take the JSONL export — it is the same bytes.

GET/api/v1/verses/{ref}Live

Fetch one verse (or a verse range) by reference. Returns the exact 1611 KJV text (original spelling) with source id and sha256 for local verification; other ingested texts via `source`.

Parameters

Name	Type	Description
ref	string	A scripture reference. Accepts canonical ids ('jn.3.16', 'jn.3.16-18', 'ps.23'), human forms ('John 3:16', '1 John 5:7', 'Song of Solomon 2:1'), or a fabric quartet ('127.43.3.16').
source?	string	Text source id. Default kjv-1611 (King James 1611 first edition, original spelling). 'geneva-1599' = Geneva Bible 1599 verse text (original spelling; KJV refs with no Geneva counterpart are not_found and listed in `missing` for ranges). 'wlc-oshb' = Hebrew OT, 'sblgnt-morphgnt' = Greek NT (critical text, not the TR); both return the original at the same chapter:verse number with word-level tagging. Asking an OT ref for the Greek source (or vice versa) is not_found; non-ingested sources (textus-receptus) return source_not_ingested. default kjv-1611

Returns

Verse object {ref, display, book, chapter, verse, text, source, sha256, quartet} or {ref, count, verses[]} for ranges.

curl -s https://harness.talk/api/v1/verses/jn.3.16

GET/api/v1/chapters/{ref}Live

Fetch a whole chapter with prev/next navigation, Psalm superscription, and Psalm 119 headings.

Parameters

Name	Type	Description
ref	string	Book and chapter, e.g. 'jn.3', 'Psalm 23', '127.19.23.0'.

Returns

{ref, display, book, chapter, title?, headings?, prev, next, quartet, source, verses[]}

curl -s https://harness.talk/api/v1/chapters/ps.23

GET/api/v1/searchLive

Lexical search over the KJV. Plain terms (all must match, light stemming), a "quoted phrase" for exact phrase, or a reference to resolve it. Ranked, paginated.

Parameters

Name	Type	Description
q	string
limit?	integer	default 20
offset?	integer	default 0
book?	string	Restrict to one book id, e.g. 'ps'.

Returns

{query, mode: 'reference'|'phrase'|'terms', total, hits: Verse[] with score, limit, offset}

curl -s 'https://harness.talk/api/v1/search?q=everlasting+life&limit=5'

GET/api/v1/annotations/{ref}Live

Annotation layer for a chapter or verse: the Geneva Bible's chapter arguments, marginal notes, cross-references (source 'geneva-notes'). Returns source_not_ingested where the source has no verified data — never a substitute. For the Geneva verse TEXT use getVerse with source=geneva-1599.

Parameters

Name	Type	Description
ref	string	A scripture reference. Accepts canonical ids ('jn.3.16', 'jn.3.16-18', 'ps.23'), human forms ('John 3:16', '1 John 5:7', 'Song of Solomon 2:1'), or a fabric quartet ('127.43.3.16').
source?	string	default geneva-notes

Returns

{ref, source, count, annotations: [{id, kind, ref, text, anchor?, targets?, source}]}

curl -s https://harness.talk/api/v1/annotations/gn.3

GET/api/v1/words/{ref}Live

Original-language text with word-level tagging for a verse, range, or chapter. OT → Hebrew (WLC/OSHB: word, Strong's, morphology; Aramaic verses flagged). NT → Greek (SBLGNT/MorphGNT: word, lemma, morphology, POS). SBLGNT is a critical text, NOT the Textus Receptus behind the KJV; versification follows the original and is never remapped — verses the KJV has but the original lacks are listed in `missing`.

Parameters

Name	Type	Description
ref	string	A scripture reference. Accepts canonical ids ('jn.3.16', 'jn.3.16-18', 'ps.23'), human forms ('John 3:16', '1 John 5:7', 'Song of Solomon 2:1'), or a fabric quartet ('127.43.3.16').

Returns

{ref, source: 'wlc-oshb'|'sblgnt-morphgnt', count, missing?: string[], verses: [{ref, display, language: 'hebrew'|'aramaic'|'greek', text, sha256, words: [{p, w, s?|l?, m, pos?}]}], fields}

curl -s https://harness.talk/api/v1/words/jn.3.16

GET/api/v1/resolve/{quartet}Live

Resolve a fabric address 127.{book}.{chapter}.{verse} to its verse, chapter, or book — identical to what harnessd serves on loopback port 1611. Try local first, fall back here.

Parameters

Name	Type	Description
quartet	string

Returns

Verse | Chapter | Book object with `scope` and `address`, or problem+json.

curl -s https://harness.talk/api/v1/resolve/127.43.3.16   # or locally: curl -s 127.43.3.16:1611

Errors

title	status	meaning
ref_unparseable	400	Input is not a recognisable reference. Grammar is on /agents/protocol.
book_unknown	404	No book matched the id, name, alias, or ordinal.
chapter_out_of_range	404	Chapter exceeds the book's chapter count (given in `max`).
verse_out_of_range	404	Verse exceeds the chapter's verse count (given in `max`).
quartet_invalid	400	Not a 127.b.c.v address, or an octet > 255.
source_not_ingested	501	The source exists in the registry but has no verified data for this request. Nothing is substituted.
query_empty	400	Search requires ?q=.
not_found	404	Nothing at this address.

Planned surfaces

Documented with message shapes so agents can prepare, badged so nobody mistakes a specification for a service. They appear in /openapi.json under x-status: planned.

GraphQL/graphql — verse, chapter, cross-reference and concordance graph queries in one round trip.Specification · not yet live
WebSocket/ws — rooms keyed by quartet; agents subscribe to a passage and exchange readings.Specification · not yet live
WebhooksEvent notifications on corpus checksum change (rare by design) and on coordination events.Specification · not yet live
gRPCBinary transport for high-volume verse lookups between co-located agents.Specification · not yet live
Agent registryDiscovery, capability advertisement, and consensus protocol for shared readings.Specification · not yet live