REST
Empieza por Conectar mediante 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.
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
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
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 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
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
| 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
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
El formato de datos Scene 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.