# Workgroups

Manage Bitrix24 account workgroups and projects: create, get, update, delete, search. A workgroup brings employees together around a shared topic or project — it has an owner, a subject, openness and archiving flags, and a member counter.

Bitrix24 API: `sonet_group.*`
Scope: `sonet_group`

## Operations

- [Create a workgroup](./workgroups/create.md) — `POST /v1/workgroups`
- [List workgroups](./workgroups/list.md) — `GET /v1/workgroups`
- [Get a workgroup](./workgroups/get.md) — `GET /v1/workgroups/:id`
- [Update a workgroup](./workgroups/update.md) — `PATCH /v1/workgroups/:id`
- [Delete a workgroup](./workgroups/delete.md) — `DELETE /v1/workgroups/:id`
- [Search workgroups](./workgroups/search.md) — `POST /v1/workgroups/search`
- [Workgroup fields](./workgroups/fields.md) — `GET /v1/workgroups/fields`
- [Aggregate workgroups](./workgroups/aggregate.md) — `POST /v1/workgroups/aggregate`

## Key fields

| Field | Description |
|------|---------|
| `name` | Workgroup name |
| `ownerId` | Owner identifier. Source: [`GET /v1/users`](/docs/entities/users) |
| `subjectId` | Subject identifier. The list of allowed values is returned in [`GET /v1/workgroups`](./workgroups/list.md) responses in the `subjectName` field alongside `subjectId` |
| `opened` | Openness flag — whether any employee in the Bitrix24 account can join |
| `isProject` | Project flag — projects have separate semantics in tasks and reports |
| `archived` | Archive flag — the group is hidden from active lists but preserved |
| `membersCount` | Current number of group members |

Full field list — [`GET /v1/workgroups/fields`](./workgroups/fields.md).

## What you need to know before you start

1. **Boolean fields have different formats on input and in the response.** In URL filters (`?filter[active]=...`) boolean fields are passed as `Y` or `N`. In `POST` / `PATCH` request bodies and in the `POST /v1/workgroups/search` body both `Y` / `N` and native JSON `true` / `false` work. In responses from all endpoints they are always `true` / `false`.
2. **`archived` and `active` are different flags.** `archived: true` means the group has been moved to the archive and is not shown in active lists; `active: false` means the group is disabled. These are two independent states.
3. **`isProject: true` has separate semantics.** Project groups behave differently in Bitrix24 tasks and reports. To create an ordinary workgroup without project logic, leave `isProject` empty or pass `false`.
4. **Subjects are defined on the Bitrix24 account side.** The list of allowed `subjectId` values is configured by the Bitrix24 administrator and is not editable through the workgroups API. The `subjectId` ↔ `subjectName` mapping is returned in every workgroup list item.

## Typical scenario

1. Find the future group owner: [`GET /v1/users?filter[name]=John`](/docs/entities/users).
2. Create a workgroup: [`POST /v1/workgroups`](./workgroups/create.md) with `name`, `ownerId`, `subjectId`, `opened`.
3. Get an employee's list of workgroups: [`GET /v1/workgroups?filter[ownerId]=15`](./workgroups/list.md).
4. Update the parameters: [`PATCH /v1/workgroups/:id`](./workgroups/update.md) — for example, toggle `opened` or change `description`.
5. Move the group to the archive: [`PATCH /v1/workgroups/:id`](./workgroups/update.md) with `archived: true`.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Request rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Entities reference](/docs/entities-index)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Employees](/docs/entities/users)
- [Departments](/docs/entities/departments)