ᚅ

LOGOS Oracle API

Swiss Ephemeris at arc-second precision. Archetype detection across five esoteric traditions. Coherence scoring. Cross-tradition synthesis. One API.

Version 1.4.0Base oracle.odinseyeenterprises.com/api/v1Format JSON

Authentication

All endpoints except /health require a Bearer token in the Authorization header.

Header

Authorization: Bearer YOUR_API_KEY

Get your API key by signing up at /pricing (free tier available). Keys are shown once at creation — store them securely.

Important

Never expose your API key in client-side code. Use environment variables and server-side calls.

Getting an API Key

Get a free API key at /pricing or programmatically via POST /api/v1/signup with your email address. All API keys use the orc_ prefix (e.g. orc_live_abc123...).

Both Supabase JWT tokens and orc_-prefixed API keys are accepted in the Authorization: Bearer header.

Base URL

Production

https://oracle.odinseyeenterprises.com/api/v1

All endpoints are relative to this base. HTTPS is required — HTTP requests will be rejected.

Rate Limits

Tier	Monthly Calls	Burst (per min)
ᚠ Free	100	10
ᚨ Acolyte	1,000	30
ᚱ Architect	10,000	60
ᚺ Hermit	Unlimited	120

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes

All responses follow a consistent envelope. On error, ok is false and error contains a machine-readable code.

Error Envelopejson

{
  "ok": false,
  "error": "invalid_request",
  "message": "Missing required field: date"
}

Status	Code	Meaning
200	—	Success
400	`invalid_request`	Missing or malformed parameters
401	`unauthorized`	Missing or invalid API key
403	`tier_exceeded`	Endpoint requires a higher tier
429	`rate_limited`	Too many requests — check X-RateLimit-Reset
500	`internal_error`	Server error — retry or contact support

Endpoints

POST/chart

Compute a natal chart with Swiss Ephemeris at arc-second precision.

Returns planetary positions, house cusps (Placidus), aspects, and the birth chord. DST is resolved automatically from the IANA timezone.

Parameters

Parameter	Type	Required	Description
`date`	`string`	required	Birth date in YYYY-MM-DD format
`time`	`string`	required	Birth time in HH:MM (24h) format
`timezone`	`string`	required	IANA timezone, e.g. "America/New_York"
`lat`	`number`	required	Latitude of birth location
`lng`	`number`	required	Longitude of birth location
`house_system`	`string`	optional	House system (default: "placidus"). Options: placidus, whole-sign, equal, koch

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/chart \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-06-15",
    "time": "14:30",
    "timezone": "America/New_York",
    "lat": 40.7128,
    "lng": -74.0060
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "chart_id": "ch_9f8a7b6c",
    "ascendant": { "sign": "Aries", "degree": 11.3, "formatted": "11°18' Aries" },
    "sun": { "sign": "Gemini", "degree": 24.2, "house": 3 },
    "moon": { "sign": "Scorpio", "degree": 8.7, "house": 8 },
    "planets": [ /* ... all planetary positions ... */ ],
    "houses": [ /* ... 12 house cusps ... */ ],
    "aspects": [ /* ... major aspects ... */ ],
    "birth_chord": { "root": "D", "quality": "minor", "intervals": [0, 3, 7] }
  }
}

POST/evaluateAcolyte+

Evaluate a LOGOS expression against a chart or symbol set.

LOGOS is a domain-specific language for querying esoteric relationships. Expressions like Sun.sign, Moon.house, or Sun TRINE Moon resolve against the provided chart data.

Parameters

Parameter	Type	Required	Description
`expression`	`string`	required	LOGOS expression to evaluate
`chart_id`	`string`	optional	Chart ID from /chart response. Required if expression references chart placements.
`context`	`object`	optional	Additional context variables for the expression

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/evaluate \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "Sun.sign == \"Gemini\" AND Moon.house == 8",
    "chart_id": "ch_9f8a7b6c"
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "result": true,
    "coherence_score": 0.87,
    "resolved_values": {
      "Sun.sign": "Gemini",
      "Moon.house": 8
    },
    "expression_tree": /* ... parsed AST ... */
  }
}

POST/detectAcolyte+

Detect archetypes present in a chart across supported traditions.

Scans planetary positions, aspects, and house placements to identify archetypal patterns. Returns scored matches from the selected tradition(s).

Parameters

Parameter	Type	Required	Description
`chart_id`	`string`	required	Chart ID from /chart response
`traditions`	`string[]`	optional	Filter to specific traditions. Default: all. Options: astrology, tarot, kabbalah, numerology, alchemy
`min_score`	`number`	optional	Minimum coherence score threshold (0-1). Default: 0.3

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/detect \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chart_id": "ch_9f8a7b6c",
    "traditions": ["astrology", "tarot"],
    "min_score": 0.5
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "archetypes": [
      {
        "symbol_id": "sym_hermit",
        "name": "The Hermit",
        "tradition": "tarot",
        "coherence_score": 0.82,
        "triggers": ["Moon in 8th", "Saturn conjunct MC"]
      },
      {
        "symbol_id": "sym_mercury_gem",
        "name": "Mercury in Domicile",
        "tradition": "astrology",
        "coherence_score": 0.91,
        "triggers": ["Sun in Gemini", "Mercury conjunct Sun"]
      }
    ]
  }
}

POST/synthesizeArchitect+

Cross-tradition synthesis — find correspondences between esoteric systems.

Maps a symbol or archetype from one tradition into equivalent concepts across all others. The coherence score reflects how strongly the mapping is supported by source texts.

Parameters

