Docs

Versiones y source maps

Registra una versión con lo que cambió en ella, y sube sus source maps para que las pilas muestren tus propios archivos y líneas.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. El objeto versión
  2. Listar versiones
  3. Crear o actualizar una versión
  4. Traer una versión
  5. Listar los source maps de una versión
  6. Subir source maps
  7. Borrar los source maps de una versión

Una versión (release) es una versión de tu app. Su version es la cadena que tu SDK envía como release: usa el commit corto de git (4f2a91c). Una versión se crea sola la primera vez que un evento trae un nombre nuevo. Créala tú, desde tu build, para agregar lo que el motor no puede saber: el commit, la versión anterior y lo que cambió. Eso es lo que le permite al agente decir «desde el cambio de ayer» y nombrar el cambio.

Los source maps convierten checkout-3f9c.js:1:48211 en src/checkout/checkout.tsx:142. Súbelos durante tu build y luego bórralos de lo que publicas. El comando sypnia sourcemaps upload hace todo; mira la referencia de la CLI.

Estos endpoints escriben, así que necesitan un token de API con el permiso admin. Guarda ese token en los secretos de tu CI.

El objeto versión

Campos

  • version
    string opcional

    El nombre de la versión. Único por proyecto y entorno.

  • environment
    string opcional
  • deployed_at
    timestamp o null opcional

    Cuándo salió, según dijiste. null para una versión que el motor solo conoció por los eventos.

  • first_seen
    timestamp o null opcional

    El primer evento que la trajo.

  • last_seen
    timestamp o null opcional
  • commit
    string o null opcional
  • previous_version
    string o null opcional
  • repository
    string o null opcional
  • source_maps
    object opcional

    Cuántos mapas se registraron y cuántos llegaron.

  • new_problems
    integer opcional

    Problemas que se vieron por primera vez en esta versión.

  • sessions
    integer opcional

    Sesiones que corrieron en ella.

  • changes
    object o null opcional

    Lo que cambió, tal como se envió, o leído de GitHub en Sypnia Cloud. null cuando no se sabe. No viene en las listas.

Listar versiones

GET /v1/releases MotorNube

Las versiones del proyecto, la más nueva primero, cada una con cuántos problemas se vieron por primera vez en ella.

Autenticación
Token de API (read)

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

  • environment
    string opcional

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Solo versiones vistas por primera vez o desplegadas después de este momento.

    Por defecto: 90d

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/releases" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

JSON
{
  "data": [
    {
      "version": "4f2a91c",
      "environment": "production",
      "deployed_at": "2026-03-11T18:40:00Z",
      "first_seen": "2026-03-11T18:41:12Z",
      "last_seen": "2026-03-12T10:31:58Z",
      "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
      "previous_version": "9c1e7b2",
      "repository": "https://github.com/acme/shop",
      "source_maps": {
        "files": 42,
        "uploaded": 42
      },
      "new_problems": 1,
      "sessions": 131
    },
    {
      "version": "9c1e7b2",
      "environment": "production",
      "deployed_at": "2026-03-09T15:12:00Z",
      "first_seen": "2026-03-09T15:13:40Z",
      "last_seen": "2026-03-12T02:10:07Z",
      "commit": "9c1e7b2a9f0b4c2d1e6f5a7b8c9d0e1f2a3b4c5d",
      "previous_version": "2e6b0f4",
      "repository": "https://github.com/acme/shop",
      "source_maps": {
        "files": 42,
        "uploaded": 42
      },
      "new_problems": 0,
      "sessions": 890
    }
  ],
  "next_cursor": null
}

Crear o actualizar una versión

POST /v1/releases MotorNube

Registra una versión, o le agrega a una que existe (la misma version y el mismo environment): los campos que envías reemplazan los guardados, los que omites se quedan. Llámalo desde tu build o tu despliegue, una vez por versión.

changes es lo que le permite al agente nombrar la causa. Envía los commits y los archivos cambiados desde previous_version. Los parches (el diff de cada archivo) son opcionales: hacen más preciso el análisis y son tu código, así que solo se guardan si los envías. En Sypnia Cloud, con la GitHub App conectada, puedes omitir changes: Sypnia lee la comparación de GitHub.

Autenticación
Token de API (admin)

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

