OPENAPI 3.1 SPECIFICATION

Supreme API World Enterprise API Documentation

Welcome to the official developer reference for the Supreme API World Vedic Astrology & Ephemeris Engine. All endpoints accept and return UTF-8 JSON with strict RFC 7807 error envelopes and sub-2ms multi-tier Redis caching.

Your First API Request

curl -X POST https://api.spritual.org/api/v1/kundli \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14.5,
    "lat": 28.6139,
    "lon": 77.2090,
    "timezone": 5.5,
    "language": "en"
  }'

Authentication

Authenticate API requests by supplying your API key either as a custom header or via Bearer HTTP Authorization:

// Method 1: Custom Header (Recommended)
x-api-key: sk_live_9f83a2e1d09b8c7...

// Method 2: Standard Bearer Token
Authorization: Bearer sk_live_9f83a2e1d09b8c7...

Secret Key Security Best Practices

Never embed your sk_live_... keys in client-side mobile applications or public frontend repositories. Always make API calls from your secure backend server or via proxy.

Live vs Sandbox Environments

Environment	Base URL	Key Prefix	Rate Limit Policy
Production (Live)	`https://api.spritual.org/api/v1`	`sk_live_...`	Tiered daily & minute burst limits
Sandbox (Test)	`https://api.spritual.org/api/v1`	`sk_test_...`	Mock & zero-cost test quota

API Versioning & Lifecycle Policy

Supreme API World maintains a backward-compatible versioning policy:

Breaking Changes: Trigger a new URI major version (e.g. /api/v2/). Existing /v1/ endpoints are guaranteed 12 months of security and uptime maintenance following any major release.
Non-Breaking Additions: New fields, astrological divisional charts, or optional parameters are added directly to /v1/ without breaking client integrations.

Official SDK Packages

Install idiomatic SDKs for your development stack:

Python 3 SDK

pip install netraa-sdk

from netraa import NetraaClient
client = NetraaClient("sk_live_your_key")
chart = client.kundli.calculate(year=1995, month=8, day=15, hour=14.5, lat=28.61, lon=77.20)

Node.js / TypeScript SDK

npm install @netraa/sdk

import { Netraa } from '@netraa/sdk';
const netraa = new Netraa({ apiKey: 'sk_live_your_key' });
const result = await netraa.kundli.get({ year: 1995, month: 8, day: 15, hour: 14.5, lat: 28.61, lon: 77.20 });

Webhooks & Signature Verification

Enterprise subscriptions support asynchronous event callbacks with HMAC-SHA256 signatures:

// Verify incoming webhook signature (PHP Example)
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NETRAA_SIGNATURE'] ?? '';
$secret = 'whsec_your_webhook_secret';

$computed = hash_hmac('sha256', $payload, $secret);
if (hash_equals($computed, $signature)) {
    // Signature is authentic & verified
}

Standardized Error Catalog (RFC 7807)

All error responses adhere to standard HTTP status codes and uniform JSON envelopes:

{
  "status": false,
  "error": {
    "code": "INVALID_BIRTH_COORDINATES",
    "message": "Latitude must be between -90.0 and 90.0 degrees.",
    "type": "invalid_request_error",
    "param": "lat",
    "request_id": "req_01J9ABC82X",
    "doc_url": "https://api.spritual.org/docs.php#errors"
  },
  "timestamp": "2026-08-29T07:15:00Z"
}

Error Code	HTTP Status	Description
`UNAUTHORIZED_API_KEY`	401 Unauthorized	Missing, invalid, or deactivated API key.
`RATE_LIMIT_EXCEEDED`	429 Too Many Requests	Request limit per minute or daily quota exhausted.
`VALIDATION_ERROR`	422 Unprocessable	Invalid date, decimal hour, or coordinate bounds.
`ENGINE_COMPUTATION_ERROR`	500 Internal Error	Ephemeris file read error or celestial boundary overflow.

POST /api/v1/free_kundli.php 100% FREE TIER Also: /api/v1/index.php

9-Point Free Kundli

Free Kundli API & Instant Snapshot Engine

A dedicated, high-performance endpoint engineered specifically for consumer apps, portals, and customer onboarding. Returns the exact 9-point foundational Free Kundli payload with standard Lahiri ayanamsha and high-precision ephemeris calculations:

1. birth_details: Standard coordinates, Lahiri ayanamsha, normalized date & time

2. kundli_snapshot: Lagna, Lagna lord, Moon/Sun signs, Nakshatra, Dasha & Dosha summary

