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/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)