# REST {/* #rest */}

Platform API 토큰을 만들려면 [API로 연결](/docs/ko/connect-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 선택](/docs/ko/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 응답은 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`을 반환합니다. 에셋 링크는 원본 소스를 유지합니다. 저장된 리소스는 아래 파일 작업으로 읽을 수 있습니다.

## 카탈로그 필터 및 버전 {/* #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[]`는 캡처 측정값을 의미상 컴포넌트 종류별로 묶습니다. Components 탭에서 컴포넌트를 열면 스크린샷, 캡처 크기, 안쪽 여백, 모서리 반경, 테두리, 그림자 및 상호작용 상태를 볼 수 있습니다. 일반 컨테이너는 컴포넌트 측정에서 제외됩니다.

`dimensionContexts[]`는 소유 관계를 추가합니다. 컴포넌트 종류, CSS 속성, 원본 값/축약형, 총 개수 및 최대 3개의 소스 샘플입니다. 샘플은 페이지, 뷰, 캡처 상대 경로, 소스 요소 ID/태그/레이블, 알려진 부모 및 최대 3개의 직계 자식을 식별합니다(`childCount`는 전체 자식 수). 이는 해당 페이지/뷰/버전의 원본 캡처 ID이며 재번호된 MCP 레이어 ID가 아닙니다. 샘플 뷰는 `laptop`처럼 정확한 저장 키이고 카탈로그 필터 뷰는 `desktop` 또는 `mobile`입니다. 없는 ID는 `-1`입니다. 개수는 캡처된 요소만 포함하며 개수나 샘플 목록이 전체 웹사이트 범위를 의미하지 않습니다.

카탈로그는 각 컴포넌트 상세 정보에 측정값을 표시합니다. padding은 요소 안쪽, margin은 바깥쪽이며 반드시 이웃 요소까지의 거리를 뜻하지는 않습니다. gap은 컨테이너에 속합니다. 나열된 자식은 예시이며 측정된 인접 쌍이 아닙니다. 크기는 컴포넌트 자체를 설명합니다. 원래 단위와 축약형을 유지하세요. 별도의 MCP [`get_spacing` 및 `get_sizing`](/docs/ko/mcp-tools#component-measurements-with-ownership-context) 도구는 한 페이지/뷰의 페이지별 컨텍스트 또는 요약을 제공합니다.

Fonts 탭은 원본 글꼴 파일을 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}`를 받습니다. 해시는 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 캡처 파일은 이 작업으로 공개되지 않습니다.

## 호출자 작업 {/* #caller-operations */}

| 메서드 및 경로 | 목적 |
|---|---|
| `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 경로는 없습니다.

## 예시 {/* #examples */}

- [curl](/docs/ko/api/rest/curl)
- [Python](/docs/ko/api/rest/python)
- [C#](/docs/ko/api/rest/csharp)
- [TypeScript](/docs/ko/api/rest/typescript)
- [Go](/docs/ko/api/rest/go)
- [Rust](/docs/ko/api/rest/rust)
- [Java](/docs/ko/api/rest/java)
- [C++](/docs/ko/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/ko/data-format)은 상태, 리소스 및 증거를 포함하는 플랫폼 중립 인터페이스 아티팩트를 정의합니다. 현재 정규화된 내보내기는 MCP `get_interface_scene`으로 얻으며 이 카탈로그 API는 별도 Scene 작업을 정의하지 않습니다.