Reference

API documentation

All endpoints are static JSON files. No authentication, no rate limiting, no SDK required. Fetch them with anything that speaks HTTP.

Endpoints

Path	Returns	Sample
/dynasties/<SLUG>.json	One dynasty record (e.g. mauryan, gupta, mughal).	/dynasties/mauryan.json
/index.json	Compact array of every dynasty slug. Use for autocomplete.	/index.json
/all.json	Every full record in one file.	/all.json
/timeline.json	All records sorted by period.start ascending — for timeline viz.	/timeline.json
/eras.json	Records bucketed into eras (ancient, classical, medieval, sultanate, mughal, maratha-sikh, colonial).	/eras.json

Base URL: https://dynasties.oriz.in · also at https://cdn.jsdelivr.net/gh/oriz-org/dynasties-api@main

Record schema

Each /dynasties/<SLUG>.json file returns one record:

type Dynasty = {
  slug:        string;               // e.g. "mauryan", "mughal"
  name:        string;               // canonical name
  alt_names:   string[];             // alternate spellings
  period: {
    start:     number;               // year, negative = BCE
    end:       number;               // year, negative = BCE
    start_era: "BCE" | "CE";         // explicit, for human readability
    end_era:   "BCE" | "CE";
  };
  region:      string;               // geographic extent
  capitals:    string[];             // capital(s) over the dynasty's life
  rulers:      Ruler[];              // chronological list of monarchs
  religion:    string;               // dominant / patronised religion(s)
  predecessor: string | null;        // slug of preceding dynasty
  successor:   string | null;        // slug of succeeding dynasty
  notable_achievements: string[];    // bullet-list highlights
  notes:       string;               // free-text annotation
};

type Ruler = {
  name:        string;
  reign_start: number | null;        // year, negative = BCE
  reign_end:   number | null;
  notes:       string;               // may be empty
};

BCE / CE convention

Years in the schema are integers. Negative values are BCE, positive values are CE. The explicit start_era and end_era strings make the convention readable without remembering the sign rule.

Example: the Mauryan Empire lasted from 322 BCE to 185 BCE, which encodes as:

{ "start": -322, "end": -185, "start_era": "BCE", "end_era": "BCE" }

Note: there is no year 0 in the proleptic conventions, but for arithmetic simplicity this dataset treats the BCE/CE boundary as a single tick — sorting and span calculations work as expected.

Sample — Mauryan Empire

{
  "slug": "mauryan",
  "name": "Mauryan Empire",
  "alt_names": ["Maurya Dynasty"],
  "period": { "start": -322, "end": -185, "start_era": "BCE", "end_era": "BCE" },
  "region": "South Asia (most of subcontinent)",
  "capitals": ["Pataliputra"],
  "rulers": [
    { "name": "Chandragupta Maurya", "reign_start": -322, "reign_end": -298, "notes": "Founder" },
    { "name": "Bindusara",           "reign_start": -297, "reign_end": -273, "notes": "" },
    { "name": "Ashoka the Great",    "reign_start": -268, "reign_end": -232, "notes": "Promoted Buddhism" }
  ],
  "religion": "Hinduism, Buddhism, Jainism (pluralistic)",
  "predecessor": "nanda",
  "successor": "shunga",
  "notable_achievements": ["Unified most of the Indian subcontinent", "Ashoka's dhamma edicts"],
  "notes": "First pan-Indian empire."
}

Errors

The only possible error is 404 — unknown slug. There is no authentication, no rate limit, and no quota, so 401/403/429 cannot occur. CORS is wide open on both origins.

License

Code (scripts/, build tooling): MIT
Data (dynasties/, *.json): CC BY-SA 4.0 (Wikipedia)

Attribution: "Source: Wikipedia — List of Indian monarchs, List of Indian dynasties, and per-dynasty articles."