REST
Начните с Подключения через 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.
Отправляйте 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. Ссылки ресурсов сохраняют исходный адрес. Сохранённые ресурсы читаются через описанную ниже файловую операцию.
Фильтры и версии каталогов
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[] — захваченные.
Измерения компонентов
componentSizing[] группирует захваченные измерения по семантическому типу компонента. На вкладке компонентов откройте компонент для просмотра снимков, размеров, внутренних отступов, радиусов, границ, теней и состояний взаимодействия. Универсальные контейнеры исключены из измерений компонентов.
dimensionContexts[] добавляет принадлежность: тип компонента, CSS-свойство, исходное значение или сокращение, общее количество и до трёх образцов источника. Образцы указывают страницу, представление, путь относительно захвата, ID/тег/подпись исходного элемента, известного родителя и до трёх прямых потомков (childCount — общее число). Это исходные ID захвата конкретной страницы/представления/версии, не перенумерованные ID слоёв MCP. Представление образца — точный сохранённый ключ, например laptop, а фильтр каталога — desktop или mobile. Отсутствующие ID равны -1. Количества охватывают только захваченные элементы; ни они, ни примеры не означают покрытие всего сайта.
Каталог показывает измерения внутри карточки каждого компонента. Padding находится внутри элемента, margin — вокруг и не обязательно равен расстоянию до соседа. Gap принадлежит контейнерам; перечисленные потомки — примеры, не измеренные соседние пары. Размер описывает сам компонент. Сохраняйте исходные единицы и сокращения. Отдельные инструменты MCP get_spacing и get_sizing предоставляют постраничный контекст или сводку одной страницы/представления.
Вкладка шрифтов скачивает исходные файлы как ZIP; JSON размеров и использования по языкам формируется из textStyles[] и fonts[].locales. Эти файлы создаются клиентом, а не отдельными точками @export. Обнаруженные языки (detectedLocales) не гарантируют наличие их снимков.
Сохранённые файлы и экспорт
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-файлы захвата эта операция не предоставляет.
Операции вызывающего пользователя
| Метод и путь | Назначение |
|---|---|
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-маршрута.
Примеры
Заявки на продукты используют 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 предоставляют одинаковые операции заявок.
Нормализованные данные интерфейса
Формат данных Scene определяет независимые от платформы артефакты интерфейса, включая состояния, ресурсы и свидетельства. Текущий нормализованный экспорт получается через MCP get_interface_scene; API каталогов не определяет отдельную операцию Scene.