3. moon_nakshatra_profile: Charan, Lord, Shubh Namakshar, Gana, Yoni, Nadi, Element & lock teaser

4. planetary_positions: 9 Grahas + Lagna table (Sign, House, Nakshatra, Deg, Retro)

5. bhavas_overview: 12 Bhavas themes/karakatvas, signs, occupying planets & lock teaser

6. current_dasha: Active Mahadasha & Antardasha lords with exact dates (no predictive text)

7. major_yogas: Detected yogas (Gaja Kesari, Ruchaka, etc.) with 'उपलब्ध (Present)' status & locked CTA

8. doshas_status: Manglik, Kaal Sarp, Pitru, Grahan/Chandal, Gandmool & Sade Sati factual statuses

9. d1_chart: Complete D1 Lagna chart with North/South SVG and mobile Canvas data

Request Parameters (JSON or Form-Data)

Field	Type	Required	Description
`name`	string	No	Native's name (default: "Native")
`gender`	string	No	`male`, `female`, or `other`
`dob`	string	Yes*	Birth date in `YYYY-MM-DD` or `DD-MM-YYYY` format. (Or pass `year`, `month`, `day`)
`tob`	string	Yes*	Birth time in `HH:MM`, `HH:MM:SS` or `12-hour AM/PM` format. (Or pass `hour` decimal)
`place` / `pob`	string	No	City or birth location (e.g., "Varanasi", "New Delhi"). Automatically geocoded if lat/lon omitted.
`latitude` / `lat`	float	No*	Latitude (-90 to +90). Resolved from `place` if omitted.
`longitude` / `lon`	float	No*	Longitude (-180 to +180). Resolved from `place` if omitted.
`timezone` / `tz`	float	No	UTC offset in decimal hours (default: `5.5` for IST)
`language` / `lang`	string	No	Language output: `en` (default) or `hi` (Devanagari)
`chart_style`	string	No	`north` (default diamond style) or `south` (box style)
`ayanamsa`	string	No	Default `lahiri` (Chitrapaksha)

cURL Request Example

curl -X POST https://api.spritual.org/api/v1/free_kundli.php \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahul Sharma",
    "gender": "male",
    "dob": "1995-05-15",
    "tob": "14:30",
    "place": "New Delhi, India",
    "lat": 28.6139,
    "lon": 77.2090,
    "tz": 5.5,
    "lang": "en",
    "chart_style": "north",
    "ayanamsa": "lahiri"
  }'

Alternative Route (/api/v1/index.php)

# You can also call the index router:
curl -X POST "https://api.spritual.org/api/v1/index.php?endpoint=free_kundli" \
  -H "Content-Type: application/json" \
  -d '{"name": "Rahul Sharma", "dob": "1995-05-15", "tob": "14:30", "lat": 28.6139, "lon": 77.2090}'

Exact 9-Point Response Payload (JSON)

