# REST {/* #rest */}

Начните с [Подключения через API](/docs/ru/connect-api), чтобы создать токен API платформы. Публичный базовый URL REST — `https://reconstruct.dev/api/v1/platform`. Приведённые ниже маршруты относительны к нему.

Обнаруживайте типы платформ и окружения через `GET /capture-options`; не фиксируйте ID в коде. Варианты платформ каталога используют `view` для типа (`desktop`/`mobile`) и `implementation` для окружения. Настольная платформа поддерживает `web`, `web-extension`, `macos`, `windows`, `linux`; мобильная — `web`, `ios`, `android`. Перед запросом данных проверяйте `captured` каждого варианта. В MCP поля называются `platform` и `environment`; `view` страницы MCP — точный ключ сохранённого профиля устройства. См. [выбор MCP](/docs/ru/mcp-tools).

Отправляйте `Authorization: Bearer <token>` с каждым запросом. Конечные точки каталогов:

| Метод и путь | Назначение |
|---|---|
| `GET /catalogs?pageSize=10&pageToken=...` | Список каталогов. `pageSize` и `pageToken` необязательны. |
| `GET /capture-options` | Поддерживаемые ID типов платформ, названия, окружения, значения по умолчанию и `requestPlatforms` для отправки запросов. Без аутентификации и учёта использования; содержимого захватов нет. |
| `GET /catalogs/{catalogId}?version=...` | Чтение экранов, платформ, языков и версий опубликованного каталога. |
| `GET /catalogs/{catalogId}/insights?locale=en&view=desktop&implementation=web` | Чтение технологий, способа рендеринга, семейств шрифтов, стилей текста, медиаресурсов и цветовых тем опубликованной версии. |

Ответ JSON использует camelCase. `GET /catalogs` возвращает `catalogs` и, если есть продолжение, `nextPageToken`. Передайте токен как `pageToken` в следующем запросе. Подробности каталога содержат `catalogId`, `name`, `kind` и `description`.

`locale`, `view` и `implementation` необязательны. `view` принимает `desktop` или `mobile`; `implementation` — `web`, `web-extension`, `windows`, `macos`, `linux`, `ios` или `android`. Подробности каталога возвращают доступные сочетания в `platforms[]`; экраны содержат свой `implementation`. Технологии, типографика и медиа ограничены этим сочетанием и языком. `technologyInventory: true` обозначает инвентарь технологий уровня версии, если обнаружение по представлению отсутствует. Веб-захваты на эмулируемом iPhone остаются `mobile` + `web`. Если старый захват не имеет подробностей страниц, ответ использует инвентарь шрифтов и ресурсов уровня версии и возвращает `pageCount: 0`. Ссылки ресурсов сохраняют исходный адрес. Сохранённые ресурсы читаются через описанную ниже файловую операцию.

## Фильтры и версии каталогов {/* #catalog-filters-and-versions */}

`ListCatalogs` принимает `query`, `sort` (`newest`, `name-asc`, `name-desc`, `screens`, `versions`), `screens` (`with`/`without`), `versions` (`single`/`multiple`) и повторяемые `platforms`, `technologies`, `renderings`, `categories`, `languages`. ID фильтра платформы объединяет тип и окружение, например `desktop:web`. Используйте ID из `filters` ответа; варианты внутри фильтра альтернативны, разные фильтры объединяются. При переходе по `nextPageToken` сохраняйте фильтры и сортировку.

`GetCatalog`, `GetCatalogInsights` и `GetCatalogFile` принимают необязательный `version`. Пустое значение выбирает последний опубликованный захват. Подробности возвращают выбранный `version` и все опубликованные `versions[]`; `latestVersion` и `latestCapturedAt` по-прежнему обозначают самый новый захват. Передавайте выбранную версию в последующие вызовы анализа и файлов для согласованности данных. Черновые и неизвестные версии возвращают 404.

Анализ также принимает `section`: `tech stack`, `typography`, `colors`, `themes` или `assets` (опустите для всех). `colorThemes[]` содержит именованные палитры. `platforms[].captured` обозначает доступные варианты платформ; `detectedLocales[]` — обнаруженные языки, `locales[]` — захваченные.

## Измерения компонентов {/* #component-measurements */}

`componentSizing[]` группирует захваченные измерения по семантическому типу компонента. На вкладке компонентов откройте компонент для просмотра снимков, размеров, внутренних отступов, радиусов, границ, теней и состояний взаимодействия. Универсальные контейнеры исключены из измерений компонентов.

`dimensionContexts[]` добавляет принадлежность: тип компонента, CSS-свойство, исходное значение или сокращение, общее количество и до трёх образцов источника. Образцы указывают страницу, представление, путь относительно захвата, ID/тег/подпись исходного элемента, известного родителя и до трёх прямых потомков (`childCount` — общее число). Это исходные ID захвата конкретной страницы/представления/версии, не перенумерованные ID слоёв MCP. Представление образца — точный сохранённый ключ, например `laptop`, а фильтр каталога — `desktop` или `mobile`. Отсутствующие ID равны `-1`. Количества охватывают только захваченные элементы; ни они, ни примеры не означают покрытие всего сайта.

