Skip to main content

​
Requisitos

  • Node.js 14+ (sin dependencias externas)
  • Cuenta activa en app.puente.xyz
  • Una Platform API Key (puente_studio_xxx) generada desde Configuración

​
1. Generar tu STUDIO_KEY

1

Entra a app.puente.xyz

Inicia sesión con tu cuenta del workspace.
2

Configuración → Puente Studio Key

En el menú lateral o desde tu avatar → Configuración → Puente Studio Key → Nueva API Key.El formato es puente_studio_xxxxxxxxxxxxxxxxxxxx.
3

Cópiala y guárdala segura

Esta es tu credencial maestra. No la commitees en ningún repo. La key solo se muestra una vez.
La STUDIO_KEY da acceso completo a todos los artefactos y tablas de tu equipo. Trata esta key como tratarías una password de admin.

​
2. Clonar el repo

git clone https://github.com/octaviofv/puente_studio_repo.git
cd puente_studio_repo

​
Estructura

puente_studio_repo/
├── .env.example              Plantilla de variables de entorno
├── .env                      Tu config local (NO commitear)
├── README.md
├── skill_puente_studio.md    Documentacion del agente
└── APP/
    ├── files/                Archivos fuente de la app (editar aqui)
    ├── json_result/          JSONs de salida (generados)
    ├── output.json           JSON listo para subir a la API
    ├── pull_artefacto.js     ⬇  API → archivos locales
    └── files_to_json.js      ⬆  Archivos locales → JSON de la API

​
3. Configurar tu .env

cp .env.example .env
Edita .env con tu key:
.env
BASE_URL=https://puente-backend-721178029791.southamerica-west1.run.app/
STUDIO_KEY=puente_studio_xxxxxxxxxxxxxxxxxxxx
El BASE_URL del ejemplo es el correcto. No lo cambies salvo que estés en un environment privado.

​
4. Verificar que funciona

Lista tus artefactos: 
curl -H "X-API-Key: $(grep STUDIO_KEY .env | cut -d= -f2)" \
  "$(grep BASE_URL .env | cut -d= -f2)studio/artefactos"
Si recibes un JSON con un array de artefactos (puede estar vacío si todavía no creaste ninguno), todo está correcto.
Si recibes 401, la STUDIO_KEY es inválida o está revocada — genera una nueva.

​
Editar una app existente

1

Bajar el artefacto a tu disco

node APP/pull_artefacto.js <id>
Esto descarga el app_content a APP/files/.
2

Editar los archivos

Modifica los archivos en APP/files/ con tu editor (VSCode, vim, Cursor, etc.).
3

Empaquetar el resultado

node APP/files_to_json.js
Genera APP/output.json listo para subir.
4

Subir los cambios

curl -X PUT "$BASE_URL/studio/artefactos/<id>" \
  -H "X-API-Key: $STUDIO_KEY" \
  -H "Content-Type: application/json" \
  -d @APP/output.json
El PUT reemplaza todo el app_content. Siempre usa el flujo completo: GET → editar → PUT con todo. Nunca subas solo los archivos modificados — los que falten se eliminan.

​
Crear una app nueva

curl -X POST "$BASE_URL/studio/artefactos" \
  -H "X-API-Key: $STUDIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Mi nueva app",
    "descripcion": "Demo",
    "app_content": {
      "index.tsx": {
        "content": "import React from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport App from \"./App\";\n\ncreateRoot(document.getElementById(\"root\")!).render(<App />);",
        "type": "tsx"
      },
      "App.tsx": {
        "content": "export default function App() { return <h1>Hola</h1>; }",
        "type": "tsx"
      }
    }
  }'
La respuesta incluye id, public_id y api_key. Guárdalas inmediatamente — la api_key no se vuelve a mostrar.

​
Configurar git para no commitear el .env

El .env está en .gitignore del repo. Igual verifica: 
grep .env .gitignore
Si no aparece, agrégalo: 
echo ".env" >> .gitignore

​
Errores comunes

Si el archivo todavía tiene {STUDIO_KEY} literal en vez de tu key real, ningún script va a funcionar. Pega tu key real sin las llaves.
Tres causas comunes:
  1. La key está revocada → regenera una nueva en Configuración
  2. Estás usando una api_key de artefacto (puente_artifact_xxx) en endpoints privados → usa la STUDIO_KEY
  3. La key pertenece a otro environment → verifica el BASE_URL
El ID no existe en tu equipo, o pertenece a otro equipo. Verifica con GET /studio/artefactos (lista solo los del equipo asociado a tu key).
Hiciste un PUT con app_content parcial. El endpoint reemplaza el objeto completo. Si tienes copia local, vuelve a empaquetar todos los archivos y haz otro PUT. Si no, baja el artefacto a tu disco antes de futuros cambios.

​
Siguiente paso

Usar con coding agents

Pegar el skill en Claude Code o Cursor para automatizar todo el flujo.

Referencia de API

Todos los endpoints con request y response.