REST
Platform API 토큰을 만들려면 API로 연결부터 시작하세요. 공개 REST 기본 URL은 https://reconstruct.dev/api/v1/platform입니다. 아래 경로는 이 URL에 대한 상대 경로입니다.
플랫폼 형식과 환경은 GET /capture-options로 검색하고 ID를 하드코딩하지 마세요. 카탈로그 플랫폼 옵션은 플랫폼 형식(desktop/mobile)에 view, 환경에 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 응답은 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처럼 뷰와 구현을 결합합니다. 응답의 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[]는 캡처 측정값을 의미상 컴포넌트 종류별로 묶습니다. Components 탭에서 컴포넌트를 열면 스크린샷, 캡처 크기, 안쪽 여백, 모서리 반경, 테두리, 그림자 및 상호작용 상태를 볼 수 있습니다. 일반 컨테이너는 컴포넌트 측정에서 제외됩니다.
dimensionContexts[]는 소유 관계를 추가합니다. 컴포넌트 종류, CSS 속성, 원본 값/축약형, 총 개수 및 최대 3개의 소스 샘플입니다. 샘플은 페이지, 뷰, 캡처 상대 경로, 소스 요소 ID/태그/레이블, 알려진 부모 및 최대 3개의 직계 자식을 식별합니다(childCount는 전체 자식 수). 이는 해당 페이지/뷰/버전의 원본 캡처 ID이며 재번호된 MCP 레이어 ID가 아닙니다. 샘플 뷰는 laptop처럼 정확한 저장 키이고 카탈로그 필터 뷰는 desktop 또는 mobile입니다. 없는 ID는 -1입니다. 개수는 캡처된 요소만 포함하며 개수나 샘플 목록이 전체 웹사이트 범위를 의미하지 않습니다.
카탈로그는 각 컴포넌트 상세 정보에 측정값을 표시합니다. padding은 요소 안쪽, margin은 바깥쪽이며 반드시 이웃 요소까지의 거리를 뜻하지는 않습니다. gap은 컨테이너에 속합니다. 나열된 자식은 예시이며 측정된 인접 쌍이 아닙니다. 크기는 컴포넌트 자체를 설명합니다. 원래 단위와 축약형을 유지하세요. 별도의 MCP get_spacing 및 get_sizing 도구는 한 페이지/뷰의 페이지별 컨텍스트 또는 요약을 제공합니다.
Fonts 탭은 원본 글꼴 파일을 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}를 받습니다. 해시는 UTF-8 원본 소스 URL 또는 데이터 URL의 SHA-256을 소문자 16진수로 표현한 것입니다. ZIP 내보내기에는 @export/assets, @export/fonts, @export/colors, @export/screenshots, @export/components, @export/languages, @export/technologies, @export/spacing-sizing도 받습니다. 간격/크기 아카이브에는 선택된 버전, 페이지 수, 집계 dimensions, componentSizing, 컨텍스트 dimensionContexts가 든 spacing-sizing.json이 있습니다. 선택한 캡처의 파일 및 내보내기에는 version을 사용하세요. 일반 JSON 캡처 파일은 이 작업으로 공개되지 않습니다.
호출자 작업
| 메서드 및 경로 | 목적 |
|---|---|
POST /requests | url 및 subject와 함께 requestType: PRODUCT_REQUEST_TYPE_ADD를 제출하거나 catalogId와 함께 requestType: PRODUCT_REQUEST_TYPE_UPDATE를 제출하세요. |
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 작업을 정의하지 않습니다.