Spirit Nation API
Verse-level scripture data for apps, study tools, search projects, and future paid integrations. Readable translations are limited to public-domain sources; original-language study panels include their own source and license attribution.
Try the API Shape
This console simulates a verse request without exposing a live key. Approved keys can use the same structure through `/api/v1`.
Endpoints
Approved API keys can request translation metadata, book lists, whole books, chapters, individual verses, verse ranges, search results, and word-study data. Use JSON responses for scripture readers, widgets, reference tools, and study applications.
Use `/api/v1/text/...`, `/api/v1/study/...`, and `/api/v1/morphology/...` for new integrations. The direct `/api/v1/{translation}/...` routes remain active as compatibility aliases.
An OpenAPI-style endpoint catalog is available at `/api/v1/openapi`. Approved keys can check quota and tier status at `/api/v1/key`.
New text, study, and morphology responses include a `meta` envelope with API version, preferred namespaces, and data-policy notes. Generated or rule-aligned morphology is always labeled; only tokens with `verified_by_spirit_nation: true` should be treated as manually reviewed.
GET /api/v1/openapi
GET /api/v1/key
GET /api/v1/translations
GET /api/v1/books?translation=kjv
GET /api/v1/source-texts
GET /api/v1/source-coverage
GET /api/v1/text/kjv/genesis/1/1
GET /api/v1/text/kjv/range?from=genesis.1.1&to=genesis.1.5
GET /api/v1/morphology/kjv/genesis/1/1
GET /api/v1/study/kjv/range?from=genesis.1.1&to=genesis.1.3
GET /api/v1/kjv/genesis
GET /api/v1/kjv/genesis/1
GET /api/v1/kjv/genesis/1/3
GET /api/v1/study/kjv/genesis/1/1
GET /api/v1/kjv/range?from=genesis.1.1&to=genesis.1.5
GET /api/v1/search?translation=kjv&q=light
Send approved keys as `Authorization: Bearer YOUR_KEY`, `X-Spirit-Nation-Key`, or `?key=YOUR_KEY`.
Recommended Integration Path
Use the versioned namespaces for all new work: `/text` for readable scripture, `/study` when you need readable text plus source panels, `/morphology` when you only need word-study tokens, and `/source-coverage` before making strict claims about a source layer.
Text reader: /api/v1/text/kjv/john/1/1
Study view: /api/v1/study/kjv/genesis/1/1?source_role=Original%20Language
Review tools: /api/v1/morphology/kjv/genesis/1/1?review_status=needs-review
Quality checks: /api/v1/source-coverage
cURL
curl -H "X-Spirit-Nation-Key: YOUR_KEY" \
"https://www.loganpendragonforge.com/labs/spirit-nation/api/v1/text/kjv/genesis/1/1"JavaScript
const res = await fetch("https://www.loganpendragonforge.com/labs/spirit-nation/api/v1/study/kjv/john/1/1", {
headers: { "X-Spirit-Nation-Key": "YOUR_KEY" }
});
const data = await res.json();PHP
$response = file_get_contents("https://www.loganpendragonforge.com/labs/spirit-nation/api/v1/source-coverage", false, stream_context_create([
"http" => ["header" => "X-Spirit-Nation-Key: YOUR_KEY\r\n"]
]));SDK Starter Notes
Keep a tiny client wrapper around the base URL and API key. Treat generated morphology as opt-in unless your app is explicitly a research or review tool.
const spiritNation = {
baseUrl: "https://www.loganpendragonforge.com/labs/spirit-nation/api/v1",
key: "YOUR_KEY",
async get(path) {
const res = await fetch(`${this.baseUrl}${path}`, {
headers: { "X-Spirit-Nation-Key": this.key }
});
if (!res.ok) throw await res.json();
return res.json();
}
};
const verse = await spiritNation.get("/text/kjv/psalms/23/1");
const study = await spiritNation.get("/study/kjv/genesis/1/1?verified_only=1");Authentication
Use one key per project. Keep keys private and send them through the bearer header whenever possible.
Authorization: Bearer sn_your_key_here
Verse Ranges
Ranges use canonical references in the same translation. Keep the start and end reference in order.
GET /api/v1/text/kjv/range?from=genesis.1.1&to=genesis.1.5
Search
Search returns matching verse records for the selected translation and query text.
GET /api/v1/search?translation=kjv&q=light
Word Study
Study responses return readable verse text plus original-language panels when source data has been attached. Tokens include study status, part of speech, morphology, source, and license metadata when available.
GET /api/v1/study/kjv/john/1/1
Study Ranges
Use the study range endpoint for a small reference window with readable text and source panels. Keep ranges tight; the current study range limit is 100 verses.
GET /api/v1/study/kjv/range?from=john.1.1&to=john.1.5
Text Surface
The `/text` namespace is the cleaner forward path for readable scripture text. The older direct translation routes remain available for compatibility.
GET /api/v1/text/kjv/genesis/1/1
Morphology Surface
The `/morphology` namespace returns source panels and token data only, without the readable translation wrapper, for tools that focus on word study. Add `verified_only=1` to return only manually reviewed Spirit Nation tokens, `include_generated=0` to hide generated/rule-aligned tokens, `source_role=Latin Tradition` to narrow panels by role, `confidence=low` to inspect weak generated morphology, or `review_status=needs-review` to pull review queues.
GET /api/v1/morphology/kjv/genesis/1/1
Source Coverage
Coverage responses list imported source texts, canon coverage, word-token totals, morphology status buckets, review maturity, Phase 5 status, and license notes for source-study layers.
GET /api/v1/source-coverage
Key Status
Approved integrations can check their tier, monthly quota, current usage, remaining calls, and last-used time.
GET /api/v1/key
Endpoint Catalog
The OpenAPI-style catalog exposes the current v1 surface so future SDKs and external documentation can be generated from a stable contract.
GET /api/v1/openapi
Error Shape
Authentication, inactive-key, and quota failures return JSON with a stable `error.code`, `error.message`, `error.status`, and optional details.
{"error":{"code":"api_key_required","status":401}}
Common Status Codes
`401` means no key was sent, `403` means the key is invalid or inactive, and `429` means the monthly quota has been exhausted.
429 monthly_quota_exceeded
Response Contract
New v1 responses use a stable top-level shape. Text endpoints return `translation`, `book`, and `data`; study endpoints add `readable_text` and `source_panels`; morphology endpoints return source panels and tokens only.
{
"meta": {
"api_version": "v1",
"endpoint": "study.verse",
"data_policy": {
"readable_text": "Public-domain scripture translations only.",
"generated_morphology": "Generated data is labeled until verified."
}
},
"translation": {"slug": "kjv", "abbreviation": "KJV"},
"book": {"slug": "genesis", "name": "Genesis"},
"source_panels": []
}Quality Filter Examples
GET /api/v1/study/kjv/genesis/1/1?verified_only=1
GET /api/v1/study/kjv/genesis/1/1?include_generated=0
GET /api/v1/morphology/kjv/genesis/1/1?confidence=low
GET /api/v1/morphology/kjv/genesis/1/1?source_role=Greek%20Tradition&review_status=needs-review
Source Roles
Source-study layers identify whether a panel is an original text, ancient Greek tradition, Latin tradition, or Aramaic/Syriac tradition.
source_text.source_role
Morphology Status
Token data is labeled as imported, dataset-backed, lexicon-aligned, rule-aligned, pending, or review-needed instead of being presented as equally verified.
token_statuses.rule_aligned
Review Metadata
Word-study tokens expose review notes, review timestamps, and whether Spirit Nation has manually verified the token correction.
tokens[].verified_by_spirit_nation
Review Maturity
Source coverage includes per-source maturity counts so API users can see how much of a source is verified, generated, pending, or still needs review.
review_maturity.verified_percent
Study Filters
Use query filters when a client needs only reviewed data, wants to exclude generated morphology, wants a single source role, or wants a review-ready confidence/status queue.
GET /api/v1/study/kjv/genesis/1/1?verified_only=1&source_role=Original%20Language
GET /api/v1/study/kjv/genesis/1/1?confidence=low
GET /api/v1/morphology/kjv/genesis/1/1?review_status=needs-review
Canon Coverage
Coverage is broken down across Old Testament, New Testament, and Apocrypha so API users can see which traditions apply to which canon groups.
canon_coverage.old.verses
Latin Vulgate morphology is backed by GreLa v0.7 / latin-lemmatized-texts annotations under CC BY-SA 4.0. Preserve attribution when using source-study data outside Spirit Nation. Syriac/Peshitta morphology combines Apache-2.0 OpenSSI candidates where cleanly mapped with Spirit Nation preliminary morphology for remaining tokens; generated Syriac data remains review-required unless explicitly marked verified.
Current Source-Study Layers
Request API Access
Register or log in to request an API key. Requests go to the admin queue for approval and quota assignment.
Register for Access