Overview

Horoscope API returns complete Vedic astrology data — sign-based Rashifal, Janma Kundli, Vimshottari Dasha, D9/Navamsa charts, dosha checks, Ashtakoot matching, and rule-based natal interpretation — for any birth date, time, and place. It serves astrology apps, devotional products, matchmaking flows, and birth-chart dashboards.

Rule of thumb: birth-based endpoints under /v1/... use POST. Public read-only endpoints use GET — including GET /v1/rashifal/:sign/:period, GET /health, and GET /status.

All responses use a standard JSON envelope with data, meta, and optional dev_notes fields. Error responses always carry a machine-readable error and a docs_url link.

All calculations use the Vedic sidereal zodiac with the Lahiri (Chitrapaksha) ayanamsa, whole-sign houses, and true nodes for Rahu/Ketu. Horoscope computation is deterministic and rule-based — natal prediction text is phrase-bank/rule output, not LLM compute.

New to Jyotish terminology? Jump to the Glossary for plain-language definitions of every term used in API responses — rashi, lagna, graha, nakshatra, dasha, and more.

curl -X POST "https://horoscope.devdarsha.com/v1/kundli" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

// Use header auth - never put api_key in client-side code
const response = await fetch("https://horoscope.devdarsha.com/v1/kundli", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    date: "1990-08-15",
    time: "10:30",
    city: "Kolkata"
  })
});

const data = await response.json();
console.log(data.data.lagna.rashi.name);          // "Tula"
console.log(data.data.grahas[0].name);            // "Surya"
console.log(data.meta.calculation.ayanamsa);      // "Lahiri (Chitrapaksha)"

import requests

response = requests.post(
    "https://horoscope.devdarsha.com/v1/kundli",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"date": "1990-08-15", "time": "10:30", "city": "Kolkata"}
)

data = response.json()
print(data["data"]["lagna"]["rashi"]["name"])       # Tula
print(data["data"]["grahas"][0]["name"])            # Surya
print(data["meta"]["calculation"]["ayanamsa"])      # Lahiri (Chitrapaksha)

{
  "data": {
    "birth":  { "date": "1990-08-15", "time": "10:30", "place": "Kolkata" },
    "lagna":  { "rashi": { "number": 7, "name": "Tula" }, "nakshatra": { "name": "Swati", "pada": 2 } },
    "grahas": [{ "name": "Surya", "rashi": { "name": "Karka" }, "house": 10, "retrograde": false }],
    "houses": [{ "house": 1, "rashi": "Tula", "lord": "Shukra" }]
  },
  "meta": {
    "api_version":  "v1",
    "service":      "horoscope",
    "data_source":  "live",
    "calculation":  { "zodiac": "sidereal", "ayanamsa": "Lahiri (Chitrapaksha)", "house_system": "whole-sign" }
  }
}

{
    "data": {
        "birth": {
            "date": "1990-08-15",
            "time": "10:30",
            "place": "Kolkata",
            "resolved_timezone": "Asia/Kolkata",
            "lat": 22.5726,
            "lon": 88.3639
        },
        "lagna": {
            "degree": 192.42,
            "rashi": { "number": 7, "name": "Tula" },
            "nakshatra": { "name": "Swati", "pada": 2 }
        },
        "grahas": [
            {
                "name": "Surya",
                "longitude": 118.31,
                "rashi": { "number": 4, "name": "Karka" },
                "house": 10,
                "nakshatra": { "name": "Ashlesha", "pada": 4 },
                "retrograde": false
            }
        ],
        "houses": [
            { "house": 1, "rashi": "Tula", "lord": "Shukra" }
        ],
        "charts": {
            "D1": {
                "name": "Rashi",
                "positions": [{ "graha": "Surya", "rashi": "Karka", "house": 10 }]
            }
        }
    },
    "meta": {
        "api_version": "v1",
        "service": "horoscope",
        "computed_at": "2026-07-01T00:00:00.000Z",
        "data_source": "live",
        "cache_age_seconds": 0,
        "calculation": {
            "zodiac": "sidereal",
            "ayanamsa": "Lahiri (Chitrapaksha)",
            "house_system": "whole-sign",
            "node": "true"
        }
    },
    "dev_notes": []
}

Authentication

Every compute endpoint requires an API key. Send it in the x-api-key request header and keep requests server-side.

How to get a key

1. Sign up — free, no credit card.
2. Open the Dashboard and create a key. You can name, rotate, and revoke keys from there.
3. Copy the key once — it is shown in full only at creation time. Store it as a server-side secret.

The same lifecycle is also available programmatically — see API Keys below.

Recommended method

Pass your key as an x-api-key request header. This keeps keys out of URLs, browser history, proxy logs, and analytics exports.

POST https://horoscope.devdarsha.com/v1/kundli
x-api-key: YOUR_API_KEY

Auth failure reference

Routes & Base URL

The clean Horoscope host is the preferred integration surface for new clients. The legacy gateway route remains documented only so existing integrations can migrate without confusion.

https://horoscope.devdarsha.com/v1

Docs examples below use the clean host. Replace the path with the legacy route only when supporting an older integration.

