# REST {/* #rest */}

首先阅读[通过 API 连接](/docs/zh/connect-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 选择](/docs/zh/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 响应采用驼峰命名的字段。`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`。资源链接保留原始来源。保存的资源可通过下述文件操作读取。

## 目录筛选和版本 {/* #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`。使用响应 `filters` 中的 ID；同一筛选内的选项是替代关系，不同筛选之间组合生效。按 `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，不是重新编号的 MCP 图层 ID。样本视图是确切的存储键（例如 `laptop`），而目录筛选视图是 `desktop` 或 `mobile`。缺失 ID 为 `-1`。计数仅覆盖已采集元素；计数和示例列表都不表示覆盖整个网站。

目录在各组件详情中展示测量值。内边距位于元素内部；外边距位于周围，不一定等于与邻居的距离。间隙属于容器；列出的子元素只是示例，不是已测量的相邻元素对。尺寸描述组件本身。保留原始单位和简写形式。独立的 MCP [`get_spacing` 和 `get_sizing`](/docs/zh/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}`，用于读取归档原件；哈希是原始来源 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 采集文件。

## 调用方操作 {/* #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/zh/api/rest/curl)
- [Python](/docs/zh/api/rest/python)
- [C#](/docs/zh/api/rest/csharp)
- [TypeScript](/docs/zh/api/rest/typescript)
- [Go](/docs/zh/api/rest/go)
- [Rust](/docs/zh/api/rest/rust)
- [Java](/docs/zh/api/rest/java)
- [C++](/docs/zh/api/rest/cpp)

产品提交在相同基础 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 提供相同的请求操作。

## 标准化界面数据 {/* #normalized-interface-data */}

[Scene 数据格式](/docs/zh/data-format)规定了与平台无关的界面制品，包括状态、资源和证据。当前通过 MCP `get_interface_scene` 获取标准化导出；此目录 API 未定义单独的 Scene 操作。