List the contents of a volume

This call lists the contents of a specific volume. The volume is specified as volume_id and consists of the owner and name of a volume (for example rfranklin/my-first-volume).

Request

https://api.sbgenomics.com/v2/storage/volumes/{volume_id}/list
https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}/list

Example request

GET /v2/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder HTTP/1.1
Host: api.sbgenomics.com  
x-sbg-auth-token: 6a3a308c112a400eb8cf753de185b5ba
curl  -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder&limit=3"
from sevenbridges import Api

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

volume = api.volumes.get(id='rfranklin/sb_qa_test')

# send GET request to SB API
volume_items = volume.list(prefix='my-folder')

for volume_object in volume_items:
    print(volume_object.location)
print(volume_items.prefixes)

Header Fields

Key

Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-type
required

application/json

Path parameters

Key

Data type

Description

volume_id
required

String

The volume that you want to query, which consists of username of the volume owner and volume name, for example rfranklin/my-first-volume.

Query parameters

Key

Data type

Description

prefix

String

The name of the folder in case you want to list the contents of a folder.

fields

String

Selector specifying a subset of fields to include in the response.

Here's the list of available values for the fields parameter and their descriptions:

Value

Description

href

Shows only the href of each returned item.

location

Shows only the location (path) within the volume for each returned item.

volume

Shows only the volume on which the returned item is located, in the <user-name>/<volume-name> format.

type

Shows only the type of the returned item. Type is s3 for items stored on an AWS S3 bucket and gcp for items stored on a Google Cloud Storage bucket.

metadata

Shows only the storage-provider-generated metadata for each of the returned items.

_all

Shows all standard fields for each returned item, with the addition of corresponding metadata.

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/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder&limit=3",
    "prefix": "my-folder",
    "limit": 3,
    "truncated": false,
    "items": [],
    "prefixes": [
        {
            "href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder/",
            "prefix": "my-folder/",
            "volume": "rfranklin/sb_qa_test"
        },
        {
            "href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder/preserve-structure",
            "prefix": "my-folder/preserve-structure",
            "volume": "rfranklin/sb_qa_test"
        },
        {
            "href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/sb_qa_test/list?prefix=my-folder/security",
            "prefix": "my-folder/security",
            "volume": "rfranklin/sb_qa_test"
        }
    ],
    "links": []
}

Interpreting the response body

  • href: Use the information contained in the href to make another request to obtain more details about a specific object within a volume.