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.

Further file properties to filter by can also be specified as query parameters.

👍

File IDs

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

Request

https://api.sbgenomics.com/v2/files
https://eu-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.

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: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=RFranklin/my-project"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send GET request to SB API
files = api.files.query(project='rfranklin/my-project')

for file in files:
    print(file.id, file.name)
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: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=RFranklin/my-project&metadata.sample_id=SAMPLE1"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send GET request to SB API
files = api.files.query(
    project='rfranklin/my-project',
    metadata={
        'sample': 'SAMPLE1'
    }
)

for file in files:
    print(file.id, file.name)
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=ERR315335&metadata.library_id=HiSeqX_R HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send GET request to SB API
files = api.files.query(
    project='rfranklin/my-project',
    metadata={
        'sample_id': 'ERR315335',
        'library_id': 'HiSeqX_R'
    }
)

for file in files:
    print(file.id, file.name)
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: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://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"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send GET request to SB API
files = api.files.query(
    project='rfranklin/my-project',
    names=[
        'dbsnp_137.b37.vcf',
        '1000G_phase1.indels.b37.vcf',
        'Mills_and_1000G_gold_standard.indels.b37.sites.vcf'
    ]
)

for file in files:
    print(file.id, file.name)
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: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=franklin/my-project&tag=test1b&tag=my_first_project"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

# send GET request to SB API
files = api.files.query(
    project='rfranklin/my-project',
    tags=[
        'test1b',
        'my_first_project'
    ]
)

for file in files:
    print(file.id, file.name)

👍

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.

Header Fields

Name

Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

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.

Name

Data type

Description

project
required if "parent" is not used

string

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.

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

parent
required if "project" is not used

string

ID of the folder whose content you want to list.

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

name

string

List file with this name. Note that the name must be an exact complete string for the results to match.

Multiple names can be separated by an OR operation, as shown in example 4 below. The OR operation is implied when the same parameter is queried multiple times in the same API request

metadata.{field}

string

List only files with that have the specified value in metadata field.

Multiple instances of the same metadata field are implicitly separated by an OR operation. Conversely, different metadata fields are implicitly separated by an AND operation, as shown in example 3 below.

origin.task

string

List only files produced by task specified by ID in this field

tag

string

List files containing this tag. Note that the tag must be an exact complete string for the results to match. Multiple tags can be separated by an OR operation, as shown in example 5 below. The OR operation is implied when the same parameter is queried multiple times in the same API request.

Keep in mind that tags are different from metadata. Learn more about tagging your files on the Platform.

📘

List files in the Public Reference Files repository

The Seven Bridges Public Reference Files repository is specified in the same way as a project on the Platform by an id of admin/sbg-public-data. You can pass this query parameter using project=admin/sbg-public-data.

👍

Limit your results

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

👍

Set the query parameter fields to _all to display tags within the response body, since tags is not automatically displayed in the response body.

Response

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

Example response body

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