Каталог показывает измерения внутри карточки каждого компонента. Padding находится внутри элемента, margin — вокруг и не обязательно равен расстоянию до соседа. Gap принадлежит контейнерам; перечисленные потомки — примеры, не измеренные соседние пары. Размер описывает сам компонент. Сохраняйте исходные единицы и сокращения. Отдельные инструменты MCP [`get_spacing` и `get_sizing`](/docs/ru/mcp-tools#component-measurements-with-ownership-context) предоставляют постраничный контекст или сводку одной страницы/представления.

Вкладка шрифтов скачивает исходные файлы как ZIP; JSON размеров и использования по языкам формируется из `textStyles[]` и `fonts[].locales`. Эти файлы создаются клиентом, а не отдельными точками `@export`. Обнаруженные языки (`detectedLocales`) не гарантируют наличие их снимков.

## Сохранённые файлы и экспорт {/* #stored-files-and-exports */}

`GET /catalogs/{catalogId}/files/{path}` возвращает JSON `BinaryFileResponse`: `data` — base64, `contentType` описывает декодированные байты. Пути берутся из `screens[]` (`imagePath`, `fullPagePath`, `sectionPaths[]`, `videoPath`, `interactionVideoPath`). Экраны отмечают неполные захваты полем `captureLimited`.

Тот же маршрут принимает `@asset/{hash}`, `@font/{hash}` и `@model/{hash}` для архивных оригиналов; хеш — `SHA-256` исходного URL или data URL в UTF-8, в нижнем шестнадцатеричном регистре. Также поддерживаются `@export/assets`, `@export/fonts`, `@export/colors`, `@export/screenshots`, `@export/components`, `@export/languages`, `@export/technologies` и `@export/spacing-sizing` для ZIP-экспорта. Архив отступов/размеров содержит `spacing-sizing.json` с выбранной версией, числом страниц, агрегированными `dimensions`, `componentSizing` и контекстными `dimensionContexts`. Для файлов и экспорта конкретного захвата используйте `version`. Обычные JSON-файлы захвата эта операция не предоставляет.

## Операции вызывающего пользователя {/* #caller-operations */}

| Метод и путь | Назначение |
|---|---|
| `POST /requests` | Отправьте `requestType: PRODUCT_REQUEST_TYPE_ADD` с `url` и `subject` или `requestType: PRODUCT_REQUEST_TYPE_UPDATE` с `catalogId`. |
| `GET /requests`, `GET /requests/{requestId}` | Постраничное чтение заявок пользователя и проверка решений, безопасности и хода захвата. |
| `GET /me/appearance`, `PUT /me/appearance` | Чтение или изменение псевдонима. |
| `GET /me/avatar`, `PUT /me/avatar`, `DELETE /me/avatar` | Чтение, загрузка (`data` в base64) или удаление аватара. |
| `GET /tokens`, `POST /tokens`, `DELETE /tokens/{id}` | Управление персональными токенами; создание принимает `name`, `scopes` (`api`, `mcp`) и `expiresInDays` (1–365). Секрет возвращается один раз. |
| `GET /me/profile`, `PUT /me/profile` | Чтение или изменение профиля учётной записи (объект `profile`). |
| `GET /me/credentials`, `GET /me/sessions`, `DELETE /me/sessions/{id}` | Просмотр учётных данных/сеансов и завершение сеанса. |

Операции учётной записи, оформления, аватара и управления токенами требуют токен сеанса вошедшего пользователя; персональные токены API их не разрешают. Каталоги и заявки принимают персональный токен с областью `api`. Потоки `WatchCatalogs` и `WatchRequests` доступны через gRPC/gRPC-Web и не имеют REST-маршрута.

## Примеры {/* #examples */}

- [curl](/docs/ru/api/rest/curl)
- [Python](/docs/ru/api/rest/python)
- [C#](/docs/ru/api/rest/csharp)
- [TypeScript](/docs/ru/api/rest/typescript)
- [Go](/docs/ru/api/rest/go)
- [Rust](/docs/ru/api/rest/rust)
- [Java](/docs/ru/api/rest/java)
- [C++](/docs/ru/api/rest/cpp)

Заявки на продукты используют `POST /requests`, `GET /requests` и `GET /requests/{request_id}` с тем же базовым URL. Для `requestType: PRODUCT_REQUEST_TYPE_ADD` нужны `url` и `subject`, `catalogId` необязателен. Для `PRODUCT_REQUEST_TYPE_UPDATE` передайте существующий `catalogId`; сервер определит название и исходный URL. Заявки сохраняются и доступны только владельцу. Перед захватом их рассматривают и могут одобрить или отклонить с причиной. Заведомо небезопасные сайты отклоняются автоматически. REST и gRPC предоставляют одинаковые операции заявок.

## Нормализованные данные интерфейса {/* #normalized-interface-data */}

[Формат данных Scene](/docs/ru/data-format) определяет независимые от платформы артефакты интерфейса, включая состояния, ресурсы и свидетельства. Текущий нормализованный экспорт получается через MCP `get_interface_scene`; API каталогов не определяет отдельную операцию Scene.