{"_id":"5695063bcaa32519009c40b3","user":"554340dfb7f4540d00fcef1d","__v":4,"parentDoc":null,"version":{"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","__v":37,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-12T13:57:15.172Z","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":37,"body":"This call modifies the metadata values for the specified file. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Metadata\",\n  \"body\": \"Learn more about [metadata fields and their values](metadata-for-private-data) for your uploaded, private files on the CGC.\"\n}\n[/block]\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[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cgc-api.sbgenomics.com/v2/files/{file_id}/metadata\",\n      \"language\": \"text\",\n      \"name\": \"Path\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"PUT and PATCH\",\n  \"body\": \"The CGC API has two method to modify file metadata. This method uses the HTTP verb `PATCH`, and the other uses the HTTP verb `PUT`. \\n\\nThe difference between the two concerns the way that they update the information stored about the user. `PATCH` allows you to update just one metadata field. On the other hand, a `PUT` request will fully overwrite the values for all metadata fields. This means that when issuing a `PUT` request you must enter values for every key required to specify the metadata, even if the values for some keys are unchanged. If you don't specify a value for a given metadata field when making the `PUT` request, then any existing value for that field will be reset.\"\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.\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  * Null values and keys are ignored and not counted towards the 1000 key-value pair limit. \n\n##Request\n\n###Example request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"PATCH /v2/files/562e449060b274321afb6091/metadata 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 '{\\\"foo\\\": \\\"bar\\\"}'  -s -H \\\"X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96\\\" -H \\\"content-type: application/json\\\" -X PATCH \\\"https://cgc-api.sbgenomics.com/v2/files/5657152ee4b0298dd2cdf724/metadata\\\"\",\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 metadata 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\nEnter a dictionary of key-value pairs to the request body. \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\": \"Freeform -- enter any key.\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The value for the corresponding key\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n###Example request body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"foo\\\": \\\"bar\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"You cannot edit the metadata for TCGA files. You can only edit metadata for files that you create or upload.\",\n  \"title\": \"TCGA metadata\"\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\nThe response contains the full metadata specification for the file, including the values that you just added with the request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"library_id\\\": \\\"12345\\\",\\n  \\\"platform\\\": \\\"my_platform\\\",\\n  \\\"foo\\\": \\\"bar\\\",\\n  \\\"my_key_1\\\": \\\"my_value_1\\\",\\n  \\\"my_key_2\\\": \\\"my_value_2\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"/files/{file_id}/metadata","slug":"modify-a-files-metadata","type":"endpoint","title":"Modify a file's metadata"}

patchModify a file's metadata

/files/{file_id}/metadata

This call modifies the metadata values for the specified file. [block:callout] { "type": "warning", "title": "Metadata", "body": "Learn more about [metadata fields and their values](metadata-for-private-data) for your uploaded, private files on the CGC." } [/block] 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). [block:code] { "codes": [ { "code": "https://cgc-api.sbgenomics.com/v2/files/{file_id}/metadata", "language": "text", "name": "Path" } ] } [/block] [block:callout] { "type": "success", "title": "PUT and PATCH", "body": "The CGC API has two method to modify file metadata. This method uses the HTTP verb `PATCH`, and the other uses the HTTP verb `PUT`. \n\nThe difference between the two concerns the way that they update the information stored about the user. `PATCH` allows you to update just one metadata field. On the other hand, a `PUT` request will fully overwrite the values for all metadata fields. This means that when issuing a `PUT` request you must enter values for every key required to specify the metadata, even if the values for some keys are unchanged. If you don't specify a value for a given metadata field when making the `PUT` request, then any existing value for that field will be reset." } [/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. * 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). * Null values and keys are ignored and not counted towards the 1000 key-value pair limit. ##Request ###Example request [block:code] { "codes": [ { "code": "PATCH /v2/files/562e449060b274321afb6091/metadata HTTP/1.1\nHost: cgc-api.sbgenomics.com\nX-SBG-Auth-Token: 565357a1e4b09c884b29334a\n", "language": "http", "name": null }, { "code": "curl --data '{\"foo\": \"bar\"}' -s -H \"X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96\" -H \"content-type: application/json\" -X PATCH \"https://cgc-api.sbgenomics.com/v2/files/5657152ee4b0298dd2cdf724/metadata\"", "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 metadata 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 Enter a dictionary of key-value pairs to the request body. [block:parameters] { "data": { "h-0": "Key", "h-1": "Datatype of value", "h-2": "Description of value", "0-0": "Freeform -- enter any key.", "0-1": "string", "0-2": "The value for the corresponding key" }, "cols": 3, "rows": 1 } [/block] ###Example request body [block:code] { "codes": [ { "code": "{\n \"foo\": \"bar\"\n}", "language": "json" } ] } [/block] [block:callout] { "type": "danger", "body": "You cannot edit the metadata for TCGA files. You can only edit metadata for files that you create or upload.", "title": "TCGA metadata" } [/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 The response contains the full metadata specification for the file, including the values that you just added with the request. [block:code] { "codes": [ { "code": "{\n \"library_id\": \"12345\",\n \"platform\": \"my_platform\",\n \"foo\": \"bar\",\n \"my_key_1\": \"my_value_1\",\n \"my_key_2\": \"my_value_2\"\n}", "language": "json" } ], "sidebar": true } [/block]