# Calendar

Bitrix24 account calendar settings — working hours, weekend days of the week, holidays and working Saturdays. The same values the Bitrix24 interface uses to mark non-working days.

**Scope:** `calendar` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Quick start](#quick-start) | [Full example](#full-example-is-this-a-working-day) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

Calendar events and sections are separate entities with their own operation sets: [Calendar events](/docs/entities/calendar-events) and [Calendar sections](/docs/entities/calendar-sections). This page covers the settings shared across the entire Bitrix24 account.

## Quick start

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/calendar/settings
```

The response contains the working-day boundaries, the weekend days of the week and the holiday lists:

```json
{
  "success": true,
  "data": {
    "workTimeStart": "10",
    "workTimeEnd": "22",
    "weekHolidays": ["SA", "SU"],
    "weekStart": "MO",
    "yearHolidays": "1.01,25.12",
    "yearWorkdays": "20.12"
  }
}
```

The main fields are shown. For the full list, see [Calendar settings](/docs/calendar/settings).

## Full example: is this a working day

The most common reason to read the settings is to decide whether a specific day is a working day in the Bitrix24 account. The answer combines three rules: the day of the week, the holiday list and the list of working weekend days.

```javascript
const VIBE_URL = 'https://vibecode.bitrix24.com'
const VIBE_API_KEY = process.env.VIBE_API_KEY

// Step 1. Read the portal settings.
const res = await fetch(`${VIBE_URL}/v1/calendar/settings`, {
  headers: { 'X-Api-Key': VIBE_API_KEY },
})
if (!res.ok) throw new Error(`Settings unavailable: ${res.status}`)
const { data, meta } = await res.json()

// Step 2. Make sure the portal returned the full set and not the default values.
const partial = meta?.warnings?.some((w) => w.code === 'calendar_settings_partial')
if (partial) {
  throw new Error('The key does not belong to a portal employee — the settings cannot be read')
}

// Step 3. Parse the lists. A day arrives both as `1.01` and as `01.01`: the format
// follows the account language, so normalise the list and the lookup key alike.
const dayKey = (day, month) => `${Number(day)}.${Number(month)}`
const parseDays = (value) => new Set(
  value
    ? value.split(',').map((d) => {
        const [day, month] = d.trim().split('.')
        return dayKey(day, month)
      })
    : [],
)
const holidays = parseDays(data.yearHolidays)
const workdays = parseDays(data.yearWorkdays)
const weekends = new Set(data.weekHolidays)

const WEEK_CODES = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']

function isWorkingDay(date) {
  const key = dayKey(date.getDate(), date.getMonth() + 1)
  // A working weekend day overrides both a weekend day of the week and a holiday.
  if (workdays.has(key)) return true
  if (holidays.has(key)) return false
  return !weekends.has(WEEK_CODES[date.getDay()])
}

// Step 4. Apply to a date range.
const start = new Date('2026-01-01')
for (let i = 0; i < 10; i += 1) {
  const day = new Date(start)
  day.setDate(start.getDate() + i)
  console.log(day.toISOString().slice(0, 10), isWorkingDay(day) ? 'working' : 'non-working')
}

console.log('Portal working hours:', data.workTimeStart, '—', data.workTimeEnd)
```

An empty string in `yearHolidays` means the holiday list is not filled in for the Bitrix24 account. In that case, non-working days are determined by the weekend days of the week alone.

A non-empty value, on the other hand, does not mean an administrator filled the list in: the setting has a localised default set, and an account whose calendar was never configured returns exactly that. The default set follows the account language rather than its country, so verify holidays against your own data instead of treating the answer as administrator-confirmed.

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| GET | [`/v1/calendar/settings`](/docs/calendar/settings) | calendar.settings.get | Bitrix24 account calendar settings |

Calendar events and sections are available as entities — [Calendar events](/docs/entities/calendar-events), [Calendar sections](/docs/entities/calendar-sections).

## Error codes

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `WRONG_PATH` | A non-existent address was requested. The error text names the correct address |
| 403 | `SCOPE_DENIED` | The key lacks the `calendar` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request — text in `message` |
| 502 | `BITRIX_UNAVAILABLE` | The portal is unavailable or returned a response with an unexpected structure |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Endpoints](/docs/calendar/endpoints)
- [Calendar events](/docs/entities/calendar-events)
- [Calendar sections](/docs/entities/calendar-sections)
- [Workday](/docs/workday)