# Volumes ## Get Volumes > Retrieves all storage volumes for a specific project.\ > \ > Args:\ > user\_info: Authenticated user information.\ > project: Identifier of the project to list volumes for.\ > region: Optional region filter.\ > include\_deleted: When True, includes soft-deleted volumes in the\ > response. Deleted volumes have a non-null \`\`deleted\_at\`\` field.\ > Defaults to False.\ > \ > Returns:\ > list\[VolumeModel]: A list of volume models belonging to the project.\ > \ > Raises:\ > HTTPException: If project is missing or user is not authorized. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"VolumeModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"region":{"type":"string","title":"Region"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deleted_at":{"type":"string","format":"datetime","nullable":true},"capacity_gb":{"type":"integer","title":"Capacity Gb"},"project":{"type":"string","title":"Project"},"interface":{"type":"string","enum":["Block","File"],"title":"Interface"},"bids":{"items":{"type":"string"},"type":"array","title":"Bids"},"reservations":{"items":{"type":"string"},"type":"array","title":"Reservations"},"attachments":{"additionalProperties":{"type":"string"},"type":"object","title":"Attachments"}},"type":"object","required":["fid","name","region","created_at","deleted_at","capacity_gb","project","interface","bids","reservations","attachments"],"title":"VolumeModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/volumes":{"get":{"tags":["volumes"],"summary":"Get Volumes","description":"Retrieves all storage volumes for a specific project.\n\nArgs:\n user_info: Authenticated user information.\n project: Identifier of the project to list volumes for.\n region: Optional region filter.\n include_deleted: When True, includes soft-deleted volumes in the\n response. Deleted volumes have a non-null ``deleted_at`` field.\n Defaults to False.\n\nReturns:\n list[VolumeModel]: A list of volume models belonging to the project.\n\nRaises:\n HTTPException: If project is missing or user is not authorized.","operationId":"get_volumes_v2_volumes_get","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"region","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Deleted"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VolumeModel"},"title":"Response Get Volumes V2 Volumes Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Volume > Creates a new storage volume.\ > \ > Args:\ > user\_info: Authenticated user information.\ > body: Request body containing volume creation details (size, region, etc).\ > \ > Returns:\ > VolumeModel: The created volume model.\ > \ > Raises:\ > HTTPException: If user unauthorized or creation fails. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"CreateVolumeRequest":{"properties":{"name":{"type":"string","maxLength":64,"pattern":"^[a-z]([-a-z0-9]*[a-z0-9])?$","title":"Name"},"project":{"type":"string","title":"Project"},"disk_interface":{"type":"string","enum":["Block","File"],"title":"Disk Interface"},"region":{"type":"string","title":"Region"},"size_gb":{"title":"Size Gb","gt":{"_unit":"b","_value":0},"lt":{"_unit":"pib","_value":2}}},"type":"object","required":["name","project","disk_interface","region","size_gb"],"title":"CreateVolumeRequest","description":"Request model for creating a new storage volume."},"VolumeModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"region":{"type":"string","title":"Region"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deleted_at":{"type":"string","format":"datetime","nullable":true},"capacity_gb":{"type":"integer","title":"Capacity Gb"},"project":{"type":"string","title":"Project"},"interface":{"type":"string","enum":["Block","File"],"title":"Interface"},"bids":{"items":{"type":"string"},"type":"array","title":"Bids"},"reservations":{"items":{"type":"string"},"type":"array","title":"Reservations"},"attachments":{"additionalProperties":{"type":"string"},"type":"object","title":"Attachments"}},"type":"object","required":["fid","name","region","created_at","deleted_at","capacity_gb","project","interface","bids","reservations","attachments"],"title":"VolumeModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/volumes":{"post":{"tags":["volumes"],"summary":"Create Volume","description":"Creates a new storage volume.\n\nArgs:\n user_info: Authenticated user information.\n body: Request body containing volume creation details (size, region, etc).\n\nReturns:\n VolumeModel: The created volume model.\n\nRaises:\n HTTPException: If user unauthorized or creation fails.","operationId":"create_volume_v2_volumes_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVolumeRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Volume > Deletes a storage volume.\ > \ > Permanently removes a volume. The volume must not be currently in use/attached.\ > \ > Args:\ > user\_info: Authenticated user information.\ > volume\_fid: Identifier of the volume to delete.\ > \ > Raises:\ > HTTPException: If volume not found, user unauthorized, or volume is in use. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/volumes/{volume_fid}":{"delete":{"tags":["volumes"],"summary":"Delete Volume","description":"Deletes a storage volume.\n\nPermanently removes a volume. The volume must not be currently in use/attached.\n\nArgs:\n user_info: Authenticated user information.\n volume_fid: Identifier of the volume to delete.\n\nRaises:\n HTTPException: If volume not found, user unauthorized, or volume is in use.","operationId":"delete_volume_v2_volumes__volume_fid__delete","parameters":[{"name":"volume_fid","in":"path","required":true,"schema":{"type":"string","title":"Volume Fid"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Update Volume > Updates a storage volume's mutable properties (e.g., name).\ > \ > Args:\ > user\_info: Authenticated user information.\ > volume\_fid: Identifier of the volume to update.\ > body: Request body containing updated fields.\ > \ > Returns:\ > VolumeModel: The updated volume model.\ > \ > Raises:\ > HTTPException: If volume not found or user unauthorized. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"UpdateVolumeRequest":{"properties":{"name":{"type":"string","maxLength":64,"pattern":"^[a-z]([-a-z0-9]*[a-z0-9])?$","title":"Name"}},"type":"object","required":["name"],"title":"UpdateVolumeRequest","description":"Request model for updating an existing storage volume.\n\nAttributes:\n name: New name for the volume. Must follow naming conventions."},"VolumeModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"region":{"type":"string","title":"Region"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deleted_at":{"type":"string","format":"datetime","nullable":true},"capacity_gb":{"type":"integer","title":"Capacity Gb"},"project":{"type":"string","title":"Project"},"interface":{"type":"string","enum":["Block","File"],"title":"Interface"},"bids":{"items":{"type":"string"},"type":"array","title":"Bids"},"reservations":{"items":{"type":"string"},"type":"array","title":"Reservations"},"attachments":{"additionalProperties":{"type":"string"},"type":"object","title":"Attachments"}},"type":"object","required":["fid","name","region","created_at","deleted_at","capacity_gb","project","interface","bids","reservations","attachments"],"title":"VolumeModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/volumes/{volume_fid}":{"patch":{"tags":["volumes"],"summary":"Update Volume","description":"Updates a storage volume's mutable properties (e.g., name).\n\nArgs:\n user_info: Authenticated user information.\n volume_fid: Identifier of the volume to update.\n body: Request body containing updated fields.\n\nReturns:\n VolumeModel: The updated volume model.\n\nRaises:\n HTTPException: If volume not found or user unauthorized.","operationId":"update_volume_v2_volumes__volume_fid__patch","parameters":[{"name":"volume_fid","in":"path","required":true,"schema":{"type":"string","title":"Volume Fid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVolumeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mithril.ai/compute-api/compute-api-reference/volumes.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.