## Иконка приложения

Иконка приложения показывается в каталоге приложений Битрикс24 и как фавикон во вкладке браузера. Платформа иконку не генерирует — вы загружаете свою через Deploy API. Эта страница — единый источник по формату и порядку загрузки, промпт «Иконка приложения» в кабинете ссылается сюда.

**Скоуп:** `vibe:infra` · **Базовый URL:** `https://vibecode.bitrix24.tech/v1` · **Авторизация:** заголовок `X-Api-Key`

## Формат

- **SVG** (`image/svg+xml`) — **до 256 КБ**, холст **до 4096×4096** после растеризации: платформа приводит SVG к PNG, и слишком большой холст отклоняется кодом `ICON_TOO_MANY_PIXELS` даже у файла в пару сотен байт. Без скриптов, обработчиков событий и внешних ссылок: никаких `<script>`, `on*`-атрибутов, `<foreignObject>`, ссылок на внешние ресурсы. Иконка проходит очистку при загрузке, небезопасное содержимое — причина отказа.
- **Растровые форматы** — PNG, JPG, GIF, WEBP, **до 5 МБ и до 4 мегапикселей** (например, 2000×2000). Формат определяется по содержимому файла, а не по имени и не по `Content-Type`. У SVG есть исключение: содержимое тоже читается, но вместе с ним нужен согласованный признак типа — `Content-Type`, начинающийся с `image/svg`, либо имя файла с расширением `.svg`, иначе загрузка отклоняется кодом `ICON_NOT_SVG`.
- **Что бы вы ни загрузили, отдаётся PNG 256×256.** По URL отдачи иконка всегда возвращается как PNG (`Content-Type: image/png`): платформа масштабирует изображение в квадрат 256×256 с сохранением пропорций и прозрачными полями. Если файл не удаётся прочитать, загрузка отклоняется с ошибкой `ICON_RASTERIZE_FAILED`, слишком большой по весу — `ICON_TOO_LARGE`, слишком большой по числу точек — `ICON_TOO_MANY_PIXELS`, неизвестный формат — `ICON_UNSUPPORTED_FORMAT`.

## Загрузка иконки — обязательный шаг (без исходников)

Подготовьте изображение и загрузите его на сервер:

```
POST /v1/infra/servers/:id/icon
Content-Type: multipart/form-data — поле file
```

Это **единственный обязательный шаг**, и он **не требует исходников приложения**: иконка сразу появляется в каталоге приложений Битрикс24 и доступна по стабильному анонимному URL отдачи `…/api/server-icons/:id`. Перезаливка/перегенерация позже — повторный тот же `POST`.

## Фавикон во вкладке — одна строка в HTML

Чтобы иконка стала ещё и фавиконом во вкладке браузера, добавьте в HTML приложения одну строку:

```html
<link rel="icon" href="/_gw/icon">
```

`/_gw/icon` — платформенный путь на том же домене приложения (его обслуживает платформа, а не ваше приложение), который всегда отдаёт **текущую** загруженную иконку. Строка не содержит id сервера и одинакова для всех приложений — её можно вписать при сборке в один заход (в том числе при создании приложения одним запросом).

Свой статический файл иконки (`/icon.svg` и подобные) в приложение класть **не нужно** — статический файл нельзя поменять через интерфейс платформы Вайбкод. `/_gw/icon` же обновляется сам: перезалили иконку через `POST …/icon` — фавикон обновится в течение ~5 минут, пересобирать приложение не надо.

## Смена иконки — без пересборки

Иконка каталога и фавикон во вкладке — **одно и то же изображение**, и обе управляются одной загрузкой:

- Загрузите новый файл тем же `POST …/icon` — обновятся и карточка в каталоге Битрикс24, и фавикон во вкладке (`/_gw/icon`, в течение ~5 минут).
- Исходники приложения для этого не нужны, пересобирать и разворачивать заново не надо — при условии, что строка `<link rel="icon" href="/_gw/icon">` была вписана при сборке.
- Если строку `<link>` не добавляли — фавикона во вкладке не будет (это ожидаемо), но иконка в каталоге работает. Добавить фавикон можно при следующей пересборке, вписав строку `<link>` (id при этом не нужен).

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `ICON_NO_FILE` | В теле нет части с файлом: тело не `multipart/form-data` либо поле названо не `file` и не `icon` |
| 400 | `ICON_EMPTY` | Файл пустой |
| 400 | `ICON_TOO_LARGE` | Файл тяжелее предела своего формата — пределы в разделе «Формат» выше |
| 400 | `ICON_TOO_MANY_PIXELS` | Слишком много точек — код приходит на обоих форматах: у растрового изображения при превышении 4 мегапикселей, у SVG при холсте больше 4096×4096 после растеризации |
| 400 | `ICON_UNSUPPORTED_FORMAT` | Формат не распознан по содержимому файла |
| 400 | `ICON_NOT_SVG` | По содержимому это SVG, но ни `Content-Type` не начинается с `image/svg`, ни имя файла не кончается на `.svg`. Тот же код приходит, когда разметка не образует корректный SVG-контейнер |
| 400 | `ICON_RASTERIZE_FAILED` | Формат распознан, но изображение не удалось привести к PNG 256×256 |
| 400 | `ICON_SVG_SCRIPT`, `ICON_SVG_EVENT_HANDLER`, `ICON_SVG_EXTERNAL_REF` и другие коды семейства `ICON_SVG_*` | SVG не прошёл очистку: в нём скрипт, обработчик события, внешняя ссылка или другая запрещённая конструкция. Код называет сработавшую проверку |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 404 | `SERVER_NOT_FOUND` | Сервера с таким `id` нет, он удалён или принадлежит другому API-ключу |
| 429 | `RATE_LIMITED` | Превышен лимит: 10 запросов в минуту на пару «API-ключ и сервер» |
| 502 | `ICON_STORAGE_FAILED` | Иконка прошла проверки, но объектное хранилище её не приняло. Повторите загрузку |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Создание сервера](/docs/infra/servers/create)
- [Deploy API](/docs/infra/deploy)
- [Корневой раздел — Инфраструктура](/docs/infra)