# REST

Start with [Connect via API](../connect-api.md) to create a Platform API token. The public REST base URL is `https://reconstruct.dev/api/v1/platform`. The routes below are relative to that URL.

Discover platform types and environments with `GET /capture-options`; do not hardcode their IDs.
Catalog platform options use `view` for the platform type (`desktop`/`mobile`)
and `implementation` for its environment. Desktop supports `web`, `macos`,
`windows`, `linux`; mobile supports `web`, `ios`, `android`. Check each option's
`captured` flag before requesting data. In MCP these fields are named `platform`
and `environment`; the MCP page `view` is the exact saved device profile key.
See [MCP selection](../mcp-tools.md).

Send `Authorization: Bearer <token>` with every request. The catalog endpoints are:

| Method and path | Purpose |
|---|---|
| `GET /catalogs?pageSize=10&pageToken=...` | List catalogs. `pageSize` and `pageToken` are optional. |
| `GET /capture-options` | Supported options of platform type IDs, labels, environment options, defaults, and `requestPlatforms` for submission. No authentication or metering; no capture content. |
| `GET /catalogs/{catalogId}?version=...` | Read screens, platforms, languages and versions of a published catalog. |
| `GET /catalogs/{catalogId}/insights?locale=en&view=desktop&implementation=web` | Read technologies, rendering, font families, text styles and media assets and color themes from a published version. |

The JSON response uses camelCase field names. `GET /catalogs` returns `catalogs` and, when more results exist, `nextPageToken`. Pass that token as `pageToken` in the next request. A catalog detail contains `catalogId`, `name`, `kind`, and `description`.

`locale`, `view` and `implementation` are optional. `view` accepts `desktop` or `mobile`; `implementation` accepts `web`, `windows`, `macos`, `linux`, `ios` or `android`. Catalog details return available combinations in `platforms[]`; screens carry their `implementation`. Technologies, typography and media are scoped to this combination and language. `technologyInventory: true` identifies a version-level technology inventory when per-view detection is missing. Web captures on an emulated iPhone remain `mobile` + `web`. If a legacy capture has no page details, the response uses its version-level font and asset inventory and returns `pageCount: 0`. Asset links retain their original source. Saved resources can be read through the file operation below.

## Catalog filters and versions

`ListCatalogs` accepts `query`, `sort` (`newest`, `name-asc`, `name-desc`, `screens`, `versions`), `screens` (`with`/`without`), `versions` (`single`/`multiple`), and repeated `platforms`, `technologies`, `renderings`, `categories`, `languages`. Platform filter IDs combine view and implementation, for example `desktop:web`. Use IDs from the response's `filters`; options within one filter are alternatives, while different filters are combined. Keep filters and sorting unchanged while following `nextPageToken`.

`GetCatalog`, `GetCatalogInsights`, and `GetCatalogFile` accept an optional `version`. Empty selects the latest published capture. Catalog detail returns the selected `version` and all published `versions[]`; `latestVersion` and `latestCapturedAt` still identify the newest capture. Pass the selected version to subsequent insights and file calls for consistent data. Draft and unknown versions return 404.

Insights also accept `section`: `tech stack`, `typography`, `colors`, or `assets` (omit for all). `colorThemes[]` contains named palettes. `platforms[].captured` identifies available platform options; `detectedLocales[]` includes discovered languages, while `locales[]` contains captured languages.

## Stored files and exports

`GET /catalogs/{catalogId}/files/{path}` returns a JSON `BinaryFileResponse`: `data` is base64, `contentType` describes the decoded bytes. Paths come from `screens[]` (`imagePath`, `fullPagePath`, `sectionPaths[]`, `videoPath`, `interactionVideoPath`). Screens flag incomplete captures with `captureLimited`.

The same route accepts `@asset/{hash}`, `@font/{hash}`, and `@model/{hash}` for archived originals; the hash is `SHA-256` of the original source URL or data URL in UTF-8, expressed as lowercase hexadecimal. It also accepts `@export/assets`, `@export/fonts`, and `@export/colors` to return ZIP exports. Use `version` for files and exports from a selected capture. Ordinary JSON capture files are not exposed by this operation.

## Caller operations

| Method and path | Purpose |
|---|---|
| `POST /requests` | Submit `requestType: PRODUCT_REQUEST_TYPE_ADD` with `url` and `subject`, or `requestType: PRODUCT_REQUEST_TYPE_UPDATE` with `catalogId`. |
| `GET /requests`, `GET /requests/{requestId}` | Paginate the caller's submissions and inspect decisions, safety checks and capture progress. |
| `GET /me/appearance`, `PUT /me/appearance` | Read/update the nickname. |
| `GET /me/avatar`, `PUT /me/avatar`, `DELETE /me/avatar` | Read, upload (`data` as base64), or remove the avatar. |
| `GET /tokens`, `POST /tokens`, `DELETE /tokens/{id}` | Manage personal tokens; creation accepts `name`, `scopes` (`api`, `mcp`), and `expiresInDays` (1–365). The secret is returned once. |
| `GET /me/profile`, `PUT /me/profile` | Read/update your account profile (`profile` object). |
| `GET /me/credentials`, `GET /me/sessions`, `DELETE /me/sessions/{id}` | Inspect credentials/sessions and terminate a session. |

Account, appearance, avatar and token-management operations require the signed-in user's session token; personal API tokens do not authorize these operations. Catalogs and requests accept a personal token with the `api` scope. Streaming `WatchCatalogs` and `WatchRequests` are available through gRPC/gRPC-Web and have no REST route.

## Examples

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

Product submissions use `POST /requests`, `GET /requests`, and `GET /requests/{request_id}` under the same base URL. For `requestType: PRODUCT_REQUEST_TYPE_ADD`, creation requires a `url` and `subject`; `catalogId` is optional. For `PRODUCT_REQUEST_TYPE_UPDATE`, provide an existing `catalogId`; the server resolves its name and source URL. Requests are persisted and accessible only to their owner. Requests are reviewed before capture and can be approved or rejected with a reason. Known unsafe sites are automatically rejected. REST and gRPC expose the same request operations.