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

Update section

PATCH /v1/calendar-sections/:id

Updates the fields of an existing section. type, ownerId, and name are required in every call — even when only the color or description changes.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionSection identifier

Request fields (body)

Field Type Required Description
Fieldtype Typestring Requiredyes DescriptionCalendar type: user, group. Must match the type of the existing section — otherwise an access error is returned
FieldownerId Typenumber Requiredyes DescriptionCalendar owner identifier. Must match the ownerId of the existing section
Fieldname Typestring Requiredyes DescriptionSection name. Required even when changing other fields — pass the current value if no rename is needed
Fielddescription Typestring Requiredno DescriptionDescription
Fieldcolor Typestring Requiredno DescriptionSection color in #RRGGBB format
FieldtextColor Typestring Requiredno DescriptionText color in #RRGGBB format
Fieldexport Typeobject Requiredno DescriptioniCal export parameters. The 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.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/calendar-sections/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "ownerId": 1,
    "name": "Team meetings",
    "color": "#FF5733",
    "description": "Updated description"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/calendar-sections/42" \
  -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",
    "color": "#FF5733",
    "description": "Updated description"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'user',
    ownerId: 1,
    name: 'Team meetings',
    color: '#FF5733',
    description: 'Updated description',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/42', {
  method: 'PATCH',
  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',
    color: '#FF5733',
    description: 'Updated description',
  }),
})

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

Response fields

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

To get the current values of the other fields, request GET /v1/calendar-sections?type=<...>&ownerId=<...>.

Response example

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

Error response example

400 — a required anchor field (type, ownerId, or name) is missing. This is checked before the request reaches Bitrix24:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "PATCH /v1/calendar-sections/{id} requires: name. Example: PATCH /v1/calendar-sections/{id} { \"name\": ..., ... }"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionA required field type, ownerId, or name is missing — checked before calling Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionInvalid field value, for example an unsupported type
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed in the request body
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 — writing is forbidden
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe update outcome is unknown: Bitrix24 may have accepted the request. Read the section again and retry only if the change did not apply

The full list of common API errors — Errors.

Known specifics

type, ownerId, name are required in every call. Partial update of a section is not supported — the three anchor fields are needed even when only the color changes. If no rename is needed, pass the current name — get it from GET /v1/calendar-sections.

A nonexistent id returns 200 with no changes. Updating a section that does not exist does not raise an error — you get { "success": true, "data": { "id": <id> } }, but nothing changes. Before relying on the result, make sure the section exists in GET /v1/calendar-sections.

The update response contains only id. To see the updated section in full, make a separate request to GET /v1/calendar-sections.

See also