REST
首先阅读通过 API 连接，创建平台 API 令牌。公共 REST 基础 URL 为 https://reconstruct.dev/api/v1/platform。下方路由均相对于该 URL。
通过 GET /capture-options 发现平台类型和环境；不要硬编码其 ID。目录平台选项使用 view 表示平台类型（desktop/mobile），使用 implementation 表示环境。桌面支持 web、web-extension、macos、windows、linux；移动端支持 web、ios、android。请求数据前，检查各选项的 captured 标记。在 MCP 中，这些字段名为 platform 和 environment；MCP 页面的 view 是已保存设备配置的确切键。参阅 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 响应采用驼峰命名的字段。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 上的 Web 采集仍然是 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。使用响应 filters 中的 ID；同一筛选内的选项是替代关系，不同筛选之间组合生效。按 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，不是重新编号的 MCP 图层 ID。样本视图是确切的存储键（例如 laptop），而目录筛选视图是 desktop 或 mobile。缺失 ID 为 -1。计数仅覆盖已采集元素；计数和示例列表都不表示覆盖整个网站。
目录在各组件详情中展示测量值。内边距位于元素内部；外边距位于周围，不一定等于与邻居的距离。间隙属于容器；列出的子元素只是示例，不是已测量的相邻元素对。尺寸描述组件本身。保留原始单位和简写形式。独立的 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}，用于读取归档原件；哈希是原始来源 URL 或 data URL 按 UTF-8 编码后的 SHA-256，表示为小写十六进制。还接受 @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 路由。
示例
产品提交在相同基础 URL 下使用 POST /requests、GET /requests 和 GET /requests/{request_id}。对于 requestType: PRODUCT_REQUEST_TYPE_ADD，创建需要 url 和 subject；catalogId 可选。对于 PRODUCT_REQUEST_TYPE_UPDATE，提供现有 catalogId；服务器会解析其名称和来源 URL。请求会被持久化，且仅所有者可访问。采集前会审核请求，可批准或附原因拒绝。已知不安全网站会自动被拒绝。REST 和 gRPC 提供相同的请求操作。
标准化界面数据
Scene 数据格式规定了与平台无关的界面制品，包括状态、资源和证据。当前通过 MCP get_interface_scene 获取标准化导出；此目录 API 未定义单独的 Scene 操作。