Seven Bridges knowledge centerDocumentation
API Reference
Start typing to search…

Get details of a volume

This call returns details of the specified volume. The volume is referred to by its ID, which you can obtain by making the call to list all the volumes you've registered.

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

Request

Example request

GET /storage/volumes/rfranklin/output HTTP/1.1
Host: cavatica-api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75
curl  -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://cavatica-api.sbgenomics.com/storage/volumes/rfranklin/output"

Header Fields

Key

Description of value

X-SBG-Auth-Token required

Your CAVATICA authentication token.

Content-type
required

application/json

Path parameters

Key

Data type of value

Description of value

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/output.

Response

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

Key

Data type of value

Description of value

active

Boolean

If a volume is deactivated, this field will be set to false

id

String

ID of this volume, containing owner/name

name

String

Name of the volume.

description

String

The description of this volume.

service

Object

This object more closely describes the mapping of the volume to the cloud service where the data is stored.

See the service object section below for an explanation of its structure.

created_on

String

The date and time this volume was created.

modified_on

String

The date and time this volume was last modified.

The service object

Key

Data type of value

Description of value

type

string

The type of cloud service supported. Currently the only valid values are "s3" for Amazon Web Services and "gcs" for Google Cloud Storage.

access_mode

string

Signifies whether this volume should be used for read-write ("RW") or read-only ("RO") operations.

The access mode is consulted independently of the credentials granted to Seven Bridges when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it.

  • default:_ "RW"

prefix

String

A service-specific prefix to prepend to all objects created in this volume. If the service supports folders, and this prefix includes them, the API will attempt to create any missing folders when it outputs a file.

  • default:_ ""

bucket

applies to type:s3 and gcs
required

String

The name of the AWS S3 or GCS bucket you wish to register as a volume.

root_url

default:https://s3.amazonaws.com fors3 type and https://www.googleapis.com/ for gcs

String

Cloud provider API endpoint to use when accessing this bucket.

For a list of AWS-supported endpoints, see AWS Regions and Endpoints.

credentials

Object

Contains credentials for the underlying cloud provider.

For Google Cloud Storage, these credentials are:

access_key_id

applies to type:s3
required

String

AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.

secret_access_key

applies to type:s3
required

String

AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.

client_email

applies to type:gcs
required

String

Google Cloud Storage user email.

private_key

applies to type:gcs
required

String

Google Cloud Storage private key.

properties

Object

Contains properties of specific service.

sse_algorithm

applies to type:s3

String

Use default AES256 server-side encryption or AWS KMS encryption when writing to this bucket.

Can be:

  • AES256 (default)
  • aws:kms

default: AES256

sse_aws_kms_key_id

applies to type:s3

String

If AWS KMS encryption is used, this should be set to the required KMS key. If not set and aws:kms is set as sse_algorithm, default KMS key is used.

Example response body

{
  "active": True,
  "description": "task outputs bucket",
  "id": "rfranklin/output",
  "service": {
    "type": "s3",
    "bucket": "sbg-test-output",
    "hostname": "s3.amazonaws.com",
    "access_key": "AKIAJRC7TPMRMEXAMPLE",
    "access_mode": "RW",
    "prefix": "",
    "sse_enabled": True,
    "created_time": "2016-06-29T11:13:10+02:00",
    "updated_time": "2016-06-29T12:15:10+02:00"
  }
}