Auth · API docs | Calendra

Authentication

Every /api/v1/* request requires an API key (prefix cal_). Create and revoke keys in account settings. Max 3 active keys per user.

Pass the key in one of these ways (prefer a header):

Request

Authorization: Bearer cal_your_key_here

Request

X-Api-Key: cal_your_key_here

Request

GET https://dev.calendra.work/api/v1/countries/
Authorization: Bearer cal_your_key_here

Rate limits

Each successful authenticated request counts toward your monthly quota (including GET /me/). Limits reset on the 1st of each UTC month. Response headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 2026-08-01T00:00:00Z

Errors

Errors are JSON objects with error and message. Common statuses:

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."
}

Key health & quota

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"
  }
}

List countries

GET /api/v1/countries/

All countries with calendar data. Names localized via lang.

Query parameters

Param	Required	Description
`lang`	optional	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"
  }
}

List languages

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" }
}

List regions

GET /api/v1/regions/

Subdivisions (states, länder, cantons, …) for a country.

Query parameters

Param	Required	Description
`country`	required	ISO alpha-2 (DE) or country slug (germany).
`lang`	optional	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" }
}

List holidays

GET /api/v1/holidays/

Public holidays for a country (and optional region) in a given year.

Query parameters

Param	Required	Description
`country`	required	ISO alpha-2 or country slug.
`year`	optional	Calendar year (default current). Range 1990–2075.
`lang`	optional	Language code (default en).
`region`	optional	Region slug (e.g. bavaria).

Request

GET https://dev.calendra.work/api/v1/holidays/?country=DE&year=2026&lang=en&region=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" }
}

Holiday name translation

GET /api/v1/translations/

Resolve a holiday kind name in a target language. Use kind_id, or kind_slug + country.

Query parameters

Param	Required	Description
`lang`	required	Target language (must be active).
`kind_id`	optional	Holiday kind id from /holidays/.
`kind_slug`	optional	Holiday kind slug (requires country).
`country`	optional	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" }
}