# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/releases-and-source-maps/

Para agentes: Referencia de los endpoints de versiones (releases) y source maps de la API de Sypnia: crear o actualizar una versión con sus cambios, listar, y subir source maps en dos pasos con enlaces firmados.

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](https://docs.sypnia.com/es/cli/commands).

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` \[Motor, Nube]

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, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `90d`): Solo versiones vistas por primera vez o desplegadas después de este momento.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

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

**Respuesta (200):**

```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` \[Motor, Nube]

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, por defecto `production`): Dónde se desplegó.
- `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:**

```bash
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
      }
    ]
  }
}
```

**Respuesta (200):**

```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:**

- `400` `invalid_request`: Falta `version` o tiene caracteres que no se permiten, o una lista es demasiado larga. `param` nombra el campo.
- `413` `payload_too_large`: El cuerpo pesa más de 2 MiB.

## Traer una versión

`GET /v1/releases/{version}` \[Motor, Nube]

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, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.

**Petición:**

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

**Respuesta (200):**

```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:**

- `404` `not_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` \[Motor, Nube]

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, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

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

**Respuesta (200):**

```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:**

- `404` `not_found`: El proyecto no tiene una versión con este nombre.

## Subir source maps

`POST /v1/releases/{version}/sourcemaps` \[Motor, Nube]

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:**

```bash
# 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"
    }
  ]
}
```

**Respuesta (200):**

```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:**

- `400` `invalid_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`.
- `409` `limit_reached`: La versión ya tiene 20.000 mapas.

## Borrar los source maps de una versión

`DELETE /v1/releases/{version}/sourcemaps` \[Motor, Nube]

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:**

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

**Errores:**

- `404` `not_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](https://docs.sypnia.com/es/api/errors-limits-pagination).
