## Workgroup fields `GET /v1/workgroups/fields` Returns the workgroup field schema and the list of operations available in batch requests. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/workgroups/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/workgroups/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { success, data } = await res.json() console.log('Fields:', Object.keys(data.fields).length) console.log('Available batch operations:', data.batch) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/workgroups/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data } = await res.json() ``` ## Response fields The `label` and `description` field captions are returned in English. Request headers do not switch the language. | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data.fields` | object | Workgroup field schema object | | `data.fields.` | object | Description of a single field | | `data.fields..type` | string | Value type: `number`, `string`, `boolean` or `datetime` | | `data.fields..readonly` | boolean | `true` — the field is filled in by the system and is not passed in write requests | | `data.fields..nullable` | boolean | `true` — the field can come back as `null`. The key is present only on such fields | | `data.batch` | array | List of entity operations available in [`POST /v1/batch`](/docs/batch): `create`, `update`, `delete` | ### Workgroup fields | Field | Type | Read-only | Description | |------|-----|:--:|---------| | `id` | number | yes | Workgroup identifier | | `name` | string | | Name | | `description` | string | | Description | | `active` | boolean | | Whether the group is active | | `visible` | boolean | | Whether it is visible in general lists | | `opened` | boolean | | Whether it is open for joining without an invitation | | `ownerId` | number | | Owner (responsible person). List: [`GET /v1/users`](/docs/entities/users) | | `subjectId` | number | | Subject identifier | | `subjectName` | string | yes | Subject name | | `membersCount` | number | yes | Number of members | | `dateCreate` | datetime | yes | Creation date | | `dateUpdate` | datetime | yes | Last update date | | `dateActivity` | datetime | yes | Last activity date | | `archived` | boolean | | Whether it is archived | | `isProject` | boolean | | Whether it is a project with tasks and deadlines | | `isExtranet` | boolean | yes | Extranet group | | `keywords` | string | | Keywords. Not saved on create — set via PATCH | | `siteId` | string | yes | Bitrix24 account site identifier | | `imageUrl` | string | yes | Group avatar URL | ## Available includes The `GET /v1/workgroups/fields` endpoint returns the list of available includes: `owner`. Usage example: [Get a workgroup](/docs/entities/workgroups/get#related-data). More on includes: [Related data](/docs/includes). ## Response example ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "ID", "description": "Identifier of the workgroup." }, "name": { "type": "string", "readonly": false, "label": "Name", "description": "Name of the workgroup." }, "description": { "type": "string", "readonly": false, "label": "Description", "description": "Text description of the workgroup." }, "active": { "type": "boolean", "readonly": false, "label": "Active", "description": "Indicates that the group is active." }, "visible": { "type": "boolean", "readonly": false, "label": "Visible in lists", "description": "Indicates that the group is shown in general lists." }, "opened": { "type": "boolean", "readonly": false, "label": "Open group", "description": "Indicates that joining the group is possible without an invitation." }, "ownerId": { "type": "number", "readonly": false, "label": "Owner", "description": "Identifier of the user responsible for the group." }, "subjectId": { "type": "number", "readonly": false, "label": "Subject ID", "description": "Identifier of the subject (area of activity) of the workgroup." }, "subjectName": { "type": "string", "readonly": true, "label": "Subject name", "description": "Name of the subject the workgroup belongs to." }, "membersCount": { "type": "number", "readonly": true, "label": "Member count", "description": "Number of members in the workgroup." }, "dateCreate": { "type": "datetime", "readonly": true, "label": "Created at", "description": "Date and time the workgroup was created." }, "dateUpdate": { "type": "datetime", "readonly": true, "label": "Updated at", "description": "Date and time the workgroup was last updated." }, "dateActivity": { "type": "datetime", "readonly": true, "label": "Last activity date", "description": "Date and time of the last activity in the workgroup." }, "archived": { "type": "boolean", "readonly": false, "label": "Archived", "description": "Indicates that the group has been placed in the archive." }, "isProject": { "type": "boolean", "readonly": false, "label": "Project", "description": "Indicates that the group is a project with tasks and deadlines." }, "isExtranet": { "type": "boolean", "readonly": true, "label": "Extranet group", "description": "Read-only flag derived from the group's site bindings in Bitrix24. Cannot be set directly." }, "keywords": { "type": "string", "readonly": false, "nullable": true, "label": "Keywords", "description": "Keywords associated with the workgroup. Bitrix24 does not save a value passed on create — the group is created with keywords null. Set keywords with PATCH /v1/workgroups/:id after the group is created." }, "siteId": { "type": "string", "readonly": true, "label": "Site ID", "description": "Identifier of the portal site the group belongs to." }, "imageUrl": { "type": "string", "readonly": true, "label": "Avatar URL", "description": "Link to the workgroup's avatar image." } }, "batch": ["create", "update", "delete"] } } ``` ## Error response example 401 — no authorization key: ```json { "success": false, "error": { "code": "MISSING_API_KEY", "message": "API key is required" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed | | 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform | | 403 | `SCOPE_DENIED` | The API key does not have the `sonet_group` scope | | 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. 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 | For the full list of common API errors, see [Errors](/docs/errors). ## Known specifics - The field list does not depend on the permissions of the key's user — the full entity schema is returned. - Besides the operations listed in `data.batch`, [`POST /v1/batch`](/docs/batch) also accepts `get`, `list` and `fields` for workgroups. ## See also - [List workgroups](./list.md) - [Create a workgroup](./create.md) - [Update a workgroup](./update.md) - [Batch](/docs/batch) - [Entity API](/docs/entity-api)