{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","examples":{"codes":[]},"method":"get","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"List files (primary method)","type":"endpoint","slug":"list-files-primary-method","excerpt":"/files\n\nFor general information on the API, including formatting, parameters, and pagination, please see the [API Overview](the-api).","body":"This call returns a list of files and subdirectories in a specified project or directory within a project, with specified properties that you can access. The project or directory whose contents you want to list is specified as a query parameter in the call. Further properties to filter by can also be specified as query parameters. \n\nNote that this call lists both files and subdirectories in the specified project or directory within a project, but not the contents of the subdirectories. To list the contents of a subdirectory, make a new call and specify the subdirectory ID as the `parent` parameter.\n\nDon't forget that projects on the Platform are specified by their [short name](doc:the-api#section-project-short-names).\n\nFurther file properties to filter by can also be specified as query parameters.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"File IDs\",\n  \"body\": \"The file IDs returned by this call are useful for issuing further queries to get more information about a particular file.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://cavatica-api.sbgenomics.com/v2/files\",\n      \"language\": \"text\",\n      \"name\": \"API path\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Alias call\",\n  \"body\": \"There is a second method for listing files in a project: [`GET projects/{project_owner}/{project_name}/files`](doc:list-files-secondary-method). The call listed here is the primary and preferred method for performing this operation.\"\n}\n[/block]\n##Request\n\n###Example requests\nSince file filtering is a powerful feature, we have included some example usages.\n\nExample 1: List all files in the project 'my-project':\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project HTTP/1.1\\nHost: cavatica-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\\n\",\n      \"language\": \"http\",\n      \"name\": null\n    },\n    {\n      \"code\": \"curl -s -H \\\"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\\\" -H \\\"content-type: application/json\\\" -X GET \\\"https://cavatica-api.sbgenomics.com/v2/files?project=RFranklin/my-project\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"cURL\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\nExample 2: List all files in 'my-project' with a specific sample ID\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project&metadata.sample_id=SAMPLE1 HTTP/1.1\\nHost: cavatica-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\",\n      \"name\": \"HTTP\"\n    },\n    {\n      \"code\": \"curl -s -H \\\"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\\\" -H \\\"content-type: application/json\\\" -X GET \\\"https://cavatica-api.sbgenomics.com/v2/files?project=RFranklin/my-project&metadata.sample_id=SAMPLE1\\\"\",\n      \"language\": \"curl\",\n      \"name\": \"cURL\"\n    }\n  ]\n}\n[/block]\nExample 3: List all files in 'my-project' that were produced by a specific task with a specific library and sample ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e HTTP/1.1\\nHost: cavatica-api.sbgenomics.com\\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\",\n      \"language\": \"http\",\n      \"name\": \"HTTP\"\n    },\n    {\n      \"code\": \"curl -s -H \\\"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\\\" -H \\\"content-type: application/json\\\" -X GET \\\"https://cavatica-api.sbgenomics.com/v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\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 CAVATICA [authentication token](doc:get-your-authentication-token).\",\n    \"h-2\": \"\"\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\": \"`project`\\n_required if \\\"parent\\\" is not used_\",\n    \"6-0\": \"**prettyPrint**\",\n    \"5-0\": \"**fields\\n**\",\n    \"0-1\": \"string\",\n    \"5-1\": \"string\",\n    \"6-1\": \"boolean\",\n    \"6-2\": \"Returns a response with indentations and line breaks.\",\n    \"5-2\": \"Selector specifying a subset of fields to include in the response.\",\n    \"0-2\": \"Specified in the following format: `{project_owner}/{project}`. `project_owner` is the owner of the project you are listing files from, while `project` is the project's [short name](doc:the-api#section-project-short-names).\\n\\nShould not be used together with `parent`. If `parent` is used, the call will list the content of the specified folder, within the project to which the folder belongs. If `project` is used, the call will list the content at the root of the project's files.\",\n    \"3-0\": \"**`metadata.{field}`\\n**\",\n    \"3-1\": \"string\",\n    \"3-2\": \"List only files with that have the specified value in metadata field.\",\n    \"2-0\": \"**`name`\\n**\",\n    \"2-1\": \"string\",\n    \"2-2\": \"List file with this name.\",\n    \"4-0\": \"**`origin.task`\\n**\",\n    \"4-1\": \"string\",\n    \"4-2\": \"List only files produced by task specified by ID in this field\",\n    \"1-0\": \"`parent`\\n_required if \\\"project\\\" is not used_\",\n    \"1-1\": \"string\",\n    \"1-2\": \"ID of the folder whose content you want to list. \\n\\nShould not be used together with `project`. If `parent` is used, the call will list the content of the specified folder, within the project to which the folder belongs. If `project` is used, the call will list the content at the root of the project's files.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Limit your results\",\n  \"body\": \"Don't forget that you can [use filtering with the `limit` parameter](doc:the-api#section-response-pagination) to restrict the number of files returned by this call.\"\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###Example response body\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"href\\\": \\\"https://cavatica-api.sbgenomics.com/v2/files?offset=0&limit=25&project=RFranklin/my-project\\\",\\n  \\\"items\\\": [\\n    {\\n      \\\"href\\\": \\\"https://cavatica-api.sbgenomics.com/v2/files/568cf5dce4b0307bc0462060\\\",\\n      \\\"id\\\": \\\"568cf5dce4b0307bc0462060\\\",\\n      \\\"name\\\": \\\"1000G_phase1.indels.b37.vc\\\",\\n      \\\"project\\\": \\\"RFranklin/my-project\\\"\\n    },\\n    {\\n      \\\"href\\\": \\\"https://cavatica-api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80\\\",\\n      \\\"id\\\": \\\"566aad1de4b0c560b469ea80\\\",\\n      \\\"name\\\": \\\"1000G_omni2.5.b37.vcf\\\",\\n      \\\"project\\\": \\\"RFranklin/my-project\\\"\\n    },\\n    {\\n      \\\"href\\\": \\\"https://cavatica-api.sbgenomics.com/v2/files/568cf5f4e4b0307bc0462062\\\",\\n      \\\"id\\\": \\\"568cf5f4e4b0307bc0462062\\\",\\n      \\\"name\\\": \\\"1000G_phase1.snps.high_confidence.b37.vcf\\\",\\n      \\\"project\\\": \\\"RFranklin/my-project\\\"\\n    }\\n  ],\\n  \\\"links\\\": []\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Tips for filtering\",\n  \"body\": \"When filtering on any resource, including the same field several times with different filtering criteria results in an implicit `OR` operation for that field and the different criteria. \\n\\nWhen filtering by different specified fields, an implicit `AND` is performed between those criteria. Thus, the call in Example 3 above would return files matching the specified project AND sample ID AND library.\"\n}\n[/block]\n\n<hr>","updates":[],"order":35,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5774e6e18029ad0e00c390eb","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","5f893e508c9862002d0614a9","6024033e2b2f6f004dfe994c","60a7a12f9a06c70052b7c4db","60a7ab97266a4700161507c4","60b0c84babba720010a8b0b5"],"_id":"5773dcfc255e820e00e1cd50","__v":39,"createdAt":"2016-06-29T14:36:44.812Z","releaseDate":"2016-06-29T14:36:44.812Z","project":"5773dcfc255e820e00e1cd4d"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"CAVATICA API","slug":"api","order":22,"from_sync":false,"reference":false,"_id":"5773df36904b0c0e00ef05ff","createdAt":"2016-06-29T14:46:14.277Z","version":"5773dcfc255e820e00e1cd50","__v":1,"project":"5773dcfc255e820e00e1cd4d"},"parentDoc":null,"project":"5773dcfc255e820e00e1cd4d","user":"575e85ac41c8ba0e00259a44","createdAt":"2016-06-30T09:31:13.050Z","githubsync":"","__v":5}

getList files (primary method)

/files For general information on the API, including formatting, parameters, and pagination, please see the [API Overview](the-api).

This call returns a list of files and subdirectories in a specified project or directory within a project, with specified properties that you can access. The project or directory whose contents you want to list is specified as a query parameter in the call. Further properties to filter by can also be specified as query parameters. Note that this call lists both files and subdirectories in the specified project or directory within a project, but not the contents of the subdirectories. To list the contents of a subdirectory, make a new call and specify the subdirectory ID as the `parent` parameter. Don't forget that projects on the Platform are specified by their [short name](doc:the-api#section-project-short-names). Further file properties to filter by can also be specified as query parameters. [block:callout] { "type": "success", "title": "File IDs", "body": "The file IDs returned by this call are useful for issuing further queries to get more information about a particular file." } [/block] [block:code] { "codes": [ { "code": "https://cavatica-api.sbgenomics.com/v2/files", "language": "text", "name": "API path" } ] } [/block] [block:callout] { "type": "warning", "title": "Alias call", "body": "There is a second method for listing files in a project: [`GET projects/{project_owner}/{project_name}/files`](doc:list-files-secondary-method). The call listed here is the primary and preferred method for performing this operation." } [/block] ##Request ###Example requests Since file filtering is a powerful feature, we have included some example usages. Example 1: List all files in the project 'my-project': [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project HTTP/1.1\nHost: cavatica-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74\n", "language": "http", "name": null }, { "code": "curl -s -H \"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\" -H \"content-type: application/json\" -X GET \"https://cavatica-api.sbgenomics.com/v2/files?project=RFranklin/my-project\"", "language": "curl", "name": "cURL" } ], "sidebar": true } [/block] Example 2: List all files in 'my-project' with a specific sample ID [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project&metadata.sample_id=SAMPLE1 HTTP/1.1\nHost: cavatica-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http", "name": "HTTP" }, { "code": "curl -s -H \"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\" -H \"content-type: application/json\" -X GET \"https://cavatica-api.sbgenomics.com/v2/files?project=RFranklin/my-project&metadata.sample_id=SAMPLE1\"", "language": "curl", "name": "cURL" } ] } [/block] Example 3: List all files in 'my-project' that were produced by a specific task with a specific library and sample ID: [block:code] { "codes": [ { "code": "GET /v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e HTTP/1.1\nHost: cavatica-api.sbgenomics.com\nX-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74", "language": "http", "name": "HTTP" }, { "code": "curl -s -H \"X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7\" -H \"content-type: application/json\" -X GET \"https://cavatica-api.sbgenomics.com/v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e\"", "language": "curl" } ] } [/block] ###Header Fields [block:parameters] { "data": { "h-0": "Name", "h-1": "Description", "0-0": "`X-SBG-Auth-Token`\n_required_", "0-1": "Your CAVATICA [authentication token](doc:get-your-authentication-token).", "h-2": "" }, "cols": 2, "rows": 1 } [/block] ##Query Parameters [block:parameters] { "data": { "h-0": "Name", "h-1": "Data type", "h-2": "Description", "0-0": "`project`\n_required if \"parent\" is not used_", "6-0": "**prettyPrint**", "5-0": "**fields\n**", "0-1": "string", "5-1": "string", "6-1": "boolean", "6-2": "Returns a response with indentations and line breaks.", "5-2": "Selector specifying a subset of fields to include in the response.", "0-2": "Specified in the following format: `{project_owner}/{project}`. `project_owner` is the owner of the project you are listing files from, while `project` is the project's [short name](doc:the-api#section-project-short-names).\n\nShould not be used together with `parent`. If `parent` is used, the call will list the content of the specified folder, within the project to which the folder belongs. If `project` is used, the call will list the content at the root of the project's files.", "3-0": "**`metadata.{field}`\n**", "3-1": "string", "3-2": "List only files with that have the specified value in metadata field.", "2-0": "**`name`\n**", "2-1": "string", "2-2": "List file with this name.", "4-0": "**`origin.task`\n**", "4-1": "string", "4-2": "List only files produced by task specified by ID in this field", "1-0": "`parent`\n_required if \"project\" is not used_", "1-1": "string", "1-2": "ID of the folder whose content you want to list. \n\nShould not be used together with `project`. If `parent` is used, the call will list the content of the specified folder, within the project to which the folder belongs. If `project` is used, the call will list the content at the root of the project's files." }, "cols": 3, "rows": 5 } [/block] [block:callout] { "type": "success", "title": "Limit your results", "body": "Don't forget that you can [use filtering with the `limit` parameter](doc:the-api#section-response-pagination) to restrict the number of files returned by this call." } [/block] ##Response [See a list of CAVATICA-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://cavatica-api.sbgenomics.com/v2/files?offset=0&limit=25&project=RFranklin/my-project\",\n \"items\": [\n {\n \"href\": \"https://cavatica-api.sbgenomics.com/v2/files/568cf5dce4b0307bc0462060\",\n \"id\": \"568cf5dce4b0307bc0462060\",\n \"name\": \"1000G_phase1.indels.b37.vc\",\n \"project\": \"RFranklin/my-project\"\n },\n {\n \"href\": \"https://cavatica-api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80\",\n \"id\": \"566aad1de4b0c560b469ea80\",\n \"name\": \"1000G_omni2.5.b37.vcf\",\n \"project\": \"RFranklin/my-project\"\n },\n {\n \"href\": \"https://cavatica-api.sbgenomics.com/v2/files/568cf5f4e4b0307bc0462062\",\n \"id\": \"568cf5f4e4b0307bc0462062\",\n \"name\": \"1000G_phase1.snps.high_confidence.b37.vcf\",\n \"project\": \"RFranklin/my-project\"\n }\n ],\n \"links\": []\n}", "language": "json" } ], "sidebar": true } [/block] [block:callout] { "type": "success", "title": "Tips for filtering", "body": "When filtering on any resource, including the same field several times with different filtering criteria results in an implicit `OR` operation for that field and the different criteria. \n\nWhen filtering by different specified fields, an implicit `AND` is performed between those criteria. Thus, the call in Example 3 above would return files matching the specified project AND sample ID AND library." } [/block] <hr>