Is your feature request related to a problem? Please describe.
We need to associate custom metadata (e.g. underlying storage backend info, region, cluster, disk type, project/owner tags) with volumes at creation time. Currently Volume.create() only accepts a name parameter — there is no way to attach arbitrary key-value pairs to a volume. This makes it difficult to tag and organize volumes in multi-tenant environments and prevents storing operational metadata alongside the volume resource itself.
Describe the solution you'd like
Add a metadata: Optional[Dict[str, str]] parameter to volume creation, following the exact same pattern already used for sandboxes. This includes:
- OpenAPI spec — Add
VolumeMetadata schema (additionalProperties: {type: string}), and add metadata fields to NewVolume, Volume, ListedVolume schemas and the GET /volumes query parameters (for filtering).
- API client model — Add
metadata: Union[Unset, Dict[str, str]] to NewVolume in api/client/models/new_volume.py.
- Python SDK — Add
metadata: Optional[Dict[str, str]] to both Volume.create() and AsyncVolume.create(), pass it through to the API model, and surface it in VolumeAndToken/VolumeInfo types so it's available after creation.
- Equivalent changes to JS SDK and CLI for consistency.
Example usage:
volume = Volume.create(
name="my-data",
metadata={
"region": "us-east-1",
"storage_class": "ssd",
"project": "my-project",
}
)
info = volume.get_info(volume.volume_id)
print(info.metadata) # {"region": "us-east-1", ...}Describe alternatives you've considered
- Encoding metadata in the volume name — fragile, limited, and not searchable via the API.
- Maintaining a separate metadata mapping service — adds unnecessary operational complexity for a feature that should be natively supported.
Additional context
Sandbox creation already supports this exact pattern end-to-end:
- Sandbox.create() accepts metadata: Optional[Dict[str, str]] (sandbox_sync/main.py:160)
- NewSandbox API model carries a metadata field (api/client/models/new_sandbox.py)
- SandboxMetadata is defined in the OpenAPI spec as additionalProperties: {type: string} (spec/openapi.yml:258-261)
- SandboxInfo.metadata surfaces it after creation (sandbox/sandbox_api.py:483)
- SandboxQuery.metadata supports filtering sandboxes by metadata when listing (sandbox/sandbox_api.py:565)
This request mirrors that same pattern for volumes.
Is your feature request related to a problem? Please describe.
We need to associate custom metadata (e.g. underlying storage backend info, region, cluster, disk type, project/owner tags) with volumes at creation time. Currently
Volume.create()only accepts anameparameter — there is no way to attach arbitrary key-value pairs to a volume. This makes it difficult to tag and organize volumes in multi-tenant environments and prevents storing operational metadata alongside the volume resource itself.Describe the solution you'd like
Add a
metadata: Optional[Dict[str, str]]parameter to volume creation, following the exact same pattern already used for sandboxes. This includes:VolumeMetadataschema (additionalProperties: {type: string}), and addmetadatafields toNewVolume,Volume,ListedVolumeschemas and theGET /volumesquery parameters (for filtering).metadata: Union[Unset, Dict[str, str]]toNewVolumeinapi/client/models/new_volume.py.metadata: Optional[Dict[str, str]]to bothVolume.create()andAsyncVolume.create(), pass it through to the API model, and surface it inVolumeAndToken/VolumeInfotypes so it's available after creation.Example usage:
Describe alternatives you've considered
Additional context
Sandbox creation already supports this exact pattern end-to-end:
This request mirrors that same pattern for volumes.