Cuerpo

  • version
    string, hasta 40 caracteres obligatorio

    El nombre de la versión, la misma cadena que tu SDK envía como release. Usa el commit corto de git.

  • environment
    string, hasta 40 caracteres opcional

    Dónde se desplegó.

    Por defecto: production

  • deployed_at
    timestamp opcional

    Cuándo salió. Por defecto, ahora.

  • commit
    string, hasta 64 caracteres opcional

    El commit completo de git.

  • previous_version
    string, hasta 40 caracteres opcional

    La versión a la que reemplazó. Por defecto, la última versión del entorno.

  • repository
    URL, hasta 300 caracteres opcional

    La URL web del repositorio. Los enlaces de la app y de los prompts apuntan a él.

  • changes
    object opcional

    Lo que cambió desde previous_version.

Límites

  • version: de 1 a 40 caracteres de A-Z a-z 0-9 . _ - +, el mismo límite del campo ver de los eventos.
  • changes.commits: hasta 200. changes.files: hasta 500.
  • patch: hasta 20.000 caracteres por archivo y 200.000 por versión. Los parches más largos se cortan y quedan marcados con truncated.

Petición

Terminal
curl -X POST "https://api.sypnia.com/v1/releases" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data @release.json

Cuerpo de la petición

JSON
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }"
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2
      }
    ]
  }
}

Respuesta200

JSON
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "first_seen": "2026-03-11T18:41:12Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "source_maps": {
    "files": 42,
    "uploaded": 42
  },
  "new_problems": 1,
  "sessions": 131,
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }",
        "truncated": false
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2,
        "patch": null,
        "truncated": false
      }
    ]
  }
}

Errores

  • 400invalid_request

    Falta version o tiene caracteres que no se permiten, o una lista es demasiado larga. param nombra el campo.

  • 413payload_too_large

    El cuerpo pesa más de 2 MiB.

Traer una versión

GET /v1/releases/{version} MotorNube

Una versión con sus changes.

Autenticación
Token de API (read)

Parámetros de ruta

  • version
    string, hasta 40 caracteres obligatorio

    El nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

  • environment
    string opcional

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

Petición

Terminal
curl "https://api.sypnia.com/v1/releases/4f2a91c" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

JSON
{
  "version": "4f2a91c",
  "environment": "production",
  "deployed_at": "2026-03-11T18:40:00Z",
  "first_seen": "2026-03-11T18:41:12Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "commit": "4f2a91c0d3b7e6a5f4c3b2a1908f7e6d5c4b3a29",
  "previous_version": "9c1e7b2",
  "repository": "https://github.com/acme/shop",
  "source_maps": {
    "files": 42,
    "uploaded": 42
  },
  "new_problems": 1,
  "sessions": 131,
  "changes": {
    "commits": [
      {
        "sha": "4f2a91c",
        "message": "Rename cart.total to cart.totalCents",
        "authored_at": "2026-03-11T18:22:05Z"
      }
    ],
    "files": [
      {
        "path": "src/cart/cart.ts",
        "additions": 3,
        "deletions": 3,
        "patch": "@@ -8,7 +8,7 @@ export interface Cart {\n   items: CartItem[];\n   currency: string;\n-  total: number;\n+  totalCents: number;\n }",
        "truncated": false
      },
      {
        "path": "src/cart/cart-summary.tsx",
        "additions": 2,
        "deletions": 2,
        "patch": null,
        "truncated": false
      }
    ]
  }
}

Errores

  • 404not_found

    El proyecto no tiene una versión con este nombre en este entorno.

Listar los source maps de una versión

GET /v1/releases/{version}/sourcemaps MotorNube

Los mapas registrados para una versión y si cada uno llegó al almacenamiento. Sirve para comprobar una subida desde CI.

Autenticación
Token de API (read)

Parámetros de ruta

  • version
    string, hasta 40 caracteres obligatorio

    El nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

JSON
{
  "data": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "map_size": 48211,
      "uploaded": true,
      "uploaded_at": "2026-03-11T18:38:11Z"
    },
    {
      "url_path": "/assets/index-a41b.js",
      "map_size": 912044,
      "uploaded": true,
      "uploaded_at": "2026-03-11T18:38:12Z"
    }
  ],
  "next_cursor": null
}

Errores

  • 404not_found

    El proyecto no tiene una versión con este nombre.

Subir source maps

