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

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

Public link to a file

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

Creates a public link to a file or returns the existing one: anyone who has the link can open the file without signing in to Bitrix24. The link cannot be revoked via the API.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFile ID. List: GET /v1/files?folderId=X

No request body is sent.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/files/10745/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/files/10745/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, file in trash:', body.meta.inTrash)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/files/10745/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, file in trash:', body.meta.inTrash)

Response fields

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

Response example

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

Error response example

404 — the file does not exist:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '999999999'."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
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 CodeDISK_PUBLIC_LINK_PLAN_UNAVAILABLE DescriptionPublic links to files are not available on the portal's plan
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner has no permission to modify the file, or public links are disabled on the portal. The response does not distinguish these causes
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo file 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 DescriptionRate 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 the request was not retried. A repeated call returns the same link if it was created
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 was unavailable while the file 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 file already has a public link, the call returns it instead of creating a new one. It may be a link created by another employee, including one with a password or an expiration date: the response does not say whether the link is protected.

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

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

See also