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.
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
-
versionstring opcionalEl nombre de la versión. Único por proyecto y entorno.
-
environmentstring opcional -
deployed_attimestamp o null opcionalCuándo salió, según dijiste.
nullpara una versión que el motor solo conoció por los eventos. -
first_seentimestamp o null opcionalEl primer evento que la trajo.
-
last_seentimestamp o null opcional -
commitstring o null opcional -
previous_versionstring o null opcional -
repositorystring o null opcional -
source_mapsobject opcionalCuántos mapas se registraron y cuántos llegaron.
-
new_problemsinteger opcionalProblemas que se vieron por primera vez en esta versión.
-
sessionsinteger opcionalSesiones que corrieron en ella.
-
changesobject o null opcionalLo que cambió, tal como se envió, o leído de GitHub en Sypnia Cloud.
nullcuando no se sabe. No viene en las listas.
Listar versiones
/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.
Parámetros de consulta
-
projectstring opcionalEl 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. -
environmentstring opcionalEl entorno que se lee. Cualquier nombre que el proyecto haya enviado, o
all.Por defecto:
production -
sincestring opcionalSolo versiones vistas por primera vez o desplegadas después de este momento.
Por defecto:
90d -
limitinteger, 1 a 200 opcionalMáximo de elementos que se devuelven.
Por defecto:
50 -
cursorstring opcionalEl
next_cursorde la página anterior. Deja iguales todos los demás parámetros.
Petición
curl "https://api.sypnia.com/v1/releases" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"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
/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.
Parámetros de consulta
-
projectstring opcionalEl 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
-
versionstring, hasta 40 caracteres obligatorioEl nombre de la versión, la misma cadena que tu SDK envía como
release. Usa el commit corto de git. -
environmentstring, hasta 40 caracteres opcionalDónde se desplegó.
Por defecto:
production -
deployed_attimestamp opcionalCuándo salió. Por defecto, ahora.
-
commitstring, hasta 64 caracteres opcionalEl commit completo de git.
-
previous_versionstring, hasta 40 caracteres opcionalLa versión a la que reemplazó. Por defecto, la última versión del entorno.
-
repositoryURL, hasta 300 caracteres opcionalLa URL web del repositorio. Los enlaces de la app y de los prompts apuntan a él.
-
changesobject opcionalLo que cambió desde
previous_version.
Límites
version: de 1 a 40 caracteres deA-Z a-z 0-9 . _ - +, el mismo límite del campoverde 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 contruncated.
Petición
curl -X POST "https://api.sypnia.com/v1/releases" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
--data @release.jsonCuerpo de la petición
{
"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
{
"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
- 400
invalid_requestFalta
versiono tiene caracteres que no se permiten, o una lista es demasiado larga.paramnombra el campo. - 413
payload_too_largeEl cuerpo pesa más de 2 MiB.
Traer una versión
/v1/releases/{version} MotorNube Una versión con sus changes.
Parámetros de ruta
-
versionstring, hasta 40 caracteres obligatorioEl nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.
Parámetros de consulta
-
projectstring opcionalEl 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. -
environmentstring opcionalEl entorno que se lee. Cualquier nombre que el proyecto haya enviado, o
all.Por defecto:
production
Petición
curl "https://api.sypnia.com/v1/releases/4f2a91c" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"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
- 404
not_foundEl proyecto no tiene una versión con este nombre en este entorno.
Listar los source maps de una versión
/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.
Parámetros de ruta
-
versionstring, hasta 40 caracteres obligatorioEl nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.
Parámetros de consulta
-
projectstring opcionalEl 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. -
limitinteger, 1 a 200 opcionalMáximo de elementos que se devuelven.
Por defecto:
50 -
cursorstring opcionalEl
next_cursorde la página anterior. Deja iguales todos los demás parámetros.
Petición
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"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
- 404
not_foundEl proyecto no tiene una versión con este nombre.
Subir source maps
/v1/releases/{version}/sourcemaps MotorNube Subir source maps toma dos pasos, porque los mapas son demasiado grandes para pasar por la API.
- 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. - Haz
PUTde 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.
Parámetros de ruta
-
versionstring, hasta 40 caracteres obligatorioEl nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.
Parámetros de consulta
-
projectstring opcionalEl 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
-
fileslista de object, hasta 2,000 elementos obligatorioLos mapas que se van a subir.
-
files[].url_pathstring, hasta 1,000 caracteresLa ruta desde la que se sirve el archivo JavaScript, empezando con
/, sin el origen ni parámetros. -
files[].map_sizeinteger, 1 a 67,108,864El tamaño del mapa en bytes.
-
files[].map_sha256stringEl 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_largeenskipped) y sus marcos quedan minificados.
Petición
# 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.mapCuerpo de la petición
{
"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
{
"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
- 400
invalid_requestfilesestá vacío o tiene más de 2.000, o a una entrada le faltaurl_path,map_sizeomap_sha256. - 409
limit_reachedLa versión ya tiene 20.000 mapas.
Borrar los source maps de una versión
/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.
Parámetros de ruta
-
versionstring, hasta 40 caracteres obligatorioEl nombre de la versión, tal como lo envía tu SDK. Codifícalo para URL.
Parámetros de consulta
-
projectstring opcionalEl 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
curl -X DELETE "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Errores
- 404
not_foundEl 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.