Holidays API

Holidays Endpoints

`GET /api/holidays`

Get public holidays for a given year, filtered by Australian state.

Permission: view:holidays

Query Parameters:

Parameter	Type	Default	Description
`year`	number	Current year	Year to fetch holidays for
`state`	string	Resolved	AU state code (e.g. `AU-VIC`). If omitted, resolved from user preference → org default

Response:

{
  "holidays": [
    {
      "id": "uuid",
      "date": "2026-01-01",
      "local_name": "New Year's Day",
      "name": "New Year's Day",
      "country_code": "AU",
      "is_global": 1,
      "counties": null,
      "year": 2026,
      "fetched_at": "2026-03-01T10:00:00"
    },
    {
      "id": "uuid",
      "date": "2026-03-09",
      "local_name": "Labour Day",
      "name": "Labour Day",
      "country_code": "AU",
      "is_global": 0,
      "counties": "[\"AU-VIC\"]",
      "year": 2026,
      "fetched_at": "2026-03-01T10:00:00"
    }
  ],
  "year": 2026,
  "state": "AU-VIC"
}

Holidays are cached in D1 for 24 hours. On cache miss, fetches from the Nager.Date API. Falls back to stale cache if the API is unavailable.

`GET /api/holidays/state`

Get the effective holiday state for the current user.

Permission: view:holidays

Response:

{
  "user_state": null,
  "org_state": "AU-VIC",
  "effective_state": "AU-VIC"
}

Organisation Settings Endpoints

`GET /api/admin/settings`

Get all organisation-level settings.

Permission: Executive only

Response:

{
  "settings": {
    "timezone": "Australia/Melbourne",
    "holiday_state": "AU-VIC"
  }
}

`PUT /api/admin/settings`

Update organisation settings. Only allowed keys are accepted.

Permission: Executive only

Request Body:

{
  "timezone": "Australia/Sydney",
  "holiday_state": "AU-NSW"
}

Allowed Keys: timezone, holiday_state

Response: Same format as GET.

User Preferences

User-level overrides for timezone and holiday state are managed through the existing users API:

`GET /api/users/me`

Now includes preferences and org_defaults in the response:

{
  "user": { ... },
  "permissions": { ... },
  "preferences": {
    "timezone": null,
    "holiday_state": null
  },
  "org_defaults": {
    "timezone": "Australia/Melbourne",
    "holiday_state": "AU-VIC"
  }
}

`PUT /api/users/me`

Now accepts timezone and holiday_state fields to set user preferences:

{
  "timezone": "Australia/Sydney",
  "holiday_state": "AU-NSW"
}

Send an empty string to clear an override and use the org default.