# REST {/* #rest */}

Mulai dari [hubungkan melalui API](/docs/id/connect-api) untuk membuat token Platform API. URL dasar REST publik adalah `https://reconstruct.dev/api/v1/platform`. Rute di bawah relatif terhadap URL itu.

Temukan jenis platform dan lingkungan dengan `GET /capture-options`; jangan hardcode ID-nya. Opsi platform katalog memakai `view` untuk jenis platform (`desktop`/`mobile`) dan `implementation` untuk lingkungan. Desktop mendukung `web`, `web-extension`, `macos`, `windows`, `linux`; mobile mendukung `web`, `ios`, `android`. Periksa penanda `captured` tiap opsi sebelum meminta data. Dalam MCP kolom ini bernama `platform` dan `environment`; `view` halaman MCP adalah kunci profil perangkat tersimpan yang tepat. Lihat [pemilihan MCP](/docs/id/mcp-tools).

Kirim `Authorization: Bearer <token>` pada setiap permintaan. Endpoint katalog adalah:

| Metode dan jalur | Tujuan |
|---|---|
| `GET /catalogs?pageSize=10&pageToken=...` | Daftar katalog. `pageSize` dan `pageToken` opsional. |
| `GET /capture-options` | Opsi yang didukung untuk ID jenis platform, label, lingkungan, default, dan `requestPlatforms` untuk pengajuan. Tanpa autentikasi atau pengukuran penggunaan; tanpa konten tangkapan. |
| `GET /catalogs/{catalogId}?version=...` | Baca layar, platform, bahasa, dan versi katalog yang diterbitkan. |
| `GET /catalogs/{catalogId}/insights?locale=en&view=desktop&implementation=web` | Baca teknologi, rendering, keluarga font, gaya teks, aset media, dan tema warna dari versi terbitan. |

Respons JSON memakai nama kolom camelCase. `GET /catalogs` mengembalikan `catalogs` dan, jika masih ada hasil, `nextPageToken`. Berikan token itu sebagai `pageToken` pada permintaan berikutnya. Detail katalog berisi `catalogId`, `name`, `kind`, dan `description`.

`locale`, `view`, dan `implementation` opsional. `view` menerima `desktop` atau `mobile`; `implementation` menerima `web`, `web-extension`, `windows`, `macos`, `linux`, `ios`, atau `android`. Detail katalog mengembalikan kombinasi yang tersedia dalam `platforms[]`; layar menyertakan `implementation` masing-masing. Teknologi, tipografi, dan media dibatasi pada kombinasi dan bahasa tersebut. `technologyInventory: true` mengidentifikasi inventaris teknologi tingkat versi ketika deteksi per tampilan tidak ada. Tangkapan Web pada iPhone emulasi tetap `mobile` + `web`. Jika tangkapan lama tidak memiliki detail halaman, respons memakai inventaris font dan aset tingkat versi serta mengembalikan `pageCount: 0`. Tautan aset mempertahankan sumber asli. Sumber daya tersimpan dapat dibaca melalui operasi berkas di bawah.

## Filter dan versi katalog {/* #catalog-filters-and-versions */}

`ListCatalogs` menerima `query`, `sort` (`newest`, `name-asc`, `name-desc`, `screens`, `versions`), `screens` (`with`/`without`), `versions` (`single`/`multiple`), dan `platforms`, `technologies`, `renderings`, `categories`, `languages` berulang. ID filter platform menggabungkan view dan implementation, misalnya `desktop:web`. Gunakan ID dari `filters` pada respons; opsi dalam satu filter merupakan alternatif, sedangkan filter berbeda digabungkan. Pertahankan filter dan pengurutan saat mengikuti `nextPageToken`.

`GetCatalog`, `GetCatalogInsights`, dan `GetCatalogFile` menerima `version` opsional. Kosong memilih tangkapan terbitan terbaru. Detail katalog mengembalikan `version` terpilih dan semua `versions[]` terbitan; `latestVersion` dan `latestCapturedAt` tetap mengidentifikasi tangkapan terbaru. Berikan versi terpilih pada panggilan insight dan berkas berikutnya agar datanya konsisten. Draf dan versi tidak dikenal mengembalikan 404.

Insight juga menerima `section`: `tech stack`, `typography`, `colors`, `themes`, atau `assets` (hilangkan untuk semua). `colorThemes[]` berisi palet bernama. `platforms[].captured` mengidentifikasi opsi platform yang tersedia; `detectedLocales[]` menyertakan bahasa yang ditemukan, sedangkan `locales[]` berisi bahasa yang ditangkap.

## Pengukuran komponen {/* #component-measurements */}

`componentSizing[]` mengelompokkan pengukuran tangkapan menurut jenis komponen semantis. Pada tab Components, buka komponen untuk memeriksa tangkapan layar, ukuran, padding, radius sudut, batas, bayangan, dan status interaksinya yang ditangkap. Kontainer generik dikecualikan dari pengukuran komponen.

`dimensionContexts[]` menambahkan kepemilikan: jenis komponen, properti CSS, nilai/bentuk singkat asli, jumlah total, dan maksimal tiga sampel sumber. Sampel mengidentifikasi halaman, tampilan, jalur relatif tangkapan, ID/tag/label elemen sumber, induk yang diketahui, dan maksimal tiga anak langsung (`childCount` memberi jumlah totalnya). Ini ID tangkapan mentah untuk halaman/tampilan/versi tertentu, bukan ID lapisan MCP yang dinomori ulang. Tampilan sampel adalah kunci tersimpan persis (misalnya `laptop`), sedangkan view filter katalog adalah `desktop` atau `mobile`. ID yang tidak ada bernilai `-1`. Jumlah hanya mencakup elemen yang ditangkap; jumlah maupun daftar contoh tidak mengklaim cakupan seluruh situs.

Katalog menyajikan pengukuran dalam detail setiap komponen. Padding berada di dalam elemen; margin di sekelilingnya, belum tentu jarak ke tetangga. Gap milik kontainer; anak yang terdaftar adalah contoh, bukan pasangan bersebelahan yang diukur. Ukuran menjelaskan komponennya sendiri. Pertahankan satuan dan bentuk singkat asli. Alat MCP terpisah [`get_spacing` dan `get_sizing`](/docs/id/mcp-tools#component-measurements-with-ownership-context) menawarkan konteks dipaginasi atau ringkasan untuk satu halaman/tampilan.

Tab Fonts mengunduh berkas font asli sebagai ZIP; unduhan JSON ukuran dan penggunaan bahasanya diturunkan dari `textStyles[]` dan `fonts[].locales`. Itu berkas yang dibuat klien, bukan endpoint `@export` tambahan. Bahasa yang ditemukan (`detectedLocales`) tidak menjamin tangkapan layar bahasa tersebut direkam.

## Berkas tersimpan dan ekspor {/* #stored-files-and-exports */}

`GET /catalogs/{catalogId}/files/{path}` mengembalikan JSON `BinaryFileResponse`: `data` berupa base64, `contentType` menjelaskan byte yang didekodekan. Jalur berasal dari `screens[]` (`imagePath`, `fullPagePath`, `sectionPaths[]`, `videoPath`, `interactionVideoPath`). Layar menandai tangkapan tidak lengkap dengan `captureLimited`.

Rute yang sama menerima `@asset/{hash}`, `@font/{hash}`, dan `@model/{hash}` untuk arsip asli; hash adalah `SHA-256` dari URL sumber asli atau URL data dalam UTF-8, dinyatakan sebagai heksadesimal huruf kecil. Rute juga menerima `@export/assets`, `@export/fonts`, `@export/colors`, `@export/screenshots`, `@export/components`, `@export/languages`, `@export/technologies`, dan `@export/spacing-sizing` untuk mengembalikan ekspor ZIP. Arsip jarak/ukuran berisi `spacing-sizing.json` dengan versi terpilih, jumlah halaman, agregat `dimensions`, `componentSizing`, dan `dimensionContexts` kontekstual. Gunakan `version` untuk berkas dan ekspor dari tangkapan terpilih. Berkas JSON tangkapan biasa tidak diekspos oleh operasi ini.

## Operasi pemanggil {/* #caller-operations */}

| Metode dan jalur | Tujuan |
|---|---|
| `POST /requests` | Kirim `requestType: PRODUCT_REQUEST_TYPE_ADD` dengan `url` dan `subject`, atau `requestType: PRODUCT_REQUEST_TYPE_UPDATE` dengan `catalogId`. |
| `GET /requests`, `GET /requests/{requestId}` | Paginasi pengajuan pemanggil dan periksa keputusan, pemeriksaan keamanan, serta progres tangkapan. |
| `GET /me/appearance`, `PUT /me/appearance` | Baca/perbarui nama panggilan. |
| `GET /me/avatar`, `PUT /me/avatar`, `DELETE /me/avatar` | Baca, unggah (`data` sebagai base64), atau hapus avatar. |
| `GET /tokens`, `POST /tokens`, `DELETE /tokens/{id}` | Kelola token pribadi; pembuatan menerima `name`, `scopes` (`api`, `mcp`), dan `expiresInDays` (1–365). Rahasia dikembalikan sekali. |
| `GET /me/profile`, `PUT /me/profile` | Baca/perbarui profil akun Anda (objek `profile`). |
| `GET /me/credentials`, `GET /me/sessions`, `DELETE /me/sessions/{id}` | Periksa kredensial/sesi dan akhiri sesi. |

Operasi akun, tampilan, avatar, dan pengelolaan token memerlukan token sesi pengguna yang masuk; token API pribadi tidak mengizinkan operasi ini. Katalog dan permintaan menerima token pribadi bercakupan `api`. Aliran `WatchCatalogs` dan `WatchRequests` tersedia melalui gRPC/gRPC-Web dan tidak memiliki rute REST.

## Contoh {/* #examples */}

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

Pengajuan produk memakai `POST /requests`, `GET /requests`, dan `GET /requests/{request_id}` pada URL dasar yang sama. Untuk `requestType: PRODUCT_REQUEST_TYPE_ADD`, pembuatan memerlukan `url` dan `subject`; `catalogId` opsional. Untuk `PRODUCT_REQUEST_TYPE_UPDATE`, berikan `catalogId` yang ada; server menentukan nama dan URL sumber. Permintaan disimpan dan hanya dapat diakses pemiliknya. Permintaan ditinjau sebelum tangkapan dan dapat disetujui atau ditolak dengan alasan. Situs yang diketahui tidak aman ditolak otomatis. REST dan gRPC mengekspos operasi permintaan yang sama.

## Data antarmuka ternormalisasi {/* #normalized-interface-data */}

[Format data Scene](/docs/id/data-format) menentukan artefak antarmuka netral platform, termasuk status, sumber daya, dan bukti. Ekspor ternormalisasi saat ini diperoleh melalui MCP `get_interface_scene`; API katalog ini tidak mendefinisikan operasi Scene terpisah.