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 Req. Description
type string yes Calendar type: user, group
ownerId number yes Calendar owner identifier. For an employee — GET /v1/users, for a workgroup — its ID
name string yes Section name
description string no Description
color string no Section color in #RRGGBB format
textColor string no Text color in #RRGGBB format
export object no Export parameters in iCal format: { "ALLOW": boolean, "SET": "all" | "3_9" | "6_12" }. Keys inside the object are uppercase. SET defines the export 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
success boolean Always true on success
data.id number Identifier 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
422 BITRIX_ERROR Required field type, ownerId, or name omitted, or an invalid field value
400 READONLY_FIELD A read-only field was passed in the request body — id, access, perm, isCollab, createdBy, dateCreate, updatedAt
400 EMPTY_CREATE_BODY The request body is empty — pass at least one field
403 SCOPE_DENIED The API key does not have the calendar scope
403 WRITE_BLOCKED_READONLY_KEY The API key is in read-only mode — writes are blocked
401 TOKEN_MISSING The API key has no configured tokens
502 BITRIX_UNAVAILABLE Bitrix24 is temporarily unavailable — retry the request later

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" } — keys are uppercase, 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