API reference

Live

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

Search the 1611 KJV in modern spelling: 'loved' finds 'loued', 'believe' finds 'beleeue' (shared normaliser, 96.6% measured bridge). Plain words: verses with every word, ranked closest-together first; if no verse has all of them, mode becomes 'idea' and verses are ranked by how many they carry. A "quoted phrase" matches exact order (spelling-insensitive). A reference resolves it. 'unmatched' lists words that occur nowhere in the text — do not infer they exist.

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'|'idea'|'common', total, hits: Verse[] with score + matched: string[] (which query words the verse carries), words: string[] (content words sought), unmatched: string[] (words absent from the text in any spelling), limit, offset}. mode 'common' = every word typed is too frequent to rank (his, unto, the); the text was scanned directly and hits are in canonical order.

curl -s 'https://harness.talk/api/v1/search?q=who+is+God%27s+friend&limit=5'

GET/api/v1/docs/searchLive

Search the harness DOCUMENTATION — a separate layer from Scripture, never mixed with it. Covers every doc page by section (protocol, addressing, hashes, errors, covenant, licence, MCP, harness, storage, translations), the tool manifest, and the corpus build reports. Use this to learn how harness.talk works; use 'search' for the Word itself. Hits carry the page, section heading, anchor URL, and a snippet.

Parameters

Name	Type	Description
q	string
limit?	integer	default 10
offset?	integer	default 0
kind?	string	Restrict to doc pages, tool definitions, or build reports.

Returns

{layer: 'documentation', query, total, hits: [{kind, url, page, kicker, heading, snippet, score, matched: string[]}], words, unmatched: string[] (words found nowhere in the documentation), limit, offset}

curl -s 'https://harness.talk/api/v1/docs/search?q=how+are+verses+hashed&limit=3'

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 — or a span like 127.43.3.16-21 / 127.43.3.16-4.2 (max 500 verses, one Merkle root over the span). 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

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

Cross references of one verse as fabric addresses, strongest first (OpenBible.info, CC-BY, ranked by reader votes). Each link has the target's 127.b.c.v address and the SHA-256 of its first verse: pass the address to resolveQuartet to walk the thread, and compare hashes to confirm the text. Verse addresses only (last octet above 0).

Parameters

Name	Type	Description
quartet	string
limit?	integer	default 15

Returns

{address, ref, display, sha256, total, count, links: [{address, ref, display, votes, sha256, text}], attribution}

curl -s 'https://harness.talk/api/v1/resolve/127.1.3.15/links?limit=5'   # or locally: curl -s 127.1.3.15:1611/links

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, an octet > 255, or a span that ends before it starts.
range_too_large	400	A span covers more than 500 verses; use the chapter address 127.b.c.0 instead.
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