# REST {/* #rest */}

[API 経由で接続](/docs/ja/connect-api)に従って Platform 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/ja/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 上の 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 を使用してください。同一フィルター内の選択肢は OR、異なるフィルター同士は AND で結合されます。`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` です。件数はキャプチャーされた要素だけを対象とし、件数も例の一覧もサイト全体の網羅を保証しません。

カタログは各コンポーネントの詳細に測定値を表示します。パディングは要素の内側、マージンは周囲の余白であり、必ずしも隣の要素との距離ではありません。ギャップはコンテナーに属します。一覧の子要素は例であり、測定された隣接ペアではありません。サイズはコンポーネント自体を表します。元の単位と短縮記法を維持してください。別の MCP ツール [`get_spacing` と `get_sizing`](/docs/ja/mcp-tools#component-measurements-with-ownership-context)は、1 ページ／ビューのページ分割された文脈または要約を提供します。

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}` を受け付けます。ハッシュは、元の参照 URL またはデータ URL を UTF-8 にしたものの `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` | アバターを読み取り、アップロード（base64 の `data`）、または削除します。 |
| `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/ja/api/rest/curl)
- [Python](/docs/ja/api/rest/python)
- [C#](/docs/ja/api/rest/csharp)
- [TypeScript](/docs/ja/api/rest/typescript)
- [Go](/docs/ja/api/rest/go)
- [Rust](/docs/ja/api/rest/rust)
- [Java](/docs/ja/api/rest/java)
- [C++](/docs/ja/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/ja/data-format)は、状態、リソース、根拠など、プラットフォームに依存しないインターフェースの成果物を定義します。現在の正規化エクスポートは MCP の `get_interface_scene` から取得します。このカタログ API に個別の Scene 操作は定義されていません。