{"__v":4,"_id":"578569b2ce05c019001afc28","category":{"__v":92,"_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","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-17T17:34:34.937Z","from_sync":false,"order":26,"slug":"api","title":"API Reference"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","user":"5613e4f8fdd08f2b00437620","version":{"__v":37,"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-12T22:05:38.604Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":85,"body":"This call lets you queue a job to import a file from a volume into a project on the Platform. Essentially, you are importing a file from your cloud storage provider (Amazon Web Services or Google Cloud Storage) via the volume onto the Platform.\n\nIf successful, an alias will be created on the Platform. Aliases appear as files on the Platform and can be copied, executed, and modified as such. They refer back to the respective file on the given volume.\n\nLearn more about using the Volumes API for [Amazon S3](aws-cloud-storage-tutorial) and for [Google Cloud Storage](google-cloud-storage-tutorial).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cgc-api.sbgenomics.com/v2/storage/imports\",\n      \"language\": \"text\",\n      \"name\": \"Path\"\n    }\n  ]\n}\n[/block]\n##Request\n\n###Example request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v2/storage/imports HTTP/1.1\\nHost: cgc-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\\nContent-Type: application/json\",\n      \"language\": \"http\",\n      \"name\": null\n    },\n    {\n      \"code\": \"curl --data ':::at:::import.json' -X POST -H \\\"X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0\\\" -H \\\"Content-Type: application/json\\\" 'https://cgc-api.sbgenomics.com/v2/storage/imports'\",\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 CGC [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###Query parameters\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\": \"`overwrite`\",\n    \"0-1\": \"Boolean\",\n    \"0-2\": \"If this is set to `True` and a named file exists in the project where the alias is about to be created, the existing file will be deleted.\\n\\n_default:_ `false`\"\n  },\n  \"cols\": 3,\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    \"0-0\": \"`source`\\n_required_\",\n    \"1-0\": \"`volume_id`\\n_required_\",\n    \"h-0\": \"Key\",\n    \"h-1\": \"Data type of value\",\n    \"0-1\": \"Object\",\n    \"1-1\": \"String\",\n    \"0-2\": \"This object should describe the source from which the file should be imported.\",\n    \"h-2\": \"Description of value\",\n    \"1-2\": \"Volume ID from which to import the file.\",\n    \"2-0\": \"`location`\\n_required_\",\n    \"2-1\": \"String\",\n    \"2-2\": \"Volume-specific location pointing to the file to import. This location should be recognizable to the underlying cloud service as a valid key or path to the file.\\n\\nPlease note that if this volume was configured with a `prefix` parameter when it was created, the `prefix` will be prepended to `location` before attempting to locate the file on the volume.\",\n    \"3-0\": \"`destination`\\n_required_\",\n    \"5-0\": \"`name`\",\n    \"6-0\": \"`overwrite`\",\n    \"3-1\": \"Object\",\n    \"4-0\": \"`project`\\n_required_\",\n    \"4-1\": \"String\",\n    \"5-1\": \"String\",\n    \"6-1\": \"Boolean\",\n    \"3-2\": \"This object should describe the Platform destination for the imported file.\",\n    \"4-2\": \"The project in which to create the alias.\",\n    \"5-2\": \"The name of the alias to create. This name should be unique to the project. If the name is already in use in the project, you should use the `overwrite` query parameter in this call to force any file with that name to be deleted before the alias is created.\\n\\nIf `name` is omitted, the alias name will default to the last segment of the complete location (including the `prefix`) on the volume. Segments are considered to be separated with forward slashes ('/').\",\n    \"6-2\": \"Whether to overwrite the file if the file with the same name already exists in the destination.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\n###Example request body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{  \\n   \\\"source\\\":{  \\n      \\\"volume\\\":\\\"rfranklin/input\\\",\\n      \\\"location\\\":\\\"example_human_Illumina.pe_1.fastq\\\"\\n   },\\n   \\\"destination\\\":{  \\n      \\\"project\\\":\\\"rfranklin/my_project\\\",\\n      \\\"name\\\":\\\"my_uploaded_example_human_Illumina.pe_1.fastq\\\"\\n   },\\n   \\\"overwrite\\\": true\\n}\",\n      \"language\": \"text\",\n      \"name\": \"Example request body for S3 service\"\n    },\n    {\n      \"code\": \"{ \\n   \\\"source\\\":{ \\n      \\\"volume\\\":\\\"rfranklin/tutorial_volume\\\",\\n      \\\"location\\\":\\\"example_human_Illumina.pe_1.fastq\\\"\\n   },\\n   \\\"destination\\\":{ \\n      \\\"project\\\":\\\"rfranklin/my-project\\\",\\n      \\\"name\\\":\\\"my_imported_example_human_Illumina.pe_1.fastq\\\"\\n   },\\n   \\\"overwrite\\\": true\\n}\",\n      \"language\": \"text\",\n      \"name\": \"Example request body for Google Cloud Storage Service\"\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###Response body\n\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\": \"`id`\",\n    \"0-1\": \"String\",\n    \"1-1\": \"String\",\n    \"1-0\": \"`state`\",\n    \"2-0\": \"`source`\",\n    \"2-1\": \"Object\",\n    \"3-0\": \"`destination`\",\n    \"3-1\": \"Object\",\n    \"4-0\": \"`result`\",\n    \"4-1\": \"Object\",\n    \"5-0\": \"`error`\",\n    \"5-1\": \"Object\",\n    \"0-2\": \"ID of this import job\",\n    \"1-2\": \"The state of this import job. Possible values are:\\n  * `PENDING`: the import is queued;\\n  * `RUNNING`: the import is running;\\n  * `COMPLETED`: the import has completed successfully;\\n  * `FAILED`: the import has failed.\",\n    \"2-2\": \"Import source, as passed when this job was started by the call to [start an import job](doc:start-an-import-job-v2) .\",\n    \"3-2\": \"Import destination, as passed when this job was started by the call to [start an import job](doc:start-an-import-job-v2)\",\n    \"4-2\": \"File object that was [imported](get-file-details).\",\n    \"5-2\": \"In case of error in the import job, standard API error is returned here.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n\n###Example response body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"href\\\": \\\"https://cgc-api.sbgenomics.com/v2/storage/imports/SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN\\\",\\n  \\\"id\\\": \\\"SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN\\\",\\n  \\\"state\\\": \\\"PENDING\\\",\\n  \\\"overwrite\\\": true,\\n  \\\"source\\\": {\\n    \\\"volume\\\": \\\"rfranklin/input\\\",\\n    \\\"location\\\": \\\"example_human_Illumina.pe_1.fastq\\\"\\n  },\\n  \\\"destination\\\": {\\n    \\\"project\\\": \\\"rfranklin/my_project\\\",\\n    \\\"name\\\": \\\"my_uploaded_example_human_Illumina.pe_1.fastq\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"start-an-import-job-v2","type":"endpoint","title":"Start an import job"}

postStart an import job


This call lets you queue a job to import a file from a volume into a project on the Platform. Essentially, you are importing a file from your cloud storage provider (Amazon Web Services or Google Cloud Storage) via the volume onto the Platform. If successful, an alias will be created on the Platform. Aliases appear as files on the Platform and can be copied, executed, and modified as such. They refer back to the respective file on the given volume. Learn more about using the Volumes API for [Amazon S3](aws-cloud-storage-tutorial) and for [Google Cloud Storage](google-cloud-storage-tutorial). [block:code] { "codes": [ { "code": "https://cgc-api.sbgenomics.com/v2/storage/imports", "language": "text", "name": "Path" } ] } [/block] ##Request ###Example request [block:code] { "codes": [ { "code": "POST /v2/storage/imports HTTP/1.1\nHost: cgc-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\nContent-Type: application/json", "language": "http", "name": null }, { "code": "curl --data '@import.json' -X POST -H \"X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0\" -H \"Content-Type: application/json\" 'https://cgc-api.sbgenomics.com/v2/storage/imports'", "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 CGC [authentication token](doc:get-your-authentication-token).", "h-2": "", "1-0": "`Content-type`\n_required_", "1-1": "`application/json`" }, "cols": 2, "rows": 2 } [/block] ###Query parameters [block:parameters] { "data": { "h-0": "Key", "h-1": "Data type of value", "h-2": "Description of value", "0-0": "`overwrite`", "0-1": "Boolean", "0-2": "If this is set to `True` and a named file exists in the project where the alias is about to be created, the existing file will be deleted.\n\n_default:_ `false`" }, "cols": 3, "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": { "0-0": "`source`\n_required_", "1-0": "`volume_id`\n_required_", "h-0": "Key", "h-1": "Data type of value", "0-1": "Object", "1-1": "String", "0-2": "This object should describe the source from which the file should be imported.", "h-2": "Description of value", "1-2": "Volume ID from which to import the file.", "2-0": "`location`\n_required_", "2-1": "String", "2-2": "Volume-specific location pointing to the file to import. This location should be recognizable to the underlying cloud service as a valid key or path to the file.\n\nPlease note that if this volume was configured with a `prefix` parameter when it was created, the `prefix` will be prepended to `location` before attempting to locate the file on the volume.", "3-0": "`destination`\n_required_", "5-0": "`name`", "6-0": "`overwrite`", "3-1": "Object", "4-0": "`project`\n_required_", "4-1": "String", "5-1": "String", "6-1": "Boolean", "3-2": "This object should describe the Platform destination for the imported file.", "4-2": "The project in which to create the alias.", "5-2": "The name of the alias to create. This name should be unique to the project. If the name is already in use in the project, you should use the `overwrite` query parameter in this call to force any file with that name to be deleted before the alias is created.\n\nIf `name` is omitted, the alias name will default to the last segment of the complete location (including the `prefix`) on the volume. Segments are considered to be separated with forward slashes ('/').", "6-2": "Whether to overwrite the file if the file with the same name already exists in the destination." }, "cols": 3, "rows": 7 } [/block] ###Example request body [block:code] { "codes": [ { "code": "{ \n \"source\":{ \n \"volume\":\"rfranklin/input\",\n \"location\":\"example_human_Illumina.pe_1.fastq\"\n },\n \"destination\":{ \n \"project\":\"rfranklin/my_project\",\n \"name\":\"my_uploaded_example_human_Illumina.pe_1.fastq\"\n },\n \"overwrite\": true\n}", "language": "text", "name": "Example request body for S3 service" }, { "code": "{ \n \"source\":{ \n \"volume\":\"rfranklin/tutorial_volume\",\n \"location\":\"example_human_Illumina.pe_1.fastq\"\n },\n \"destination\":{ \n \"project\":\"rfranklin/my-project\",\n \"name\":\"my_imported_example_human_Illumina.pe_1.fastq\"\n },\n \"overwrite\": true\n}", "language": "text", "name": "Example request body for Google Cloud Storage Service" } ] } [/block] ##Response [See a list of CGC-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": "`id`", "0-1": "String", "1-1": "String", "1-0": "`state`", "2-0": "`source`", "2-1": "Object", "3-0": "`destination`", "3-1": "Object", "4-0": "`result`", "4-1": "Object", "5-0": "`error`", "5-1": "Object", "0-2": "ID of this import job", "1-2": "The state of this import job. Possible values are:\n * `PENDING`: the import is queued;\n * `RUNNING`: the import is running;\n * `COMPLETED`: the import has completed successfully;\n * `FAILED`: the import has failed.", "2-2": "Import source, as passed when this job was started by the call to [start an import job](doc:start-an-import-job-v2) .", "3-2": "Import destination, as passed when this job was started by the call to [start an import job](doc:start-an-import-job-v2)", "4-2": "File object that was [imported](get-file-details).", "5-2": "In case of error in the import job, standard API error is returned here." }, "cols": 3, "rows": 6 } [/block] ###Example response body [block:code] { "codes": [ { "code": "{\n \"href\": \"https://cgc-api.sbgenomics.com/v2/storage/imports/SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN\",\n \"id\": \"SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN\",\n \"state\": \"PENDING\",\n \"overwrite\": true,\n \"source\": {\n \"volume\": \"rfranklin/input\",\n \"location\": \"example_human_Illumina.pe_1.fastq\"\n },\n \"destination\": {\n \"project\": \"rfranklin/my_project\",\n \"name\": \"my_uploaded_example_human_Illumina.pe_1.fastq\"\n }\n}", "language": "json" } ], "sidebar": true } [/block]