{
  "status": true,
  "message": "Success",
  "data": {
    "birth_details": {
      "name": "Rahul Sharma",
      "gender": "Male",
      "dob": "1995-05-15",
      "tob": "14:30:00",
      "place": "New Delhi, India",
      "latitude": 28.6139,
      "longitude": 77.209,
      "timezone": 5.5,
      "ayanamsha": "Lahiri"
    },
    "kundli_snapshot": {
      "lagna": "Virgo",
      "lagna_lord": "Mercury",
      "moon_sign": "Scorpio",
      "moon_nakshatra": "Anuradha",
      "charan": 2,
      "sun_sign": "Taurus",
      "current_mahadasha": "Ketu",
      "mahadasha_end_date": "2032-06-12",
      "current_antardasha": "Venus",
      "antardasha_start_date": "2025-11-09",
      "antardasha_end_date": "2027-01-11",
      "top_yoga_highlight": "Gaja Kesari Yoga - Jupiter in Kendra from Moon grants powerful intellect, fame, wealth and leadership qualities.",
      "doshas_status_summary": "Manglik: Active | Kaal Sarp: Absent | Pitru Dosha: Present | Grahan/Chandal: Absent | Gandmool: Normal | Shani Sade Sati/Dhaiya: Inactive"
    },
    "moon_nakshatra_profile": {
      "moon_sign": "Scorpio",
      "nakshatra": "Anuradha",
      "charan": 2,
      "nakshatra_lord": "Saturn",
      "shubh_namakshar": "नी (Nee)",
      "gana": "Deva",
      "yoni": "Mriga (Deer)",
      "nadi": "Madhya",
      "element": "Water",
      "lock_notice": "🔒 Deep psychological personality analysis, subconscious karmic patterns, emotional temperament, and customized life path tendencies are locked. Upgrade to Full Kundli Report to unlock."
    },
    "planetary_positions": [
      { "planet": "Ascendant (Lagna)", "sign": "Virgo", "house": 1, "nakshatra": "Uttara Phalguni", "charan": 2, "degree": "1° 39' 06\"", "degree_decimal": 1.65, "is_retrograde": false },
      { "planet": "Sun", "sign": "Taurus", "house": 9, "nakshatra": "Krittika", "charan": 2, "degree": "0° 17' 02\"", "degree_decimal": 0.28, "is_retrograde": false },
      { "planet": "Moon", "sign": "Scorpio", "house": 3, "nakshatra": "Anuradha", "charan": 2, "degree": "9° 52' 14\"", "degree_decimal": 9.87, "is_retrograde": false },
      { "planet": "Mars", "sign": "Leo", "house": 12, "nakshatra": "Magha", "charan": 1, "degree": "4° 10' 32\"", "degree_decimal": 4.18, "is_retrograde": false },
      { "planet": "Mercury", "sign": "Taurus", "house": 9, "nakshatra": "Rohini", "charan": 3, "degree": "23° 41' 18\"", "degree_decimal": 23.69, "is_retrograde": false },
      { "planet": "Jupiter", "sign": "Scorpio", "house": 3, "nakshatra": "Anuradha", "charan": 4, "degree": "16° 48' 20\"", "degree_decimal": 16.81, "is_retrograde": false },
      { "planet": "Venus", "sign": "Aries", "house": 8, "nakshatra": "Bharani", "charan": 4, "degree": "28° 12' 40\"", "degree_decimal": 28.21, "is_retrograde": false },
      { "planet": "Saturn", "sign": "Aquarius", "house": 6, "nakshatra": "Shatabhisha", "charan": 1, "degree": "29° 04' 15\"", "degree_decimal": 29.07, "is_retrograde": false },
      { "planet": "Rahu", "sign": "Libra", "house": 2, "nakshatra": "Swati", "charan": 1, "degree": "11° 14' 08\"", "degree_decimal": 11.24, "is_retrograde": true },
      { "planet": "Ketu", "sign": "Aries", "house": 8, "nakshatra": "Ashwini", "charan": 3, "degree": "11° 14' 08\"", "degree_decimal": 11.24, "is_retrograde": true }
    ],
    "bhavas_overview": [
      { "house": 1, "theme": "Tanu Bhava (Self, Personality, Vitality, Character & Longevity)", "sign": "Virgo", "occupying_planets": ["Ascendant (Lagna)"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 2, "theme": "Dhana Bhava (Wealth, Family Lineage, Speech, Assets & Eye)", "sign": "Libra", "occupying_planets": ["Rahu"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 3, "theme": "Sahaja Bhava (Courage, Younger Siblings, Communication, Skills)", "sign": "Scorpio", "occupying_planets": ["Moon", "Jupiter"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 4, "theme": "Sukha Bhava (Mother, Real Estate, Vehicles, Heart & Inner Happiness)", "sign": "Sagittarius", "occupying_planets": [], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 5, "theme": "Putra Bhava (Children, Intellect, Speculation, Romance, Purva Punya)", "sign": "Capricorn", "occupying_planets": [], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 6, "theme": "Ripu/Ari Bhava (Debts, Enemies, Disease, Competition, Service & Daily Work)", "sign": "Aquarius", "occupying_planets": ["Saturn"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 7, "theme": "Kalatra Bhava (Spouse, Marriage, Business Partnerships & Foreign Public)", "sign": "Pisces", "occupying_planets": [], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 8, "theme": "Randhra Bhava (Longevity, Transformations, Sudden Events, Occult & Secrets)", "sign": "Aries", "occupying_planets": ["Venus", "Ketu"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 9, "theme": "Dharma/Bhagya Bhava (Fortune, Higher Philosophy, Father, Guru & Pilgrimage)", "sign": "Taurus", "occupying_planets": ["Sun", "Mercury"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 10, "theme": "Karma Bhava (Profession, Career Authority, Social Status & Fame)", "sign": "Gemini", "occupying_planets": [], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 11, "theme": "Labha Bhava (Gains, Incomes, Aspirations, Elder Siblings & Network)", "sign": "Cancer", "occupying_planets": [], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." },
      { "house": 12, "theme": "Vyaya Bhava (Expenditures, Foreign Residency, Subconscious & Moksha)", "sign": "Leo", "occupying_planets": ["Mars"], "premium_lock_teaser": "🔒 Detailed bhava bala, SAV bindus, aspect strength, and timing of manifestation locked." }
    ],
    "current_dasha": {
      "active_mahadasha": { "lord": "Ketu", "end_date": "2032-06-12" },
      "active_antardasha": { "lord": "Venus", "start_date": "2025-11-09", "end_date": "2027-01-11" },
      "lock_notice": "🔒 Full 120-year Vimshottari planetary timeline, Sookshma/Pratyantar cycles, and detailed event predictive forecasts are locked."
    },
    "major_yogas": {
      "total_detected": 6,
      "yogas": [
        { "name": "Gaja Kesari Yoga", "category": "shubha", "status": "उपलब्ध (Present)", "description": "Jupiter in Kendra from Moon grants powerful intellect, fame, wealth and leadership qualities.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." },
        { "name": "Budhaditya Yoga", "category": "shubha", "status": "उपलब्ध (Present)", "description": "Mercury conjunct Sun in Taurus — blesses with exceptional intellectual sharpness and eloquent communication.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." },
        { "name": "Raj Yoga (Jupiter+Mercury)", "category": "shubha", "status": "उपलब्ध (Present)", "description": "Jupiter (H4 lord) and Mercury (H1 lord) form Raj Yoga in mutual aspect.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." },
        { "name": "Neech Bhanga Raj Yoga (Moon)", "category": "shubha", "status": "उपलब्ध (Present)", "description": "Moon is debilitated but its cancellation converts weakness into resilience and transformative success.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." },
        { "name": "Harsha Yoga (Saturn in H6)", "category": "shubha", "status": "उपलब्ध (Present)", "description": "6th lord Saturn placed in dusthana house H6 forms Harsha Yoga — invincible against rivals with untarnished reputation.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." },
        { "name": "Sarala Yoga (Mars in H12)", "category": "shubha", "status": "उपलब्ध (Present)", "description": "8th lord Mars placed in dusthana house H12 forms Sarala Yoga — grants long life and fearlessness.", "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions." }
      ],
      "locked_cta": "🔒 Unlock full Kundli report to reveal life area activation, timing, and manifestation predictions."
    },
    "doshas_status": {
      "manglik": { "status": "Active", "details": "Mars is in H12 from Lagna (Manglik). Active references: 1/3. Intensity: Lagna-based Manglik." },
      "kaal_sarp": { "status": "Absent", "details": "Planets are not hemmed between Rahu and Ketu." },
      "pitru_dosha": { "status": "Present", "details": "Conditional / Possible Pitru Dosha (9th lord Venus in 8th house conjunct Ketu). Sun in 9th house is unafflicted." },
      "grahan_chandal": { "status": "Absent", "details": "No luminaries or Jupiter severely afflicted by Rahu/Ketu." },
      "gandmool": { "status": "Normal", "details": "Moon is in normal auspicious Nakshatra (Anuradha)." },
      "shani_sade_sati_dhaiya": { "status": "Inactive", "details": "Transiting Saturn is currently unafflicted to natal Moon." },
      "summary": "Manglik: Active | Kaal Sarp: Absent | Pitru Dosha: Present | Grahan/Chandal: Absent | Gandmool: Normal | Shani Sade Sati/Dhaiya: Inactive"
    },
    "d1_chart": {
      "chart_type": "D1",
      "name": "Lagna / Rashi Chart",
      "style": "north",
      "ascendant_sign": "Virgo",
      "ascendant_sign_index": 5,
      "ascendant_sign_num": 6,
      "houses": { ... },
      "svg": "",
      "canvas_data": {
        "chart_style": "north",
        "ascendant_sign_num": 6,
        "house_signs": [6, 7, 8, 9, 10, 11, 12, 1, 2, 3, 4, 5],
        "planets_by_house": { "1": ["Asc"], "2": ["Ra"], "3": ["Mo", "Ju"], ... }
      }
    }
  }
}

POST /api/v1/kundli

BPHS Sphuta

Complete Kundli & Planetary Sphuta

Calculates Nirayana sidereal planetary longitudes, dignities, retrograde states, nakshatra & pada, 12 bhavas, and 4-level Vimshottari Dasa.

Request Body (JSON)

Field	Type	Required	Description
`year`	integer	Yes	Gregorian birth year (e.g. 1995)
`month`	integer	Yes	Month of birth (1–12)
`day`	integer	Yes	Day of birth (1–31)
`hour`	number	Yes	Decimal hour of birth (e.g. 14.5 for 2:30 PM)
`lat`	number	Yes	Latitude in decimal degrees (-90.0 to 90.0)
`lon`	number	Yes	Longitude in decimal degrees (-180.0 to 180.0)
`timezone`	number	Yes	Timezone offset in hours (e.g. 5.5 for IST)
`language`	string	No	Localization code (en, hi, ta, te, kn, mr)

POST /api/v1/marriage-analysis

विवाह एवं कुटुम्ब

Marriage & Family Analysis (Self API)

Evaluates the 7th house (Kalatra Bhava), 2nd house (Kutumba Bhava), and 4th house (Sukha Bhava), assessing planetary occupants, lord placements, aspect networks, and Navamsha D9 indicators. Operates as a standalone API without full Kundli generation using direct birth parameters, or optionally reuses an existing kundli object.

Request Body (JSON)

Field	Type	Required	Description
`year`	integer	Yes*	Gregorian birth year (e.g. 1995)
`month`	integer	Yes*	Month of birth (1–12)
`day`	integer	Yes*	Day of birth (1–31)
`hour`	number	Yes*	Decimal hour of birth (e.g. 14.5 for 2:30 PM)
`lat`	number	Yes*	Latitude in decimal degrees (-90.0 to 90.0)
`lon`	number	Yes*	Longitude in decimal degrees (-180.0 to 180.0)
`timezone`	number	Yes*	Timezone offset in hours (e.g. 5.5 for IST)
`language`	string	No	Localization code (`en` or `hi`)
`kundli`	object	No	Optional pre-calculated Kundli data. *If provided, birth coordinates are not required.

Example Request (cURL)

curl -X POST https://api.spritual.org/api/v1/marriage-analysis \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14.5,
    "lat": 28.6139,
    "lon": 77.2090,
    "timezone": 5.5,
    "language": "en"
  }'

Response Output Fields

{
  "status": true,
  "data": {
    "domain": "marriage_and_family",
    "overview": {
      "marriage_house": 7,
      "marriage_sign": "Taurus",
      "marriage_sign_lord": "Venus",
      "seventh_lord_placement": "House 9",
      "family_harmony_score": 85,
      "rating_label": "Harmonious & Auspicious"
    },
    "marriage_nature_and_probabilities": {
      "love_marriage_probability": "52.4%",
      "arranged_marriage_probability": "47.6%",
      "primary_inclination": "Love / Self-chosen Marriage",
      "indicative_marriage_age": "24 - 28 years",
      "delay_risk": "Low / On-time"
    },
    "spouse_profile": {
      "physical_traits": ["Attractive complexion", "Medium built"],
      "likely_profession_inclinations": ["Creative Arts", "Banking", "Public Relations"],
      "temperament": "Gentle, balanced, and aesthetic"
    },
    "family_dynamics": {
      "family_wealth_status": "Strong financial continuity",
      "domestic_bliss_rating": "High peace and domestic harmony"
    },
    "classical_remedies": [
      "Wear Pearl or White Sapphire if Venus or 7th lord is debilitated",
      "Recite Shukra Beej Mantra (ॐ शुं शुक्राय नमः)"
    ]
  }
}

POST /api/v1/career-analysis

आजीविका एवं व्यवसाय

Career & Job Analysis (Self API)

Evaluates the Karma Bhava (10th house), 6th house (daily service/job), 11th house (gains), and Dashamsha (D10) influences. Computes Job vs. Business suitability percentages, Government Job likelihood, top vocational fields, and peak professional growth ages.

Request Body (JSON)

Field	Type	Required	Description
`year`	integer	Yes*	Gregorian birth year (e.g. 1995)
`month`	integer	Yes*	Month of birth (1–12)
`day`	integer	Yes*	Day of birth (1–31)
`hour`	number	Yes*	Decimal hour of birth (e.g. 14.5 for 2:30 PM)
`lat`	number	Yes*	Latitude in decimal degrees (-90.0 to 90.0)
`lon`	number	Yes*	Longitude in decimal degrees (-180.0 to 180.0)
`timezone`	number	Yes*	Timezone offset in hours (e.g. 5.5 for IST)
`language`	string	No	Localization code (`en` or `hi`)
`kundli`	object	No	Optional pre-calculated Kundli object

Example Request (cURL)

curl -X POST https://api.spritual.org/api/v1/career-analysis \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14.5,
    "lat": 28.6139,
    "lon": 77.2090,
    "timezone": 5.5,
    "language": "en"
  }'

Response Output Fields

{
  "status": true,
  "data": {
    "domain": "career_and_job",
    "overview": {
      "career_house": 10,
      "career_sign": "Leo",
      "career_sign_lord": "Sun",
      "tenth_lord_placement": "House 9",
      "planets_in_tenth_house": ["Mercury"]
    },
    "work_mode_preference": {
      "job_service_suitability": "48.1%",
      "business_entrepreneurship_suitability": "51.9%",
      "primary_career_path": "Independent Business / Entrepreneurship"
    },
    "government_job_analysis": {
      "government_job_probability": "95%",
      "assessment": "High Potential for Government / Public Sector Leadership"
    },
    "top_vocational_fields": [
      { "sector": "Administration & Civil Services", "compatibility": "High" },
      { "sector": "Information Technology & Analytics", "compatibility": "Very High" },
      { "sector": "Finance, Advisory & Strategic Planning", "compatibility": "Favorable" }
    ],
    "progression_and_growth_ages": [28, 32, 36, 42, 48],
    "career_remedies": [
      "Offer Arghya (water) to Lord Surya daily at sunrise",
      "Chant Aditya Hridaya Stotra or Surya Gayatri Mantra"
    ]
  }
}

POST /api/v1/gemstones-remedies

रत्न एवं वैदिक उपाय

Gemstones & Remedies Analysis (Self API)

Prescribes classical Shastric gemstones: Life Stone (Jeevan Ratna), Lucky Stone (Bhagya Ratna), and Benefic Stone (Karak Ratna) along with prohibited Maraka stones. Recommends authentic Mukhi Rudraksha, Vedic Beej Mantras, fasting days, and charitable donation items.

Request Body (JSON)

Field	Type	Required	Description
`year`	integer	Yes*	Gregorian birth year (e.g. 1995)
`month`	integer	Yes*	Month of birth (1–12)
`day`	integer	Yes*	Day of birth (1–31)
`hour`	number	Yes*	Decimal hour of birth (e.g. 14.5 for 2:30 PM)
`lat`	number	Yes*	Latitude in decimal degrees (-90.0 to 90.0)
`lon`	number	Yes*	Longitude in decimal degrees (-180.0 to 180.0)
`timezone`	number	Yes*	Timezone offset in hours (e.g. 5.5 for IST)
`language`	string	No	Localization code (`en` or `hi`)
`kundli`	object	No	Optional pre-calculated Kundli object

Example Request (cURL)

curl -X POST https://api.spritual.org/api/v1/gemstones-remedies \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14.5,
    "lat": 28.6139,
    "lon": 77.2090,
    "timezone": 5.5,
    "language": "en"
  }'

Response Output Fields

{
  "status": true,
  "data": {
    "domain": "gemstones_and_remedies",
    "ascendant_info": {
      "lagna_sign": "Scorpio",
      "lagna_lord": "Mars"
    },
    "gemstones": {
      "life_stone": {
        "category": "Jeevan Ratna (Life Stone - Lagna Lord)",
        "governing_planet": "Mars",
        "gemstone_en": "Red Coral (Moonga)",
        "gemstone_hi": "मूँगा (Red Coral)",
        "substitute": "Carnelian",
        "finger": "Ring Finger (अनामिका)",
        "metal": "Gold or Copper",
        "day": "Tuesday (मंगलवार) morning",
        "mantra": "ॐ क्रां क्रीं क्रौं सः भौमाय नमः",
        "weight_carats": "5 - 8 Carats (6 - 9 Ratti)"
      },
      "lucky_stone": {
        "category": "Bhagya Ratna (Fortune Stone - 9th Lord)",
        "governing_planet": "Moon",
        "gemstone_en": "Pearl (Moti)",
        "finger": "Little Finger (कनिष्ठिका)",
        "metal": "Silver"
      },
      "prohibited_gemstones": [
        { "gemstone": "Emerald (Panna)", "reason": "Mercury rules Dusthana houses (8th/11th)" }
      ]
    },
    "rudraksha_recommendations": [
      { "mukhi": "3 Mukhi Rudraksha", "deity": "Agni Dev", "purpose": "Purifies vitality and Lagna lord Mars" }
    ],
    "vedic_remedies": {
      "fasting_day": "Tuesday",
      "daan_charity": "Donate red lentils (masoor dal), copper vessels, or jaggery",
      "daily_mantras": ["ॐ क्रां क्रीं क्रौं सः भौमाय नमः"]
    }
  }
}

POST /api/v1/dosha-analysis

दोष विचार एवं शांति

Complete Vedic Dosha Analysis (Self API)

Unified dosha diagnostics calculating Manglik (Kuja) Dosha with 14 classical cancellation rules, Kaal Sarp Dosha (12 classical types), Saturn Sade Sati & Dhaiya phase tracking, Pitru Dosha, Gandanta Dosha, and Graha Afflictions (Guru Chandal, Grahan, Angarak, Kemadruma).

Request Body (JSON)

Field	Type	Required	Description
`year`	integer	Yes*	Gregorian birth year (e.g. 1995)
`month`	integer	Yes*	Month of birth (1–12)
`day`	integer	Yes*	Day of birth (1–31)
`hour`	number	Yes*	Decimal hour of birth (e.g. 14.5 for 2:30 PM)
`lat`	number	Yes*	Latitude in decimal degrees (-90.0 to 90.0)
`lon`	number	Yes*	Longitude in decimal degrees (-180.0 to 180.0)
`timezone`	number	Yes*	Timezone offset in hours (e.g. 5.5 for IST)
`language`	string	No	Localization code (`en` or `hi`)
`kundli`	object	No	Optional pre-calculated Kundli object

Example Request (cURL)

curl -X POST https://api.spritual.org/api/v1/dosha-analysis \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14.5,
    "lat": 28.6139,
    "lon": 77.2090,
    "timezone": 5.5,
    "language": "en"
  }'

Response Output Fields

{
  "status": true,
  "data": {
    "domain": "dosha_analysis",
    "dosha_summary": {
      "has_active_dosha": true,
      "active_doshas_count": 1,
      "overall_severity_score": 20,
      "severity_classification": "Mild / Negligible Dosha"
    },
    "manglik_dosha": {
      "is_present": true,
      "intensity": "Partial",
      "mars_house": 11,
      "is_cancelled": true,
      "cancellations": [
        "Aries/Scorpio Lagna: Mars is the lagna lord — dosha substantially neutralised"
      ],
      "detailed_verdict": "Manglik dosha is neutralized by classical cancellation rules."
    },
    "kaal_sarp_dosha": {
      "is_present": false,
      "type_name": "None",
      "verdict": "No Kaal Sarp Dosha present in chart."
    },
    "sade_sati": {
      "is_undergoing": false,
      "current_phase": "None",
      "verdict": "Native is currently free from Shani Sade Sati."
    },
    "pitru_dosha": {
      "is_present": false,
      "verdict": "9th house is clean; no Pitru Dosha indicated."
    },
    "gandanta_dosha": {
      "is_present": false,
      "verdict": "No Gandanta sandhi afflictions."
    },
    "graha_afflictions": {
      "guru_chandal": { "is_present": false },
      "grahan_dosha": { "is_present": false },
      "angarak_dosha": { "is_present": false },
      "kemadruma_yoga": { "is_present": false }
    }
  }
}

POST /api/v1/chat MOBILE & WEB READY

Conversational AI Astrologer & Kundli Chat (KARMA AI)

Multi-turn conversational Vedic Astrologer engine for Mobile (iOS / Android / Flutter / React Native) and Web. Calculates astrological charts, planetary yogas, and dasha on-the-fly to deliver authenticated, empathetic, and evidence-grounded consultation.

Mobile & Web Integration Examples

curl -X POST https://api.spritual.org/api/v1/chat \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Mera career aur wealth yog kaisa rahega?",
    "language": "hi",
    "birth_input": {
      "year": 1995,
      "month": 5,
      "day": 15,
      "hour": 14,
      "min": 30,
      "lat": 28.6139,
      "lon": 77.2090
    }
  }'

// Web (Fetch) & Mobile (React Native)
async function askAiAstrologer(message, birthDetails) {
  const response = await fetch('https://api.spritual.org/api/v1/chat', {
    method: 'POST',
    headers: {
      'x-api-key': 'sk_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: message,
      language: 'hi', // 'hi', 'en', 'hinglish', 'gu', 'mr', 'bn', etc.
      birth_input: birthDetails
    })
  });

  const result = await response.json();
  if (result.status && result.data) {
    console.log("AI Astrologer:", result.data.answer);
  }
}

// Flutter / Dart (iOS & Android)
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String?> askKarmaAstrologer(String question) async {
  final url = Uri.parse('https://api.spritual.org/api/v1/chat');
  final response = await http.post(
    url,
    headers: {
      'x-api-key': 'sk_live_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'message': question,
      'language': 'hi',
      'birth_input': {
        'year': 1995, 'month': 5, 'day': 15,
        'hour': 14, 'min': 30, 'lat': 28.6139, 'lon': 77.2090
      }
    }),
  );

  if (response.statusCode == 200) {
    final body = jsonDecode(response.body);
    return body['data']?['answer'];
  }
  return null;
}

