> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Update provisioned performance > Change IOPS or throughput without resizing or restarting the instance. At least one dimension is required. Poll the volume's performance state until applied. Identical pending requests resume the same operation; a different request during an operation is rejected. Billing changes only after application. Selecting the included allowance removes paid extras. ## OpenAPI ````yaml /api-reference/specs/storage.yaml post /v1/volumes/{volume_id}/performance openapi: 3.0.3 info: title: Basaltic Storage API version: 1.0.0 description: > Storage references accept UUIDs, CRNs, or scoped names in one field. Snapshot names require a fixed volume; source_snapshot accepts UUID or nested CRN only. Block volumes with their snapshots and snapshot policies, plus bucket management for object storage. The S3 wire protocol itself is served separately at `objects.{region}.basaltic.cloud`. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://storage.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - BearerAuth: [] paths: /v1/volumes/{volume_id}/performance: post: tags: - Storage summary: Update provisioned performance description: > Change IOPS or throughput without resizing or restarting the instance. At least one dimension is required. Poll the volume's performance state until applied. Identical pending requests resume the same operation; a different request during an operation is rejected. Billing changes only after application. Selecting the included allowance removes paid extras. operationId: updateVolumePerformance parameters: - $ref: '#/components/parameters/VolumeId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VolumePerformanceRequest' responses: '202': description: Performance request accepted content: application/json: schema: $ref: '#/components/schemas/VolumeResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: Volume busy or performance capacity unavailable content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: parameters: VolumeId: name: volume_id in: path description: Volume ID required: true schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: VolumePerformanceRequest: type: object additionalProperties: false description: > Independently provision total sustained, combined read/write performance. Omitted dimensions retain their current value (included allowance on create). SSD permits up to 8000 IOPS and 250 MiB/s; NVMe up to 12000 and 500 MiB/s. The minimum is the volume's included allowance; higher grandfathered allowances remain available free of charge. Throughput is whole MiB/s, except an exact fractional legacy allowance may be selected to remove the paid add-on. Increases require account quota, regional capacity, and healthy storage. Applied extras bill by elapsed duration, including while detached or stopped. properties: iops: type: integer minimum: 1 example: 6000 throughput_mib_s: type: number minimum: 0 example: 250 VolumeResponse: type: object properties: volume: $ref: '#/components/schemas/Volume' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters params: type: object additionalProperties: true description: >- Optional non-sensitive values for interpolation of localized errors, keyed by error code. Never present for server errors. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 Volume: type: object required: - faults properties: id: type: string format: uuid readOnly: true example: 5f8d2c1a-9b3e-4d7a-8c6f-1e2a3b4c5d6e crn: type: string readOnly: true description: Cloud Resource Name (name-based, region-scoped). example: crn:storage:sa-saopaulo-1:my-account:volume/data-volume-01 name: description: >- Resource names must not start with the literal crn: prefix or be UUIDs (canonical, compact, braced, or urn:uuid: forms, in either case). type: string maxLength: 128 example: data-vol-01 description: type: string example: Primary data volume for app-01 tags: $ref: '#/components/schemas/Tags' volume_type: $ref: '#/components/schemas/VolumeTypeName' size_gb: type: integer minimum: 1 maximum: 16384 example: 100 performance: $ref: '#/components/schemas/VolumePerformance' included_io_limits: $ref: '#/components/schemas/IncludedIOLimits' status: $ref: '#/components/schemas/VolumeStatus' bootable: type: boolean description: | Set at create time when the volume is provisioned from a bootable image. Immutable after creation. example: false source_image_id: type: string format: uuid nullable: true description: Image the volume was cloned from, when applicable. example: a3c9e7b1-2d4f-4a6b-8e1c-9f0a1b2c3d4e source_snapshot_id: type: string format: uuid nullable: true description: Snapshot the volume was cloned from (restore path), when applicable. example: 019f24a8-4bbe-7441-93af-6bbac0413943 faults: type: array readOnly: true description: >- Active faults, newest first. Empty when healthy. Status is error if and only if an active error-severity fault exists. Resolved history is retained internally. items: $ref: '#/components/schemas/Fault' created_at: type: string format: date-time readOnly: true example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time readOnly: true example: '2026-01-15T09:31:12Z' Tags: type: object additionalProperties: type: string example: environment: production team: backend VolumeTypeName: type: string enum: - hdd - ssd - nvme description: | Customer-facing storage tier a volume is stored on. Mapped per-region to a storage pool by operator config (the mapping is opaque to API callers). example: ssd VolumePerformance: type: object readOnly: true required: - requested - applied - state properties: requested: $ref: '#/components/schemas/IncludedIOLimits' applied: $ref: '#/components/schemas/IncludedIOLimits' state: type: string enum: - creating - pending - applied operation_id: type: string format: uuid applied_at: type: string format: date-time last_error: type: string description: Latest retryable failure; the accepted request remains durable. IncludedIOLimits: type: object readOnly: true description: > Per-volume combined read/write allowance. New SSD and NVMe volumes include 3000 IOPS and 131072000 bytes/s (125 MiB/s), independently of capacity, with no burst. Existing higher sustained or burst allowances are retained as fixed legacy entitlements. Resizing does not change these values. These are shared-storage ceilings, not a latency or reservation SLA. Additional provisioned performance is charged separately only above this allowance. required: - iops - bytes_per_sec - burst_iops - burst_bytes_per_sec - burst_seconds properties: iops: type: integer minimum: 0 example: 3000 bytes_per_sec: type: integer format: int64 minimum: 0 example: 131072000 burst_iops: type: integer minimum: 0 description: Zero disables IOPS bursting. example: 0 burst_bytes_per_sec: type: integer format: int64 minimum: 0 description: Zero disables throughput bursting. example: 0 burst_seconds: type: integer minimum: 0 description: Legacy burst duration; zero when both burst maxima are disabled. example: 0 VolumeStatus: type: string enum: - creating - available - in_use - extending - deleting - error example: available Fault: type: object required: - code - severity - message - details - first_at - last_at - occurrences properties: code: type: string description: Stable machine-readable code owned by the reporting operation. example: BACKUP_FAILED severity: type: string enum: - error - warning message: type: string example: Backup upload failed. details: type: object nullable: true additionalProperties: true description: Structured context; legacy strings are preserved in legacy_text. first_at: type: string format: date-time description: First observation in this active occurrence series. last_at: type: string format: date-time description: Latest observation in this active occurrence series. occurrences: type: integer minimum: 1 example: 1 responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | An OAuth 2.0 bearer token, sent as `Authorization: Bearer `. This is the recommended way to authenticate. Get one by exchanging a service account's access key pair at `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the standard client-credentials grant, so any OAuth-aware library will obtain and refresh it for you. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.