REST
Bắt đầu với Kết nối qua 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.
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
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
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 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
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
| 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ụ
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
Định dạng Scene 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.