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

Batch operations on calendar sections

POST /v1/calendar-sections/batch

Bulk create, update, or delete calendar sections in a single request — up to 500 items per call. This is a dedicated endpoint for the entity, not to be confused with the universal batch, which combines operations across different entities and is limited to 50 calls.

Request fields (body)

Field Type Required Description
Fieldaction Typestring Requiredyes DescriptionOperation type: create, update, or delete
Fielditems Typearray Requiredyes for create and update DescriptionList of items, up to 500. For create — [{ type, ownerId, name, color?, ... }]. For update — [{ id, type, ownerId, name, ... }]. The item field set matches the body of POST /v1/calendar-sections and PATCH /v1/calendar-sections/:id
Fieldids Typenumber[] Requiredyes for delete DescriptionSection identifiers to delete, up to 500
Fieldtype Typestring Requiredyes for delete DescriptionCalendar type, passed alongside ids. Values: user, group, company_calendar, location
FieldownerId Typenumber Requiredyes for delete DescriptionCalendar owner identifier, passed alongside ids. For type=user — the employee id from GET /v1/users, for type=group — the workgroup id, for type=location — 0

For create and update, the type + ownerId pair and the name field are included in each items element. For delete, type and ownerId are shared across the whole batch and passed at the top level alongside ids.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "type": "user", "ownerId": 1, "name": "Team meetings", "color": "#ff5b49" },
      { "type": "user", "ownerId": 1, "name": "Personal", "color": "#2fc6f6" }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections/batch" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "type": "user", "ownerId": 1, "name": "Team meetings", "color": "#ff5b49" },
      { "type": "user", "ownerId": 1, "name": "Personal", "color": "#2fc6f6" }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { type: 'user', ownerId: 1, name: 'Team meetings', color: '#ff5b49' },
      { type: 'user', ownerId: 1, name: 'Personal', color: '#2fc6f6' },
    ],
  }),
})

const { data } = await res.json()
data.results.forEach((item) => {
  if (item.success) console.log(`#${item.index} → id=${item.id}`)
  else console.log(`#${item.index} → error: ${item.error} ${item.message}`)
})

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { type: 'user', ownerId: 1, name: 'Team meetings', color: '#ff5b49' },
      { type: 'user', ownerId: 1, name: 'Personal', color: '#2fc6f6' },
    ],
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true if the request passed top-level validation. The result of each item is in data.results[i].success
Fielddata.results Typearray DescriptionArray of results in the same order as the request's items or ids
Fielddata.results[].index Typenumber DescriptionItem index, starting from 0
Fielddata.results[].success Typeboolean DescriptionResult of this operation
Fielddata.results[].id Typenumber DescriptionSection identifier for create, update, and delete
Fielddata.results[].error Typestring DescriptionError code for the failed item, UNKNOWN if the code is not determined. May be an empty string if Bitrix24 returned only text without a code
Fielddata.results[].message Typestring DescriptionError text for the failed item
Fielddata.summary.total Typenumber DescriptionTotal items processed
Fielddata.summary.succeeded Typenumber DescriptionHow many succeeded
Fielddata.summary.failed Typenumber DescriptionHow many failed with an error

Response example

action: create — both sections created:

JSON 
{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "id": 181 },
      { "index": 1, "success": true, "id": 183 }
    ],
    "summary": { "total": 2, "succeeded": 2, "failed": 0 }
  }
}

action: update — an item without type failed, while the top-level success stayed true:

JSON 
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "success": false,
        "error": "",
        "message": "Required parameter \"type\" is not set for the \"calendar.section.update\" method"
      }
    ],
    "summary": { "total": 1, "succeeded": 0, "failed": 1 }
  }
}

Error response example

400 — with action: delete, type and ownerId were not passed alongside ids:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "POST /v1/calendar-sections/batch { action: \"delete\" } requires type, ownerId alongside ids. Example: { \"action\": \"delete\", \"ids\": [...], \"type\": ..., \"ownerId\": ... }",
    "missing": ["type", "ownerId"]
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS Descriptionaction: delete without type or ownerId alongside ids
HTTP400 CodeINVALID_BATCH_ACTION Descriptionaction is not a supported operation
HTTP400 CodeBATCH_ITEM_VALIDATION Descriptionitems or ids is empty or not an array, or an update item is missing id
HTTP400 CodeBATCH_LIMIT_EXCEEDED DescriptionMore than 500 items were passed in the request
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the calendar scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode — writing is not allowed
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionA management key was used instead of an application key
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 30 requests per minute per portal (a batch costs more than a plain read). All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

Individual item errors arrive inside data.results[i] — the error field with a code or an empty string, and message with the text.

For the full list of common API errors, see Errors.

Known specifics

The top-level success stays true if the request passed top-level validation. Failed items do not turn the entire response into an error — this lets you handle a partial result. Before using the result, check data.results[i].success for each item, and see the summary in data.summary.

Batch update does not fill in type, ownerId, and name from the existing section. Unlike the single PATCH /v1/calendar-sections/:id, which substitutes these fields itself, in a batch you must pass them in each items element. Without them the item fails, while the rest continue to be processed.

See also