render 1.1.0__tar.gz → 1.2.0__tar.gz

{render-1.1.0 → render-1.2.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.2.0] - 2026-09-23
+
+### Added
+
+- (Workflows) `start_task()` and `run_task()` accept a keyword-only `idempotency_key`, which makes starting a run safe to retry: repeating a call with the same key within 24 hours returns the run the first call started
+- (Workflows) `ctx.metadata` exposes `task_run_id`, `root_task_run_id` and `parent_task_run_id` for the running task. The IDs come from the task's initial input, so reading them does not make a network request; each is `None` when unavailable
+- (Sandboxes) Snapshot names: `snapshots.create()` accepts `name`, `sandboxes.create()` accepts `snapshot_name` to start from the snapshot that name resolves to, and `Snapshot` exposes `name`. Passing both `snapshot_id` and `snapshot_name` raises `ValueError`
+
+### Changed
+
+- Regenerated the REST client from the latest OpenAPI schema: blueprint creation, `include_previews` when listing build sources, and allowed domains on sandbox network policies. `Deploy` no longer has a `build_id` field
+
 ## [1.1.0] - 2026-09-10
 
 ### Added

{render-1.1.0 → render-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: render
-Version: 1.1.0
+Version: 1.2.0
 Summary: Python SDK for Render Workflows
 Author-email: Render <support@render.com>
 License-File: LICENSE
@@ -102,6 +102,17 @@ from tasks_b import app as app_b
 combined = Workflows.from_workflows(app_a, app_b)
 ```
 
+### Task run IDs
+
+The task context exposes a read-only `ctx.metadata` object with
+`task_run_id`, `root_task_run_id`, and `parent_task_run_id` fields. The SDK reads
+them from the initial input response and keeps them for that execution, so
+accessing metadata does not make a network request.
+
+For a root run, `ctx.metadata.root_task_run_id` equals
+`ctx.metadata.task_run_id` and `ctx.metadata.parent_task_run_id` is `None`.
+IDs are `None` when unavailable.
+
 ### Running the Local Task Server
 
 For local development, use the Render CLI:
@@ -159,6 +170,19 @@ for event in render.workflows.task_run_events([task_run.id]):
 runs = render.workflows.list_task_runs(ListTaskRunsParams(limit=10))
 ```
 
+#### Idempotency Keys
+
+Pass an `idempotency_key` to make starting a run safe to retry. Repeating a call
+with the same key within 24 hours returns the run the first call started instead
+of starting another one, so a client that retries after a timeout does not run
+the task twice. Keys are scoped to a single workflow version.
+
+```python
+task_run = render.workflows.start_task(
+    "my-workflow/charge", [order_id], idempotency_key=f"charge-{order_id}"
+)
+```
+
 #### Async Usage
 
 For async contexts (e.g. FastAPI), use `RenderAsync`:

{render-1.1.0 → render-1.2.0}/README.md

@@ -77,6 +77,17 @@ from tasks_b import app as app_b
 combined = Workflows.from_workflows(app_a, app_b)
 ```
 
+### Task run IDs
+
+The task context exposes a read-only `ctx.metadata` object with
+`task_run_id`, `root_task_run_id`, and `parent_task_run_id` fields. The SDK reads
+them from the initial input response and keeps them for that execution, so
+accessing metadata does not make a network request.
+
+For a root run, `ctx.metadata.root_task_run_id` equals
+`ctx.metadata.task_run_id` and `ctx.metadata.parent_task_run_id` is `None`.
+IDs are `None` when unavailable.
+
 ### Running the Local Task Server
 
 For local development, use the Render CLI:
@@ -134,6 +145,19 @@ for event in render.workflows.task_run_events([task_run.id]):
 runs = render.workflows.list_task_runs(ListTaskRunsParams(limit=10))
 ```
 
+#### Idempotency Keys
+
+Pass an `idempotency_key` to make starting a run safe to retry. Repeating a call
+with the same key within 24 hours returns the run the first call started instead
+of starting another one, so a client that retries after a timeout does not run
+the task twice. Keys are scoped to a single workflow version.
+
+```python
+task_run = render.workflows.start_task(
+    "my-workflow/charge", [order_id], idempotency_key=f"charge-{order_id}"
+)
+```
+
 #### Async Usage
 
 For async contexts (e.g. FastAPI), use `RenderAsync`:

render-1.2.0/example/task/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)"
+    ]
+  }
+}

