# REST {/* #rest */}

Bắt đầu với [Kết nối qua API](/docs/vi/connect-api) để tạo token API. URL gốc REST công khai là `https://reconstruct.dev/api/v1/platform`. Các tuyến dưới tương đối với URL đó.

Phát hiện loại/môi trường qua `GET /capture-options`; không mã hóa cứng ID. Tùy chọn danh mục dùng `view` cho loại (`desktop`/`mobile`), `implementation` cho môi trường. Desktop hỗ trợ `web`, `web-extension`, `macos`, `windows`, `linux`; mobile hỗ trợ `web`, `ios`, `android`. Kiểm tra `captured` trước khi lấy dữ liệu. Trong MCP, tên là `platform`, `environment`; `view` trang là khóa hồ sơ thiết bị lưu chính xác. Xem [lựa chọn MCP](/docs/vi/mcp-tools).

Gửi `Authorization: Bearer <token>` với mọi yêu cầu. Endpoint danh mục gồm:

| Phương thức và đường dẫn | Mục đích |
|---|---|
| `GET /catalogs?pageSize=10&pageToken=...` | Liệt kê danh mục; `pageSize`, `pageToken` tùy chọn. |
| `GET /capture-options` | ID loại, nhãn, tùy chọn môi trường, mặc định và `requestPlatforms` để gửi yêu cầu. Không xác thực/đo sử dụng; không có nội dung thu thập. |
| `GET /catalogs/{catalogId}?version=...` | Đọc màn hình, nền tảng, ngôn ngữ và phiên bản đã công bố. |
| `GET /catalogs/{catalogId}/insights?locale=en&view=desktop&implementation=web` | Đọc công nghệ, kết xuất, họ phông, kiểu chữ, tài nguyên đa phương tiện và chủ đề màu của phiên bản công bố. |

JSON dùng tên camelCase. `GET /catalogs` trả `catalogs` và `nextPageToken` khi còn kết quả. Truyền token thành `pageToken` ở yêu cầu sau. Chi tiết gồm `catalogId`, `name`, `kind`, `description`.

`locale`, `view`, `implementation` tùy chọn. `view` nhận `desktop`/`mobile`; `implementation` nhận `web`, `web-extension`, `windows`, `macos`, `linux`, `ios`, `android`. Chi tiết trả tổ hợp trong `platforms[]`; màn hình có `implementation` riêng. Công nghệ, kiểu chữ, media thuộc tổ hợp/ngôn ngữ này. `technologyInventory: true` chỉ kho công nghệ cấp phiên bản khi thiếu phát hiện từng view. Web trên iPhone giả lập vẫn là `mobile` + `web`. Bản cũ thiếu chi tiết trang dùng kho phông/tài nguyên cấp phiên bản, trả `pageCount: 0`. Liên kết tài nguyên giữ nguồn gốc; tài nguyên lưu đọc qua thao tác tệp dưới.

## Bộ lọc và phiên bản danh mục {/* #catalog-filters-and-versions */}

`ListCatalogs` nhận `query`, `sort` (`newest`, `name-asc`, `name-desc`, `screens`, `versions`), `screens` (`with`/`without`), `versions` (`single`/`multiple`) và bộ lọc lặp `platforms`, `technologies`, `renderings`, `categories`, `languages`. ID nền tảng kết hợp view/implementation, như `desktop:web`. Dùng ID trong `filters`; tùy chọn cùng bộ lọc là lựa chọn thay thế, bộ lọc khác kết hợp. Giữ lọc/sắp xếp khi theo `nextPageToken`.

`GetCatalog`, `GetCatalogInsights`, `GetCatalogFile` nhận `version` tùy chọn. Rỗng chọn bản công bố mới nhất. Chi tiết trả `version` chọn và toàn bộ `versions[]`; `latestVersion`, `latestCapturedAt` vẫn chỉ mới nhất. Truyền phiên bản chọn cho insight/tệp tiếp theo để nhất quán. Bản nháp/không biết trả 404.

Insight nhận `section`: `tech stack`, `typography`, `colors`, `themes`, `assets` (bỏ để lấy tất cả). `colorThemes[]` chứa bảng màu có tên. `platforms[].captured` chỉ tùy chọn có sẵn; `detectedLocales[]` gồm ngôn ngữ phát hiện, `locales[]` gồm đã thu thập.

## Số đo thành phần {/* #component-measurements */}

`componentSizing[]` nhóm số đo theo loại ngữ nghĩa. Mở thành phần trong tab Components để xem ảnh, kích thước, padding, bo góc, viền, bóng và trạng thái. Không tính container chung.

`dimensionContexts[]` thêm ngữ cảnh sở hữu: loại, thuộc tính CSS, giá trị/cú pháp gốc, tổng và tối đa ba mẫu. Mẫu chỉ trang, view, đường dẫn tương đối, ID/tag/nhãn nguồn, cha biết được và tối đa ba con trực tiếp (`childCount` là tổng). Đây là ID thu thập gốc của trang/view/phiên bản, không phải ID lớp MCP đánh lại. View mẫu là khóa chính xác, như `laptop`; lọc danh mục là `desktop`/`mobile`. ID thiếu là `-1`. Số lượng chỉ bao gồm phần đã thu thập; số lượng/mẫu không hứa phủ toàn trang web.

Danh mục hiển thị số đo trong chi tiết thành phần. Padding bên trong; margin bao quanh, không nhất thiết khoảng cách tới hàng xóm. Gap thuộc container; con liệt kê là ví dụ, không phải cặp kề đo được. Sizing mô tả chính thành phần. Giữ đơn vị/cú pháp gốc. MCP [`get_spacing` và `get_sizing`](/docs/vi/mcp-tools#component-measurements-with-ownership-context) cho ngữ cảnh phân trang/tổng hợp một trang/view.

Tab Fonts tải phông gốc dạng ZIP; JSON kích thước/sử dụng ngôn ngữ suy từ `textStyles[]`, `fonts[].locales`. Đây là tệp tạo phía khách, không phải endpoint `@export` thêm. Ngôn ngữ phát hiện (`detectedLocales`) không bảo đảm có ảnh tương ứng.

## Tệp lưu trữ và xuất {/* #stored-files-and-exports */}

`GET /catalogs/{catalogId}/files/{path}` trả JSON `BinaryFileResponse`: `data` base64, `contentType` mô tả byte giải mã. Đường dẫn từ `screens[]` (`imagePath`, `fullPagePath`, `sectionPaths[]`, `videoPath`, `interactionVideoPath`). `captureLimited` đánh dấu bản chưa đầy đủ.

Tuyến nhận `@asset/{hash}`, `@font/{hash}`, `@model/{hash}` cho bản gốc; hash là `SHA-256` của URL nguồn/data URL UTF-8, dạng hex chữ thường. Nhận thêm `@export/assets`, `@export/fonts`, `@export/colors`, `@export/screenshots`, `@export/components`, `@export/languages`, `@export/technologies`, `@export/spacing-sizing` để trả ZIP. Kho khoảng cách/kích thước có `spacing-sizing.json` với phiên bản, số trang, `dimensions` tổng hợp, `componentSizing`, `dimensionContexts`. Dùng `version` cho bản chọn. Không cung cấp JSON thu thập thông thường qua thao tác này.

## Thao tác của người gọi {/* #caller-operations */}

| Phương thức và đường dẫn | Mục đích |
|---|---|
| `POST /requests` | Gửi `requestType: PRODUCT_REQUEST_TYPE_ADD` với `url`, `subject`, hoặc `requestType: PRODUCT_REQUEST_TYPE_UPDATE` với `catalogId`. |
| `GET /requests`, `GET /requests/{requestId}` | Phân trang yêu cầu của người gọi, xem quyết định, kiểm tra an toàn và tiến độ. |
| `GET /me/appearance`, `PUT /me/appearance` | Đọc/cập nhật biệt danh. |
| `GET /me/avatar`, `PUT /me/avatar`, `DELETE /me/avatar` | Đọc, tải lên (`data` base64), xóa ảnh đại diện. |
| `GET /tokens`, `POST /tokens`, `DELETE /tokens/{id}` | Quản lý token cá nhân; tạo nhận `name`, `scopes` (`api`, `mcp`), `expiresInDays` (1–365). Bí mật chỉ trả một lần. |
| `GET /me/profile`, `PUT /me/profile` | Đọc/cập nhật hồ sơ (đối tượng `profile`). |
| `GET /me/credentials`, `GET /me/sessions`, `DELETE /me/sessions/{id}` | Xem thông tin xác thực/phiên, chấm dứt phiên. |

Tài khoản, giao diện, ảnh và quản lý token cần token phiên người dùng; token API cá nhân không cho phép. Danh mục/yêu cầu chấp nhận token phạm vi `api`. `WatchCatalogs`, `WatchRequests` có qua gRPC/gRPC-Web, không có REST.

## Ví dụ {/* #examples */}

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

Gửi sản phẩm dùng `POST /requests`, `GET /requests`, `GET /requests/{request_id}` dưới cùng URL gốc. `requestType: PRODUCT_REQUEST_TYPE_ADD` cần `url`, `subject`; `catalogId` tùy chọn. `PRODUCT_REQUEST_TYPE_UPDATE` cần `catalogId` hiện có; máy chủ xác định tên/URL. Yêu cầu được lưu, chỉ chủ sở hữu truy cập. Được duyệt trước khi thu thập, có thể chấp thuận/từ chối kèm lý do. Trang không an toàn đã biết tự bị từ chối. REST/gRPC có cùng thao tác.

## Dữ liệu giao diện chuẩn hóa {/* #normalized-interface-data */}

[Định dạng Scene](/docs/vi/data-format) quy định hiện vật giao diện trung lập nền tảng, gồm trạng thái, tài nguyên, bằng chứng. Hiện lấy xuất chuẩn hóa qua MCP `get_interface_scene`; API danh mục không có thao tác Scene riêng.