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
action string yes Operation type: create, update, or delete
items array yes for create and update List 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
ids number[] yes for delete Section identifiers to delete, up to 500
type string yes for delete Calendar type, passed alongside ids. Values — user, group, company_calendar, location
ownerId number yes for delete Calendar 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
success boolean Always true if the request passed top-level validation. The result of each item is in data.results[i].success
data.results array Array of results in the same order as the request's items or ids
data.results[].index number Item index, starting from 0
data.results[].success boolean Result of this operation
data.results[].id number Section identifier for create, update, and delete
data.results[].error string Error 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
data.results[].message string Error text for the failed item
data.summary.total number Total items processed
data.summary.succeeded number How many succeeded
data.summary.failed number How 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
400 MISSING_REQUIRED_PARAMS action: delete without type or ownerId alongside ids
400 INVALID_BATCH_ACTION action is not a supported operation
400 BATCH_ITEM_VALIDATION items or ids is empty or not an array, or an update item is missing id
400 BATCH_LIMIT_EXCEEDED More than 500 items were passed in the request
403 SCOPE_DENIED The key is missing the calendar scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode — writing is not allowed
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS A management key was used instead of an application key
401 TOKEN_MISSING The key has no configured tokens

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

The full list of common API errors — 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