VERSE engine
Read a passage, with art.
Sign in to try it
Runs cost credits. Ask us for credits.
Example results
What VERSE returns
Real results, not mock-ups.
Sent
Matthew 11:28-30
Returned by VERSE v1 · API v1.
Anxiety and fear
For when your mind won't settle. · 14 passages
Temptation
For when something keeps pulling at you. · 8 passages
Grief and heartache
For when something hurts and won't stop. · 2 passages
Doubt
For when you're not sure what you believe. · 14 passages
Identity and worth
For when you wonder if you matter. · 1 passage
Hope
For when it all feels heavy. · 14 passages
Anger
For when you're about to say something you'll regret. · 5 passages
Forgiveness and a fresh start
For when you've messed up. · 10 passages
Friends and people
For the people around you. · 3 passages
Growing in faith
For going a little deeper. · 17 passages
More passages
Everything else we hold. · 5 passages
30 of 30 passages
Most wanted
Passages people looked for that we don't have yet.
- Matthew 10:8–10Looked for 1 time
- Matthew 28:18–20Looked for 1 time
On the way
Requested and waiting to be made.
- Matthew 10:8–101 request on the way
Read a passage
Funded account or a bound service bearer600 calls / hour per account<1s
A reference ("Psalm 34:18") → the verse card.
- · 1 credit per read; a 402 carries `required` / `available`.
- · Marked no-store — do not cache a paid read.
- · 503 catalog_unavailable: retryable, not charged.
Query parameters
| Field | Type | Meaning |
|---|---|---|
refrequired | string | The scripture reference. Any range resolves. A reference that does not resolve answers 400 invalid_reference and is not charged. |
locale | string | Which baked art locale to prefer. Falls back to clean artwork when that locale has no bake. |
Response
| Field | Type | Meaning |
|---|---|---|
reference / osisIds | string / string[] | The human display of the resolved span and its OSIS ids. |
text / fullText | string / string | text is what the card renders; fullText is always the public-domain WEB passage. |
source / shepStatus | string / "draft" | "certified" | null | Which rendering text came from. |
tagline | string | null | Our one-line tagline for the passage, where we have one. |
art | { url, variant, cleanUrl, generic, locale, composeText, alt, embedHtml } | null | Our self-hosted art: the baked share image (verse, reference and attribution in its pixels) where one exists, with cleanUrl always the clean artwork. composeText tells you whether you must render the verse text yourself. For a passage not in the catalog: a borrowed flagship clean background (generic: true) with embedHtml composing the WEB text over it for you. |
miss | boolean | true when the passage is not in our catalog (neither one of our flagship verses nor one a reader has funded). A miss carries a request offer, and is recorded (best-effort) as demand. |
request | { available, credits, url, endpoint } | null | What a reader may pay to have made (a SHEP translation, VerseArt, or both), the credits each costs, the page to request it on (it offers sign-in to a signed-out reader) and the endpoint a signed-in reader POSTs to. Null when nothing is missing. |
translation | { code, provider, license } | Attribution for the text. |
credits | { reserved, balance } | Settled before the response: reserved is what is still held for this read (0), balance is yours after the read's flat 1-credit charge. |
Try it
Sign in with a funded account to send.
GET /api/verse
Response
// the response will appear here
Call it from your code
server-to-server (service bearer)
curl -sS 'https://<your-shepherd-host>/api/verse?ref=Matthew+11%3A28-30' \ -H 'Authorization: Bearer $SHEPHERD_API_KEY'
Never ship the service key to a browser.
Versions
Every response from every Shepherd engine — a result, an estimate, a refusal or an error — says which versions produced it, under the same three headers on every engine. A JSON object body carries the same three as `versions: { api, engine, engines }`.
Response headers
| Field | Type | Meaning |
|---|---|---|
X-API-Versionrequired | v<N> | The API version: the request/response contract, the same for every engine ("v1"). It changes only for a breaking change to that contract. |
X-Engine-Versionrequired | <engine>-engine/<line>-v<N> | The responding engine's version ("truth-engine/research-v32", "verse-engine/card-v1"). The number goes up whenever the engine's behaviour changes: its prompts, its models, its retrieval or its rules. |
X-Engine-Versionsrequired | JSON object | The versions of the engines this response's own work called, by engine name ({"lifeline": "lifeline-engine/match-v1", "truth": "truth-engine/research-v32"} from a FORMATION study; {} when it called none — a refusal before any work, or a result served from a recent identical run). |
- · Read as a label, a version is the engine's name, its number and the API's: "VERSE v3 · API v1". The example results on every engine page are labelled this way, with the versions each was captured under.
- · A result stored for later (a TRUTH read, a FORMATION study's reviews) keeps the version that produced it; the headers name the versions answering now.
- · TRUTH's assessment endpoints return the frozen assessment contract, which carries its own provenance.truth_engine_version, so there the versions are in the headers only. The open contract endpoint runs the deterministic stub and answers as truth-engine/stub-v0.