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 Req. Description
id (path) number yes Section identifier

Request fields (body)

Field Type Req. Description
type string yes Calendar type: user, group. Must match the type of the existing section — otherwise an access error is returned
ownerId number yes Calendar owner identifier. Must match the ownerId of the existing section
name string yes Section name. Required even when changing other fields — pass the current value if no rename is needed
description string no Description
color string no Section color in #RRGGBB format
textColor string no Text color in #RRGGBB format
export object no iCal export parameters: { "ALLOW": boolean, "SET": "all" | "3_9" | "6_12" }. The keys inside the object are uppercase

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
success boolean Always true on success
data.id number Identifier of the updated section — the only field in the update response

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

Response example

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

Error response example

400 — a required anchor type, ownerId, or name is missing, checked before calling 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
400 MISSING_REQUIRED_PARAMS A required field type, ownerId, or name is missing — checked before calling Bitrix24
422 BITRIX_ERROR Invalid field value, for example an unsupported type
400 READONLY_FIELD A read-only field was passed in the request body
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 — writing is forbidden
401 TOKEN_MISSING The API key has no configured tokens
502 BITRIX_UNAVAILABLE Bitrix24 is temporarily unavailable — retry the request later

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 — it can be obtained via 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