## 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 |
|----------|-----|:-----:|----------|
| `id` (path) | number | yes | Site ID. List: [`GET /v1/sites`](/docs/entities/sites/list) |
| `scope` (query) | string | no | Site type: `KNOWLEDGE` — knowledge base, `GROUP` — workgroup site, `MAINPAGE` — home page. Omit the parameter for all other sites |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data.previewUrl` | string \| null | URL 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`](/docs/entities/sites/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 |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `id` is not a positive integer |
| 400 | `INVALID_SCOPE` | `scope` is not one of `KNOWLEDGE`, `GROUP`, `MAINPAGE` |
| 404 | `ENTITY_NOT_FOUND` | No 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` |
| 409 | `LANDING_MODULE_NOT_ENABLED` | The Sites module is unavailable on the Bitrix24 account |
| 422 | `BITRIX_ERROR` | Bitrix24 returned the preview as something other than a string, or rejected the request. The reason is in `message` |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access: the key's user is not an administrator, or the feature is unavailable on the Bitrix24 account |
| 403 | `SCOPE_DENIED` | The key lacks the `landing` scope |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |

Full list of common API errors — [Errors](/docs/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

- [Site public URL](/docs/entities/sites/public-url)
- [Get a site](/docs/entities/sites/get)
- [Site list](/docs/entities/sites/list)
- [Sites](/docs/entities/sites)
- [Errors](/docs/errors)