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 Req. Description
id (path) number ★ Workgroup identifier. List: GET /v1/workgroups

Request fields (body)

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

Field Type Req. Default Description
name string no current value Workgroup name
description string no current value Description
ownerId number no current value Identifier of the new group owner. List: GET /v1/users
subjectId number no current value Subject identifier
active boolean no current value Whether the group is active
visible boolean no current value Whether it is visible in shared lists
opened boolean no current value Whether it is open for joining without an invitation
archived boolean no current value Whether it is placed into the archive
isProject boolean no current value Whether it is a project
isExtranet boolean no current value Extranet group
keywords string no current value Keywords for search

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

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
success boolean Always true on success
data object The 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
400 READONLY_FIELD A read-only field was passed in the body (id, subjectName, membersCount, dateCreate, dateUpdate, dateActivity, siteId, imageUrl)
422 BITRIX_ERROR Bitrix24 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)
401 MISSING_API_KEY The X-Api-Key header was not passed in the request
401 INVALID_API_KEY The provided key is invalid or revoked
403 SCOPE_DENIED The 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 there are no permissions to change it. To distinguish these two cases, make an additional GET /v1/workgroups/:id request: a 404 response — the group is missing, a successful response — no permission to change.

See also