# REST {/* #rest */}

Empieza por [Conectar mediante API](/docs/es/connect-api) para crear un token API de la plataforma. La URL base REST pública es `https://reconstruct.dev/api/v1/platform`. Las rutas siguientes son relativas a esa URL.

Descubre tipos de plataforma y entornos con `GET /capture-options`; no fijes sus ID en el código. Las opciones de plataforma del catálogo usan `view` para el tipo (`desktop`/`mobile`) e `implementation` para su entorno. Escritorio admite `web`, `web-extension`, `macos`, `windows`, `linux`; móvil admite `web`, `ios`, `android`. Comprueba `captured` de cada opción antes de solicitar datos. En MCP estos campos se llaman `platform` y `environment`; `view` de página MCP es la clave exacta del perfil de dispositivo guardado. Consulta la [selección MCP](/docs/es/mcp-tools).

Envía `Authorization: Bearer <token>` con cada solicitud. Los endpoints de catálogo son:

| Método y ruta | Finalidad |
|---|---|
| `GET /catalogs?pageSize=10&pageToken=...` | Listar catálogos. `pageSize` y `pageToken` son opcionales. |
| `GET /capture-options` | Opciones admitidas de ID de tipo de plataforma, etiquetas, entornos, valores predeterminados y `requestPlatforms` para enviar solicitudes. Sin autenticación ni medición; no incluye contenido de captura. |
| `GET /catalogs/{catalogId}?version=...` | Leer pantallas, plataformas, idiomas y versiones de un catálogo publicado. |
| `GET /catalogs/{catalogId}/insights?locale=en&view=desktop&implementation=web` | Leer tecnologías, renderizado, familias tipográficas, estilos de texto, recursos multimedia y temas de color de una versión publicada. |

La respuesta JSON utiliza nombres de campo camelCase. `GET /catalogs` devuelve `catalogs` y, si hay más resultados, `nextPageToken`. Pasa ese token como `pageToken` en la siguiente solicitud. Un detalle de catálogo contiene `catalogId`, `name`, `kind` y `description`.

`locale`, `view` e `implementation` son opcionales. `view` acepta `desktop` o `mobile`; `implementation` acepta `web`, `web-extension`, `windows`, `macos`, `linux`, `ios` o `android`. El detalle devuelve combinaciones disponibles en `platforms[]`; las pantallas incluyen su `implementation`. Tecnologías, tipografía y medios se limitan a esa combinación e idioma. `technologyInventory: true` identifica un inventario tecnológico de versión cuando falta detección por vista. Las capturas web en un iPhone emulado siguen siendo `mobile` + `web`. Si una captura heredada no tiene detalles de página, la respuesta utiliza el inventario de fuentes y recursos de versión y devuelve `pageCount: 0`. Los enlaces de recursos conservan su origen. Los recursos guardados se leen mediante la operación de archivos siguiente.

## Filtros y versiones de catálogo {/* #catalog-filters-and-versions */}

`ListCatalogs` acepta `query`, `sort` (`newest`, `name-asc`, `name-desc`, `screens`, `versions`), `screens` (`with`/`without`), `versions` (`single`/`multiple`) y los filtros repetidos `platforms`, `technologies`, `renderings`, `categories`, `languages`. Los ID de filtro de plataforma combinan vista e implementación, por ejemplo `desktop:web`. Usa los ID de `filters` de la respuesta; las opciones de un filtro son alternativas, mientras que filtros distintos se combinan. Mantén filtros y ordenación al seguir `nextPageToken`.

`GetCatalog`, `GetCatalogInsights` y `GetCatalogFile` aceptan `version` opcional. Vacío selecciona la última captura publicada. El detalle devuelve la `version` seleccionada y todas las `versions[]` publicadas; `latestVersion` y `latestCapturedAt` siguen identificando la más reciente. Pasa la versión seleccionada a las llamadas posteriores de insights y archivos para mantener datos coherentes. Las versiones borrador o desconocidas devuelven 404.

Los insights también aceptan `section`: `tech stack`, `typography`, `colors`, `themes` o `assets` (omítelo para todos). `colorThemes[]` contiene paletas con nombre. `platforms[].captured` identifica opciones disponibles; `detectedLocales[]` contiene idiomas descubiertos y `locales[]`, idiomas capturados.

## Mediciones de componentes {/* #component-measurements */}

`componentSizing[]` agrupa mediciones capturadas por tipo semántico de componente. En la pestaña Componentes, abre uno para inspeccionar capturas de pantalla, tamaños, relleno, radio de esquina, bordes, sombras y estados de interacción. Los contenedores genéricos se excluyen de estas mediciones.

`dimensionContexts[]` añade pertenencia: tipo de componente, propiedad CSS, valor o abreviatura original, recuento total y hasta tres muestras de origen. Las muestras identifican página, vista, ruta relativa a la captura, ID/etiqueta/texto del elemento fuente, padre conocido y hasta tres hijos directos (`childCount` da el total). Son ID de captura sin procesar de esa página/vista/versión, no ID de capa MCP renumerados. La vista de muestra es la clave almacenada exacta (por ejemplo `laptop`), mientras que la vista de filtro del catálogo es `desktop` o `mobile`. Los ID ausentes son `-1`. Los recuentos solo abarcan elementos capturados; ni los recuentos ni los ejemplos afirman cubrir todo el sitio.

