{"_id":"568e64135e12fb0d00325160","version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":38,"createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77","59a555bccdbd85001bfb1442"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"554340dfb7f4540d00fcef1d","__v":3,"project":"55faf11ba62ba1170021a9a7","category":{"_id":"55faf9aa17b9d00d00969f49","pages":["56312d239ead230d00a188f2","56312e0d82d96a0d00b0fb08","56315777fc94aa0d00e9b553","56315b779ead230d00a1894a","5631657c9c25801700dac34f","56317884fc94aa0d00e9b586","56318386c3b04b0d00ba9bb9","563240ccdcc27a170082363b","563240dfbddb091700ad5e82","563240edfe9acd1900cc1d10","56324504fa40240d007c8d5f","56324b30c3b04b0d00ba9c96","563273ae45f2cb0d006be3fa","563273c08c9cda0d0025266d","563273cc38f8aa0d00d30f55","563273d838f8aa0d00d30f59","5632740945f2cb0d006be3fc","56327411df556c0d00cd0905","5632741b8c9cda0d0025266f","563274ea10b6040d008793d8","5632757cdf556c0d00cd0908","563275b710b6040d008793da","563275f938f8aa0d00d30f60","5632762fb904a10d0032f6fc","5632767110b6040d008793dd","563276c0b904a10d0032f700","5632770162c48a0d00334d53","5632843d8c9cda0d00252698","5632846e62c48a0d00334d78","56328a7e49e16d0d00122420","56328aaf49e16d0d00122425","56328b2238f8aa0d00d30f88","56328b6c8c9cda0d002526a2","56328c0710b6040d008793ff","56328c3710b6040d00879401","56328c5938f8aa0d00d30f8c","56328c90b904a10d0032f722","56328cc449e16d0d0012242a","56328ce68c9cda0d002526a8","56328d1338f8aa0d00d30f8e","56328d5810b6040d00879407","56328d7cdf556c0d00cd092f","56328d9a10b6040d00879409","56328db438f8aa0d00d30f92","56328dd762c48a0d00334d8b","56328df649e16d0d0012242d","56328e1edf556c0d00cd0931","56328e4662c48a0d00334d8e","56328e5edf556c0d00cd0933","56328e8f8c9cda0d002526ab","56328eb3b904a10d0032f72a","56328edb38f8aa0d00d30f95","56328ef210b6040d0087940d","56328f148c9cda0d002526ad","56328f2962c48a0d00334d90","56328f54b904a10d0032f72c","56328f6c38f8aa0d00d30f98","56328f858c9cda0d002526af","56328fae62c48a0d00334d95","56328fd838f8aa0d00d30f9c","5637f069ee0ee60d0024ec18","5641ffaa9417b40d00c0fc35","564355240d9748190079dea9","5644cfeb2c74cf1900da4831","56450f856b0ca50d00f6bd8f","56706537cbb2fb0d00f7c7dd","567065bc3d29830d00376213","56706fc2cbb2fb0d00f7c87e","568bf5a1e662f40d00eee866","568c0699e662f40d00eee881","568cff0274c77f2d00d56d51","568d10f58602880d001ce277","568d2abc37b636250036b904","568d343413c5ad0d00b34efb","568d593a8602880d001ce2d3","568e64135e12fb0d00325160","568e66f05e12fb0d00325162","568e78aa5e12fb0d0032517a","569433cfd8c04d1700e5ae0c","56943723d8c04d1700e5ae14","5694393b3e9d080d00f0655d","5694e6cf953b810d008f91bc","5694f301c5c5ce0d00058e68","569502ef9797fa1900f704e7","5695063bcaa32519009c40b3","569511cccaa32519009c40d9","569557e2fcb1032d0089dfe2","569562fefcb1032d0089dfee","56956428fe18811700c9c058","569639b87596a90d0014e5a3","56a90197e590350d004b5103","56a9021e9ec7660d002e08c2"],"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","__v":92,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-17T17:34:34.937Z","from_sync":false,"order":27,"slug":"api","title":"API Reference"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-07T13:11:47.903Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"method":"patch","auth":"required","params":[],"url":""},"isReference":true,"order":32,"body":"This call updates the name, the full set metadata, and tags for a specified file.\n\nFiles are specified by their IDs, which you can obtain by making the API call to [list files in a project ](doc:list-files-in-a-project).\n\nA full list of metadata fields and their permissible values on the CGC is available on the page [TCGA Metadata](doc:metadata-for-private-data). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cgc-api.sbgenomics.com/v2/files/{file_id}\",\n      \"language\": \"text\",\n      \"name\": \"Path\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"File names and IDs\",\n  \"body\": \"Note that the file name is not the same as its ID. The ID is a hexadecimal string, automatically assigned to a file in a project. The file's name is a human-readable string. For information, please see [the API overview](http://docs.cancergenomicscloud.org/docs/the-cgc-api#section-identifying-projects-users-apps-files-and-tasks).\"\n}\n[/block]\n##Custom metadata fields\n\nApart from the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the CGC. Custom metadata can be added via the command line uploader or via the API, but *not* through the visual interface.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by [getting file details via the API](doc:get-file-details).\"\n}\n[/block]\nWhen adding custom metadata fields, you need to pay attention to the following set of rules:\n  * Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the CGC.\n  * Maximum number of key-value pairs per file is 1000, including null-value keys.\n  * Keys and values are UTF-8 encoded strings.\n  * Maximum length of a key is 100 bytes (UTF-8 encoding).\n  * Maximum length of a value is 300 bytes (UTF-8 encoding).\n \n##TAGS\n\nYou can use this API request to add or edit previously existing tags for your file. You can tag your files on the CGC with keywords to make it easier to identify and organize files you’ve imported from datasets or copied between projects. Learn more about [tagging your files](doc:tag-your-files) on the CGC.\n\nIn addition to editing tags on your files, you can do the following via the API:\n\n  * [Add tags to a file](doc:add-tags-to-a-file) \n  * [View tags you've set on your files](doc:get-file-details) \n  * [Filter files by tags](doc:list-files-in-a-project#tags)\n\n##Request\n\n###Example request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PATCH /v2/files/562e449060b274321afb6091 HTTP/1.1\\nHost: cgc-api.sbgenomics.com\\nX-SBG-Auth-Token: 565357a1e4b09c884b29334a\\n\",\n      \"language\": \"http\",\n      \"name\": null\n    },\n    {\n      \"code\": \"curl --data '{\\\"metadata\\\": {disease_type: \\\"Acute Myeloid Leukemia\\\"}} -s -H \\\"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\\\" -H \\\"content-type: application/json\\\" -X PATCH \\\"https://cgc-api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a\\\"\",\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\": \"Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`X-SBG-Auth-Token`\\n_required_\",\n    \"0-1\": \"Your CGC [authentication token](doc:get-your-authentication-token).\",\n    \"h-2\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n###Path parameters\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`file_id`\",\n    \"h-0\": \"Name\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"The ID of the file whose details you want to update.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n###Query parameters\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Data type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`fields`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Selector specifying a subset of fields to include in the response.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n##Request body\nYou should enter the body as key-value pairs, with the following format:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Datatype of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`name`\",\n    \"1-0\": \"`metadata`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The new name of the file.\",\n    \"1-1\": \"dictionary of key-value pairs. The keys and values are strings.\",\n    \"1-2\": \"The metadata fields and their values that you want to update.\",\n    \"2-0\": \"`tags`\",\n    \"2-1\": \"array\",\n    \"2-2\": \"The tags you want to update.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n###Example request body\nIn the example below, I have submitted a request to add the metadata field `disease_type` with value `\"Acute Myeloid Leukemia\"`. This request also adds the tags `test 1b` and `big sample`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"1_1000Genomes_phase1.snps.high_confidence.b37.vcf\\\",\\n  \\\"metadata\\\": {\\n    disease_type: \\\"Acute Myeloid Leukemia\\\"\\n    },\\n  \\\"tags\\\": [\\\"test 1b\\\", \\\"big sample\\\"]\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n##Response\n\n[See a list of CGC-specific response codes that may be contained in the body of the response.](doc:api-status-codes) \n\n###Example response body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"href\\\": \\\"https://cgc-api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80\\\",\\n  \\\"id\\\": \\\"566aad1de4b0c560b469ea80\\\",\\n  \\\"name\\\": \\\"1_1000G_phase1.snps.high_confidence.b37.vcf\\\",\\n  \\\"size\\\": 363,\\n  \\\"project\\\": \\\"RFranklin/my-project\\\",\\n  \\\"created_on\\\": \\\"2015-12-11T11:01:49Z\\\",\\n  \\\"modified_on\\\": \\\"2016-01-07T12:22:12Z\\\",\\n  \\\"origin\\\": {},\\n  \\\"metadata\\\": {\\n    \\\"file_type\\\": \\\"vcf\\\",\\n    \\\"disease_type\\\": \\\"Acute Myeloid Leukemia\\\",\\n    \\\"file_extension\\\": \\\"VCF\\\"\\n  },\\n  \\\"tags\\\":[\\n    \\\"test 1b\\\",\\n    \\\"big sample\\\"\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n Interpreting the response body:\n\n  * The object `origin` denotes the task that produced the file, if it was created by a task on the CGC.\n  * The dictionary object `metadata` lists the metadata fields and values for the file.\n  * The object `tags` lists the tags for the file. Learn more about [tagging your files](doc:tag-your-files) on the CGC.","excerpt":"files/{file_id}","slug":"update-file-details","type":"endpoint","title":"Update file details"}

patchUpdate file details

files/{file_id}

This call updates the name, the full set metadata, and tags for a specified file. Files are specified by their IDs, which you can obtain by making the API call to [list files in a project ](doc:list-files-in-a-project). A full list of metadata fields and their permissible values on the CGC is available on the page [TCGA Metadata](doc:metadata-for-private-data). [block:code] { "codes": [ { "code": "https://cgc-api.sbgenomics.com/v2/files/{file_id}", "language": "text", "name": "Path" } ] } [/block] [block:callout] { "type": "warning", "title": "File names and IDs", "body": "Note that the file name is not the same as its ID. The ID is a hexadecimal string, automatically assigned to a file in a project. The file's name is a human-readable string. For information, please see [the API overview](http://docs.cancergenomicscloud.org/docs/the-cgc-api#section-identifying-projects-users-apps-files-and-tasks)." } [/block] ##Custom metadata fields Apart from the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the CGC. Custom metadata can be added via the command line uploader or via the API, but *not* through the visual interface. [block:callout] { "type": "info", "body": "Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by [getting file details via the API](doc:get-file-details)." } [/block] When adding custom metadata fields, you need to pay attention to the following set of rules: * Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the CGC. * Maximum number of key-value pairs per file is 1000, including null-value keys. * Keys and values are UTF-8 encoded strings. * Maximum length of a key is 100 bytes (UTF-8 encoding). * Maximum length of a value is 300 bytes (UTF-8 encoding). ##TAGS You can use this API request to add or edit previously existing tags for your file. You can tag your files on the CGC with keywords to make it easier to identify and organize files you’ve imported from datasets or copied between projects. Learn more about [tagging your files](doc:tag-your-files) on the CGC. In addition to editing tags on your files, you can do the following via the API: * [Add tags to a file](doc:add-tags-to-a-file) * [View tags you've set on your files](doc:get-file-details) * [Filter files by tags](doc:list-files-in-a-project#tags) ##Request ###Example request [block:code] { "codes": [ { "code": "PATCH /v2/files/562e449060b274321afb6091 HTTP/1.1\nHost: cgc-api.sbgenomics.com\nX-SBG-Auth-Token: 565357a1e4b09c884b29334a\n", "language": "http", "name": null }, { "code": "curl --data '{\"metadata\": {disease_type: \"Acute Myeloid Leukemia\"}} -s -H \"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\" -H \"content-type: application/json\" -X PATCH \"https://cgc-api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a\"", "language": "curl", "name": "cURL" } ], "sidebar": true } [/block] ###Header Fields [block:parameters] { "data": { "h-0": "Name", "h-1": "Description", "0-0": "`X-SBG-Auth-Token`\n_required_", "0-1": "Your CGC [authentication token](doc:get-your-authentication-token).", "h-2": "" }, "cols": 2, "rows": 1 } [/block] ###Path parameters [block:parameters] { "data": { "0-0": "`file_id`", "h-0": "Name", "h-1": "Description", "0-1": "The ID of the file whose details you want to update." }, "cols": 2, "rows": 1 } [/block] ###Query parameters [block:parameters] { "data": { "h-0": "Name", "h-1": "Data type", "h-2": "Description", "0-0": "`fields`", "0-1": "string", "0-2": "Selector specifying a subset of fields to include in the response." }, "cols": 3, "rows": 1 } [/block] ##Request body You should enter the body as key-value pairs, with the following format: [block:parameters] { "data": { "h-0": "Key", "h-1": "Datatype of value", "h-2": "Description of value", "0-0": "`name`", "1-0": "`metadata`", "0-1": "string", "0-2": "The new name of the file.", "1-1": "dictionary of key-value pairs. The keys and values are strings.", "1-2": "The metadata fields and their values that you want to update.", "2-0": "`tags`", "2-1": "array", "2-2": "The tags you want to update." }, "cols": 3, "rows": 3 } [/block] ###Example request body In the example below, I have submitted a request to add the metadata field `disease_type` with value `"Acute Myeloid Leukemia"`. This request also adds the tags `test 1b` and `big sample`. [block:code] { "codes": [ { "code": "{\n \"name\": \"1_1000Genomes_phase1.snps.high_confidence.b37.vcf\",\n \"metadata\": {\n disease_type: \"Acute Myeloid Leukemia\"\n },\n \"tags\": [\"test 1b\", \"big sample\"]\n}", "language": "text" } ] } [/block] ##Response [See a list of CGC-specific response codes that may be contained in the body of the response.](doc:api-status-codes) ###Example response body [block:code] { "codes": [ { "code": "{\n \"href\": \"https://cgc-api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80\",\n \"id\": \"566aad1de4b0c560b469ea80\",\n \"name\": \"1_1000G_phase1.snps.high_confidence.b37.vcf\",\n \"size\": 363,\n \"project\": \"RFranklin/my-project\",\n \"created_on\": \"2015-12-11T11:01:49Z\",\n \"modified_on\": \"2016-01-07T12:22:12Z\",\n \"origin\": {},\n \"metadata\": {\n \"file_type\": \"vcf\",\n \"disease_type\": \"Acute Myeloid Leukemia\",\n \"file_extension\": \"VCF\"\n },\n \"tags\":[\n \"test 1b\",\n \"big sample\"\n ]\n}", "language": "json" } ], "sidebar": true } [/block] Interpreting the response body: * The object `origin` denotes the task that produced the file, if it was created by a task on the CGC. * The dictionary object `metadata` lists the metadata fields and values for the file. * The object `tags` lists the tags for the file. Learn more about [tagging your files](doc:tag-your-files) on the CGC.