import requests

url = "https://api.spritual.org/api/v1/chat"
headers = {
    "x-api-key": "sk_live_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "message": "Mera career aur financial status kaisa rahega?",
    "language": "hi",
    "birth_input": {
        "year": 1995, "month": 5, "day": 15,
        "hour": 14, "min": 30, "lat": 28.6139, "lon": 77.2090
    }
}
resp = requests.post(url, headers=headers, json=payload)
data = resp.json()
print("Answer:", data["data"]["answer"])

Sample Response

{
  "status": true,
  "message": "Success",
  "request_id": "req_2ee712cfc8bf01ce",
  "data": {
    "success": true,
    "session_id": "sess_user_guest_38513f4e",
    "kundali_id": "1c29a1d1-1146-4ead-a5cd-85f5600228f3",
    "intent": "career",
    "topic": "career",
    "language": "hinglish",
    "answer": "Namaste. Aapke planetary chart ke anusar dashmesh Guru shubh sthiti mein hai...",
    "model": "Groq-qwen/qwen3.8-27b",
    "detected_entities": ["lagna_and_rashi", "current_dasha"]
  }
}

POST /api/v1/ai_chat

AI Text Completion & Vedic Reasoning (LLM Gateway)

High-throughput natural language Vedic inference gateway powered by Google Gemini and OpenAI with shastra-grounded system prompts.

