> ## Documentation Index > Fetch the complete documentation index at: https://docs.baseten.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a sandbox volume > Creates persistent storage for sandbox files. Related guide: [Sandbox volumes](https://docs.baseten.co/sandboxes/volumes.md). ## OpenAPI ````yaml post /v1/sandboxes/volumes openapi: 3.1.0 info: description: REST API for management of Baseten resources title: Baseten management API version: 1.0.0 servers: - url: https://api.baseten.co security: - BearerAuth: [] paths: /v1/sandboxes/volumes: post: tags: - Volumes summary: Create a volume description: >- Create a persistent volume that outlives the sandboxes it is mounted in. Mount it at sandbox creation with the volumes field; a volume is mounted in at most one sandbox at a time and must be in the same region. The name is generated when omitted. Volume size and count are limited by the team's plan. operationId: CreateSandboxVolume parameters: - $ref: '#/components/parameters/TeamId' - $ref: '#/components/parameters/TeamIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSandboxVolumeRequestV1' examples: complete: $ref: '#/components/examples/CreateSandboxVolume' responses: '201': description: >- Volume created. Provisioning may continue; inspect status for readiness. content: application/json: schema: $ref: '#/components/schemas/SandboxVolumeV1' examples: complete: $ref: '#/components/examples/SandboxVolumeReady' '400': $ref: '#/components/responses/SandboxError400' '401': $ref: '#/components/responses/SandboxError401' '403': $ref: '#/components/responses/SandboxError403' '409': $ref: '#/components/responses/SandboxError409' '429': $ref: '#/components/responses/SandboxError429' '500': $ref: '#/components/responses/SandboxError500' components: parameters: TeamId: name: team_id in: query required: false description: >- Optional team ID. Must match X-Team-Id when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string TeamIdHeader: name: X-Team-Id in: header required: false description: >- Optional team ID. Must match the team_id query parameter when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string schemas: CreateSandboxVolumeRequestV1: type: object description: Volume to create. Only size is required. properties: name: type: string description: Volume name, unique in the team. Generated when omitted. minLength: 1 maxLength: 49 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ example: datasets size: oneOf: - type: string - type: integer x-go-type: VolumeSize description: >- Capacity, as a size (e.g. "10Gi", "512Mi") or a number of Mi (e.g. 1024). Can grow later, never shrink. example: 10Gi region: type: string description: >- Region of the volume. Defaults to the default sandbox region. Sandboxes mounting it must be in the same region. example: us-pdx-1 labels: $ref: '#/components/schemas/SandboxMetadataLabelsV1' required: - size SandboxVolumeV1: type: object description: Persistent volume. properties: name: type: string description: >- Volume name, used in volume_name path parameters and sandbox volumes. readOnly: true example: datasets size: oneOf: - type: string - type: integer x-go-type: VolumeSize description: >- Capacity, as a size (e.g. "10Gi", "512Mi") or a number of Mi (e.g. 1024). example: 10Gi region: type: string description: Region of the volume. example: us-pdx-1 status: $ref: '#/components/schemas/SandboxVolumeStatusV1' attached_to: type: string description: >- Name of the sandbox the volume is mounted in. Absent when not mounted. readOnly: true example: baseten-api-review-0916 labels: description: Labels. Omitted from list responses. allOf: - $ref: '#/components/schemas/SandboxMetadataLabelsV1' created_at: type: string format: date-time readOnly: true example: '2026-10-12T12:00:00Z' updated_at: type: string format: date-time readOnly: true example: '2026-10-12T12:00:00Z' created_by: type: string description: User or service account that created the volume. readOnly: true example: sandbox-automation updated_by: type: string description: User or service account that last updated the volume. readOnly: true example: sandbox-automation required: - name - size - region - status SandboxMetadataLabelsV1: type: object description: >- Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy. additionalProperties: type: string example: env: development project: api-review team: engineering SandboxVolumeStatusV1: type: string description: Volume status, always uppercase. enum: - DEPLOYING - DEPLOYED - FAILED - DELETING example: DEPLOYED examples: CreateSandboxVolume: summary: One gigabyte volume value: name: datasets size: 10Gi region: us-pdx-1 labels: project: api-review SandboxVolumeReady: summary: Volume mounted in a sandbox value: name: datasets size: 10Gi region: us-pdx-1 status: DEPLOYED attached_to: baseten-api-review-0916 labels: project: api-review created_at: '2026-10-12T12:00:00Z' updated_at: '2026-10-12T12:00:00Z' created_by: sandbox-automation updated_by: sandbox-automation responses: SandboxError400: description: >- Invalid request. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INVALID_REQUEST message: One or more request parameters are invalid. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError401: description: >- Missing or invalid authentication. Returns a JSON error with code, message, and optional details. content: application/json: example: code: UNAUTHORIZED message: Provide a valid authentication token in the Authorization header. details: header: Authorization SandboxError403: description: >- Insufficient permissions. Returns a JSON error with code, message, and optional details. content: application/json: example: code: FORBIDDEN message: >- This authentication token does not grant permission to perform this operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError409: description: >- Resource is currently in use or conflicts with the requested operation. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RESOURCE_IN_USE message: >- The resource is currently in use or conflicts with the requested operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError429: description: >- Request limit exceeded. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RATE_LIMITED message: Too many requests. Try again in 30 seconds. details: retry_after_seconds: 30 SandboxError500: description: >- Internal server error. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INTERNAL_ERROR message: The request could not be completed. Try again later. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send `Authorization: Bearer `. The legacy `Authorization: Api-Key ` scheme is also accepted. ````