For AI agents: markdown of this page — /docs-content-en/entities/calendar-sections/create.md documentation index — /llms.txt

Create a section

POST /v1/calendar-sections

Creates a new calendar section for an employee, group, or company. The section is created on behalf of the employee whose tokens are bound to the API key. A Bitrix24 account administrator can create sections for other employees.

Request fields (body)

Field Type Required Description
Fieldtype Typestring Requiredyes DescriptionCalendar type: user, group
FieldownerId Typenumber Requiredyes DescriptionCalendar owner identifier. For an employee — GET /v1/users, for a workgroup — its ID
Fieldname Typestring Requiredyes DescriptionSection name
Fielddescription Typestring Requiredno DescriptionDescription
Fieldcolor Typestring Requiredno DescriptionSection color in #RRGGBB format
FieldtextColor Typestring Requiredno DescriptionText color in #RRGGBB format
Fieldexport Typeobject Requiredno DescriptionExport parameters in iCal format. Keys inside the object are uppercase
Fieldexport.ALLOW Typeboolean Requiredno DescriptionAllow calendar export
Fieldexport.SET Typestring Requiredno DescriptionExport period: all — all time, 3_9 — 3 months back and 9 forward, 6_12 — 6 months back and 12 forward

Read-only fields — id, access, perm, isCollab, createdBy, dateCreate, updatedAt — cannot be passed in the request body. The Vibecode API returns 400 READONLY_FIELD.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team meetings",
    "description": "Calendar for regular calls",
    "color": "#9cbeee",
    "textColor": "#283000",
    "export": {
      "ALLOW": true,
      "SET": "3_9"
    }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team meetings",
    "description": "Calendar for regular calls",
    "color": "#9cbeee",
    "textColor": "#283000",
    "export": {
      "ALLOW": true,
      "SET": "3_9"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'user',
    ownerId: 1,
    name: 'Team meetings',
    description: 'Calendar for regular calls',
    color: '#9cbeee',
    textColor: '#283000',
    export: {
      ALLOW: true,
      SET: '3_9',
    },
  }),
})

const { success, data } = await res.json()
console.log('Section identifier:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'user',
    ownerId: 1,
    name: 'Team meetings',
    description: 'Calendar for regular calls',
    color: '#9cbeee',
    textColor: '#283000',
    export: {
      ALLOW: true,
      SET: '3_9',
    },
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionIdentifier of the created section — the only field in the create response

To get the remaining fields of the created section, such as color, access, and perm, call GET /v1/calendar-sections?type=<...>&ownerId=<...> and find the record by id.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 99
  }
}

Error response example

422 — a required field was omitted:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Invalid value for the \"name\" parameter"
  }
}

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR DescriptionA required field (type, ownerId, or name) is missing, or a field value is invalid
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed in the request body — id, access, perm, isCollab, createdBy, dateCreate, updatedAt
HTTP400 CodeEMPTY_CREATE_BODY DescriptionThe request body is empty — pass at least one field
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the calendar scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe API key is in read-only mode — writes are blocked
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe create outcome is unknown: Bitrix24 may have accepted the request. Look up the section with a separate read and retry creation only after confirming that it does not exist

Full list of common API errors — Errors.

Known specifics

The create response contains only id. The other fields of the new section, including the assigned access and perm, are not returned in the response — to get them, make a separate request to GET /v1/calendar-sections.

The export field preserves case. Pass exactly { "ALLOW": true, "SET": "3_9" } with uppercase keys. The Vibecode API does not convert them to camelCase. Lowercase export keys are not applied.

The SET key never comes back. The section list returns export with the keys ALLOW, PATH, and LINK — the export period does not appear in the response. If you need the period for display, store the value you sent on your side.

See also