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

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

Public link to a folder

POST /v1/folders/:id/public-link

Creates a public link to a folder or returns the existing one: anyone who has the link can open the entire folder contents, including files added later. The link cannot be revoked through the API.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFolder ID. List: GET /v1/folders?parentId=X. The root folder of a storage cannot be published

No request body is sent.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/public-link" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/public-link" \
  -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/folders/10741/public-link', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
const link = body.data.url
console.log('Link received, folder in trash:', body.meta.inTrash)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/public-link', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
const link = body.data.url
console.log('Link received, folder in trash:', body.meta.inTrash)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.url Typestring DescriptionPublic link to the folder. Opens the folder and all its contents without authorization
Fielddata.revocableViaApi Typeboolean DescriptionAlways false: the link cannot be revoked through the API
Fieldmeta.inTrash Typeboolean Descriptiontrue — the folder is in the trash. The link is issued but opens the folder only after restoration

Response example

JSON 
{
  "success": true,
  "data": {
    "url": "https://bitrix24public.com/<portal>.bitrix24.com/folder/EXAMPLE_TOKEN",
    "revocableViaApi": false
  },
  "meta": {
    "inTrash": false
  }
}

Error response example

400 — the folder is a storage root:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "A storage root cannot be published."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe folder is a storage root. The request is rejected before it reaches Bitrix24, so that the entire personal or shared Drive is not exposed
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 creating a link changes portal data
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner has no permission to change the folder, or public links are disabled on the portal. The response does not distinguish these reasons
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no folder with this id
HTTP422 CodeDISK_PUBLIC_LINK_REFUSED DescriptionBitrix24 did not return a link
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused to create the link; 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 link was requested. The outcome is unknown, and no retry was made. A repeat call returns the same link if it was created
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 was unavailable while the folder was being read; the link was not requested

Full list of common API errors — Errors.

Known specifics

The link is an access secret. The response comes with the Cache-Control: private, no-store header. Do not write data.url to logs, audit records or telemetry.

Existing link. If the folder already has a public link, the call returns it instead of creating a new one. It may be another employee's link, including one with a password or an expiration date: the response does not say whether it is protected.

Trash and deletion. While the folder is in the trash, the link does not open it; after restoration it opens the folder again. Via the API, the only way to disable the link is to permanently delete the folder.

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

See also