POST /v1/releases/{version}/sourcemaps MotorNube

Subir source maps toma dos pasos, porque los mapas son demasiado grandes para pasar por la API.

  1. Llama a este endpoint con la lista de archivos. Para cada uno di a qué archivo JavaScript pertenece (url_path, la ruta desde la que tu sitio lo sirve) y el tamaño y el SHA-256 del mapa. La respuesta trae un enlace de subida por cada mapa que el motor todavía no tiene.
  2. Haz PUT de cada mapa a su enlace, con los encabezados indicados, en menos de 15 minutos.

Eso es todo: no hay llamada de «terminar». El motor usa un mapa desde el momento en que está en el almacenamiento. Los mapas que ya se subieron con el mismo SHA-256 aparecen en skipped, así que correr la subida dos veces cuesta poco. La versión se crea si no existe.

El motor encuentra el mapa de un marco de la pila por la ruta del archivo del marco, así que url_path debe ser la ruta tal como aparece en el navegador, sin el origen. Los empaquetadores que nombran los mapas distinto a sus archivos (Turbopack) quedan cubiertos porque aquí tú nombras la pareja.

Los source maps se guardan 90 días después de la última vez que se vio la versión. No los publiques: borra los archivos .map de lo que despliegas.

Autenticación
Token de API (admin)

Parámetros de ruta

  • version
    string, hasta 40 caracteres obligatorio

    El nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

Cuerpo

  • files
    lista de object, hasta 2,000 elementos obligatorio

    Los mapas que se van a subir.

  • files[].url_path
    string, hasta 1,000 caracteres

    La ruta desde la que se sirve el archivo JavaScript, empezando con /, sin el origen ni parámetros.

  • files[].map_size
    integer, 1 a 67,108,864

    El tamaño del mapa en bytes.

  • files[].map_sha256
    string

    El SHA-256 del mapa, en hexadecimal.

Límites

  • Archivos en una llamada: 2.000. Llama otra vez para más.
  • Un mapa: 64 MB. Los mapas más grandes se rechazan (map_too_large en skipped) y sus marcos quedan minificados.

Petición

Terminal
# 1. Ask for upload links
curl -X POST "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data @maps.json

# 2. Upload each map to its link
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  --data-binary @dist/assets/checkout-3f9c.js.map

Cuerpo de la petición

JSON
{
  "files": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "map_size": 48211,
      "map_sha256": "9b1f6c0a7d2e4b8f3a5c1e9d7b0f2a4c6e8d0b2f4a6c8e0d1b3f5a7c9e1d3b5f"
    },
    {
      "url_path": "/assets/index-a41b.js",
      "map_size": 912044,
      "map_sha256": "1d3b5f7a9c1e3d5b7f9a1c3e5d7b9f1a3c5e7d9b1f3a5c7e9d1b3f5a7c9e1d3b"
    }
  ]
}

Respuesta200

JSON
{
  "release": "4f2a91c",
  "uploads": [
    {
      "url_path": "/assets/checkout-3f9c.js",
      "method": "PUT",
      "upload_url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/sourcemaps/4f2a91c/…?X-Amz-Signature=…",
      "headers": {
        "Content-Type": "application/json"
      },
      "expires_at": "2026-03-11T18:52:00Z"
    }
  ],
  "skipped": [
    {
      "url_path": "/assets/index-a41b.js",
      "reason": "already_uploaded"
    }
  ]
}

Errores

  • 400invalid_request

    files está vacío o tiene más de 2.000, o a una entrada le falta url_path, map_size o map_sha256.

  • 409limit_reached

    La versión ya tiene 20.000 mapas.

Borrar los source maps de una versión

DELETE /v1/releases/{version}/sourcemaps MotorNube

Borra todos los source maps de la versión. Las pilas que ya se tradujeron siguen traducidas; las fallas nuevas de esta versión muestran marcos minificados.

Autenticación
Token de API (admin)

Parámetros de ruta

  • version
    string, hasta 40 caracteres obligatorio

    El nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.

Parámetros de consulta

  • project
    string opcional

    El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es 403.

Petición

Terminal
curl -X DELETE "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"

Errores

  • 404not_found

    El proyecto no tiene una versión con este nombre.

Los errores que cualquier endpoint puede responder (401, 403, 429, 500, 503) están en Errores, límites, paginación.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar