{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","examples":{"codes":[]},"method":"patch","params":[],"results":{"codes":[]}},"next":{"description":"","pages":[]},"title":"Update a volume","type":"endpoint","slug":"update-a-volume-v2","excerpt":"","body":"This call updates the details of a specific volume.\n\nLearn more about using the Volumes API for [Amazon S3](http://docs.sevenbridges.com/docs/aws-cloud-storage-tutorial) and for [Google Cloud Storage](http://docs.sevenbridges.com/docs/google-cloud-storage-tutorial).\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cavatica-api.sbgenomics.com/v2/storage/volumes/{volume_id}\",\n      \"language\": \"text\",\n      \"name\": \"API path\"\n    }\n  ]\n}\n[/block]\n##Request\n\n###Example request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PATCH /v2/storage/volumes/rfranklin/output HTTP/1.1\\nHost: cavatica-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75\\nContent-Type: application/json\",\n      \"language\": \"http\",\n      \"name\": null\n    },\n    {\n      \"code\": \"curl  --data ':::at:::patch-volume.json' -s -H \\\"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\\\" -H \\\"Content-Type: application/json\\\" -X PATCH \\\"https://cavatica-api.sbgenomics.com/storage/volumes/rfranklin/output\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"cURL\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n###Header Fields\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Description of value\",\n    \"0-0\": \"`X-SBG-Auth-Token`\\n_required_\",\n    \"0-1\": \"Your Cavatica [authentication token](doc:get-your-authentication-token).\",\n    \"h-2\": \"\",\n    \"1-0\": \"`Content-type`\\n_required_\",\n    \"1-1\": \"`application/json`\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n###Path parameters\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Description of value\",\n    \"0-0\": \"`volume_id`\",\n    \"0-1\": \"The volume that you want to update.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n###Request body\n\nIn the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.\n[block:parameters]\n{\n  \"data\": {\n    \"1-0\": \"`description`\",\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"1-1\": \"String\",\n    \"h-2\": \"Description of value\",\n    \"1-2\": \"An optional description of this volume.\",\n    \"2-0\": \"`service`\\n_required_\",\n    \"2-1\": \"Object\",\n    \"2-2\": \"This object should contain the information about the cloud service that this volume represents.\\n\\nSee the <code><a href=\\\"#section-the-service-object\\\">service</code> object section</a> below for an explanation of its structure.\",\n    \"0-0\": \"`access_mode`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Signifies whether this volume should be used for read-write (`\\\"RW\\\"`) or read-only (`\\\"RO\\\"`) operations.\\n\\nThe access mode is consulted independently of the credentials granted to Seven Bridges when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it.\\n\\n_default:_ `\\\"RW\\\"`\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n###The `service` object\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`credentials`\",\n    \"0-1\": \"Object\",\n    \"0-2\": \"Contains credentials for the underlying cloud provider.\\n\\nFor Amazon Web Services, these credentials depend on the type of AWS identity that is used to connect the volume, *IAM role* or *IAM user*.\\n<span style=\\\"margin:10px;\\\"></span>\\n* AWS IAM user:\\n    * [`access-key-id`](#access-key-id)\\n    * [`secret_access-key`](#secret-access-key)\\n<span style=\\\"margin:10px;\\\"></span>\\n* AWS IAM role:\\n    * <a href=\\\"#external-id\\\">`external_id`</a> (optional, used if an External ID is defined as required in for the role in the AWS console)\\n    * <a href=\\\"#role-arn\\\">`role_arn`</a>\\n<span style=\\\"margin:10px;\\\"></span>\\n\\nFor Google Cloud Storage, these credentials are:\\n\\n* [`client_email`](#client-email)\\n* [`private_key`](#private-key)\",\n    \"1-0\": \"<a name=\\\"access-key-id\\\"></a>`access_key_id`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`, if using an IAM user_</span>\\n_required_\",\n    \"1-1\": \"String\",\n    \"1-2\": \"AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.\",\n    \"2-0\": \"<a name=\\\"secret-access-key\\\"></a>`secret_access_key`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`, if using an IAM user_</span>\\n_required_\",\n    \"2-1\": \"String\",\n    \"2-2\": \"AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.\",\n    \"5-0\": \"<a name=\\\"client-email\\\"></a>`client_email`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `gcs`_</span>\\n_required_\",\n    \"5-1\": \"String\",\n    \"5-2\": \"Google Cloud Platform user email.\",\n    \"6-0\": \"<a name=\\\"private-key\\\"></a>`private_key`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `gcs`_</span>\\n_required_\",\n    \"6-1\": \"String\",\n    \"6-2\": \"Google Cloud Platform private key.\",\n    \"7-0\": \"`properties`\",\n    \"7-1\": \"Object\",\n    \"7-2\": \"Contains properties of specific service.\",\n    \"8-0\": \"`sse_algorithm`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`_</span>\",\n    \"8-1\": \"String\",\n    \"8-2\": \"Use default AES256 server-side encryption when writing to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)\\n\\nCan be:\\n  * AES256 (default)\\n  * `aws:kms`\\n  * null\\n\\n_default: AES256_\",\n    \"9-0\": \"`sse_aws_kms_key_id`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`_</span>\",\n    \"9-2\": \"Provide your AWS KMS ID here if you specify `aws:kms` as your `sse_algorithm`. Learn more about [AWS KMS](https://aws.amazon.com/documentation/kms/).\",\n    \"9-1\": \"String\",\n    \"3-0\": \"<a name=\\\"external-id\\\"></a> `external_id`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`, if using an IAM role_</span>\",\n    \"4-0\": \"<a name=\\\"role-arn\\\"></a>`role_arn`\\n\\n<span style=\\\"color:#871818\\\">_applies to type: `s3`, if using an IAM role_</span>\\n_required_\",\n    \"3-1\": \"String\",\n    \"4-1\": \"String\",\n    \"3-2\": \"Optional information that you can use in an IAM role trust policy to designate who can assume the role. Must be provided if it is configured in your role trust policy on AWS. [More info](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).\",\n    \"4-2\": \"The [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns) (Amazon Resource Name) for the role that you want to use to connect the volume.\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n \n\n###Example request body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"description\\\": null,\\n  \\\"service\\\": {\\n    \\\"properties\\\": {\\n      \\\"sse_algorithm\\\": \\\"AES256\\\"\\n    }\\n  },\\n}\\n\",\n      \"language\": \"text\",\n      \"name\": \"Example request body\"\n    }\n  ]\n}\n[/block]\n##Response\n\n[See a list of Cavatica-specific response codes that may be contained in the body of the response.](doc:api-status-codes) \n\n###Response body\nThe response object contains information about the specified volume. The information is structured using the following key-value pairs:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`active`\",\n    \"1-0\": \"`id`\",\n    \"0-1\": \"Boolean\",\n    \"1-1\": \"String\",\n    \"2-1\": \"String\",\n    \"2-0\": \"`name`\",\n    \"3-0\": \"`description`\",\n    \"3-1\": \"String\",\n    \"4-0\": \"`service`\",\n    \"4-1\": \"Object\",\n    \"5-0\": \"`created_on`\",\n    \"5-1\": \"String\",\n    \"6-0\": \"`modified_on`\",\n    \"6-1\": \"String\",\n    \"0-2\": \"If a volume is deactivated, this field will be set to false\",\n    \"1-2\": \"ID of this volume, containing owner/name\",\n    \"2-2\": \"Name of the volume.\",\n    \"3-2\": \"The description of this volume.\",\n    \"4-2\": \"This object more closely describes the mapping of the volume to the cloud service where the data is stored.\\n\\nSee the <code><a href=\\\"#section-the-service-object\\\">service</code> object section</a> above for an explanation of its structure.\",\n    \"5-2\": \"The date and time this volume was created.\",\n    \"6-2\": \"The date and time this volume was last modified.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\n\n###Example response body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"href\\\": \\\"https://cavatica-api.sbgenomics.com/v2/storage/volumes/rfranklin/output\\\",\\n  \\\"id\\\": \\\"rfranklin/output\\\",\\n  \\\"name\\\": \\\"output\\\",\\n  \\\"access_mode\\\": \\\"RW\\\",\\n  \\\"service\\\": {\\n    \\\"type\\\": \\\"S3\\\",\\n    \\\"bucket\\\": \\\"output_bucket\\\",\\n    \\\"prefix\\\": \\\"outfiles\\\",\\n    \\\"endpoint\\\": \\\"s3.amazonaws.com\\\",\\n    \\\"credentials\\\": {\\n      \\\"access_key_id\\\": \\\"AKIAJRC7TPMRMDKOFXGA\\\"\\n    },\\n    \\\"properties\\\": {\\n      \\\"sse_algorithm\\\": \\\"AES256\\\"\\n    }\\n  },\\n  \\\"created_on\\\": \\\"2016-06-30T08:14:02Z\\\",\\n  \\\"modified_on\\\": \\\"2016-06-30T08:14:02Z\\\",\\n  \\\"active\\\": true\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to [list volumes](list-volumes-v2).\"\n}\n[/block]","updates":[],"order":84,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5790a4f9f7ff000e004ba3a7","createdAt":"2016-07-21T10:33:29.496Z","project":"5773dcfc255e820e00e1cd4d","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Cavatica API","slug":"api","order":18,"from_sync":false,"reference":false,"_id":"5773df36904b0c0e00ef05ff","createdAt":"2016-06-29T14:46:14.277Z","version":"5773dcfc255e820e00e1cd50","__v":0,"project":"5773dcfc255e820e00e1cd4d"},"user":"575e85ac41c8ba0e00259a44","__v":1,"parentDoc":null,"version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5773dcfc255e820e00e1cd51","5773df36904b0c0e00ef05ff","577baf92451b1e0e006075ac","577bb183b7ee4a0e007c4e8d","577ce77a1cf3cb0e0048e5ea","577d11865fd4de0e00cc3dab","578e62792c3c790e00937597","578f4fd98335ca0e006d5c84","578f5e5c3d04570e00976ebb","57bc35f7531e000e0075d118","57f801b3760f3a1700219ebb","5804d55d1642890f00803623","581c8d55c0dc651900aa9350","589dcf8ba8c63b3b00c3704f","594cebadd8a2f7001b0b53b2","59a562f46a5d8c00238e309a","5a2aa096e25025003c582b58","5a2e79566c771d003ca0acd4","5a3a5166142db90026f24007","5a3a52b5bcc254001c4bf152","5a3a574a2be213002675c6d2","5a3a66bb2be213002675cb73","5a3a6e4854faf60030b63159","5c8a68278e883901341de571","5cb9971e57bf020024523c7b","5cbf1683e2a36d01d5012ecd","5dc15666a4f788004c5fd7d7","5eaff69e844d67003642a020","5eb00899b36ba5002d35b0c1","5eb0172be179b70073dc936e","5eb01b42b36ba5002d35ebba","5eb01f202654a20136813093","5eb918ef149186021c9a76c8","5f0839d3f4b24e005ebbbc29"],"_id":"5773dcfc255e820e00e1cd50","__v":34,"createdAt":"2016-06-29T14:36:44.812Z","releaseDate":"2016-06-29T14:36:44.812Z","project":"5773dcfc255e820e00e1cd4d"},"githubsync":""}

Get started

Cavatica Projects

Find apps

Bring your private data

Set metadata associated with a file

Collaborate securely

BRING YOUR TOOLS

Docker

Developer tools

EDIT AN APP

Tool wrapping tips and tricks

Describe your tool (Legacy)

Browse public datasets

Run an analysis

Task Execution

Review a task

Cavatica Datasets

Cavatica API

Connect cloud storage

SBFS (Beta)

BULK API ACTIONS

ASYNC BULK ACTIONS

DRS API

CAVATICA DATASETS API (Advanced Access)

Video tutorials

Data Cruncher

SBFS (Beta)

SBFS Command reference

patchUpdate a volume

This call updates the details of a specific volume. Learn more about using the Volumes API for [Amazon S3](http://docs.sevenbridges.com/docs/aws-cloud-storage-tutorial) and for [Google Cloud Storage](http://docs.sevenbridges.com/docs/google-cloud-storage-tutorial). [block:code] { "codes": [ { "code": "https://cavatica-api.sbgenomics.com/v2/storage/volumes/{volume_id}", "language": "text", "name": "API path" } ] } [/block] ##Request ###Example request [block:code] { "codes": [ { "code": "PATCH /v2/storage/volumes/rfranklin/output HTTP/1.1\nHost: cavatica-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75\nContent-Type: application/json", "language": "http", "name": null }, { "code": "curl --data '@patch-volume.json' -s -H \"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\" -H \"Content-Type: application/json\" -X PATCH \"https://cavatica-api.sbgenomics.com/storage/volumes/rfranklin/output\"", "language": "curl", "name": "cURL" } ], "sidebar": true } [/block] ###Header Fields [block:parameters] { "data": { "h-0": "Key", "h-1": "Description of value", "0-0": "`X-SBG-Auth-Token`\n_required_", "0-1": "Your Cavatica [authentication token](doc:get-your-authentication-token).", "h-2": "", "1-0": "`Content-type`\n_required_", "1-1": "`application/json`" }, "cols": 2, "rows": 2 } [/block] ###Path parameters [block:parameters] { "data": { "h-0": "Key", "h-1": "Description of value", "0-0": "`volume_id`", "0-1": "The volume that you want to update." }, "cols": 2, "rows": 1 } [/block] ###Request body In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table. [block:parameters] { "data": { "1-0": "`description`", "h-0": "Key", "h-1": "Data type of value", "1-1": "String", "h-2": "Description of value", "1-2": "An optional description of this volume.", "2-0": "`service`\n_required_", "2-1": "Object", "2-2": "This object should contain the information about the cloud service that this volume represents.\n\nSee the <code><a href=\"#section-the-service-object\">service</code> object section</a> below for an explanation of its structure.", "0-0": "`access_mode`", "0-1": "String", "0-2": "Signifies whether this volume should be used for read-write (`\"RW\"`) or read-only (`\"RO\"`) operations.\n\nThe access mode is consulted independently of the credentials granted to Seven Bridges when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it.\n\n_default:_ `\"RW\"`" }, "cols": 3, "rows": 3 } [/block] ###The `service` object [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type", "h-2": "Description", "0-0": "`credentials`", "0-1": "Object", "0-2": "Contains credentials for the underlying cloud provider.\n\nFor Amazon Web Services, these credentials depend on the type of AWS identity that is used to connect the volume, *IAM role* or *IAM user*.\n<span style=\"margin:10px;\"></span>\n* AWS IAM user:\n * [`access-key-id`](#access-key-id)\n * [`secret_access-key`](#secret-access-key)\n<span style=\"margin:10px;\"></span>\n* AWS IAM role:\n * <a href=\"#external-id\">`external_id`</a> (optional, used if an External ID is defined as required in for the role in the AWS console)\n * <a href=\"#role-arn\">`role_arn`</a>\n<span style=\"margin:10px;\"></span>\n\nFor Google Cloud Storage, these credentials are:\n\n* [`client_email`](#client-email)\n* [`private_key`](#private-key)", "1-0": "<a name=\"access-key-id\"></a>`access_key_id`\n\n<span style=\"color:#871818\">_applies to type: `s3`, if using an IAM user_</span>\n_required_", "1-1": "String", "1-2": "AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.", "2-0": "<a name=\"secret-access-key\"></a>`secret_access_key`\n\n<span style=\"color:#871818\">_applies to type: `s3`, if using an IAM user_</span>\n_required_", "2-1": "String", "2-2": "AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.", "5-0": "<a name=\"client-email\"></a>`client_email`\n\n<span style=\"color:#871818\">_applies to type: `gcs`_</span>\n_required_", "5-1": "String", "5-2": "Google Cloud Platform user email.", "6-0": "<a name=\"private-key\"></a>`private_key`\n\n<span style=\"color:#871818\">_applies to type: `gcs`_</span>\n_required_", "6-1": "String", "6-2": "Google Cloud Platform private key.", "7-0": "`properties`", "7-1": "Object", "7-2": "Contains properties of specific service.", "8-0": "`sse_algorithm`\n\n<span style=\"color:#871818\">_applies to type: `s3`_</span>", "8-1": "String", "8-2": "Use default AES256 server-side encryption when writing to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)\n\nCan be:\n * AES256 (default)\n * `aws:kms`\n * null\n\n_default: AES256_", "9-0": "`sse_aws_kms_key_id`\n\n<span style=\"color:#871818\">_applies to type: `s3`_</span>", "9-2": "Provide your AWS KMS ID here if you specify `aws:kms` as your `sse_algorithm`. Learn more about [AWS KMS](https://aws.amazon.com/documentation/kms/).", "9-1": "String", "3-0": "<a name=\"external-id\"></a> `external_id`\n\n<span style=\"color:#871818\">_applies to type: `s3`, if using an IAM role_</span>", "4-0": "<a name=\"role-arn\"></a>`role_arn`\n\n<span style=\"color:#871818\">_applies to type: `s3`, if using an IAM role_</span>\n_required_", "3-1": "String", "4-1": "String", "3-2": "Optional information that you can use in an IAM role trust policy to designate who can assume the role. Must be provided if it is configured in your role trust policy on AWS. [More info](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).", "4-2": "The [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns) (Amazon Resource Name) for the role that you want to use to connect the volume." }, "cols": 3, "rows": 10 } [/block] ###Example request body [block:code] { "codes": [ { "code": "{\n \"description\": null,\n \"service\": {\n \"properties\": {\n \"sse_algorithm\": \"AES256\"\n }\n },\n}\n", "language": "text", "name": "Example request body" } ] } [/block] ##Response [See a list of Cavatica-specific response codes that may be contained in the body of the response.](doc:api-status-codes) ###Response body The response object contains information about the specified volume. The information is structured using the following key-value pairs: [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description of value", "0-0": "`active`", "1-0": "`id`", "0-1": "Boolean", "1-1": "String", "2-1": "String", "2-0": "`name`", "3-0": "`description`", "3-1": "String", "4-0": "`service`", "4-1": "Object", "5-0": "`created_on`", "5-1": "String", "6-0": "`modified_on`", "6-1": "String", "0-2": "If a volume is deactivated, this field will be set to false", "1-2": "ID of this volume, containing owner/name", "2-2": "Name of the volume.", "3-2": "The description of this volume.", "4-2": "This object more closely describes the mapping of the volume to the cloud service where the data is stored.\n\nSee the <code><a href=\"#section-the-service-object\">service</code> object section</a> above for an explanation of its structure.", "5-2": "The date and time this volume was created.", "6-2": "The date and time this volume was last modified." }, "cols": 3, "rows": 7 } [/block] ###Example response body [block:code] { "codes": [ { "code": "{\n \"href\": \"https://cavatica-api.sbgenomics.com/v2/storage/volumes/rfranklin/output\",\n \"id\": \"rfranklin/output\",\n \"name\": \"output\",\n \"access_mode\": \"RW\",\n \"service\": {\n \"type\": \"S3\",\n \"bucket\": \"output_bucket\",\n \"prefix\": \"outfiles\",\n \"endpoint\": \"s3.amazonaws.com\",\n \"credentials\": {\n \"access_key_id\": \"AKIAJRC7TPMRMDKOFXGA\"\n },\n \"properties\": {\n \"sse_algorithm\": \"AES256\"\n }\n },\n \"created_on\": \"2016-06-30T08:14:02Z\",\n \"modified_on\": \"2016-06-30T08:14:02Z\",\n \"active\": true\n}", "language": "json" } ], "sidebar": true } [/block] [block:callout] { "type": "success", "body": "Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to [list volumes](list-volumes-v2)." } [/block]