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

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

Site preview

GET /v1/sites/:id/preview

Returns the URL of the preview image for the site's home page. Use it to show a site thumbnail in a list or a card.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionSite ID. List: GET /v1/sites
Parameterscope (query) Typestring Requiredno DescriptionSite type: KNOWLEDGE — knowledge base, GROUP — workgroup site, MAINPAGE — home page. Omit the parameter for all other sites

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/sites/42/preview" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/sites/42/preview" \
  -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/sites/42/preview', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
if (data.previewUrl === null) {
  console.log('The site has no preview')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/42/preview', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
if (data.previewUrl === null) {
  console.log('The site has no preview')
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.previewUrl Typestring | null DescriptionURL of the preview image. Either a full URL or a path from the site root, for example /preview.jpg. Prefix the path with the site's public address from GET /v1/sites/:id/public-url. A protocol-relative URL //host/... is expanded to https://host/.... null — the site has no preview

Response example

The preview is given as a path from the site root:

JSON 
{
  "success": true,
  "data": {
    "previewUrl": "/preview.jpg"
  }
}

The site has no preview:

JSON 
{
  "success": true,
  "data": {
    "previewUrl": null
  }
}

Error response example

404 — the site does not exist or is not visible to the key:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Site not found or not visible"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer
HTTP400 CodeINVALID_SCOPE Descriptionscope is not one of KNOWLEDGE, GROUP, MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo site with this id exists, or it is not visible to the key. A knowledge base, workgroup site or home page requires the scope parameter. An ordinary site requested with scope also returns 404
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is unavailable on the Bitrix24 account
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned the preview as something other than a string, or rejected the request. The reason is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access: the key's user is not an administrator, or the feature is unavailable on the Bitrix24 account
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the landing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

  • The /preview.jpg path may lead to a placeholder. On the Bitrix24 account we tested, 26 of 27 sites returned /preview.jpg, and for all of them that path opened the same "preview in progress" image rather than a snapshot of the page. To tell a real preview from the placeholder, compare the image contents.

See also