Public research calls use plain HTTPS and work without an Authorization header. Use REST directly, import the OpenAPI file, or connect by MCP. Search results return passage IDs and stable Sacred Matrix URLs so people and agents can read, compare, and cite the exact source page they used.
The public surface is read-only and citation-oriented. It is built for normal research, user-directed assistant work, and tools that need source-linked passages without scraping the whole archive.
Find passages, texts, topics, dossiers, traditions, and public Deep Thoughts.
Retrieve an exact verse, chapter, section, or range from an indexed text.
Load exact passage records by stable IDs returned from another call.
Find cross-tradition parallels after the client has one or more seed passages.
Discover available texts by query or tradition before reading.
Inspect versions, books, chapters, and section anchors for a text.
Find themed public pages that connect passages across traditions.
Use direct HTTPS calls from scripts, apps, backend jobs, and agents that do not need a full MCP client.
GET https://thesacredmatrix.com/api/agent/search?q=John%2014%3A12&limit=5Import the schema into agent builders, API clients, and documentation tools. Public retrieval operations have no auth requirement.
https://thesacredmatrix.com/openapi.jsonConnect Claude, ChatGPT-style agents, desktop tools, and research assistants through Streamable HTTP JSON-RPC.
https://thesacredmatrix.com/mcpPublic retrieval is open for normal research. Start with search, keep returned passage IDs and URLs, then read exact passages before quoting. Anonymous calls do not need an auth header.
Use The Sacred Matrix as a source-labeled retrieval service for sacred texts.
Public read calls need no Authorization header.
Start with search_sacred_texts for references, titles, figures, symbols, phrases, and themes.
Read exact passages with read_text or get_passages before quoting.
Use find_similar_passages only after you have one or more passage IDs.
Cite the returned Sacred Matrix URL with any answer that uses retrieved material.
Cache successful responses during the user task. Keep automated retrieval tied to the active research question.
If a 429 is returned, wait for Retry-After before continuing.
Do not bulk-pull the archive anonymously.curl -s 'https://thesacredmatrix.com/api/agent/search?q=John%2014%3A12&limit=5'curl -s 'https://thesacredmatrix.com/api/agent/read?text_slug=john&book=John&chapter=14&verse_start=12&limit=1'curl -s 'https://thesacredmatrix.com/api/agent/similar?ids=PASSAGE_ID&limit=12'https://thesacredmatrix.com/mcphttps://thesacredmatrix.com/adminmcphttps://thesacredmatrix.com/adminmcp/claudehttps://thesacredmatrix.com/adminmcp/connecthttps://thesacredmatrix.com/adminmcp/.well-known/mcp.jsonhttps://thesacredmatrix.com/adminmcp/claude/.well-known/mcp.jsonhttps://thesacredmatrix.com/openapi.jsonhttps://thesacredmatrix.com/.well-known/openapi.jsonhttps://thesacredmatrix.com/llms.txthttps://thesacredmatrix.com/api/agent/toolshttps://thesacredmatrix.com/.well-known/mcp.jsonEvery public retrieval tool is available without an auth header. Choose the surface that matches the client, then use the same returned passage IDs and URLs across follow-up calls.
Anonymous retrieval is the default. Connected accounts only add user-specific saved state and a higher paced request ceiling.
Search, read, passage lookup, similarity, text lists, text structure, and topics work without sign-in.
No Authorization headerA user can connect an account when saved passages or profile-linked research should follow them across sessions.
Optional OAuth bearer tokenAnonymous clients are rate limited by IP. Connected clients receive higher limits. A 429 response includes retry headers.
Retry-After: 60These are plain HTTPS calls. Do not send an Authorization header for public search, reading, passage lookup, similarity, text lists, text structure, or topics.
First call for references, phrases, symbols, titles, people, themes, and traditions.
curl -s 'https://thesacredmatrix.com/api/agent/search?q=John%2014%3A12&limit=5'Use when the client already knows the text slug and location.
curl -s 'https://thesacredmatrix.com/api/agent/read?text_slug=john&book=John&chapter=14&verse_start=12&limit=1'Use passage IDs returned by search, read, or similarity.
curl -s 'https://thesacredmatrix.com/api/agent/passages?ids=PASSAGE_ID,SECOND_PASSAGE_ID'Start from one or more known passage IDs.
curl -s 'https://thesacredmatrix.com/api/agent/similar?ids=PASSAGE_ID&limit=12'Find available texts by tradition or search term before reading.
curl -s 'https://thesacredmatrix.com/api/agent/texts?q=gnostic&limit=10'Get available versions, books, chapters, and sections for a text.
curl -s 'https://thesacredmatrix.com/api/agent/texts/john/structure'Find cross-tradition topic pages.
curl -s 'https://thesacredmatrix.com/api/agent/topics?q=resurrection&limit=10'Machine-readable tool list, public examples, equivalent calls, and usage policy.
curl -s 'https://thesacredmatrix.com/api/agent/tools'Import into API clients, agent builders, and documentation tools.
curl -s 'https://thesacredmatrix.com/openapi.json'On a 429 response, read Retry-After, wait for that window, then retry the same request. Cache successful results during the active research task.
const url = new URL("https://thesacredmatrix.com/api/agent/search");
url.searchParams.set("q", "John 14:12");
url.searchParams.set("limit", "5");
const res = await fetch(url);
if (res.status === 429) {
const retryAfter = Number(res.headers.get("Retry-After") || "60");
throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`);
}
const data = await res.json();
console.log(data.hits);The same search can be called as REST, imported as an OpenAPI operation, or sent through MCP. These public examples do not use an Authorization header.
curl -s 'https://thesacredmatrix.com/api/agent/search?q=John%2014%3A12&limit=5'{
"openapi": "https://thesacredmatrix.com/openapi.json",
"operationId": "searchSacredTexts",
"parameters": {
"q": "John 14:12",
"limit": 5
}
}{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "search_sacred_texts",
"arguments": {
"query": "John 14:12",
"limit": 5
}
}
}Start broad, then move to exact passages. Agents should keep returned IDs and URLs so citations stay stable.
search_sacred_textsGET /api/agent/searchget_passagesGET /api/agent/passagesfind_similar_passagesGET /api/agent/similarread_textGET /api/agent/readlist_textsGET /api/agent/textsget_text_structureGET /api/agent/texts/{text_slug}/structurelist_topicsGET /api/agent/topicsSearch by reference, person, symbol, phrase, or theme.
Keep the returned passage_id and source URL.
Read the exact passage or chapter before quoting it.
Use similar-passages only after you have a seed passage ID.
Cite the returned Sacred Matrix URL when you answer a user.
The public tool manifest at /api/agent/tools publishes this same reference in machine-readable form with parameters, operation IDs, MCP names, examples, and the current usage policy.
GET /api/agent/searchsearchSacredTextssearch_sacred_textsq, kind, limitGET /api/agent/readreadTextread_texttext_slug, version_slug, book, chapter, verse_start, verse_end, limitGET /api/agent/passagesgetPassagesget_passagesidsGET /api/agent/similarfindSimilarPassagesfind_similar_passagesids, limitGET /api/agent/textslistTextslist_textstradition_slug, q, limitGET /api/agent/texts/{text_slug}/structuregetTextStructureget_text_structuretext_slugGET /api/agent/topicslistTopicslist_topicsq, limitUse REST when plain HTTPS is enough, OpenAPI when an importer wants operation IDs and schemas, and MCP when the client wants tool discovery and structured JSON-RPC calls.
GET /api/agent/search?q=John%2014%3A12&limit=5{
"operationId": "searchSacredTexts",
"parameters": {
"q": "John 14:12",
"limit": 5
}
}{
"method": "tools/call",
"params": {
"name": "search_sacred_texts",
"arguments": { "query": "John 14:12", "limit": 5 }
}
}GET /api/agent/read?text_slug=john&book=John&chapter=14&verse_start=12&limit=1{
"operationId": "readText",
"parameters": {
"text_slug": "john",
"book": "John",
"chapter": "14",
"verse_start": "12",
"limit": 1
}
}{
"method": "tools/call",
"params": {
"name": "read_text",
"arguments": {
"text_slug": "john",
"book": "John",
"chapter": "14",
"verse_start": "12",
"limit": 1
}
}
}GET /api/agent/passages?ids=PASSAGE_ID,SECOND_PASSAGE_ID{
"operationId": "getPassages",
"parameters": {
"ids": "PASSAGE_ID,SECOND_PASSAGE_ID"
}
}{
"method": "tools/call",
"params": {
"name": "get_passages",
"arguments": { "ids": ["PASSAGE_ID", "SECOND_PASSAGE_ID"] }
}
}GET /api/agent/similar?ids=PASSAGE_ID&limit=12{
"operationId": "findSimilarPassages",
"parameters": {
"ids": "PASSAGE_ID",
"limit": 12
}
}{
"method": "tools/call",
"params": {
"name": "find_similar_passages",
"arguments": { "ids": ["PASSAGE_ID"], "limit": 12 }
}
}GET /api/agent/texts?q=gnostic&limit=10{
"operationId": "listTexts",
"parameters": {
"q": "gnostic",
"limit": 10
}
}{
"method": "tools/call",
"params": {
"name": "list_texts",
"arguments": { "query": "gnostic", "limit": 10 }
}
}GET /api/agent/texts/john/structure{
"operationId": "getTextStructure",
"parameters": {
"text_slug": "john"
}
}{
"method": "tools/call",
"params": {
"name": "get_text_structure",
"arguments": { "text_slug": "john" }
}
}GET /api/agent/topics?q=resurrection&limit=10{
"operationId": "listTopics",
"parameters": {
"q": "resurrection",
"limit": 10
}
}{
"method": "tools/call",
"params": {
"name": "list_topics",
"arguments": { "query": "resurrection", "limit": 10 }
}
}MCP clients use the same public retrieval tools through Streamable HTTP JSON-RPC.
For admin-owned MCP clients. Hosted Claude users can use the admin connector link or add this exact URL.
{
"mcpServers": {
"the-sacred-matrix-admin": {
"type": "http",
"url": "https://thesacredmatrix.com/adminmcp"
}
}
}For MCP clients that accept a Streamable HTTP server URL.
{
"mcpServers": {
"the-sacred-matrix": {
"type": "http",
"url": "https://thesacredmatrix.com/mcp"
}
}
}For agent builders, API importers, SDK generators, and documentation tools.
{
"openapi": "https://thesacredmatrix.com/openapi.json"
}For crawlers and agents that first look for a plain-text site guide.
https://thesacredmatrix.com/llms.txtFor scripts and services that only need HTTPS retrieval.
BASE_URL="https://thesacredmatrix.com"
curl -s "$BASE_URL/api/agent/search?q=John%2014%3A12&limit=5"curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-agent",
"version": "1.0.0"
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "search_sacred_texts",
"arguments": {
"query": "John 14:12",
"limit": 5
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "read_text",
"arguments": {
"text_slug": "john",
"book": "John",
"chapter": "14",
"verse_start": "12",
"limit": 1
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "get_passages",
"arguments": {
"ids": ["PASSAGE_ID", "SECOND_PASSAGE_ID"]
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "find_similar_passages",
"arguments": {
"ids": ["PASSAGE_ID"],
"limit": 12
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "list_texts",
"arguments": {
"query": "gnostic",
"limit": 10
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "get_text_structure",
"arguments": {
"text_slug": "john"
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "list_topics",
"arguments": {
"query": "resurrection",
"limit": 10
}
}
}'Retrieval responses include IDs, labels, references, citations, and URLs that agents can pass back to users.
passage_idStable ID used by get_passages, find_similar_passages, and follow-up retrieval.referenceHuman-readable location such as John 14:12 or Book of the Dead 30B:3.text_titleThe text or version title returned with the result.source_labelPlain-language source label for citation context.urlCanonical Sacred Matrix page URL for humans, crawlers, and citations.{
"hits": [
{
"kind": "passage",
"passage_id": "PASSAGE_ID",
"reference": "John 14:12",
"text_title": "World English Bible",
"source_label": "Public-domain translation",
"url": "https://thesacredmatrix.com/reader/john?book=John&chapter=14#passage-PASSAGE_ID"
}
]
}Anonymous access supports general research, citation, active assistant conversations, and user-facing reading tools. Sustained anonymous archive-pull bursts receive HTTP 429 with retry metadata. Connected MCP/account clients receive higher limits, but still need to pace requests.
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Window: 60 seconds
{
"detail": "Agent request rate limit reached. Wait briefly, then continue."
}MCP rate limits use the same HTTP status and headers. The JSON-RPC error code is -32029.
Public retrieval does not require sign-in. A connected account is only for user-specific saved state, profile-linked submissions, and higher paced request limits.
save_passageSave a passage to the connected user's profile.
list_saved_passagesReturn passages saved by the connected user.
publish_deep_thoughtSubmit a user-approved article linked to indexed passages.
Admin MCP tools let a trusted assistant inspect coverage gaps, save reviewed corpus import drafts, and preserve source images. Use https://thesacredmatrix.com/adminmcp for hosted Claude custom connectors, Claude Code, and local MCP clients.
mcp_connection_statusConfirm whether the current MCP request is anonymous, OAuth-connected, or admin-authenticated.
admin_get_corpus_gapsReview launch coverage gaps and pick the next source-safe import target.
admin_get_harvest_briefReturn the controlled vocabulary, import rules, image rules, review URLs, and recommended corpus targets.
admin_list_agent_tasksList queued Claude or agent harvest assignments.
admin_ensure_default_agent_tasksRestore the default prioritized Claude operator task queue without duplicating active targets.
admin_create_agent_taskCreate a corpus or source-image harvest assignment.
admin_get_agent_taskRetrieve one harvest assignment by task ID.
admin_get_agent_task_handoffRetrieve a copy-ready handoff prompt and evidence rules for one harvest assignment.
admin_get_next_agent_task_handoffRetrieve the next prioritized open task with its handoff prompt and evidence rules.
admin_claim_agent_taskClaim an assignment before a long harvest run.
admin_update_agent_taskAttach progress notes, source URLs, draft IDs, and image slugs to an assignment.
admin_get_embedding_statusCheck embedding coverage and search-index status for approved content.
admin_backfill_embeddingsBackfill missing embeddings for already-published passages.
admin_rebuild_search_indexRefresh Typesense for scoped approved content.
admin_find_duplicate_textsAudit proposed text imports against live slugs, titles, and source URLs.
admin_preview_importValidate seed-format JSON before it is saved for review.
admin_submit_import_draftSave a corpus import draft for admin review without publishing it.
admin_submit_harvest_packageSave a combined review package with draft payloads, source URLs, sidecars, notes, and task progress.
admin_list_import_draftsList saved import drafts in the admin review queue.
admin_get_import_draftRetrieve one saved import draft by ID.
admin_archive_source_imagePreserve a source image URL with rights metadata and content links.
admin_archive_source_imagesPreserve multiple source image URLs with per-image review results.
admin_list_source_image_sidecarsReview preserved source-image sidecars without importing them.
admin_ingest_source_image_sidecarsDry-run or import preserved source-image sidecars.
Add the admin MCP server to a Claude Code session that you control. The admin endpoint is protected at connection time, so clients that support MCP OAuth can request mcp:admin before listing tools. If adding the server does not open a login prompt, run the login command shown here or authenticate from Claude Code's /mcp menu. Header auth remains available for local clients that support static headers.
claude mcp add-json the-sacred-matrix-admin '{"type":"http","url":"https://thesacredmatrix.com/adminmcp","oauth":{"scopes":"mcp:admin","authServerMetadataUrl":"https://thesacredmatrix.com/.well-known/oauth-authorization-server"}}'
claude mcp login the-sacred-matrix-admin --no-browser{
"mcpServers": {
"the-sacred-matrix": {
"type": "http",
"url": "https://thesacredmatrix.com/mcp",
"headersHelper": "/secure/local/path/sacredmatrix-mcp-headers.sh"
}
}
}Start with the harvest brief, then submit seed-format JSON as a draft after source, rights, and passage structure are checked.
curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
-H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
--data '{
"jsonrpc": "2.0",
"id": 20,
"method": "tools/call",
"params": {
"name": "admin_get_harvest_brief",
"arguments": {
"limit": 5
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
-H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
--data '{
"jsonrpc": "2.0",
"id": 21,
"method": "tools/call",
"params": {
"name": "admin_submit_import_draft",
"arguments": {
"title": "Agent gathered public-domain source draft",
"payload": {
"texts": []
}
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
-H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
--data '{
"jsonrpc": "2.0",
"id": 22,
"method": "tools/call",
"params": {
"name": "admin_get_import_draft",
"arguments": {
"draft_id": "IMPORT_DRAFT_UUID"
}
}
}'curl -s 'https://thesacredmatrix.com/mcp' \
-H 'Content-Type: application/json' \
-H 'X-Admin-Token: YOUR_ADMIN_TOKEN' \
--data '{
"jsonrpc": "2.0",
"id": 23,
"method": "tools/call",
"params": {
"name": "admin_archive_source_image",
"arguments": {
"payload": {
"download_url": "https://museum.example/object-image.jpg",
"slug": "source-object-slug",
"title": "Source Object Title",
"source_url": "https://museum.example/object-page",
"rights_status": "Public domain",
"public_domain": true,
"display_allowed": true,
"ingest": false,
"relationships": {
"text_slugs": ["book-of-the-dead"],
"topic_slugs": ["afterlife"]
}
}
}
}
}'MCP clients can discover the authorization server and register dynamically when a user chooses to connect an account.
https://thesacredmatrix.com/.well-known/oauth-authorization-serverhttps://thesacredmatrix.com/.well-known/oauth-protected-resource/mcphttps://thesacredmatrix.com/.well-known/oauth-protected-resource/adminmcphttps://thesacredmatrix.com/.well-known/oauth-protected-resource/adminmcp/claudehttps://thesacredmatrix.com/.well-known/oauth-authorization-serverhttps://thesacredmatrix.com/.well-known/oauth-authorization-server/adminmcphttps://thesacredmatrix.com/registerhttps://thesacredmatrix.com/register/adminmcpFor public browsing, start with the reader or topics.