{render-1.1.0 → render-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "render"
-version = "1.1.0"
+version = "1.2.0"
 description = "Python SDK for Render Workflows"
 authors = [{ name = "Render", email = "support@render.com" }]
 readme = "README.md"

{render-1.1.0 → render-1.2.0}/render/__init__.py

@@ -33,7 +33,7 @@ Async REST API access:
     result = await task_run
 """
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 # Render/RenderAsync are lazy-loaded so the workflow worker path stays fast.
 from typing import TYPE_CHECKING
@@ -42,6 +42,7 @@ from render.workflows import (
     Options,
     Retry,
     TaskContext,
+    TaskRunMetadata,
     Workflows,
     start,
     task,
@@ -58,6 +59,7 @@ __all__ = [
     "RenderAsync",  # Async REST API client
     "Workflows",  # Task definition
     "TaskContext",  # First parameter of every task
+    "TaskRunMetadata",
     # Configuration
     "Options",
     "Retry",

{render-1.1.0 → render-1.2.0}/render/client/tests/test_client.py

@@ -118,6 +118,62 @@ async def test_start_task_success(
     mock_create_task_asyncio.assert_called_once()
 
 
+@pytest.mark.asyncio
+async def test_start_task_omits_idempotency_key_when_not_given(
+    mock_create_task_asyncio, workflows_service, mock_task_run
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    await workflows_service.start_task("test-task", {"input": "data"})
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert "idempotencyKey" not in body.to_dict()
+
+
+@pytest.mark.asyncio
+async def test_start_task_sends_idempotency_key(
+    mock_create_task_asyncio, workflows_service, mock_task_run
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    await workflows_service.start_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert body.to_dict()["idempotencyKey"] == "order-42"
+
+
+@pytest.mark.asyncio
+async def test_run_task_sends_idempotency_key(
+    mocker,
+    mock_create_task_asyncio,
+    workflows_service,
+    mock_task_run,
+    mock_task_run_details,
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+    mocker.patch.object(
+        AwaitableTaskRun,
+        "_wait_for_completion",
+        new_callable=mocker.AsyncMock,
+        return_value=mock_task_run_details,
+    )
+
+    await workflows_service.run_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert body.idempotency_key == "order-42"
+
+
 @pytest.mark.asyncio
 async def test_start_task_failure(mock_create_task_asyncio, workflows_service):
     """Test task start failure."""

{render-1.1.0 → render-1.2.0}/render/client/tests/test_workflows_sync.py

@@ -117,6 +117,58 @@ def test_start_task_success(
     mock_create_task_sync.assert_called_once()
 
 
+def test_start_task_omits_idempotency_key_when_not_given(
+    mock_create_task_sync, sync_workflows_service, mock_task_run
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    sync_workflows_service.start_task("test-task", {"input": "data"})
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert "idempotencyKey" not in body.to_dict()
+
+
+def test_start_task_sends_idempotency_key(
+    mock_create_task_sync, sync_workflows_service, mock_task_run
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    sync_workflows_service.start_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert body.to_dict()["idempotencyKey"] == "order-42"
+
+
+def test_run_task_sends_idempotency_key(
+    mocker,
+    mock_create_task_sync,
+    sync_workflows_service,
+    mock_task_run,
+    mock_task_run_details,
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+    mocker.patch.object(
+        sync_workflows_service,
+        "_task_run_completed_with_sse",
+        return_value=mock_task_run_details,
+    )
+
+    sync_workflows_service.run_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert body.idempotency_key == "order-42"
+
+
 def test_start_task_failure(mock_create_task_sync, sync_workflows_service):
     """Test task start failure."""
 

{render-1.1.0 → render-1.2.0}/render/client/workflows.py

@@ -184,6 +184,8 @@ class WorkflowsService:
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> AwaitableTaskRun:
         """Start a task and return an awaitable task run without waiting for completion.
 
@@ -203,6 +205,9 @@ class WorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             AwaitableTaskRun: A task run that can be awaited for the result
@@ -212,7 +217,11 @@ class WorkflowsService:
             ServerError: For 5xx server errors and network failures
             TimeoutError: If the request times out
         """
-        response = (await self._create_task_api_call(task_slug, input_data)).parsed
+        response = (
+            await self._create_task_api_call(
+                task_slug, input_data, idempotency_key=idempotency_key
+            )
+        ).parsed
 
         return AwaitableTaskRun(response, self)
 
@@ -220,6 +229,8 @@ class WorkflowsService:
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> TaskRunDetails:
         """Start a task and wait for it to complete, returning the result.
 
@@ -231,6 +242,9 @@ class WorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             TaskRunDetails: The completed task run details
@@ -241,12 +255,18 @@ class WorkflowsService:
             TimeoutError: If the request times out
             TaskRunError: If the task run fails with an error
         """
-        task_run = await self.start_task(task_slug, input_data)
+        task_run = await self.start_task(
+            task_slug, input_data, idempotency_key=idempotency_key
+        )
         return await task_run
 
     @handle_http_errors("create task")
     async def _create_task_api_call(
-        self, task_slug: TaskSlug, input_data: TaskData
+        self,
+        task_slug: TaskSlug,
+        input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> Response[Error | TaskRun]:
         """Internal method to make the create task API call."""
         # Convert dict to TaskDataType1 for named parameters
@@ -260,6 +280,7 @@ class WorkflowsService:
         run_task = RunTask(
             task=task_slug,
             input_=task_data_input,
+            idempotency_key=idempotency_key if idempotency_key is not None else UNSET,
         )
 
         # Make the API call

{render-1.1.0 → render-1.2.0}/render/client/workflows_sync.py

@@ -105,6 +105,8 @@ class SyncWorkflowsService:
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> TaskRun:
         """Start a task and return the task run without waiting for completion.
 
@@ -118,6 +120,9 @@ class SyncWorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             TaskRun: The created task run
@@ -127,12 +132,16 @@ class SyncWorkflowsService:
             ServerError: For 5xx server errors and network failures
             TimeoutError: If the request times out
         """
-        return self._create_task_api_call(task_slug, input_data).parsed
+        return self._create_task_api_call(
+            task_slug, input_data, idempotency_key=idempotency_key
+        ).parsed
 
     def run_task(
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> TaskRunDetails:
         """Start a task and wait for it to complete, returning the result.
 
@@ -143,6 +152,9 @@ class SyncWorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             TaskRunDetails: The completed task run details
@@ -153,7 +165,9 @@ class SyncWorkflowsService:
             TimeoutError: If the request times out
             TaskRunError: If the task run fails with an error
         """
-        task_run = self.start_task(task_slug, input_data)
+        task_run = self.start_task(
+            task_slug, input_data, idempotency_key=idempotency_key
+        )
 
         # If already in a terminal state, just get the details
         status = task_run.status.value
@@ -183,7 +197,11 @@ class SyncWorkflowsService:
 
     @handle_http_errors("create task")
     def _create_task_api_call(
-        self, task_slug: TaskSlug, input_data: TaskData
+        self,
+        task_slug: TaskSlug,
+        input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> Response[Error | TaskRun]:
         """Internal method to make the create task API call."""
         # Convert dict to TaskDataType1 for named parameters
@@ -197,6 +215,7 @@ class SyncWorkflowsService:
         run_task = RunTask(
             task=task_slug,
             input_=task_data_input,
+            idempotency_key=idempotency_key if idempotency_key is not None else UNSET,
         )
 
         # Make the API call

{render-1.1.0 → render-1.2.0}/render/experimental/sandbox/api.py

@@ -167,6 +167,7 @@ def _to_snapshot(model: GeneratedSandboxSnapshot) -> Snapshot:
         status=model.status.value,
         plan=model.plan.value,
         requested_at=model.requested_at,
+        name=_set_or_none(model.name),
         captured_at=_set_or_none(model.captured_at),
         expires_at=model.expires_at,
         size_bytes=_set_or_none(model.size_bytes),
@@ -242,6 +243,7 @@ class SandboxApi:
         region: str | None,
         env: dict[str, str] | None,
         snapshot_id: str | None,
+        snapshot_name: str | None,
     ) -> Sandbox:
         body = SandboxPOST(owner_id=owner_id)
         if plan is not None:
@@ -258,16 +260,19 @@ class SandboxApi:
             body.env = SandboxPOSTEnv.from_dict(env)
         if snapshot_id is not None:
             body.snapshot_id = snapshot_id
+        if snapshot_name is not None:
+            body.snapshot_name = snapshot_name
 
         with request_errors("create sandbox"):
             response = await create_sandbox.asyncio_detailed(
                 client=self.client, body=body
             )
-        if snapshot_id is None:
+        snapshot_ref = snapshot_id if snapshot_id is not None else snapshot_name
+        if snapshot_ref is None:
             handle_api_error(response, "create sandbox")
         else:
             _handle_snapshot_api_error(
-                response, snapshot_id, "create sandbox", path_names_snapshot=False
+                response, snapshot_ref, "create sandbox", path_names_snapshot=False
             )
         if not isinstance(response.parsed, GeneratedSandbox):
             raise RenderError("Failed to create sandbox: unexpected response type")
@@ -348,11 +353,13 @@ class SandboxApi:
         self,
         sandbox_id: str,
         kind: str,
+        name: str | None,
         expires_at: datetime | None,
         owner_id: str | Unset,
     ) -> Snapshot:
         body = SandboxSnapshotPOST(
             kind=SandboxSnapshotKind(kind),
+            name=name if name is not None else UNSET,
             expires_at=expires_at if expires_at is not None else UNSET,
         )
         with request_errors("create snapshot"):

{render-1.1.0 → render-1.2.0}/render/experimental/sandbox/api_sync.py

@@ -169,6 +169,7 @@ def _to_snapshot(model: GeneratedSandboxSnapshot) -> Snapshot:
         status=model.status.value,
         plan=model.plan.value,
         requested_at=model.requested_at,
+        name=_set_or_none(model.name),
         captured_at=_set_or_none(model.captured_at),
         expires_at=model.expires_at,
         size_bytes=_set_or_none(model.size_bytes),
@@ -244,6 +245,7 @@ class SyncSandboxApi:
         region: str | None,
         env: dict[str, str] | None,
         snapshot_id: str | None,
+        snapshot_name: str | None,
     ) -> Sandbox:
         body = SandboxPOST(owner_id=owner_id)
         if plan is not None:
@@ -260,14 +262,17 @@ class SyncSandboxApi:
             body.env = SandboxPOSTEnv.from_dict(env)
         if snapshot_id is not None:
             body.snapshot_id = snapshot_id
+        if snapshot_name is not None:
+            body.snapshot_name = snapshot_name
 
         with request_errors("create sandbox"):
             response = create_sandbox.sync_detailed(client=self.client, body=body)
-        if snapshot_id is None:
+        snapshot_ref = snapshot_id if snapshot_id is not None else snapshot_name
+        if snapshot_ref is None:
             handle_api_error(response, "create sandbox")
         else:
             _handle_snapshot_api_error(
-                response, snapshot_id, "create sandbox", path_names_snapshot=False
+                response, snapshot_ref, "create sandbox", path_names_snapshot=False
             )
         if not isinstance(response.parsed, GeneratedSandbox):
             raise RenderError("Failed to create sandbox: unexpected response type")
@@ -348,11 +353,13 @@ class SyncSandboxApi:
         self,
         sandbox_id: str,
         kind: str,
+        name: str | None,
         expires_at: datetime | None,
         owner_id: str | Unset,
     ) -> Snapshot:
         body = SandboxSnapshotPOST(
             kind=SandboxSnapshotKind(kind),
+            name=name if name is not None else UNSET,
             expires_at=expires_at if expires_at is not None else UNSET,
         )
         with request_errors("create snapshot"):

{render-1.1.0 → render-1.2.0}/render/experimental/sandbox/client.py

@@ -60,6 +60,7 @@ class SandboxClient:
         region: str | None = None,
         env: dict[str, str] | None = None,
         snapshot_id: str | None = None,
+        snapshot_name: str | None = None,
     ) -> Sandbox:
         """Create a sandbox and return its initial state.
 
@@ -67,13 +68,16 @@ class SandboxClient:
         workspace defaults enforced by the API (plan starter, 7200s timeout,
         workspace default region and network policy).
 
-        snapshot_id starts the sandbox from that snapshot instead of the base
-        image. The snapshot must be available and in the same sandbox group;
-        for a runtime snapshot, plan must match the snapshot's plan. Raises
-        SnapshotNotFoundError if the snapshot does not exist,
+        snapshot_id starts the sandbox from that snapshot; snapshot_name starts
+        it from the available snapshot that name currently resolves to in the
+        sandbox group. The two parameters are mutually exclusive. For a runtime
+        snapshot, plan must match the snapshot's plan. Raises
+        SnapshotNotFoundError if the snapshot ID or name does not resolve,
         SnapshotNotReadyError if it is not available, and
         SnapshotPlanMismatchError on a runtime plan mismatch.
         """
+        if snapshot_id is not None and snapshot_name is not None:
+            raise ValueError("snapshot_id and snapshot_name are mutually exclusive")
         resolved_owner_id = self._resolve_owner_id(owner_id)
         resolved_region = region or self._default_region
         return await self.api.create(
@@ -84,6 +88,7 @@ class SandboxClient:
             region=resolved_region,
             env=env,
             snapshot_id=snapshot_id,
+            snapshot_name=snapshot_name,
         )
 
     async def from_id(self, sandbox_id: str, *, owner_id: str | None = None) -> Sandbox:
@@ -211,14 +216,16 @@ class SnapshotClient:
         sandbox_id: str,
         *,
         kind: str = "filesystem",
+        name: str | None = None,
         expires_at: datetime | None = None,
         owner_id: str | None = None,
     ) -> Snapshot:
         """Capture a snapshot of a running sandbox.
 
         kind is filesystem (the writable filesystem) or runtime (also memory and
-        CPU state). expires_at must be in the future; omit it for Render's
-        default snapshot lifetime. The snapshot is returned in
+        CPU state). name is case sensitive and can be reused within a sandbox
+        group. expires_at must be in the future; omit it for Render's default
+        snapshot lifetime. The snapshot is returned in
         status creating; poll from_id until it is available or failed. Raises
         SandboxNotFoundError if the sandbox does not exist, and a ClientError
         with code sandbox_not_running if it is not running.
