Overview

Numerology API returns complete numerology data — core name-and-date profiles, name-only numbers, and personal cycle numbers — for any name and date of birth. It computes both the Western letter systems (Pythagorean and Chaldean) and the Ank Jyotish date-number layer (Moolank, Bhagyank, and ruling planet) from a single request.

Rule of thumb: compute endpoints under /v1/numerology/... use POST. Public read-only endpoints use GET — including 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.

Numerology output is computed and reproducible for the same input — there is no LLM in the calculation path. The engine never assumes a system: you request Pythagorean, Chaldean, or both, and the Ank Jyotish date layer is derived alongside.

New to numerology terminology? Jump to the Glossary for plain-language definitions of every term used in API responses — moolank, bhagyank, life path, expression, soul urge, and more.

curl -X POST "https://panchang.devdarsha.com/v1/numerology/core" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Aarav Sharma","date_of_birth":"1990-07-15","systems":["pythagorean","chaldean"]}'

// Use header auth - never put api_key in client-side code
const response = await fetch("https://panchang.devdarsha.com/v1/numerology/core", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    full_name: "Aarav Sharma",
    date_of_birth: "1990-07-15",
    systems: ["pythagorean", "chaldean"]
  })
});

const data = await response.json();
console.log(data.data.results.pythagorean.expression_number); // 4
console.log(data.data.date_numbers.life_path_number);         // 5
console.log(data.data.ank_jyotish.moolank.number);            // 6

import requests

response = requests.post(
    "https://panchang.devdarsha.com/v1/numerology/core",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"full_name": "Aarav Sharma", "date_of_birth": "1990-07-15",
          "systems": ["pythagorean", "chaldean"]}
)

data = response.json()
print(data["data"]["results"]["pythagorean"]["expression_number"])  # 4
print(data["data"]["date_numbers"]["life_path_number"])             # 5
print(data["data"]["ank_jyotish"]["moolank"]["number"])            # 6

{
  "data": {
    "input":        { "full_name": "Aarav Sharma", "date_of_birth": "1990-07-15" },
    "date_numbers": { "moolank": 6, "bhagyank": 5, "life_path_number": 5 },
    "results": {
      "pythagorean": { "name_number": 4, "expression_number": 4, "soul_urge_number": 5 },
      "chaldean":    { "name_number": 9, "expression_number": 9, "soul_urge_number": 5 }
    },
    "ank_jyotish":  { "moolank": { "number": 6, "planet": { "english_name": "Venus" } } }
  },
  "meta": {
    "api_version":         "v1",
    "service":             "numerology",
    "data_source":         "computed",
    "calculation_systems": ["pythagorean", "chaldean"],
    "quota_cost_units":    2
  }
}

