The Oracle & Divination Systems API exposes ceremonial blueprints for traditional and contemporary divination practices. Each blueprint provides core mechanics, guided reading protocols, AI augmentation modes, and integration prompts to support ethical, well-documented practice.
Endpoints#
GET /v1/divination/oracles#
Returns a catalogue of available divination systems with summary metadata for discovery.
BFF proxy: Access via the BFF base URL (e.g.,
https://api.example.org/v1/divination/oracles) to benefit from built-in fallbacks and observability. The BFF forwards catalogue requests to the content service and transparently falls back to the curated dataset if the downstream dependency is unavailable.
Example response:
{
"systems": [
{
"slug": "tarot",
"name": "Tarot",
"tradition": "Esoteric Western Mystery Schools",
"type": "card",
"primaryTool": "78-card tarot deck (Major & Minor Arcana)",
"digitalSupports": [
"Sequence-based shuffle visualizer",
"Sigil-based intention recorder",
"Spread annotator",
"Archetype cross-reference library",
"Narrative weaving canvas",
"Integration reminder scheduler"
]
}
],
"metadata": {
"count": 4,
"generated_at": "2025-01-01T00:00:00.000Z",
"documentation": "docs/oracle-divination-systems.md",
"sources": [
"WorldMythology.ClassicalDivinationCorpus",
"MysticPractices.OracularTraditions"
]
}
}
GET /v1/divination/oracles/:slug#
Retrieves the full divination workflow for a specific system, including reading
protocols, prompt templates, and digital augmentation guidance. Slugs include
i-ching, tarot, runes, and dream-oracle.
{
"slug": "i-ching",
"name": "I Ching",
"tradition": "Classical Chinese",
"origins": {
"region": "Zhou Dynasty China",
"era": "c. 1000 BCE",
"lineage": "King Wen, Duke of Zhou, Confucian commentaries"
},
"type": "casting",
"primaryTool": "Yarrow stalks or three coins",
"supportTools": [
"Hexagram charts",
"Line change tracker",
"Commentary corpus navigator"
],
"coreMechanics": [
"64 hexagrams derived from broken and solid lines",
"Dynamic line changes indicating present transformations",
"Nuclear hexagrams revealing hidden influences"
],
"interpretivePrinciples": [
"Balance between yin and yang polarities",
"Movement through changing lines and resultant hexagram",
"Consultant alignment with Dao through responsive action"
],
"readingProtocols": [
{
"phase": "Preparation",
"focus": [
"Clarify heart-mind question",
"Ground in breath and respectful posture"
],
"actions": [
"Document inquiry with context and emotional tone",
"Set intention for guidance rather than prediction"
],
"digitalSupports": [
"Guided breathing timer",
"Intention journaling template"
]
}
],
"promptTemplates": {
"guidance": [
"What changes are emerging through the moving lines, and how do they mirror my inner state?",
"Where do I witness harmony or resistance between the primary and resulting hexagrams?"
],
"integration": [
"What concrete action honors the counsel of the Dao within the next six days?",
"Which relationship or domain requires balancing yin and yang right now?"
],
"reflection": [
"How did the outcome evolve compared to the counsel received?",
"What new pattern of change am I noticing after following the guidance?"
]
},
"digitalAugmentations": {
"aiReadingModes": [
"Classical commentary synthesis (Wilhelm, Cheng Yi, Wang Bi)",
"Somatic integration prompts based on moving lines"
],
"journalingWorkflows": [
"Hexagram lineage tracker",
"Change log with seasonal markers"
],
"ritualEnhancements": [
"Breath paced coin casting animation",
"Sound bath tuned to trigram resonance"
]
}
}
TypeScript SDK Integration#
The Lilith TypeScript SDK exposes strongly typed helpers for both endpoints.
import { APIClient } from '@lilith/sdk-ts';
const client = new APIClient({ baseUrl: 'https://api.example.org' });
// Catalogue discovery
const catalogue = await client.listDivinationSystems();
catalogue.systems.forEach((system) => {
console.log(system.name, system.digitalSupports.length);
});
// Detailed blueprint
const runes = await client.getDivinationSystem('runes');
console.log(runes.promptTemplates.guidance[0]);
All responses include safeguarding guidance, integration prompts, and AI augmentation suggestions to support ethical divination practices.