@@ -226,6 +233,7 @@ class SnapshotClient:
         return await self._sandboxes.api.create_snapshot(
             sandbox_id,
             kind,
+            name,
             expires_at,
             self._sandboxes._optional_owner_id(owner_id),
         )

{render-1.1.0 → render-1.2.0}/render/experimental/sandbox/client_sync.py

@@ -62,6 +62,7 @@ class SyncSandboxClient:
         region: str | None = None,
         env: dict[str, str] | None = None,
         snapshot_id: str | None = None,
+        snapshot_name: str | None = None,
     ) -> Sandbox:
         """Create a sandbox and return its initial state.
 
@@ -69,13 +70,16 @@ class SyncSandboxClient:
         workspace defaults enforced by the API (plan starter, 7200s timeout,
         workspace default region and network policy).
 
-        snapshot_id starts the sandbox from that snapshot instead of the base
-        image. The snapshot must be available and in the same sandbox group;
-        for a runtime snapshot, plan must match the snapshot's plan. Raises
-        SnapshotNotFoundError if the snapshot does not exist,
+        snapshot_id starts the sandbox from that snapshot; snapshot_name starts
+        it from the available snapshot that name currently resolves to in the
+        sandbox group. The two parameters are mutually exclusive. For a runtime
+        snapshot, plan must match the snapshot's plan. Raises
+        SnapshotNotFoundError if the snapshot ID or name does not resolve,
         SnapshotNotReadyError if it is not available, and
         SnapshotPlanMismatchError on a runtime plan mismatch.
         """
