API Quick Reference

Base path: /api/v1/. The full, generated reference is Swagger UI at /api/v1/docs/ and the OpenAPI file backend/schema.yml. Contracts and limits: docs/design/m1-api.md.

Authentication

Anonymous calls work, limited to 60 a minute per IP. With an API key the plan's limits apply:

curl -H "Authorization: Bearer hops_<prefix>_<secret>" \
  "https://<your-host>/api/v1/business-days/check/?country=PK&date=2027-03-23"

Plan	Per key	Per month	Keys
Free	120 / minute	10,000	3
Pro	1,200 / minute	1,000,000	20

Throttled calls get 429 with a Retry-After header.

Endpoints

Endpoint	Answers
GET /countries/	every supported country with its regions, languages, categories and weekend
GET /holidays/?country=PK&year=2027	the holidays in a year
GET /business-days/check/?country=SA&date=2027-04-02	is this a working day, and why
GET /business-days/add/?country=PK&date=2027-03-20&days=5	the date N working days later (or earlier, with negative days)
GET /business-days/between/?country=AE&start=2027-01-01&end=2027-01-31	how many working days, both ends included
GET /business-days/range/?country=PK&start=2027-03-01&end=2027-03-31	a check result for every day in the range

Common parameters

Parameter	Rule
country	ISO 3166-1 alpha-2 code, case-insensitive
subdiv	optional region code, from /countries/
language	optional; defaults to the country's own language
categories	optional, comma-separated; default public
calendar	a company calendar's UUID, instead of country (not with subdiv, language or categories); private calendars need a key or session of that organization, otherwise 404

Limits: years 1970 to 2100, days from -1000 to 1000, between spans up to 3660 days, range up to 366 days.

The check answer

{"date": "2027-04-02", "is_business_day": false, "reason": "weekend", "holidays": [], "half_day": false}

reason is one of working_day, weekend, holiday, or weekend_workday (a weekend day the country moved to a working day). With calendar= it can also be closure, half_day (a working day with half_day: true) or custom_working_day.

Errors

400 with field errors, for example {"days": ["Ensure this value is less than or equal to 1000."]}. Error messages follow the Accept-Language header (en, ur, ar).

SDKs

Python and TypeScript clients are generated from the schema in sdks/. They are not published to PyPI or npm yet; install them from the repository.