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

Workgroup fields

GET /v1/workgroups/fields

Returns the workgroup field schema and the list of operations available in batch requests.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workgroups/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
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.<name> object Description of a single field
data.fields.<name>.type string Value type: number, string, boolean or datetime
data.fields.<name>.readonly boolean true — the field is filled in by the system and is not passed in write requests
data.batch array List of entity operations available in POST /v1/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
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 Extranet group
keywords string Keywords
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.

More on includes: Related data.

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": false, "label": "Extranet group", "description": "Indicates that the group belongs to the extranet." },
      "keywords": { "type": "string", "readonly": false, "label": "Keywords", "description": "Keywords associated with the workgroup." },
      "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 An invalid key was passed
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 exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — 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 also accepts get, list and fields for workgroups.

See also