feat: add optional name to createSnapshot and return snapshot names

.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

@@ -20,10 +20,10 @@ import {
   SandboxListOpts,
   SandboxPaginator,
   SandboxBetaCreateOpts,
-  SandboxApiOpts,
   SnapshotListOpts,
   SnapshotInfo,
   SnapshotPaginator,
+  CreateSnapshotOpts,
 } from './sandboxApi'
 import { getSignature } from './signature'
 import { compareVersions } from 'compare-versions'
@@ -610,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.
    *
@@ -620,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/js-sdk/tests/sandbox/snapshot-api.test.ts

@@ -141,6 +141,24 @@ sandboxTest.skipIf(isDebug)(
   }
 )
 
+sandboxTest.skipIf(isDebug)(
+  'create a named snapshot',
+  async ({ sandbox, sandboxTestId }) => {
+    const snapshotName = `snap-${sandboxTestId}`
+
+    const snapshot = await sandbox.createSnapshot({ name: snapshotName })
+
+    try {
+      assert.isString(snapshot.snapshotId)
+      assert.isArray(snapshot.names)
+      assert.isTrue(snapshot.names.length > 0)
+      assert.isTrue(snapshot.names.some((n) => n.includes(snapshotName)))
+    } finally {
+      await Sandbox.deleteSnapshot(snapshot.snapshotId)
+    }
+  }
+)
+
 sandboxTest.skipIf(isDebug)('delete snapshot', async ({ sandbox }) => {
   const snapshot = await sandbox.createSnapshot()
 

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

@@ -695,6 +695,7 @@ async def beta_pause(
     @overload
     async def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -706,14 +707,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:
         """
@@ -722,14 +726,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:
         """
@@ -741,10 +747,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,7 @@ 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 else UNSET),
         )
 
         if res.status_code == 404:
@@ -320,7 +321,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

@@ -692,6 +692,7 @@ def beta_pause(
     @overload
     def create_snapshot(
         self,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         """
@@ -703,14 +704,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:
         """
@@ -719,14 +723,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:
         """
@@ -738,10 +744,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
         ]

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

@@ -324,6 +324,7 @@ def _cls_connect(
     def _cls_create_snapshot(
         cls,
         sandbox_id: str,
+        name: Optional[str] = None,
         **opts: Unpack[ApiParams],
     ) -> SnapshotInfo:
         config = ConnectionConfig(**opts)
@@ -332,7 +333,7 @@ def _cls_create_snapshot(
         res = post_sandboxes_sandbox_id_snapshots.sync_detailed(
             sandbox_id,
             client=api_client,
-            body=PostSandboxesSandboxIDSnapshotsBody(),
+            body=PostSandboxesSandboxIDSnapshotsBody(name=name if name else UNSET),
         )
 
         if res.status_code == 404:
@@ -347,7 +348,10 @@ 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
     def _cls_delete_snapshot(

packages/python-sdk/tests/async/sandbox_async/test_snapshot_api.py

@@ -96,6 +96,21 @@ async def test_list_snapshots_for_sandbox(async_sandbox: AsyncSandbox):
         await AsyncSandbox.delete_snapshot(snapshot.snapshot_id)
 
 
+@pytest.mark.skip_debug()
+async def test_create_named_snapshot(async_sandbox: AsyncSandbox, sandbox_test_id: str):
+    snapshot_name = f"snap-{sandbox_test_id}"
+
+    snapshot = await async_sandbox.create_snapshot(name=snapshot_name)
+
+    try:
+        assert snapshot.snapshot_id
+        assert isinstance(snapshot.names, list)
+        assert len(snapshot.names) > 0
+        assert any(snapshot_name in n for n in snapshot.names)
+    finally:
+        await AsyncSandbox.delete_snapshot(snapshot.snapshot_id)
+
+
 @pytest.mark.skip_debug()
 async def test_delete_snapshot(async_sandbox: AsyncSandbox):
     snapshot = await async_sandbox.create_snapshot()