api documentation

home | api | admin

overview

the indian history database provides api endpoints for accessing historical data programmatically. all endpoints return json format responses.

base url

http://indianhistorydb.local/api/v1/

endpoints

get all empires

get /empires

returns list of all empires in database

field type description
id integer unique identifier
name string empire name
period string dates of reign
founder string founder name
capital string capital city

get empire by id

get /empires/[id]

returns single empire record with detailed information

get all figures

get /figures

returns list of all historical figures

field type description
id integer unique identifier
name string figure name
period string time period
role string role or title
significance string historical significance

get all sites

get /sites

returns list of all archaeological sites

search

get /search?q=[query]

search across all content types. query parameter required. minimum 2 characters.

response format

success response

{ "status": "success", "data": [ { "id": 1, "name": "mauryan empire", ... } ], "count": 1 }

error response

{ "status": "error", "message": "not found", "code": 404 }

status codes

code meaning
200 success - request completed
400 bad request - invalid parameters
404 not found - resource does not exist
500 server error - internal error

example requests

get all empires

curl http://indianhistorydb.local/api/v1/empires

get specific empire

curl http://indianhistorydb.local/api/v1/empires/1

search

curl http://indianhistorydb.local/api/v1/search?q=ashoka

rate limiting

api requests are limited to 100 requests per minute per ip address. exceeding this limit will result in 429 (too many requests) response.

authentication

currently, the api does not require authentication for read-only endpoints. write operations (post, put, delete) require api key.

cors policy

cross-origin requests are allowed from specified domains. contact administrator for cors whitelist additions.