Route mapping

Quick Start

For all /v1/... endpoints, send a JSON body with your request fields and authenticate using x-api-key. Start with Kundli because it verifies birth input, timezone resolution, chart computation, and the response envelope in one call.

curl -X POST "https://horoscope.devdarsha.com/v1/kundli" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

curl -X POST "https://horoscope.devdarsha.com/v1/kundli" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","lat":22.5726,"lon":88.3639,"tz":"Asia/Kolkata"}'

Plans & Feature Gates

Horoscope API uses a separate public plan ladder: Free, Topaz, Ruby, Diamond, Eclipse, Zenith, and Infinity. Free covers basic testing. Topaz is the paid endpoint threshold. Higher tiers increase usage, support, SLA, and commercial terms without changing the v1 path shape. Plan entitlements are product-isolated. Full pricing lives on pricing.

Access gates

• Free: /rashifal and /kundli only. Free endpoints still require an API key.
• Topaz and above: all v1 horoscope endpoints — Dasha, D9, doshas, matching, and natal prediction.
• Ruby / Diamond / Eclipse / Zenith / Infinity: same endpoint set as Topaz with higher quota, rate limits, support, and SLA.

Endpoint access

Quota cost per call

• GET /v1/rashifal/:sign/:period — 1 request.
• POST /v1/kundli — 1 request.
• POST /v1/dasha — 1 request unless expanded levels are billed separately in the active plan.
• POST /v1/divisional/:varga, /v1/doshas, /v1/matching, and /v1/predict/natal — 1 request each.
• GET /health and GET /status — no quota cost.

The actual charge is echoed in X-Quota-Cost. If you call an endpoint that is not on your plan, the response is 403 plan_required. See Error Codes.

Signup

Create a new DevDarsha account programmatically. Returns an account record and a first API key. No authentication required.

Most users will sign up through the website signup form instead — this endpoint is for partners and SDKs that provision accounts on a user's behalf.

Request Body (JSON)

Example Request

curl -X POST "https://panchang.devdarsha.com/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"a-strong-password","plan":"free"}'

Response

{
  "data": {
    "account": { "id": "acc_...", "email": "[email protected]", "plan": "free" },
    "api_key": "sk_live_..."
  },
  "meta": { "version": "v1", "computed_at": "2026-07-01T10:00:00Z" }
}

API Key Management

List, create, rotate, and revoke API keys for your account. All key endpoints require an existing API key with admin scope (your first key has admin scope by default). You can also manage keys from the Dashboard.

Operations

Create a key

curl -X POST "https://panchang.devdarsha.com/v1/keys" \
  -H "x-api-key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-server","scope":"read"}'

Response (create / rotate)

{
  "data": {
    "key_id": "key_abc123",
    "api_key": "sk_live_...",
    "name": "production-server",
    "scope": "read",
    "created_at": "2026-07-01T10:00:00Z"
  },
  "meta": { "version": "v1" }
}

Usage

Returns the current billing period's usage and remaining quota for the authenticated key. Useful for surfacing a quota meter in your own dashboard or alerting before you run out.

Example Request

curl "https://horoscope.devdarsha.com/v1/usage" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "plan": "topaz",
    "period_start": "2026-07-01T00:00:00Z",
    "period_end":   "2026-08-01T00:00:00Z",
    "calls_used":      1250,
    "calls_included":  10000,
    "calls_remaining": 8750
  },
  "meta": { "version": "v1", "computed_at": "2026-07-02T10:00:00Z" }
}

Rashifal

Returns sign-based Rashifal for a rashi and period. This endpoint does not require birth details. Not familiar with these terms? See the Glossary.

Path parameters

Query parameters

Example Request

curl -X GET "https://horoscope.devdarsha.com/v1/rashifal/mesha/daily?lang=en" \
  -H "x-api-key: YOUR_API_KEY"

Kundli

Returns a basic Janma Kundli / D1 chart with lagna, graha positions, rashi, house, nakshatra, and pada fields. This is the recommended first integration test.

Request Body (JSON)

Uses the common Birth Input object.

curl -X POST "https://horoscope.devdarsha.com/v1/kundli" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

Response Fields

Dasha Topaz+

Returns Vimshottari Dasha periods computed from the natal Moon. Use this when your product needs current Maha Dasha, Antardasha, and timeline context.

Request Body (JSON)

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/dasha" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata","levels":2}'

Divisional Charts Topaz+

Returns a divisional chart for the requested varga. v1 supports D1 and D9. Use D9 for Navamsa workflows.

Path parameters

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/divisional/D9" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

Response Fields

Doshas Topaz+

Returns deterministic dosha checks for common Jyotish conditions. Treat the output as an informational calculation layer, not as a prediction of specific outcomes or remedies.

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/doshas" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

Response Fields

Matching Topaz+

Returns Ashtakoot / Gun Milan compatibility scoring between two birth profiles. Use boy and girl objects for compatibility with common North Indian matching terminology; applications may relabel the result in their own UI.

Request Body (JSON)

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/matching" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"boy":{"date":"1990-08-15","time":"10:30","city":"Kolkata"},"girl":{"date":"1992-03-21","time":"14:05","city":"Mumbai"}}'

