Feature Request: Add metadata parameter to volume creation (similar to sandbox create)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 13.9k
- Forks
- 1k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 70
Description
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
VolumeMetadataschema (additionalProperties: {type: string}), and addmetadatafields toNewVolume,Volume,ListedVolumeschemas and theGET /volumesquery parameters (for filtering). - API client model — Add
metadata: Union[Unset, Dict[str, str]]toNewVolumeinapi/client/models/new_volume.py. - Python SDK — Add
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. - 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the volume paths with the existing sandbox pattern in sandbox_sync/main.py:160, api/client/models/new_sandbox.py, sandbox/sandbox_api.py, and spec/openapi.yml:258-261. Then trace volume creation and info types across the Python SDK, JS SDK, CLI, and api/client/models/new_volume.py. Done means metadata is accepted, persisted, returned, and filterable consistently across the OpenAPI schemas and all clients.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi, python, typescript
- Domain
- api, backend, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100