For AI agents: markdown of this page — /docs-content-en/infra/work-schedules/create.md documentation index — /llms.txt

Create a schedule

POST /v1/work-schedules

Creates a custom work schedule in the library of the Bitrix24 account.

The created schedule is assigned to servers by setting the run mode.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionName, from 1 to 80 characters. Leading and trailing spaces are trimmed
Fieldtimezone Typestring Requiredyes DescriptionIANA time zone used to interpret the windows, for example Europe/Berlin
Fieldwindows Typearray Requiredyes DescriptionWindows { isoDay, start, end }, at most two per day. Window rules are on the section index
Fieldwindows[].isoDay Typenumber Requiredyes DescriptionWeekday: 1 — Monday, 7 — Sunday
Fieldwindows[].start Typestring Requiredyes DescriptionWindow start, local time HH:MM in 30-minute increments
Fieldwindows[].end Typestring Requiredyes DescriptionWindow end, local time HH:MM in 30-minute increments. Midnight is 24:00

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/work-schedules \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse shifts",
    "timezone": "Europe/Berlin",
    "windows": [
      { "isoDay": 1, "start": "09:00", "end": "18:00" },
      { "isoDay": 2, "start": "09:00", "end": "13:00" },
      { "isoDay": 2, "start": "14:00", "end": "24:00" }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/work-schedules \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse shifts",
    "timezone": "Europe/Berlin",
    "windows": [
      { "isoDay": 1, "start": "09:00", "end": "18:00" },
      { "isoDay": 2, "start": "09:00", "end": "13:00" },
      { "isoDay": 2, "start": "14:00", "end": "24:00" }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/work-schedules', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Warehouse shifts',
    timezone: 'Europe/Berlin',
    windows: [
      { isoDay: 1, start: '09:00', end: '18:00' },
      { isoDay: 2, start: '09:00', end: '13:00' },
      { isoDay: 2, start: '14:00', end: '24:00' },
    ],
  }),
})
const { data } = await res.json()
console.log(`Created schedule ${data.id}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/work-schedules', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Warehouse shifts',
    timezone: 'Europe/Berlin',
    windows: [
      { isoDay: 1, start: '09:00', end: '18:00' },
      { isoDay: 2, start: '09:00', end: '13:00' },
      { isoDay: 2, start: '14:00', end: '24:00' },
    ],
  }),
})
const { data } = await res.json()

Response fields

The response status is 201 Created.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionID of the created schedule
Fielddata.kind Typestring DescriptionAlways CUSTOM
Fielddata.name Typestring DescriptionName
Fielddata.presetKey Typenull DescriptionAlways null for a custom schedule
Fielddata.timezone Typestring DescriptionIANA time zone
Fielddata.windows Typearray DescriptionWindows { isoDay, start, end } ordered by day and time
Fielddata.version Typenumber DescriptionVersion number, 1 for a new schedule
Fielddata.canEdit Typeboolean Descriptiontrue: the author may edit their own schedule
Fielddata.assignedCount Typenumber Description0: a new schedule is not assigned to any server yet
Fielddata.defaultForNewMachines Typeboolean Descriptionfalse: a new schedule is not yet selected as the default for new machines. An administrator of the Bitrix24 account selects the default — Set the default schedule
Fielddata.defaultForNewAgents Typeboolean Descriptionfalse: a new schedule is not yet selected as the default for new agents and bots

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "cmfp4r0q2000a1ocg7h2k9x3d",
    "kind": "CUSTOM",
    "name": "Warehouse shifts",
    "presetKey": null,
    "timezone": "Europe/Berlin",
    "windows": [
      { "isoDay": 1, "start": "09:00", "end": "18:00" },
      { "isoDay": 2, "start": "09:00", "end": "13:00" },
      { "isoDay": 2, "start": "14:00", "end": "24:00" }
    ],
    "version": 1,
    "canEdit": true,
    "assignedCount": 0,
    "defaultForNewMachines": false,
    "defaultForNewAgents": false
  }
}

Error response example

400 — a window time is not in HH:MM format:

JSON 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "windows.0.end: must be local time HH:MM (24:00 for midnight)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeVALIDATION_ERROR DescriptionThe body does not match the schema — an unknown field, an empty name, an unknown time zone, a time not in HH:MM format — or the windows break the week rules. For a schema violation, message carries the field path and the reason. For a week-rule violation, message carries the day and the window bounds in minutes from midnight
HTTP400 CodeWORK_SCHEDULE_EMPTY DescriptionAn empty windows array was passed: a server on such a schedule would never run
HTTP400 CodeRUN_MODE_UNAVAILABLE DescriptionRun modes are not enabled for the Bitrix24 account yet
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized: no such key exists on the platform
HTTP403 CodeWORK_SCHEDULE_LIMIT DescriptionThe Bitrix24 account already keeps 50 custom schedules. Delete an unused one or assign a preset
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode — it cannot create schedules
HTTP403 CodeINFRA_SCOPE_REQUIRED DescriptionThe key lacks the vibe:infra scope
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe call was made with a Cowork key, which cannot access the schedule library. For instructions, see Project deploy key
HTTP404 CodeNOT_FOUND DescriptionThe key is not bound to a Bitrix24 account
HTTP429 CodeRATE_LIMITED DescriptionThe limit of 20 requests per minute per key is exceeded. The current limit is returned in the x-ratelimit-limit header

For the full list of common API errors, see Errors.

Known specifics

  • The author is the key owner. The schedule's author is recorded as the key owner, not the user of an OAuth application session. The key owner and an administrator of the Bitrix24 account can then edit and delete the schedule.
  • Presets do not count toward the limit. The limit of 50 schedules counts custom schedules only — platform presets do not take up any of it.

See also