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
name string yes Name, from 1 to 80 characters. Leading and trailing spaces are dropped
timezone string yes IANA time zone the windows are read in, for example Europe/Berlin
windows array yes Windows { isoDay, start, end }, at most two per day. Window rules are on the section index
windows[].isoDay number yes Weekday: 1 — Monday, 7 — Sunday
windows[].start string yes Window start, local HH:MM on a 30-minute step
windows[].end string yes Window end, local HH:MM on a 30-minute step. 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 comes with status 201 Created.

Field Type Description
success boolean Always true on success
data.id string ID of the created schedule
data.kind string Always CUSTOM
data.name string Name
data.presetKey null Always null for a custom schedule
data.timezone string IANA time zone
data.windows array Windows { isoDay, start, end } ordered by day and time
data.version number Version number, 1 for a new schedule
data.canEdit boolean true: the author may edit their own schedule
data.assignedCount number 0: a new schedule is not assigned to anyone yet

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

Error response example

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

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
400 VALIDATION_ERROR The body does not fit the schema — an unknown field, an empty name, an unknown time zone, a time not in HH:MM form — or the windows break the week rules. message carries the field path and the reason
400 WORK_SCHEDULE_EMPTY An empty windows was passed: a server on such a schedule would never run
400 RUN_MODE_UNAVAILABLE Run modes are not enabled for the Bitrix24 account yet
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The key is not recognized: no such key exists on the platform
403 WORK_SCHEDULE_LIMIT The Bitrix24 account already keeps 50 custom schedules. Delete an unused one or assign a preset
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — creating is closed to it
403 INFRA_SCOPE_REQUIRED The key lacks the vibe:infra scope
403 INFRA_FORBIDDEN_FOR_COWORK_KEY The call was made with a Cowork/Code key — the schedule library is closed to such a key. What to do — Project deploy key
404 NOT_FOUND The key is not bound to a Bitrix24 account
429 RATE_LIMITED The limit of 20 requests per minute per key is exceeded. The exact value is in the x-ratelimit-limit header (the ceiling is split between replicas)

Full list of shared error codes — 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. Later the schedule can be edited and deleted by them and by an administrator of the Bitrix24 account.
  • Presets do not count toward the limit. The limit of 50 schedules counts custom schedules only; platform presets take no place in it.

See also