List files (primary method)

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 names.

👍

File IDs

The file IDs returned by this call are useful for issuing further queries to get more information about a particular file.

https://cgc-api.sbgenomics.com/v2/files

🚧

Alias call

There is a second method for listing files in a project: GET projects/{project_owner}/{project_name}/files. The call listed here is the primary and preferred method for performing this operation.

Request

Header Fields

Query Parameters

You can use query parameters, listed in the table below, to return specific results. See the tip box below for details on OR and AND operations while filtering. Below the table, you'll see examples of API requests using various parameters.

👍

Tips for filtering

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.

When 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.

👍

Limit your results

Don't forget that you can use filtering with the limit parameter to restrict the number of files returned by this call.

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':

GET /v2/files?project=rfranklin/my-project HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

curl -s -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/files?project=RFranklin/my-project"

Example 2: List all files in 'my-project' with a specific sample ID

GET /v2/files?project=rfranklin/my-project&metadata.sample_id=SAMPLE1 HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

curl -s -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/files?project=RFranklin/my-project&metadata.sample_id=SAMPLE1"

Example 3: List all files in 'my-project' that were produced by a specific task with a specific library and sample ID:

GET /v2/files?project=rfranklin/my-project&metadata.sample_id=ERR3153351&metadata.library_id=HiSeqX_Re HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

curl -s -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/files?project=my-project&metadata.sample_id=ERR3153351&origin.task=1262d368-1fde-4f06-a755-917a53a03e7e"

Example 4: List all files in 'my-project' matching the exact names included in the query parameters:

GET /v2/files?project=rfranklin/my-project&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

curl -s -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/files?project=my-project&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf"

Example 5: List all files in 'my-project' matching the exact tags included in the parameters:

GET /v2/files?project=rfranklin/my-project&tag=test1b&tag=my_first_project&fields=_all HTTP/1.1
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

curl -s -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/files?project=franklin/my-project&tag=test1b&tag=my_first_project"

Example 6: List all files in 'my-project' from the TCGA GRCh38 dataset.

GET /v2/files?project=rfranklin/my-project&origin.dataset=tcga_grch38&fields=name,origin&limit=100
Host: cgc-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74

Response

See a list of CGC-specific response codes that may be contained in the body of the response.

Example response body

{
  "href": "https://cgc-api.sbgenomics.com/v2/files?offset=0&limit=25&project=RFranklin/my-project",
  "items": [
    {
      "href": "https://cgc-api.sbgenomics.com/v2/files/561cf5dce4b0307bc0462060",
      "id": "561cf5dce4b0307bc0462060",
      "name": "1000G_phase1.indels.b37.vc",
      "project": "RFranklin/my-project"
    },
    {
      "href": "https://cgc-api.sbgenomics.com/v2/files/566acd1de4b0c560b469ea80",
      "id": "566acd1de4b0c560b469ea80",
      "name": "1000G_omni2.5.b37.vcf",
      "project": "RFranklin/my-project"
    },
    {
      "href": "https://cgc-api.sbgenomics.com/v2/files/568cf5f4e4b1207bc0462062",
      "id": "568cf5f4e4b1207bc0462062",
      "name": "1000G_phase1.snps.high_confidence.b37.vcf",
      "project": "RFranklin/my-project"
    }
  ],
  "links": []
}