+        if snapshot_id is not None and snapshot_name is not None:
+            raise ValueError("snapshot_id and snapshot_name are mutually exclusive")
         resolved_owner_id = self._resolve_owner_id(owner_id)
         resolved_region = region or self._default_region
         return self.api.create(
@@ -86,6 +90,7 @@ class SyncSandboxClient:
             region=resolved_region,
             env=env,
             snapshot_id=snapshot_id,
+            snapshot_name=snapshot_name,
         )
 
     def from_id(self, sandbox_id: str, *, owner_id: str | None = None) -> Sandbox:
@@ -213,14 +218,16 @@ class SyncSnapshotClient:
         sandbox_id: str,
         *,
         kind: str = "filesystem",
+        name: str | None = None,
         expires_at: datetime | None = None,
         owner_id: str | None = None,
     ) -> Snapshot:
         """Capture a snapshot of a running sandbox.
 
         kind is filesystem (the writable filesystem) or runtime (also memory and
-        CPU state). expires_at must be in the future; omit it for Render's
-        default snapshot lifetime. The snapshot is returned in
+        CPU state). name is case sensitive and can be reused within a sandbox
+        group. expires_at must be in the future; omit it for Render's default
+        snapshot lifetime. The snapshot is returned in
         status creating; poll from_id until it is available or failed. Raises
         SandboxNotFoundError if the sandbox does not exist, and a ClientError
         with code sandbox_not_running if it is not running.
@@ -228,6 +235,7 @@ class SyncSnapshotClient:
         return self._sandboxes.api.create_snapshot(
             sandbox_id,
             kind,
+            name,
             expires_at,
             self._sandboxes._optional_owner_id(owner_id),
         )