{
    "data": {
        "input": {
            "full_name": "Aarav Sharma",
            "date_of_birth": "1990-07-15",
            "systems": ["pythagorean", "chaldean"]
        },
        "date_numbers": {
            "birthday_number": 6,
            "birth_number": 6,
            "moolank": 6,
            "life_path_number": 5,
            "bhagyank": 5,
            "attitude_number": 22
        },
        "results": {
            "pythagorean": {
                "system": "pythagorean",
                "normalized_name": "AARAV SHARMA",
                "name_number": 4,
                "expression_number": 4,
                "soul_urge_number": 5,
                "personality_number": 8,
                "maturity_number": 9
            },
            "chaldean": {
                "system": "chaldean",
                "normalized_name": "AARAV SHARMA",
                "name_number": 9,
                "expression_number": 9,
                "soul_urge_number": 5,
                "personality_number": 22,
                "maturity_number": 5
            }
        },
        "ank_jyotish": {
            "system": "ank_jyotish",
            "moolank": { "number": 6, "planet": { "english_name": "Venus" } },
            "bhagyank": { "number": 5 }
        }
    },
    "meta": {
        "api_version": "v1",
        "service": "numerology",
        "data_source": "computed",
        "calculation_systems": ["pythagorean", "chaldean"],
        "life_path_method": "full_sum",
        "preserve_masters": true,
        "master_numbers": [11, 22, 33],
        "quota_cost_units": 2
    },
    "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://panchang.devdarsha.com/v1/numerology/core
x-api-key: YOUR_API_KEY

Auth failure reference

Base URL

Numerology API is served through the DevDarsha API gateway. Send requests to the /v1/numerology/* path on the gateway host.

https://panchang.devdarsha.com/v1/numerology

Numerology endpoints are namespaced under /v1/numerology/*. All eight endpoints — /core, /name, /cycles, /compatibility, /lo-shu, /report, /name-correction, and /bulk — are live and documented below.

Quick Start

For all /v1/numerology/... endpoints, send a JSON body with your request fields and authenticate using x-api-key. Start with the Core Profile endpoint because it verifies name normalization, date parsing, system selection, and the response envelope in one call.

curl -X POST "https://panchang.devdarsha.com/v1/numerology/core" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Aarav Sharma","date_of_birth":"1990-07-15","systems":["pythagorean","chaldean"]}'

curl -X POST "https://panchang.devdarsha.com/v1/numerology/name" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Aarav Sharma","systems":["pythagorean","chaldean"]}'

Plans & Feature Gates

Numerology API uses a graduated public plan ladder: free, starter, plus, pro, and scale. Each tier unlocks more features. Plan entitlements are product-isolated: a paid plan in Panchang or Horoscope grants no Numerology access. Full pricing lives on pricing.

Access gates

• Free: /core only (Pythagorean basic + Ank Jyotish date numbers). For evaluation, not production.
• Starter and above: adds /name, /cycles, /report, and full Chaldean output.
• Plus: adds /lo-shu.
• Pro: adds /compatibility and /name-correction.
• Scale: adds /bulk (batch processing).

Endpoint access

Quota cost per call

Each request charges 1 quota unit per system computed:

• A dual-system /core or /name request charges 2 requests.
• The actual charge is echoed in both X-Quota-Cost and meta.quota_cost_units.
• GET /health and GET /status have no quota cost.

If you call an endpoint or feature 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://panchang.devdarsha.com/v1/usage" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "data": {
    "plan": "starter",
    "period_start": "2026-07-01T00:00:00Z",
    "period_end":   "2026-08-01T00:00:00Z",
    "calls_used":      320,
    "calls_included":  5000,
    "calls_remaining": 4680
  },
  "meta": { "version": "v1", "computed_at": "2026-07-02T10:00:00Z" }
}

Core Profile

Returns the full core numerology profile: per-system name numbers under data.results, the shared date layer under data.date_numbers, and the Ank Jyotish layer under data.ank_jyotish. This is the recommended first integration test. Not familiar with these terms? See the Glossary.

Request Body (JSON)

Uses the common Systems & Input fields. Add include_calculations: true for a step-by-step trace under data.details.

Response Fields

Name Numbers Starter+

Returns name-only numerology numbers without the date layer. For historical compatibility this endpoint returns its per-system output under data.systems (not data.results).

Example Request

{
  "full_name": "Aarav Sharma",
  "systems": ["pythagorean", "chaldean"]
}

Personal Cycles Starter+

Returns personal year, month, and day cycle numbers as flat data.personal_*_number fields for a given date of birth and reference date.

Example Request

{
  "date_of_birth": "1990-07-15",
  "date": "2026-07-02"
}

Response Fields

Compatibility Pro

Returns a deterministic numerology compatibility read between two profiles. Output is computed from name and date numbers with pair-level evidence — it is not LLM output. Requires the Pro plan or higher; under-tier keys receive 402 upgrade_required.

Example Request

{
  "person_a": { "full_name": "Aarav Sharma", "date_of_birth": "1990-08-15" },
  "person_b": { "full_name": "Diya Kapoor", "date_of_birth": "1992-11-30" },
  "systems": ["pythagorean", "chaldean"],
  "lang": "en"
}

Response Fields

Extended Endpoints

These endpoints are live and plan-gated. Each returns the standard { data, meta, dev_notes } envelope and is fully deterministic (no LLM). Requests below the required plan return 403 plan_required.

Health Check

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

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

Status

Status returns service availability and degraded-mode information for dashboards and support tooling. No authentication required.

{
  "data": {
    "service": "numerology",
    "status": "operational",
    "degraded": false
  },
  "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 Numerology refund downgrades only the Numerology entitlement.

Systems & Input

Numerology API never assumes a system. You must pass either system (a single value) or systems (an array). Supported systems are pythagorean and chaldean.

Response Envelope

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

Error Codes

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

{
  "error": "invalid_system",
  "message": "Provide system or systems (pythagorean or chaldean).",
  "docs_url": "https://platform.devdarsha.com/numerology-documentation#errors"
}

Master Numbers

The Numerology API recognizes the master numbers 11, 22, and 33. Handling differs by endpoint so results match the convention developers expect for each calculation:

• Core and Name: master numbers are preserved by default in name and birth calculations.
• Cycles: master numbers are reduced by default. Pass cycle_preserve_masters: true to keep them.
• meta.preserve_masters reports which behavior applied to the response.

Calculation Conventions

• Two Western letter systems: Pythagorean and Chaldean. The system is never assumed — you must request it.
• The Ank Jyotish layer derives Moolank and Bhagyank with a ruling planet.
• Life path uses full-sum reduction (life_path_method: "full_sum").
• Master numbers 11 / 22 / 33 are preserved in core/name and reduced in cycles by default.
• v1 name input is Latin/romanized only.
• Numerology computation is deterministic and rule-based — there is no LLM in the calculation path.

Versioning & Compatibility

The current Numerology API version is v1. All routes are prefixed /v1/. We use URI versioning — breaking changes will use a new prefix such as /v2/, never a header toggle.

• Current: https://panchang.devdarsha.com/v1/numerology/*.
• Stable shapes: the per-route response paths (data.results, data.systems, flat cycle fields) are part of the v1 contract.
• 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 shown 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

Numerology Glossary

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