curl -X POST https://api.spritual.org/api/v1/ai_chat \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain the spiritual and scientific significance of Gayatri Mantra",
    "language": "hi"
  }'

POST /api/v1/osint/email/pdf PDF-1.4

DOOT Cyber Sarthi - Email Intelligence & Enterprise PDF Dossier

Autonomous multi-source digital footprint reconnaissance engine. Cross-references verified public sources without touching stolen credential dumps:

15-Platform Footprint Matrix: GitHub, Reddit, Pinterest, Gravatar, Telegram, GitLab, HackerNews, Dev.to, Medium, YouTube, Keybase, SoundCloud, Twitter/X, Instagram, LinkedIn.
Visual & Avatar Forensics: Cryptographic SHA-256 (clone detection) and perceptual difference hashing (dHash/pHash) for altered variants.
Dark Web Reconnaissance: 36 monitored onion repositories + 4 discovery indexes with explicit Tor runtime connectivity audit statements.
Corroborated Evidence Graph: Independent source attribution (CORROBORATED vs UNVERIFIED) with pairwise pivot links.

cURL Request (Direct PDF Download)

curl -X POST https://api.spritual.org/api/v1/osint/email/pdf \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "uppsrn@gmail.com",
    "deep_search": true,
    "check_holehe": true,
    "check_breach": true,
    "check_username": true,
    "check_darkweb": true,
    "async_mode": false
  }' \
  --output "doot_osint_dossier.pdf"