Response Fields

{
  "data": {
    "score": { "total": 26, "max": 36, "percent": 72.22 },
    "kootas": [
      { "name": "Varna", "score": 1, "max": 1, "status": "matched" },
      { "name": "Vashya", "score": 2, "max": 2, "status": "matched" }
    ],
    "verdict": "compatible",
    "notes": ["..."]
  }
}

Natal Prediction Topaz+

Returns deterministic natal interpretation generated from chart factors and a phrase-bank/rule system. It is not LLM output and should not be presented as a fixed prediction of future events.

Request Body (JSON)

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/predict/natal" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata","lang":"en"}'

Full Forecast Topaz+

Returns a deterministic multi-signal forecast that fuses the D1 and D9 charts, the active mahā/antar daśā, doshas, Sade Sati and gochar (transits) into per-domain scores with phrase-bank text. It is computed from chart factors and a rule system — not LLM output.

Request Body (JSON)

Example Request

curl -X POST "https://horoscope.devdarsha.com/v1/forecast/full" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata","as_of":"2026-07-03","lang":"en"}'

Health Check

Use this endpoint for uptime monitors and deployment smoke tests. No authentication required and no quota cost.

{ "ok": true, "service": "horoscope", "status": "healthy" }

Status

Status returns service availability and degraded-mode information for dashboards and support tooling. The public marketing status is Live.

{
  "data": {
    "service": "horoscope",
    "status": "operational",
    "degraded": false,
    "components": [
      { "name": "gateway", "status": "operational" },
      { "name": "horoscope-engine", "status": "operational" },
      { "name": "cache", "status": "operational" }
    ]
  },
  "meta": { "api_version": "v1" }
}

Feedback Endpoint

Submit feedback about the API. Does not require authentication.

Contact

Send a sales, partnership, or support enquiry. Mirrors the contact form on the website. No authentication required. Submissions are rate-limited per IP and per email.

Request Body (JSON)

Responds with 202 Accepted on success. Replies usually arrive within 1 business day at the email you supplied.

Billing & Webhooks

Most users will manage subscriptions, invoices, and payment methods from the Dashboard. The endpoints below let you do the same programmatically and let payment providers notify DevDarsha when something changes.

Operations

All operations except the webhook require an authenticated API key. An unknown product returns 400 invalid_product.

Webhook events

Configure the webhook in your Razorpay dashboard to point at /v1/billing/razorpay/webhook. DevDarsha verifies the X-Razorpay-Signature header before trusting the body. Events are at-least-once and handled idempotently. A Horoscope refund downgrades only the Horoscope entitlement.

Birth Input

Birth-based endpoints require date and time, plus location. The API accepts a trusted place lookup or explicit coordinates with an explicit timezone. Timezone is never guessed from bare coordinates in production integrations.

{ "date": "1990-08-15", "time": "10:30", "city": "Kolkata" }

{ "date": "1990-08-15", "time": "10:30", "lat": 22.5726, "lon": 88.3639, "tz": "Asia/Kolkata" }

Response Envelope

Successful responses use a standard JSON envelope. Clients should read from data and use meta for diagnostics, caching, and support.

Error Codes

Error responses always include a machine-readable error, human-readable message, and docs_url.

{
  "error": "plan_required",
  "message": "This Horoscope API endpoint requires a paid plan.",
  "docs_url": "https://platform.devdarsha.com/horoscope-documentation#errors"
}

Signs & Periods

For stable integrations, use Sanskrit rashi slugs. Display names can be translated in your UI.

Localization

Use lang for display text where the endpoint supports localized output. Numeric positions, dates, rashi IDs, and machine-readable keys remain stable across languages.

Calculation Conventions

• Vedic sidereal zodiac with Lahiri / Chitrapaksha ayanamsa.
• Whole-sign houses for chart house mapping.
• True nodes for Rahu/Ketu unless a future version explicitly documents otherwise.
• Divisional chart v1 scope is D1 and D9.
• Vimshottari Dasha is derived from the natal Moon nakshatra.
• Horoscope computation is deterministic and rule-based.
• Natal prediction text is deterministic phrase-bank/rule output, not LLM compute.

Versioning & Sunset Policy

The current Horoscope API version is v1. All routes are prefixed /v1/. We use URI versioning — breaking changes use a new prefix such as /v2/, never a header toggle. Legacy /v1/horoscope/* routes remain compatibility routes, not the preferred route for new integrations.

• Current: https://horoscope.devdarsha.com/v1/*.
• Legacy-compatible: https://panchang.devdarsha.com/v1/horoscope/*.
• Deprecation: Announce migration guidance before removing compatibility routes.
• Client rule: key application logic off stable fields, not prose text.

Rate Limits

Rate limits are enforced per API key and plan. Exact limits are displayed in the dashboard and echoed by rate-limit headers.

On 429, the response includes Retry-After. Do not retry immediately in a tight loop. To check live consumption from your app, call GET /v1/usage.

Response Headers

Horoscope Glossary

A quick reference for the Jyotish terms used throughout this API and its responses.