Parameter	Type	Required	Description
`source_tradition`	`string`	required	Origin tradition: astrology, tarot, kabbalah, numerology, alchemy
`symbol`	`string`	required	Symbol or concept to synthesize, e.g. "The Tower", "Saturn", "Geburah"
`target_traditions`	`string[]`	optional	Target traditions. Default: all except source.

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/synthesize \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_tradition": "tarot",
    "symbol": "The Tower"
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "source": { "tradition": "tarot", "symbol": "The Tower" },
    "source_authority": "Rider-Waite-Smith (1909)",
    "correspondences": [
      { "tradition": "astrology", "symbol": "Mars", "coherence_score": 0.88 },
      { "tradition": "kabbalah", "symbol": "Peh (פ)", "coherence_score": 0.92 },
      { "tradition": "numerology", "symbol": "16 → 7", "coherence_score": 0.75 },
      { "tradition": "alchemy", "symbol": "Calcination", "coherence_score": 0.81 }
    ]
  }
}

POST/rosettaAcolyte+

Translate a symbol between two specific traditions.

Like /synthesize but focused: maps one symbol from a source tradition to a single target tradition with extended context, reasoning, and source references.

Parameters

Parameter	Type	Required	Description
`symbol`	`string`	required	The symbol to translate
`from`	`string`	required	Source tradition
`to`	`string`	required	Target tradition

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/rosetta \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "Saturn",
    "from": "astrology",
    "to": "kabbalah"
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "source": { "tradition": "astrology", "symbol": "Saturn" },
    "target": { "tradition": "kabbalah", "symbol": "Binah (Understanding)" },
    "coherence_score": 0.93,
    "reasoning": "Saturn governs structure, limitation, and time. Binah is the third sephirah representing form, understanding through limitation, and the maternal principle of containment.",
    "sources": ["Sefer Yetzirah", "777 (Crowley)"]
  }
}

POST/grimoire/queryArchitect+

Query the grimoire — the Oracle's knowledge base of esoteric texts and correspondences.

Semantic search over indexed esoteric source material. Returns passages with citation, tradition, and relevance scoring.

Parameters

Parameter	Type	Required	Description
`query`	`string`	required	Natural language query or LOGOS expression
`traditions`	`string[]`	optional	Filter by tradition. Default: all.
`limit`	`number`	optional	Max results (default: 5, max: 20)

Example Request

cURLbash

curl -X POST https://oracle.odinseyeenterprises.com/api/v1/grimoire/query \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Saturn return and spiritual initiation",
    "traditions": ["astrology", "kabbalah"],
    "limit": 3
  }'

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "results": [
      {
        "passage": "The Saturn return marks the completion of the first cycle...",
        "source": "Liz Greene, Saturn: A New Look at an Old Devil",
        "tradition": "astrology",
        "relevance": 0.94
      }
    ]
  }
}

GET/health

Server health check. No authentication required.

Example Request

cURLbash

curl https://oracle.odinseyeenterprises.com/api/v1/health

Example Response

Responsejson

{
  "ok": true,
  "data": {
    "status": "operational",
    "version": "1.4.0",
    "ephemeris": "swiss-2.10",
    "uptime_seconds": 847293
  }
}

What is LOGOS?

LOGOS is a domain-specific expression language for querying esoteric relationships. It powers the /evaluate endpoint and can be used in /grimoire/query.

Expression Examples

LOGOS Expressions

// Property access
Sun.sign                          → "Gemini"
Moon.house                        → 8

// Comparisons
Sun.sign == "Gemini"              → true
Moon.degree > 10                 → false

// Aspect queries
Sun TRINE Moon                    → { orb: 2.3, applying: true }
Saturn CONJUNCT MC                → { orb: 1.1, applying: false }

// Boolean logic
Sun.sign == "Gemini" AND Moon.house == 8
(Venus TRINE Jupiter) OR (Venus SEXTILE Jupiter)

// Cross-tradition references
tarot.major[16]                   → "The Tower"
kabbalah.sephirah[3]              → "Binah"

Supported Traditions

☼

Astrology

Western tropical, Swiss Ephemeris

⚖

Tarot

Major & Minor Arcana mappings

✡

Kabbalah

Tree of Life, paths & sephiroth

𝟷

Numerology

Pythagorean & Chaldean systems

⚛

Alchemy

Seven stages, planetary metals

Coherence Scoring

Every cross-tradition mapping and archetype detection returns a coherence_score between 0 and 1. This measures how strongly the correspondence is supported by indexed source texts and established attributions.

Range	Label	Interpretation
0.80 – 1.00	Strong	Well-established correspondence across multiple sources
0.50 – 0.79	Moderate	Supported by some sources, may have competing attributions
0.00 – 0.49	Weak	Speculative or loosely associated — use with caution

SDKs

Official client libraries for quick integration:

Installbash

# Node.js / TypeScript
npm install @odins-oracle/sdk

# Python
pip install odins-oracle

Usage (JavaScript)js

import { Oracle } from '@odins-oracle/sdk';

const oracle = new Oracle({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://oracle.odinseyeenterprises.com/api/v1',
});

const chart = await oracle.chart({
  date: '1990-06-15',
  time: '14:30',
  timezone: 'America/New_York',
  lat: 40.7128,
  lng: -74.0060,
});

console.log(chart.ascendant.formatted); // "11°18' Aries"
console.log(chart.birth_chord);         // { root: "D", quality: "minor" }

Changelog

2026-03-18v1.4.0 — Full API documentation page. SDK packages published.

2026-03-10v1.3.0 — Grimoire query endpoint, coherence scoring model v2.

2026-02-22v1.2.0 — Cross-tradition synthesis, Rosetta endpoint.

2026-02-01v1.1.0 — LOGOS expression evaluator, archetype detection.

2026-01-15v1.0.0 — Initial release. Chart computation with Swiss Ephemeris.