Browser / JavaScript Blob Download

const response = await fetch("https://api.spritual.org/api/v1/osint/email/pdf", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "target@example.com",
    deep_search: true,
    check_holehe: true,
    check_breach: true,
    check_username: true,
    check_darkweb: true,
    async_mode: false
  })
});
const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
window.open(url, "_blank");

POST /api/v1/osint/mobile/pdf PDF-1.4

DOOT Cyber Sarthi - Mobile Intelligence & Enterprise PDF Dossier

Validates mobile numbers across national & E.164 formats, line type, carrier attribution, circle region, authorized directory records, and public messaging protocol references.

curl -X POST https://api.spritual.org/api/v1/osint/mobile/pdf \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "+919876543210",
    "check_intelligence": true,
    "deep_search": true,
    "async_mode": false
  }' \
  --output "mobile_osint_dossier.pdf"

POST /api/v1/osint/search/pdf PDF-1.4

DOOT Cyber Sarthi - Universal OSINT Search & Dossier

Universal ingress gateway supporting both email and mobile targets dynamically in a single unified API endpoint.

curl -X POST https://api.spritual.org/api/v1/osint/search/pdf \
  -H "x-api-key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "query": "target@example.com",
    "deep_search": true,
    "async_mode": false
  }' \
  --output "universal_osint_dossier.pdf"