Каждый запрос к /api/v1/* требует API-ключ (префикс cal_). Ключи создаются и отзываются в настройках аккаунта. Максимум 3 активных ключа на пользователя.
Передай ключ одним из способов (лучше через заголовок):
Request
Authorization: Bearer cal_your_key_hereRequest
X-Api-Key: cal_your_key_hereRequest
GET https://dev.calendra.work/api/v1/countries/
Authorization: Bearer cal_your_key_hereКаждый успешный авторизованный запрос считается в месячную квоту (включая GET /me/). Сброс — 1-го числа каждого месяца по UTC. Заголовки ответа:
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 2026-08-01T00:00:00ZОшибки — JSON с полями error и message. Типичные статусы:
401 unauthorized
{
"error": "unauthorized",
"message": "Valid API key required. Use Authorization: Bearer cal_… or X-Api-Key."
}429 rate_limit
{
"error": "rate_limit",
"message": "Monthly API request limit reached.",
"usage": {
"plan": "free",
"used": 5,
"limit": 5,
"remaining": 0,
"ym": "2026-07",
"reset_at": "2026-08-01T00:00:00Z"
}
}422 validation
{
"error": "validation",
"message": "Query param country is required (ISO alpha-2 or slug)."
}404 not_found
{
"error": "not_found",
"message": "Country not found."
}
GET
/api/v1/me/
Validates the key and returns current plan usage. Counts as one request.
Request
GET https://dev.calendra.work/api/v1/me/
Authorization: Bearer cal_••••••••Response 200
{
"ok": true,
"plan": "free",
"usage": {
"plan": "free",
"used": 1,
"limit": 5,
"remaining": 4,
"ym": "2026-07",
"reset_at": "2026-08-01T00:00:00Z"
}
}
GET
/api/v1/countries/
All countries with calendar data. Names localized via lang.
| Параметр | Обязательность | Описание |
|---|---|---|
lang |
опциональный | Language code (default en). Falls back to en if inactive. |
Request
GET https://dev.calendra.work/api/v1/countries/?lang=en
Authorization: Bearer cal_••••••••Response 200
{
"lang": "en",
"items": [
{
"code": "DE",
"slug": "germany",
"name": "Germany",
"name_en": "Germany"
}
],
"usage": {
"plan": "free",
"used": 2,
"limit": 5,
"remaining": 3,
"ym": "2026-07",
"reset_at": "2026-08-01T00:00:00Z"
}
}
GET
/api/v1/languages/
Active UI/content languages available for localization.
Request
GET https://dev.calendra.work/api/v1/languages/
X-Api-Key: cal_••••••••Response 200
{
"items": [
{
"code": "en",
"name": "English",
"name_en": "English"
},
{
"code": "de",
"name": "Deutsch",
"name_en": "German"
}
],
"usage": { "plan": "free", "used": 3, "limit": 5, "remaining": 2, "ym": "2026-07", "reset_at": "2026-08-01T00:00:00Z" }
}
GET
/api/v1/regions/
Subdivisions (states, länder, cantons, …) for a country.
| Параметр | Обязательность | Описание |
|---|---|---|
country |
обязательный | ISO alpha-2 (DE) or country slug (germany). |
lang |
опциональный | Language code (default en). |
Request
GET https://dev.calendra.work/api/v1/regions/?country=DE&lang=en
Authorization: Bearer cal_••••••••Response 200
{
"country": {
"code": "DE",
"slug": "germany",
"name": "Germany"
},
"lang": "en",
"items": [
{
"slug": "bavaria",
"code": "BY",
"name": "Bavaria",
"name_en": "Bavaria"
}
],
"usage": { "plan": "free", "used": 4, "limit": 5, "remaining": 1, "ym": "2026-07", "reset_at": "2026-08-01T00:00:00Z" }
}
GET
/api/v1/holidays/
Public holidays for a country (and optional region) in a given year.
| Параметр | Обязательность | Описание |
|---|---|---|
country |
обязательный | ISO alpha-2 or country slug. |
year |
опциональный | Calendar year (default current). Range 1990–2075. |
lang |
опциональный | Language code (default en). |
region |
опциональный | Region slug (e.g. bavaria). |
Request
GET https://dev.calendra.work/api/v1/holidays/?country=DE&year=2026&lang=en®ion=bavaria
Authorization: Bearer cal_••••••••Response 200
{
"country": {
"code": "DE",
"slug": "germany",
"name": "Germany"
},
"region": {
"slug": "bavaria",
"name": "Bavaria",
"code": "BY"
},
"year": 2026,
"lang": "en",
"holidays": [
{
"date": "2026-01-01",
"name": "New Year's Day",
"local_name": null,
"type": "national",
"type_label": "National holiday",
"kind_id": 123,
"kind_slug": "new-year"
}
],
"usage": { "plan": "free", "used": 5, "limit": 5, "remaining": 0, "ym": "2026-07", "reset_at": "2026-08-01T00:00:00Z" }
}
GET
/api/v1/translations/
Resolve a holiday kind name in a target language. Use kind_id, or kind_slug + country.
| Параметр | Обязательность | Описание |
|---|---|---|
lang |
обязательный | Target language (must be active). |
kind_id |
опциональный | Holiday kind id from /holidays/. |
kind_slug |
опциональный | Holiday kind slug (requires country). |
country |
опциональный | Required with kind_slug — ISO alpha-2 or slug. |
Request
GET https://dev.calendra.work/api/v1/translations/?kind_slug=new-year&country=DE&lang=de
Authorization: Bearer cal_••••••••Response 200
{
"kind_id": 123,
"kind_slug": "new-year",
"lang": "de",
"name": "Neujahr",
"name_en": "New Year's Day",
"translated": true,
"usage": { "plan": "starter", "used": 42, "limit": 10000, "remaining": 9958, "ym": "2026-07", "reset_at": "2026-08-01T00:00:00Z" }
}