{
  "openapi": "3.0.0",
  "info": {
    "version": "2.0.0",
    "title": "Mahabharat API",
    "description": "## Knowledge graph API for Mahabharat\nThis API returns information about people, events, and journeys.",
    "contact": {
      "email": "ab.techwriter@gmail.com"
    },
    "license": {
      "name": "CC BY-NC 4.0",
      "url": "https://creativecommons.org/licenses/by-nc/4.0/"
    }
  },
  "externalDocs": {
    "description": "Indica APIs home",
    "url": "https://aninditabasu.github.io/indica/"
  },
  "servers": [
    {
      "url": "https://indica-1hwj.onrender.com/mb/v2",
      "description": "Mahabharat API"
    }
  ],
  "paths": {
    "/persons": {
      "get": {
        "summary": "List all persons",
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["basic", "details"],
              "default": "basic"
            }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "default": "false"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of persons",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPersons"
                }
              }
            }
          }
        }
      }
    },

    "/persons/names": {
      "get": {
        "summary": "List all person names",
        "responses": {
          "200": {
            "description": "Person names"
          }
        }
      }
    },

    "/persons/{name}": {
      "get": {
        "summary": "Get person by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["basic", "details"],
              "default": "basic"
            }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Person object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/persons/{name}/armour": {
      "get": {
        "summary": "Get person armour",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Armour info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Armour"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/persons/{name}/journeys": {
      "get": {
        "summary": "Get journeys of a person",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated journeys",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedJourneys"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/explore/{name}": {
      "get": {
        "summary": "Explore person",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Explore response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExplorePersonResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/weapons": {
      "get": {
        "summary": "List all weapons",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated weapons",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedWeapons"
                }
              }
            }
          }
        }
      }
    },

    "/weapons/names": {
      "get": {
        "summary": "List all weapon names",
        "responses": {
          "200": { "description": "Weapon names" }
        }
      }
    },

    "/weapons/{name}": {
      "get": {
        "summary": "Get weapon by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Weapon object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Weapon"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/weapons/{name}/owners": {
      "get": {
        "summary": "Get owners of a weapon",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated owners",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedStringList"
                }
              }
            }
          }
        }
      }
    },

    "/events": {
      "get": {
        "summary": "List all events",
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["basic", "details"],
              "default": "basic"
            }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedEvents"
                }
              }
            }
          }
        }
      }
    },

    "/events/names": {
      "get": {
        "summary": "List event names",
        "responses": {
          "200": {
            "description": "Event names"
          }
        }
      }
    },

    "/events/{name}": {
      "get": {
        "summary": "Get event by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["basic", "details"]
            }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Event object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/clans": {
      "get": {
        "summary": "List all clans",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated clans",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedClans"
                }
              }
            }
          }
        }
      }
    },

    "/clans/names": {
      "get": {
        "summary": "List clan names",
        "responses": {
          "200": {
            "description": "Clan names"
          }
        }
      }
    },

    "/clans/{name}": {
      "get": {
        "summary": "Get clan by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Clan object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Clan"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/journeys": {
      "get": {
        "summary": "List all journeys",
        "parameters": [
          {
            "name": "person",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "place",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated journeys",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedJourneys"
                }
              }
            }
          }
        }
      }
    },

    "/journeys/names": {
      "get": {
        "summary": "List journey names",
        "responses": {
          "200": {
            "description": "Journey names"
          }
        }
      }
    },

    "/journeys/{name}": {
      "get": {
        "summary": "Get journey by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "expand",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["true", "false"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Journey object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Journey"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },

    "/places": {
      "get": {
        "summary": "List all places",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated places",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPlaces"
                }
              }
            }
          }
        }
      }
    },

    "/places/names": {
      "get": {
        "summary": "List place names",
        "responses": {
          "200": {
            "description": "Place names"
          }
        }
      }
    },

    "/places/{name}": {
      "get": {
        "summary": "Get place by name",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Place object",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Place"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },

  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },

    "schemas": {
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "total": { "type": "integer" },
          "pages": { "type": "integer" },
          "hasNext": { "type": "boolean" },
          "hasPrev": { "type": "boolean" }
        }
      },

      "PaginatedPersons": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Person" }
          }
        }
      },

      "PaginatedWeapons": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Weapon" }
          }
        }
      },

      "PaginatedEvents": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Event" }
          }
        }
      },

      "PaginatedJourneys": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Journey" }
          }
        }
      },

      "PaginatedClans": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Clan" }
          }
        }
      },

      "PaginatedPlaces": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Place" }
          }
        }
      },

      "PaginatedStringList": {
        "type": "object",
        "properties": {
          "meta": { "$ref": "#/components/schemas/PaginationMeta" },
          "data": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },

      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      },

      "Armour": {
        "type": "object",
        "properties": {
          "weapons": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Weapon" }
          },
          "panoplies": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Panoply" }
          }
        }
      },

      "ExplorePersonResponse": {
        "type": "object",
        "properties": {
          "person": { "type": "string" },
          "clan": { "$ref": "#/components/schemas/Clan" },
          "armour": { "$ref": "#/components/schemas/Armour" },
          "events": { "$ref": "#/components/schemas/PaginatedEvents" },
          "journeys": { "$ref": "#/components/schemas/PaginatedJourneys" },
          "places": {
            "type": "array",
            "items": { "type": "string" }
          },
          "death": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Death" }
          }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "string" } },
          "shortDesc": { "type": "string" },
          "gender": { "type": "string" },
          "clan": { "type": "string" },
          "fatherReal": { "type": "string" },
          "motherReal": { "type": "string" },
          "fatherAdoptive": { "type": "string" },
          "motherAdoptive": { "type": "string" },
          "childrenReal": { "type": "array", "items": { "type": "string" } },
          "childrenAdopted": { "type": "array", "items": { "type": "string" } },
          "spouses": { "type": "array", "items": { "type": "string" } },
          "foughtWar": {"type": "string", "nullable": true},
          "aliveAtWarStart": {"type": "string", "nullable": true},
          "aliveAtWarEnd": {"type": "string", "nullable": true},
          "weapons": { "type": "array", "items": { "type": "string" } },
          "longDesc": { "type": "string" }
        }
      },
      "Weapon": {
        "type": "object",
        "properties": {
          "weaponName": { "type": "string" },
          "weaponDescription": { "type": "string" },
          "weaponAntidote": {
            "type": "array",
            "items": { "type": "string" }
          },
          "weaponHP": { "type": "string" }
        }
      },
      "Clan": {
        "type": "object",
        "properties": {
          "clanName": { "type": "string" },
          "clanAliases": {
            "type": "array",
            "items": { "type": "string" }
          },
          "clanHome": {
            "type": "array",
            "items": { "type": "string" }
          },
          "clanInfo": { "type": "string" }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "eventName": { "type": "string" },
          "eventPrecededBy": {
            "type": "array",
            "items": { "type": "string" }
          },
          "eventFollowedBy": {
            "type": "array",
            "items": { "type": "string" }
          },
          "eventLocation": {
            "type": "array",
            "items": { "type": "string" }
          },
          "eventDescription": { "type": "string" },
          "eventPersons": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "Journey": {
        "type": "object",
        "properties": {
          "journeyName": { "type": "string" },
          "journeyRoute": {
            "type": "array",
            "items": { "type": "string" }
          },
          "journeyPersons": {
            "type": "array",
            "items": { "type": "string" }
          },
          "journeyEvent": { "type": "string" }
        }
      },
      "Panoply": {
        "type": "object",
        "properties": {
          "person": { "type": "string" },
          "chariotBanner": { "type": "string" },
          "bow": { "type": "string" },
          "sword": { "type": "string" },
          "conch": { "type": "string" },
          "chariotHorses": { "type": "string" }
        }
      },
      "Place": {
        "type": "object",
        "properties": {
          "placeNameEpic": { "type": "string" },
          "placeAliasEpic": {
            "type": "array",
            "items": { "type": "string" }
          },
          "placeNameHistorical": {
            "type": "array",
            "items": { "type": "string" }
          },
          "placeNameCurrent": {
            "type": "array",
            "items": { "type": "string" }
          },
          "placeCountryCurrent": {
            "type": "array",
            "items": { "type": "string" }
          },
          "placeType": { "type": "string" },
          "placeInfo": { "type": "string" }
        }
      },
      "Death": {
        "type": "object",
        "properties": {
          "personName": { "type": "string" },
          "personKilledWhoAll": {
            "type": "array",
            "items": { "type": "string" }
          },
          "personKilledByWhom": {
            "type": "array",
            "items": { "type": "string" }
          },
          "personKilledHow": { "type": "string" },
          "personKilledAtEvent": {"type": "string", "nullable": true}
        }
      }
    }
  }
}