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

Update a workgroup

PATCH /v1/workgroups/:id

Updates the specified workgroup fields. Returns the full group object after the update. Fields not mentioned in the body remain unchanged.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Required★ DescriptionWorkgroup identifier. List: GET /v1/workgroups

Request fields (body)

Pass only the fields you need to change. The rest keep their current values.

Field Type Required Default Description
Fieldname Typestring Requiredno Defaultcurrent value DescriptionWorkgroup name
Fielddescription Typestring Requiredno Defaultcurrent value DescriptionDescription
FieldownerId Typenumber Requiredno Defaultcurrent value DescriptionIdentifier of the new group owner. List: GET /v1/users
FieldsubjectId Typenumber Requiredno Defaultcurrent value DescriptionSubject identifier
Fieldactive Typeboolean Requiredno Defaultcurrent value DescriptionWhether the group is active
Fieldvisible Typeboolean Requiredno Defaultcurrent value DescriptionWhether it is visible in shared lists
Fieldopened Typeboolean Requiredno Defaultcurrent value DescriptionWhether it is open for joining without an invitation
Fieldarchived Typeboolean Requiredno Defaultcurrent value DescriptionWhether the group is archived
FieldisProject Typeboolean Requiredno Defaultcurrent value DescriptionWhether it is a project. A collab group does not accept false — 422 BITRIX_ERROR
Fieldkeywords Typestring Requiredno Defaultcurrent value DescriptionKeywords for search

The fields id, subjectName, membersCount, dateCreate, dateUpdate, dateActivity, siteId, imageUrl, isExtranet are read-only. Passing any of them in the body returns 400 READONLY_FIELD.

isExtranet is derived from the group's site bindings in Bitrix24. The names isExtranet, IS_EXTRANET, is_extranet and isextranet are rejected before the group is changed, whether the value is false or true, even if it repeats the current value. Remove this field from write bodies; reads still return the actual flag.

In POST /v1/workgroups/batch with action: create or action: update, this field causes 400 BATCH_ITEM_VALIDATION before the entire batch is sent. In POST /v1/batch, the rejected operation receives READONLY_FIELD in data.errors.<id>; the HTTP status is 400 if all operations are rejected, or 200 for a mixed result, with valid sibling operations executed.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/workgroups/85" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated team description",
    "opened": true,
    "archived": false
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/workgroups/85" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated team description",
    "opened": true,
    "archived": false
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/85', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Updated team description',
    opened: true,
    archived: false,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/85', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Updated team description',
    opened: true,
    archived: false,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe full workgroup object after the update — see all fields in Get a workgroup

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 85,
    "siteId": "s1",
    "name": "Marketing 2026",
    "description": "Updated team description",
    "dateCreate": "2026-05-12T08:14:21.000Z",
    "dateUpdate": "2026-05-26T05:58:08.000Z",
    "active": true,
    "visible": true,
    "opened": true,
    "archived": false,
    "subjectId": 1,
    "ownerId": 1,
    "keywords": "project,team",
    "membersCount": 7,
    "dateActivity": "2026-05-26T05:58:08.000Z",
    "subjectName": "Workgroups",
    "isProject": false,
    "isExtranet": false
  }
}

Error response example

Bitrix24 does not distinguish "the group does not exist" from "no permission to update":

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "User has no permissions to update group"
  }
}

Errors

HTTP error.code Description
HTTP400 error.codeREADONLY_FIELD DescriptionA read-only field was passed in the body (id, subjectName, membersCount, dateCreate, dateUpdate, dateActivity, siteId, imageUrl, isExtranet)
HTTP422 error.codeBITRIX_ERROR DescriptionBitrix24 declined the update. The text is in error.message. Typical reasons: validation error, value conflict, no permission to change, no workgroup with the specified id (the last two cases return the same message)
HTTP401 error.codeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed in the request
HTTP401 error.codeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 error.codeSCOPE_DENIED DescriptionThe key does not have the sonet_group scope

Full list of common API errors — Errors.

Known specifics

  • The User has no permissions to update group message is returned both when there is no workgroup with the specified id and when you have no permission to change it. To tell these two cases apart, make an additional GET /v1/workgroups/:id request: a 404 response means the group does not exist, and a successful response means you have no permission to change it.

See also