El catálogo presenta las mediciones dentro del detalle de cada componente. El relleno está dentro del elemento; el margen, alrededor, y no es necesariamente la distancia al vecino. Las separaciones pertenecen a contenedores; los hijos listados son ejemplos, no pares adyacentes medidos. El tamaño describe el propio componente. Conserva unidades y abreviaturas originales. Las herramientas MCP independientes [`get_spacing` y `get_sizing`](/docs/es/mcp-tools#component-measurements-with-ownership-context) ofrecen contexto paginado o resumen de una página/vista.

La pestaña Fuentes descarga archivos originales como ZIP; las descargas JSON de tamaños y uso por idioma se derivan de `textStyles[]` y `fonts[].locales`. Son archivos generados por el cliente, no endpoints `@export` adicionales. Los idiomas descubiertos (`detectedLocales`) no garantizan capturas de pantalla en esos idiomas.

## Archivos almacenados y exportaciones {/* #stored-files-and-exports */}

`GET /catalogs/{catalogId}/files/{path}` devuelve un JSON `BinaryFileResponse`: `data` es base64 y `contentType` describe los bytes decodificados. Las rutas proceden de `screens[]` (`imagePath`, `fullPagePath`, `sectionPaths[]`, `videoPath`, `interactionVideoPath`). Las pantallas indican capturas incompletas con `captureLimited`.

La misma ruta acepta `@asset/{hash}`, `@font/{hash}` y `@model/{hash}` para originales archivados; el hash es el `SHA-256` de la URL de origen o URL de datos original en UTF-8, expresado en hexadecimal minúsculo. También acepta `@export/assets`, `@export/fonts`, `@export/colors`, `@export/screenshots`, `@export/components`, `@export/languages`, `@export/technologies` y `@export/spacing-sizing` para devolver ZIP. El archivo de espaciado/tamaños contiene `spacing-sizing.json` con la versión seleccionada, recuento de páginas, `dimensions` agregadas, `componentSizing` y `dimensionContexts` contextuales. Utiliza `version` para archivos y exportaciones de una captura concreta. Esta operación no expone archivos JSON de captura ordinarios.

## Operaciones del llamante {/* #caller-operations */}

| Método y ruta | Finalidad |
|---|---|
| `POST /requests` | Envía `requestType: PRODUCT_REQUEST_TYPE_ADD` con `url` y `subject`, o `requestType: PRODUCT_REQUEST_TYPE_UPDATE` con `catalogId`. |
| `GET /requests`, `GET /requests/{requestId}` | Paginar los envíos del llamante e inspeccionar decisiones, comprobaciones de seguridad y progreso de captura. |
| `GET /me/appearance`, `PUT /me/appearance` | Leer o actualizar el apodo. |
| `GET /me/avatar`, `PUT /me/avatar`, `DELETE /me/avatar` | Leer, subir (`data` en base64) o eliminar el avatar. |
| `GET /tokens`, `POST /tokens`, `DELETE /tokens/{id}` | Gestionar tokens personales; la creación acepta `name`, `scopes` (`api`, `mcp`) y `expiresInDays` (1–365). El secreto se devuelve una sola vez. |
| `GET /me/profile`, `PUT /me/profile` | Leer o actualizar el perfil de cuenta (objeto `profile`). |
| `GET /me/credentials`, `GET /me/sessions`, `DELETE /me/sessions/{id}` | Inspeccionar credenciales/sesiones y finalizar una sesión. |

Las operaciones de cuenta, apariencia, avatar y gestión de tokens requieren el token de sesión del usuario conectado; los tokens API personales no las autorizan. Catálogos y solicitudes aceptan un token personal con ámbito `api`. Los flujos `WatchCatalogs` y `WatchRequests` están disponibles mediante gRPC/gRPC-Web y no tienen ruta REST.

## Ejemplos {/* #examples */}

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

Los envíos de productos utilizan `POST /requests`, `GET /requests` y `GET /requests/{request_id}` bajo la misma URL base. Para `requestType: PRODUCT_REQUEST_TYPE_ADD`, la creación requiere `url` y `subject`; `catalogId` es opcional. Para `PRODUCT_REQUEST_TYPE_UPDATE`, facilita un `catalogId` existente; el servidor resuelve su nombre y URL de origen. Las solicitudes se guardan y solo su propietario puede acceder a ellas. Se revisan antes de capturar y pueden aprobarse o rechazarse con un motivo. Los sitios inseguros conocidos se rechazan automáticamente. REST y gRPC exponen las mismas operaciones de solicitud.

## Datos de interfaz normalizados {/* #normalized-interface-data */}

El [formato de datos Scene](/docs/es/data-format) especifica artefactos de interfaz independientes de la plataforma, incluidos estados, recursos y pruebas. La exportación normalizada actual se obtiene mediante MCP `get_interface_scene`; esta API de catálogo no define una operación Scene independiente.