Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

feat(sdk): add name filter to snapshot list (#1523)

Mish Ushakov2c77fc00bb11
diff --git a/.changeset/snapshot-list-name-filter.md b/.changeset/snapshot-list-name-filter.md
new file mode 100644
index 000000000..d2d9df7fe
--- /dev/null
+++ b/.changeset/snapshot-list-name-filter.md
@@ -0,0 +1,27 @@
+---
+"e2b": minor
+"@e2b/python-sdk": minor
+---
+
+Add a `name` filter to `Sandbox.listSnapshots()` / `Sandbox.list_snapshots()`.
+
+The filter accepts a snapshot name or ID, optionally tag-qualified (e.g.
+`"my-snapshot"`, `"my-team/my-snapshot"` or `"my-snapshot:v1"`). Unknown names
+return an empty list rather than an error. It can be combined with the existing
+`sandboxId` / `sandbox_id` filter (results must match both).
+
+```ts
+// JS/TS
+const paginator = Sandbox.listSnapshots({ name: 'my-snapshot' })
+const snapshots = await paginator.nextItems()
+```
+
+```python
+# Python (sync)
+paginator = Sandbox.list_snapshots(name="my-snapshot")
+snapshots = paginator.next_items()
+
+# Python (async)
+paginator = AsyncSandbox.list_snapshots(name="my-snapshot")
+snapshots = await paginator.next_items()
+```
diff --git a/packages/js-sdk/src/api/schema.gen.ts b/packages/js-sdk/src/api/schema.gen.ts
index c6f357d03..79764409e 100644
--- a/packages/js-sdk/src/api/schema.gen.ts
+++ b/packages/js-sdk/src/api/schema.gen.ts
@@ -622,6 +622,7 @@ export interface paths {
query?: {
/** @description Maximum number of items to return per page */
limit?: components["parameters"]["paginationLimit"];
+ name?: string;
/** @description Cursor to start the list from */
nextToken?: components["parameters"]["paginationNextToken"];
sandboxID?: string;
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index 4cedebcfa..2da2aafc5 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -450,6 +450,12 @@ export interface SnapshotListOpts extends Omit<SandboxApiOpts, 'signal'> {
*/
sandboxId?: string
+ /**
+ * Filter snapshots by name or ID, optionally tag-qualified
+ * (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
+ */
+ name?: string
+
/**
* Number of snapshots to return per page.
*
@@ -1335,11 +1341,13 @@ export class SandboxPaginator extends Paginator<SandboxInfo, SandboxApiOpts> {
*/
export class SnapshotPaginator extends Paginator<SnapshotInfo, SandboxApiOpts> {
private readonly sandboxId?: string
+ private readonly name?: string
constructor(opts?: SnapshotListOpts) {
super(opts, opts?.limit, opts?.nextToken)
this.sandboxId = opts?.sandboxId
+ this.name = opts?.name
}
async nextItems(opts?: SandboxApiOpts): Promise<SnapshotInfo[]> {
@@ -1354,6 +1362,7 @@ export class SnapshotPaginator extends Paginator<SnapshotInfo, SandboxApiOpts> {
params: {
query: {
sandboxID: this.sandboxId,
+ name: this.name,
limit: this.limit,
nextToken: this.nextToken,
},
diff --git a/packages/js-sdk/tests/sandbox/snapshot-api.test.ts b/packages/js-sdk/tests/sandbox/snapshot-api.test.ts
index e22387a4a..3c6432af6 100644
--- a/packages/js-sdk/tests/sandbox/snapshot-api.test.ts
+++ b/packages/js-sdk/tests/sandbox/snapshot-api.test.ts
@@ -159,6 +159,34 @@ sandboxTest.skipIf(isDebug)(
}
)
+sandboxTest.skipIf(isDebug)(
+ 'list snapshots filtered by name',
+ async ({ sandbox, sandboxTestId }) => {
+ const snapshotName = `snap-filter-${sandboxTestId}`
+
+ const snapshot = await sandbox.createSnapshot({ name: snapshotName })
+
+ try {
+ // Filtering by the snapshot name should return the snapshot
+ const paginator = Sandbox.listSnapshots({ name: snapshotName })
+ const snapshots = await paginator.nextItems()
+
+ const found = snapshots.find((s) => s.snapshotId === snapshot.snapshotId)
+ assert.isDefined(found)
+
+ // Filtering by an unknown name should return an empty list
+ const emptyPaginator = Sandbox.listSnapshots({
+ name: `${snapshotName}-does-not-exist`,
+ })
+ const emptySnapshots = await emptyPaginator.nextItems()
+ assert.isArray(emptySnapshots)
+ assert.equal(emptySnapshots.length, 0)
+ } finally {
+ await Sandbox.deleteSnapshot(snapshot.snapshotId)
+ }
+ }
+)
+
sandboxTest.skipIf(isDebug)('delete snapshot', async ({ sandbox }) => {
const snapshot = await sandbox.createSnapshot()
diff --git a/packages/python-sdk/e2b/api/client/api/snapshots/get_snapshots.py b/packages/python-sdk/e2b/api/client/api/snapshots/get_snapshots.py
index 1b826e3d6..13f6b1758 100644
--- a/packages/python-sdk/e2b/api/client/api/snapshots/get_snapshots.py
+++ b/packages/python-sdk/e2b/api/client/api/snapshots/get_snapshots.py
@@ -13,6 +13,7 @@ from ...types import UNSET, Response, Unset
def _get_kwargs(
*,
sandbox_id: Union[Unset, str] = UNSET,
+ name: Union[Unset, str] = UNSET,
limit: Union[Unset, int] = 100,
next_token: Union[Unset, str] = UNSET,
) -> dict[str, Any]:
@@ -20,6 +21,8 @@ def _get_kwargs(
params["sandboxID"] = sandbox_id
+ params["name"] = name
+
params["limit"] = limit
params["nextToken"] = next_token
@@ -76,6 +79,7 @@ def sync_detailed(
*,
client: AuthenticatedClient,
sandbox_id: Union[Unset, str] = UNSET,
+ name: Union[Unset, str] = UNSET,
limit: Union[Unset, int] = 100,
next_token: Union[Unset, str] = UNSET,
) -> Response[Union[Error, list["SnapshotInfo"]]]:
@@ -83,6 +87,8 @@ def sync_detailed(
Args:
sandbox_id (Union[Unset, str]): Filter snapshots by source sandbox ID
+ name (Union[Unset, str]): Filter snapshots by name or ID, optionally tag-qualified (e.g.
+ "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
limit (Union[Unset, int]): Default: 100.
next_token (Union[Unset, str]):
@@ -96,6 +102,7 @@ def sync_detailed(
kwargs = _get_kwargs(
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
)
@@ -111,6 +118,7 @@ def sync(
*,
client: AuthenticatedClient,
sandbox_id: Union[Unset, str] = UNSET,
+ name: Union[Unset, str] = UNSET,
limit: Union[Unset, int] = 100,
next_token: Union[Unset, str] = UNSET,
) -> Optional[Union[Error, list["SnapshotInfo"]]]:
@@ -118,6 +126,8 @@ def sync(
Args:
sandbox_id (Union[Unset, str]): Filter snapshots by source sandbox ID
+ name (Union[Unset, str]): Filter snapshots by name or ID, optionally tag-qualified (e.g.
+ "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
limit (Union[Unset, int]): Default: 100.
next_token (Union[Unset, str]):
@@ -132,6 +142,7 @@ def sync(
return sync_detailed(
client=client,
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
).parsed
@@ -141,6 +152,7 @@ async def asyncio_detailed(
*,
client: AuthenticatedClient,
sandbox_id: Union[Unset, str] = UNSET,
+ name: Union[Unset, str] = UNSET,
limit: Union[Unset, int] = 100,
next_token: Union[Unset, str] = UNSET,
) -> Response[Union[Error, list["SnapshotInfo"]]]:
@@ -148,6 +160,8 @@ async def asyncio_detailed(
Args:
sandbox_id (Union[Unset, str]): Filter snapshots by source sandbox ID
+ name (Union[Unset, str]): Filter snapshots by name or ID, optionally tag-qualified (e.g.
+ "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
limit (Union[Unset, int]): Default: 100.
next_token (Union[Unset, str]):
@@ -161,6 +175,7 @@ async def asyncio_detailed(
kwargs = _get_kwargs(
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
)
@@ -174,6 +189,7 @@ async def asyncio(
*,
client: AuthenticatedClient,
sandbox_id: Union[Unset, str] = UNSET,
+ name: Union[Unset, str] = UNSET,
limit: Union[Unset, int] = 100,
next_token: Union[Unset, str] = UNSET,
) -> Optional[Union[Error, list["SnapshotInfo"]]]:
@@ -181,6 +197,8 @@ async def asyncio(
Args:
sandbox_id (Union[Unset, str]): Filter snapshots by source sandbox ID
+ name (Union[Unset, str]): Filter snapshots by name or ID, optionally tag-qualified (e.g.
+ "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
limit (Union[Unset, int]): Default: 100.
next_token (Union[Unset, str]):
@@ -196,6 +214,7 @@ async def asyncio(
await asyncio_detailed(
client=client,
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
)
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index d0982864f..f5aaaffb6 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -606,10 +606,12 @@ class SnapshotPaginatorBase(PaginatorBase[SnapshotInfo, ApiParams]):
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
):
super().__init__(limit=limit, next_token=next_token, **opts)
self.sandbox_id = sandbox_id
+ self.name = name
class SandboxPaginatorBase(PaginatorBase[SandboxInfo, ApiParams]):
diff --git a/packages/python-sdk/e2b/sandbox_async/main.py b/packages/python-sdk/e2b/sandbox_async/main.py
index 791b9b360..50fbdaa0f 100644
--- a/packages/python-sdk/e2b/sandbox_async/main.py
+++ b/packages/python-sdk/e2b/sandbox_async/main.py
@@ -771,6 +771,7 @@ class AsyncSandbox(SandboxApi):
self,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> AsyncSnapshotPaginator:
"""
@@ -778,6 +779,7 @@ class AsyncSandbox(SandboxApi):
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
@@ -789,6 +791,7 @@ class AsyncSandbox(SandboxApi):
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> AsyncSnapshotPaginator:
"""
@@ -797,6 +800,7 @@ class AsyncSandbox(SandboxApi):
:param sandbox_id: Filter snapshots by source sandbox ID
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
@@ -807,6 +811,7 @@ class AsyncSandbox(SandboxApi):
self,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> AsyncSnapshotPaginator:
"""
@@ -814,11 +819,13 @@ class AsyncSandbox(SandboxApi):
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
return AsyncSnapshotPaginator(
sandbox_id=self.sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
**self.connection_config.get_api_params(**opts),
@@ -829,10 +836,12 @@ class AsyncSandbox(SandboxApi):
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> AsyncSnapshotPaginator:
return AsyncSnapshotPaginator(
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
**opts,
diff --git a/packages/python-sdk/e2b/sandbox_async/paginator.py b/packages/python-sdk/e2b/sandbox_async/paginator.py
index 269248c5e..bc8f5380a 100644
--- a/packages/python-sdk/e2b/sandbox_async/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_async/paginator.py
@@ -116,6 +116,7 @@ class AsyncSnapshotPaginator(SnapshotPaginatorBase):
res = await get_snapshots.asyncio_detailed(
client=api_client,
sandbox_id=self.sandbox_id if self.sandbox_id else UNSET,
+ name=self.name if self.name else UNSET,
limit=self.limit if self.limit else UNSET,
next_token=self._next_token if self._next_token else UNSET,
)
diff --git a/packages/python-sdk/e2b/sandbox_sync/main.py b/packages/python-sdk/e2b/sandbox_sync/main.py
index df73f2b08..005e2d30a 100644
--- a/packages/python-sdk/e2b/sandbox_sync/main.py
+++ b/packages/python-sdk/e2b/sandbox_sync/main.py
@@ -761,6 +761,7 @@ class Sandbox(SandboxApi):
self,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> SnapshotPaginator:
"""
@@ -768,6 +769,7 @@ class Sandbox(SandboxApi):
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
@@ -779,6 +781,7 @@ class Sandbox(SandboxApi):
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> SnapshotPaginator:
"""
@@ -787,6 +790,7 @@ class Sandbox(SandboxApi):
:param sandbox_id: Filter snapshots by source sandbox ID
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
@@ -797,6 +801,7 @@ class Sandbox(SandboxApi):
self,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> SnapshotPaginator:
"""
@@ -804,11 +809,13 @@ class Sandbox(SandboxApi):
:param limit: Maximum number of snapshots to return per page
:param next_token: Token for pagination
+ :param name: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1")
:return: Paginator for listing snapshots
"""
return SnapshotPaginator(
sandbox_id=self.sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
**self.connection_config.get_api_params(**opts),
@@ -819,10 +826,12 @@ class Sandbox(SandboxApi):
sandbox_id: Optional[str] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ name: Optional[str] = None,
**opts: Unpack[ApiParams],
) -> SnapshotPaginator:
return SnapshotPaginator(
sandbox_id=sandbox_id,
+ name=name,
limit=limit,
next_token=next_token,
**opts,
diff --git a/packages/python-sdk/e2b/sandbox_sync/paginator.py b/packages/python-sdk/e2b/sandbox_sync/paginator.py
index 9f0d4bf22..aa896dd4b 100644
--- a/packages/python-sdk/e2b/sandbox_sync/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_sync/paginator.py
@@ -116,6 +116,7 @@ class SnapshotPaginator(SnapshotPaginatorBase):
res = get_snapshots.sync_detailed(
client=api_client,
sandbox_id=self.sandbox_id if self.sandbox_id else UNSET,
+ name=self.name if self.name else UNSET,
limit=self.limit if self.limit else UNSET,
next_token=self._next_token if self._next_token else UNSET,
)
diff --git a/packages/python-sdk/tests/async/sandbox_async/test_snapshot_api.py b/packages/python-sdk/tests/async/sandbox_async/test_snapshot_api.py
index e9673b069..80354a62e 100644
--- a/packages/python-sdk/tests/async/sandbox_async/test_snapshot_api.py
+++ b/packages/python-sdk/tests/async/sandbox_async/test_snapshot_api.py
@@ -96,6 +96,31 @@ async def test_list_snapshots_for_sandbox(async_sandbox: AsyncSandbox):
await AsyncSandbox.delete_snapshot(snapshot.snapshot_id)
+async def test_list_snapshots_filtered_by_name(
+ async_sandbox: AsyncSandbox, sandbox_test_id: str
+):
+ snapshot_name = f"snap-filter-{sandbox_test_id}"
+
+ snapshot = await async_sandbox.create_snapshot(name=snapshot_name)
+
+ try:
+ paginator = AsyncSandbox.list_snapshots(name=snapshot_name)
+ snapshots = await paginator.next_items()
+
+ found = any(s.snapshot_id == snapshot.snapshot_id for s in snapshots)
+ assert found
+
+ empty_paginator = AsyncSandbox.list_snapshots(
+ name=f"{snapshot_name}-does-not-exist"
+ )
+ empty_snapshots = await empty_paginator.next_items()
+ assert isinstance(empty_snapshots, list)
+ assert len(empty_snapshots) == 0
+ finally:
+ 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}"
diff --git a/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_api.py b/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_api.py
index 1eef251d9..2fa6d2982 100644
--- a/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_api.py
+++ b/packages/python-sdk/tests/sync/sandbox_sync/test_snapshot_api.py
@@ -94,6 +94,27 @@ def test_list_snapshots_for_sandbox(sandbox: Sandbox):
Sandbox.delete_snapshot(snapshot.snapshot_id)
+def test_list_snapshots_filtered_by_name(sandbox: Sandbox, sandbox_test_id: str):
+ snapshot_name = f"snap-filter-{sandbox_test_id}"
+
+ snapshot = sandbox.create_snapshot(name=snapshot_name)
+
+ try:
+ paginator = Sandbox.list_snapshots(name=snapshot_name)
+ snapshots = paginator.next_items()
+
+ found = any(s.snapshot_id == snapshot.snapshot_id for s in snapshots)
+ assert found
+
+ empty_paginator = Sandbox.list_snapshots(name=f"{snapshot_name}-does-not-exist")
+ empty_snapshots = empty_paginator.next_items()
+ assert isinstance(empty_snapshots, list)
+ assert len(empty_snapshots) == 0
+ finally:
+ Sandbox.delete_snapshot(snapshot.snapshot_id)
+
+
@pytest.mark.skip_debug()
def test_create_named_snapshot(sandbox: Sandbox, sandbox_test_id: str):
snapshot_name = f"snap-{sandbox_test_id}"
diff --git a/spec/openapi.yml b/spec/openapi.yml
index 0f20f8d70..f772100d1 100644
--- a/spec/openapi.yml
+++ b/spec/openapi.yml
@@ -2618,6 +2618,12 @@ paths:
schema:
type: string
description: Filter snapshots by source sandbox ID
+ - name: name
+ in: query
+ required: false
+ schema:
+ type: string
+ description: Filter snapshots by name or ID, optionally tag-qualified (e.g. "my-snapshot", "my-team/my-snapshot" or "my-snapshot:v1").
- $ref: '#/components/parameters/paginationLimit'
- $ref: '#/components/parameters/paginationNextToken'
responses: