feat: add optional name parameter to createSnapshot and return snapshot names

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: mishushakov

.changeset/snapshot-name.md

@@ -0,0 +1,6 @@
+---
+'@e2b/python-sdk': patch
+'e2b': patch
+---
+
+add optional name parameter to createSnapshot and return snapshot names

packages/js-sdk/src/index.ts

@@ -63,6 +63,7 @@ export type {
   SnapshotInfo,
   SnapshotListOpts,
   SnapshotPaginator,
+  CreateSnapshotOpts,
 } from './sandbox/sandboxApi'
 
 export type { McpServer } from './sandbox/mcp'

packages/js-sdk/src/sandbox/index.ts

@@ -24,6 +24,7 @@ import {
   SnapshotListOpts,
   SnapshotInfo,
   SnapshotPaginator,
+  CreateSnapshotOpts,
 } from './sandboxApi'
 import { getSignature } from './signature'
 import { compareVersions } from 'compare-versions'
@@ -609,7 +610,7 @@ export class Sandbox extends SandboxApi {
    *
    * Use the returned `snapshotId` with `Sandbox.create(snapshotId)` to create a new sandbox from the snapshot.
    *
-   * @param opts connection options.
+   * @param opts snapshot creation options including optional name and connection options.
    *
    * @returns snapshot information including the snapshot ID.
    *
@@ -619,17 +620,17 @@ export class Sandbox extends SandboxApi {
    * await sandbox.files.write('/app/state.json', '{"step": 1}')
    *
    * // Create a snapshot
-   * const snapshot = await sandbox.createSnapshot()
+   * const snapshot = await sandbox.createSnapshot({ name: 'my-snapshot' })
    *
    * // Create a new sandbox from the snapshot
    * const newSandbox = await Sandbox.create(snapshot.snapshotId)
    * ```
    */
-  async createSnapshot(opts?: SandboxApiOpts): Promise<SnapshotInfo> {
-    return await SandboxApi.createSnapshot(
-      this.sandboxId,
-      this.resolveApiOpts(opts)
-    )
+  async createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo> {
+    return await SandboxApi.createSnapshot(this.sandboxId, {
+      ...this.resolveApiOpts(opts),
+      name: opts?.name,
+    })
   }
 
   /**

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -283,6 +283,23 @@ export interface SnapshotInfo {
    * Can be used with Sandbox.create() to create a new sandbox from this snapshot.
    */
   snapshotId: string
+
+  /**
+   * Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2).
+   */
+  names: string[]
+}
+
+/**
+ * Options for creating a snapshot.
+ */
+export interface CreateSnapshotOpts extends SandboxApiOpts {
+  /**
+   * Optional name for the snapshot template.
+   * If a snapshot template with this name already exists, a new build will be assigned
+   * to the existing template instead of creating a new one.
+   */
+  name?: string
 }
 
 /**
@@ -688,13 +705,13 @@ export class SandboxApi {
    * The snapshot is a persistent image that survives sandbox deletion.
    *
    * @param sandboxId sandbox ID to create snapshot from.
-   * @param opts connection options.
+   * @param opts snapshot creation options including optional name and connection options.
    *
    * @returns snapshot information including the snapshot name that can be used with Sandbox.create().
    */
   static async createSnapshot(
     sandboxId: string,
-    opts?: SandboxApiOpts
+    opts?: CreateSnapshotOpts
   ): Promise<SnapshotInfo> {
     const config = new ConnectionConfig(opts)
     const client = new ApiClient(config)
@@ -705,7 +722,7 @@ export class SandboxApi {
           sandboxID: sandboxId,
         },
       },
-      body: {},
+      body: opts?.name ? { name: opts.name } : {},
       signal: config.getSignal(opts?.requestTimeoutMs),
     })
 
@@ -720,6 +737,7 @@ export class SandboxApi {
 
     return {
       snapshotId: res.data!.snapshotID,
+      names: res.data!.names ?? [],
     }
   }
 
@@ -1045,6 +1063,7 @@ export class SnapshotPaginator extends BasePaginator<SnapshotInfo> {
     return (res.data ?? []).map(
       (snapshot: components['schemas']['SnapshotInfo']) => ({
         snapshotId: snapshot.snapshotID,
+        names: snapshot.names ?? [],
       })
     )
   }

packages/python-sdk/e2b/sandbox/sandbox_api.py

@@ -296,6 +296,8 @@ class SnapshotInfo:
 
     snapshot_id: str
     """Snapshot identifier — template ID with tag, or namespaced name with tag (e.g. my-snapshot:latest). Can be used with Sandbox.create() to create a new sandbox from this snapshot."""
+    names: List[str] = field(default_factory=list)
+    """Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2)."""
 
 
 class PaginatorBase:

packages/python-sdk/e2b/sandbox_async/main.py

@@ -694,6 +694,7 @@ async def beta_pause(
     @overload
     async def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -705,14 +706,17 @@ async def create_snapshot(
 
         Use the returned `snapshot_id` with `AsyncSandbox.create(snapshot_id)` to create a new sandbox from the snapshot.
 
-        :return: Snapshot information including the snapshot ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
+
+        :return: Snapshot information including the snapshot ID and names
         """
         ...
 
     @overload
     @staticmethod
     async def create_snapshot(
         sandbox_id: str,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -721,14 +725,16 @@ async def create_snapshot(
         The sandbox will be paused while the snapshot is being created.
 
         :param sandbox_id: Sandbox ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
 
-        :return: Snapshot information including the snapshot ID
+        :return: Snapshot information including the snapshot ID and names
         """
         ...
 
     @class_method_variant("_cls_create_snapshot")
     async def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -740,10 +746,13 @@ async def create_snapshot(
 
         Use the returned `snapshot_id` with `AsyncSandbox.create(snapshot_id)` to create a new sandbox from the snapshot.
 
-        :return: Snapshot information including the snapshot ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
+
+        :return: Snapshot information including the snapshot ID and names
         """
         return await SandboxApi._cls_create_snapshot(
             sandbox_id=self.sandbox_id,
+            name=name,
             **self.connection_config.get_api_params(**opts),
         )
 

packages/python-sdk/e2b/sandbox_async/paginator.py

@@ -121,5 +121,9 @@ async def next_items(self) -> List[SnapshotInfo]:
             raise SandboxException(f"{res.parsed.message}: Request failed")
 
         return [
-            SnapshotInfo(snapshot_id=snapshot.snapshot_id) for snapshot in res.parsed
+            SnapshotInfo(
+                snapshot_id=snapshot.snapshot_id,
+                names=list(snapshot.names) if snapshot.names else [],
+            )
+            for snapshot in res.parsed
         ]

packages/python-sdk/e2b/sandbox_async/sandbox_api.py

@@ -297,6 +297,7 @@ async def _cls_get_metrics(
     async def _cls_create_snapshot(
         cls,
         sandbox_id: str,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         config = ConnectionConfig(**opts)
@@ -305,7 +306,9 @@ async def _cls_create_snapshot(
         res = await post_sandboxes_sandbox_id_snapshots.asyncio_detailed(
             sandbox_id,
             client=api_client,
-            body=PostSandboxesSandboxIDSnapshotsBody(),
+            body=PostSandboxesSandboxIDSnapshotsBody(
+                name=name if name is not None else UNSET
+            ),
         )
 
         if res.status_code == 404:
@@ -320,7 +323,10 @@ async def _cls_create_snapshot(
         if isinstance(res.parsed, Error):
             raise SandboxException(f"{res.parsed.message}: Request failed")
 
-        return SnapshotInfo(snapshot_id=res.parsed.snapshot_id)
+        return SnapshotInfo(
+            snapshot_id=res.parsed.snapshot_id,
+            names=list(res.parsed.names) if res.parsed.names else [],
+        )
 
     @classmethod
     async def _cls_delete_snapshot(

packages/python-sdk/e2b/sandbox_sync/main.py

@@ -691,6 +691,7 @@ def beta_pause(
     @overload
     def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -702,14 +703,17 @@ def create_snapshot(
 
         Use the returned `snapshot_id` with `Sandbox.create(snapshot_id)` to create a new sandbox from the snapshot.
 
-        :return: Snapshot information including the snapshot ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
+
+        :return: Snapshot information including the snapshot ID and names
         """
         ...
 
     @overload
     @staticmethod
     def create_snapshot(
         sandbox_id: str,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -718,14 +722,16 @@ def create_snapshot(
         The sandbox will be paused while the snapshot is being created.
 
         :param sandbox_id: Sandbox ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
 
-        :return: Snapshot information including the snapshot ID
+        :return: Snapshot information including the snapshot ID and names
         """
         ...
 
     @class_method_variant("_cls_create_snapshot")
     def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -737,10 +743,13 @@ def create_snapshot(
 
         Use the returned `snapshot_id` with `Sandbox.create(snapshot_id)` to create a new sandbox from the snapshot.
 
-        :return: Snapshot information including the snapshot ID
+        :param name: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
+
+        :return: Snapshot information including the snapshot ID and names
         """
         return SandboxApi._cls_create_snapshot(
             sandbox_id=self.sandbox_id,
+            name=name,
             **self.connection_config.get_api_params(**opts),
         )
 

packages/python-sdk/e2b/sandbox_sync/paginator.py

@@ -121,5 +121,9 @@ def next_items(self) -> List[SnapshotInfo]:
             raise SandboxException(f"{res.parsed.message}: Request failed")
 
         return [
-            SnapshotInfo(snapshot_id=snapshot.snapshot_id) for snapshot in res.parsed
+            SnapshotInfo(
+                snapshot_id=snapshot.snapshot_id,
+                names=list(snapshot.names) if snapshot.names else [],
+            )
+            for snapshot in res.parsed
         ]