لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/folders/shares.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Share a folder with a user

POST /v1/folders/:id/shares

Grants a Bitrix24 account user access to a folder at the selected level. Access takes effect immediately, before the user responds to the invitation.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFolder ID. List: GET /v1/folders?parentId=X

Request fields (body)

Field Type Required Description
FielduserId Typenumber Requiredyes DescriptionID of the Bitrix24 account user who receives access. List: GET /v1/users
Fieldaccess Typestring Requiredyes DescriptionAccess level: read — read access, add — add access, edit — edit access, full — full access. A numeric id from GET /v1/folders/access-levels is not accepted

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/shares" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":8,"access":"read"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/shares" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":8,"access":"read"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/shares', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 8, access: 'read' }),
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Access granted, user verified:', body.meta.recipientVerified)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/shares', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 8, access: 'read' }),
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Access granted, user verified:', body.meta.recipientVerified)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue — access granted
Fielddata.folderId Typenumber DescriptionFolder ID
Fielddata.userId Typenumber DescriptionID of the user who received access
Fielddata.access Typestring DescriptionGranted level: read, add, edit or full
Fieldmeta.recipientVerified Typeboolean Descriptiontrue — before access was granted, the API verified that the user exists and is not dismissed. false — no check was made: the key has no user, user_basic or user_brief scope

Response example

Access granted — HTTP status 201 Created:

JSON 
{
  "success": true,
  "data": {
    "folderId": 10741,
    "userId": 8,
    "access": "read"
  },
  "meta": {
    "recipientVerified": true
  }
}

Error response example

409 — the user owns the storage that contains the folder:

JSON 
{
  "success": false,
  "error": {
    "code": "DISK_SHARE_NOT_CREATED",
    "message": "No access was granted: the recipient may own this storage."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID DescriptionThe folder id is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe userId or access field is missing
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer, or access is not one of read, add, edit, full
HTTP400 CodeINVALID_PARAMS DescriptionThe user is dismissed. Checked when the key has the user, user_basic or user_brief scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key's portal has no authorization tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode, and granting access changes portal data
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused to let the key owner grant access to this folder
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no folder with this id
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe user was not found. Checked when the key has the user, user_basic or user_brief scope
HTTP409 CodeDISK_SHARE_NOT_CREATED DescriptionAccess was not granted: the user owns the storage that contains the folder
HTTP409 CodeDISK_ALREADY_SHARED DescriptionThe user already has access to this folder. The level cannot be changed through the API
HTTP422 CodeDISK_SHARE_REFUSED DescriptionBitrix24 did not confirm that access was granted
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused to grant access; the reason is in message
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded — wait 1-2 seconds and retry
HTTP502 CodeDISK_OUTCOME_UNKNOWN DescriptionThe connection to Bitrix24 dropped after the request was sent. The outcome is unknown, and no retry was made. If access was granted, a repeat call returns 409 DISK_ALREADY_SHARED
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or did not return the user's data during the check; access was not granted

Full list of general API errors — Errors.

Known specifics

Invitation. The user receives a notification inviting them to accept or decline the folder. The rights apply from the moment they are granted; accepting only connects the folder to the user's Drive. On Bitrix24 accounts with auto-connection, the folder is connected immediately.

User check. The check runs with the key owner's permissions: if the key owner cannot see the user in GET /v1/users, the response is 404. Without the user, user_basic and user_brief scopes there is no check, and the rights may be assigned to a nonexistent user — verify userId yourself before the call.

Access cannot be changed or revoked through the API. Granting a level higher than the key owner's own level is not possible either.

Storage types. Access is granted to folders in user storages, group storages and the shared drive.

Batch calls. The method is not part of POST /v1/batch — call it as a separate request.

See also