List all API paths
This call returns all API paths, so that you don't need to rely on documentation in the terminal.
https://api.sbgenomics.com/v2/https://eu-api.sbgenomics.com/v2/https://gcp-api.sbgenomics.com/v2/Listing API calls
Your authentication token is not necessary to make this call (only).
GET /v2/ 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/{
"rate_limit_url": "https://api.sbgenomics.com/v2/rate_limit",
"user_url": "https://api.sbgenomics.com/v2/user",
"users_url": "https://api.sbgenomics.com/v2/users",
"billing_url": "https://api.sbgenomics.com/v2/billing",
"projects_url": "https://api.sbgenomics.com/v2/projects",
"files_url": "https://api.sbgenomics.com/v2/files",
"tasks_url": "https://api.sbgenomics.com/v2/tasks",
"apps_url": "https://api.sbgenomics.com/v2/apps",
"action_url": "https://api.sbgenomics.com/v2/action",
"upload_url":"https://api.sbgenomics.com/v2/upload",
"storage_url": "https://api.sbgenomics.com/v2/storage"
}
Get my information
/user
For general information on the API, including formatting, parameters, and pagination, please see the API Overview.
This call returns information about your account on the Seven Bridges Platform.
https://api.sbgenomics.com/v2/userhttps://eu-api.sbgenomics.com/v2/userhttps://gcp-api.sbgenomics.com/v2/userX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
In the response body, you can see the information about your account. If you have associated a CGC account with your Seven Bridges Platform account, you can see the type of TCGA data you can access under tags, such as tcga-oa for TCGA Open Data and tcga-ca for TCGA Controlled Data.
GET /v2/user HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://cgc-api.sbgenomics.com/v2/user"{
"href": "https://api.sbgenomics.com/v2/users/RFranklin",
"username": "RFranklin",
"email": "rosalind.franklin@sbgenomics.com",
"first_name": "Rosalind",
"last_name": "Franklin",
"tags": [
{
"tag": "tcga-oa",
"expires_at": 3053937952000
},
{
"tag": "tcga-ca",
"expires_at": 1506729600000
}
],
"affiliation": "Seven Bridges",
"phone": "",
"address": "",
"city": "London",
"state": "",
"country": "United Kingdom",
"zip_code": ""
}List user resources
This call returns information about the specified user. Note that currently you can view only your own user information, and so this call is equivalent to the call to Get my information.
https://api.sbgenomics.com/v2/users/{username}https://eu-api.sbgenomics.com/v2/users/{username}https://gcp-api.sbgenomics.com/v2/users/{username}This call will only return a successful response if {username} is replaced with your own username.
Case sensitivity
Don't forget to capitalize your username in the same way as you set it when you registered on the Seven Bridges Platform.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
username
Username of the user you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/users/RFranklin HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/users/RFranklin"{
"href": "https://api.sbgenomics.com/v2/users/RFranklin",
"username": "RFranklin",
"email": "rosalind.franklin@sbgenomics.com",
"first_name": "Rosalind",
"last_name": "Franklin",
"affiliation": "Seven Bridges",
"phone": "",
"address": "",
"city": "London",
"state": "",
"country": "United Kingdom",
"zip_code": ""
}List billing API paths
This call returns a list of paths used to access billing information via the API.
https://api.sbgenomics.com/v2/billinghttps://eu-api.sbgenomics.com/v2/billinghttps://gcp-api.sbgenomics.com/v2/billingX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/billing HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: a42c0608d5934bdeb91d0f9e0cdddb48curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/billing"{
"billing_groups_url": "https://api.sbgenomics.com/v2/billing/groups/",
"invoices_url": "https://api.sbgenomics.com/v2/billing/invoices/"
}List billing groups
This call lists all your billing groups, including groups that are pending or have been disabled.
https://api.sbgenomics.com/v2/billing/groups https://eu-api.sbgenomics.com/v2/billing/groups https://gcp-api.sbgenomics.com/v2/billing/groupsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
limit
integer
The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 25. This is a pagination-specific attribute.
offset
integer
The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute.
GET /v2/billing/groups 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" GET "https://api.sbgenomics.com/v2/billing/groups"{
"href": "https://api.sbgenomics.com/v2/billing/groups?offset=0&limit=25",
"items": [
{
"id": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
"href": "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
"name": "RFranklin Billing Group"
}
],
"links": []
}Get a single billing group
This call retrieves a single billing group, specified by {billing_group}. To find the billing_group, use the call list billing groups to list all your billing groups. The information returned includes the billing group owner, the total balance, and the status of the billing group (pending or confirmed).
https://api.sbgenomics.com/v2/billing/groups/{billing_group}https://eu-api.sbgenomics.com/v2/billing/groups/{billing_group}https://gcp-api.sbgenomics.com/v2/billing/groups/{billing_group}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
billing_group
required
ID of the billing group you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/billing/groups/8ccc6222-ef6f-4526-99d7-9f56b716d43a HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 97a1ad73db6349a487ef77b7655edae2curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7"{
{
"id": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
"href": "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
"owner": "RFranklin",
"name": "RFranklin Billing Group",
"type": "free",
"pending": false,
"disabled": false,
"balance": {
"currency": "USD",
"amount": 0
}
}Get breakdown for a billing group
This call returns a breakdown of spending per-project for the billing group specified by billing_group. For each project that the billing group is associated with, information is shown on each task run, including its initiating user (the runner_username), start and end times, and cost.
To find the billing_group, use the call list billing groups to list all your billing groups.
https://api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdownhttps://eu-api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdownhttps://gcp-api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdownBilling periods
The spending will be shown for the current billing period.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
billing_group
The ID of the billing group.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/billing/groups/8ccc6222-ef6f-4526-99d7-9f56b716d43a/breakdown HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 8ccc6222-ef6f-4526-99d7-9f56b716d43a" -H "content-type: application/json" - X GET "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7/breakdown"{
"href": "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7/breakdown",
"project_breakdown": [
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my_project",
"analysis_spending": {
"currency": "USD",
"amount": "0.23"
},
"task_breakdown": [
{
"href": "https://api.sbgenomics.com/v2/tasks/39bc3e8c-6cf6-4f8f-b550-21e9633c1f4b",
"runner_username": "Kate",
"time_started": "2015-12-11T11:03:08Z",
"time_finished": "2015-12-11T11:08:49Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
}
]
},
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/test",
"analysis_spending": {
"currency": "USD",
"amount": "0.92"
},
"task_breakdown": [
{
"href": "https://api.sbgenomics.com/v2/tasks/f586a3fb-c9e4-4415-b22b-648a66969a37",
"runner_username": "RFranklin",
"time_started": "2015-11-26T14:15:18Z",
"time_finished": "2015-11-26T14:20:30Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
{
"href": "https://api.sbgenomics.com/v2/tasks/98c8dc8b-e1e0-4410-8448-d857a9c2cf16",
"runner_username": "RFranklin",
"time_started": "2015-11-25T16:26:23Z",
"time_finished": "2015-11-25T16:30:46Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
{
"href": "https://api.sbgenomics.com/v2/tasks/6961273b-0f6a-45a3-95c1-d5d895fc6ea0",
"runner_username": "RFranklin",
"time_started": "2015-11-26T12:11:58Z",
"time_finished": "2015-11-26T12:16:33Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
]
},
{
"href": "https://api.sbgenomics.com/v2/projects/Kate/my-project",
"analysis_spending": {
"currency": "USD",
"amount": "0.46"
},
"task_breakdown": [
{
"href": "https://api.sbgenomics.com/v2/tasks/a466e8b9-6f48-4cf9-b903-50fc4701bb2e",
"runner_username": "RFranklin",
"time_started": "2015-11-25T14:02:13Z",
"time_finished": "2015-11-25T14:07:06Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
{
"href": "https://api.sbgenomics.com/v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6",
"runner_username": "RFranklin",
"time_started": "2015-11-24T19:19:52Z",
"time_finished": "2015-11-24T19:24:45Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
]
},
{
"analysis_spending": {
"currency": "USD",
"amount": "0.69"
},
"task_breakdown": [
{
"href": "https://api.sbgenomics.com/v2/tasks/468dca93-7e90-4625-bcef-a080151d0687",
"runner_username": "RFranklin",
"time_started": "2015-11-25T14:30:45Z",
"time_finished": "2015-11-25T14:35:31Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
{
"href": "https://api.sbgenomics.com/v2/tasks/dc0e6559-a706-4e30-a040-72e5bfb3c077",
"runner_username": "RFranklin",
"time_started": "2015-11-25T14:37:59Z",
"time_finished": "2015-11-25T14:47:10Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
},
{
"href": "https://api.sbgenomics.com/v2/tasks/a8364b07-f1f9-4548-864a-045a3a2c41a1",
"runner_username": "RFranklin",
"time_started": "2015-11-25T14:43:02Z",
"time_finished": "2015-11-25T14:48:18Z",
"task_cost": {
"currency": "USD",
"amount": "0.23"
}
}
]
}
],
"total_spending": {
"currency": "USD",
"amount": "2.00"
}
}List invoices
This call returns a list of invoices, with information about each, including whether or not the invoice is pending and the billing period it covers.
The call returns information about all your available invoices, unless you use the query parameter bg_id to specify the ID of a particular billing group, in which case it will return the invoice incurred by that billing group only.
https://api.sbgenomics.com/v2/billing/invoiceshttps://eu-api.sbgenomics.com/v2/billing/invoiceshttps://gcp-api.sbgenomics.com/v2/billing/invoicesX-SBG-Auth-Token
required
Your CGC authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
GET v2/billing/invoices HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET https://api.sbgenomics.com/v2/billing/invoices -H "Accept: application/json"{
"href": "https://api.sbgenomics.com/v2/billing/invoices/",
"items": [
{
"href": "https://api.sbgenomics.com/v2/billing/invoices/7779079019",
"invoice_id": "7779079019",
"pending": false,
"invoice_period": {
"from": "2015-03-26T13:55:26Z",
"to": "2015-03-27T00:00:00Z"
}
},
{
"href": "https://api.sbgenomics.com/v2/billing/invoices/7443918961",
"invoice_id": "7443918961",
"pending": false,
"invoice_period": {
"from": "2015-03-27T00:00:00Z",
"to": "2015-03-30T00:00:00Z"
}
}
]
}Get a specific invoice
This call retrieves information about a selected invoice, including the costs for analysis and storage, and the invoice period.
Use the call to list invoices to retrieve the invoice_ids for a specified billing group.
https://api.sbgenomics.com/v2/billing/invoices/{invoice_id}https://eu-api.sbgenomics.com/v2/billing/invoices/{invoice_id}https://gcp-api.sbgenomics.com/v2/billing/invoices/{invoice_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
invoice_id
The ID of the invoice you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/billing/invoices/7779079019 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/billing/invoices/7779079019"{
"href": "https://api.sbgenomics.com/v2/billing/invoices/7779079019",
"invoice_id": "7779079019",
"pending": false,
"approval_date": "2015-03-26T00:00:00Z",
"invoice_period": {
"from": "2015-03-26T13:55:26Z",
"to": "2015-03-27T00:00:00Z"
},
"analysis_costs": {
"currency": "USD",
"amount": "1.64"
},
"storage_costs": {
"currency": "USD",
"amount": "0.00"
},
"total": {
"currency": "USD",
"amount": "1.64"
}
}List all your projects
This call returns a list of all projects you are a member of. Each project's project_id and URL on the Seven Bridges Platform will be returned.
https://api.sbgenomics.com/v2/projectshttps://eu-api.sbgenomics.com/v2/projectshttps://gcp-api.sbgenomics.com/v2/projectsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
offset
integer
The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute.
limit
integer
The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 25. This is a pagination-specific attribute.
GET /v2/projects 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/projects"{
"href": "https://api.sbgenomics.com/v2/projects?offset=0&limit=25",
"items": [
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/test",
"id": "RFranklin/test",
"name": "test"
},
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/sandbox",
"id": "RFranklin/sandbox",
"name": "sandbox"
},
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project",
"id": "RFranklin/my-project",
"name": "my project"
}
],
"links": []
}List projects owned by a particular user
List the projects owned by and accessible to a particular user. Each project's ID and URL will be returned. Please keep in mind that you will only be able to list projects you are a member of.
https://api.sbgenomics.com/v2/projects/{owner}https://eu-api.sbgenomics.com/v2/projects/{owner}https://gcp-api.sbgenomics.com/v2/projects/{owner}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
owner
The owner whose projects you want to query.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/projects/RFranklin 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/projects/RFranklin"{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin",
"items": [
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/Quickstart",
"id": "RFranklin/Quickstart",
"name": "Quickstart",
},
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project",
"id": "RFranklin/my-project",
"name": "My project",
"description": "testing testing.\n* one\n* two\n* three"
}
]
}Create a new project
This call creates a new project.
https://api.sbgenomics.com/v2/projectshttps://eu-api.sbgenomics.com/v2/projectshttps://gcp-api.sbgenomics.com/v2/projectsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.
name
required
string
The name of the project you are creating.
billing_group
required
string
The ID of the billing group for the project.
List all billing groups to find your billing group ID
description
string
A description of the project.
type
string
If you are running the Platform on AWS, and you want to create an 'old-style' non-developer project, then set this to v1.
settings
dictionary
This dictionary contains two fields, locked and use_interruptible_instances - see below for further information.
Boolean
This field can be true or false.
Set this field to true to lock down a project. Locking down a project prevents any Seven Bridges team member from viewing any information about the task.
use_interruptible_instances
Boolean
This field can be true or false.
Set this field to true to allow the use of spot instances.
Project short names
Recall from the API Overview that projects are assigned short names. When you specify the given name of your project, in the request body, the short name will be automatically generated, using the process described in the API Overview.
POST /v2/projects HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
content-type: application/json
curl --data '{"name": "My New Project", "description": "A project for testing my apps", "billing_group": "1f0c2751-694c-4e98-b863-06b68f5a61ca"}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/projects"{
"name": "My New Project",
"description": "A project for testing my apps",
"billing_group": "1f0c2751-694c-4e98-b863-06b68f5a61ca",
"settings":{
"locked": true,
"use_interruptible_instances": false
}
}{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-new-project",
"id": "RFranklin/my-new-project",
"name": "My New Project",
"type": "v2",
"tags": [],
"description": "A project for testing my apps",
"settings": {
"locked": true,
"use_interruptible_instances": false
},
"billing_group": "1f0c2751-694c-4e98-b863-06b68f5a61ca"
}Interpreting the response body
- The response will include an empty list
[]for the objecttags. This is a legacy feature of the API, and should be ignored. - The field
lockedis set totrue, which means you've created a locked project. Locking down a project prevents any Seven Bridges team member from viewing any information about the task.
Edit a project
This call edits a project on the Seven Bridges Platform. You can use it to change the name, description, or billing group of the project.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}PATCH
If your client does not support PATCH requests, you can use POST to send this request, along with the query parameter _method=PATCH:
i.e. https://api.sbgenomics.com/v2/projects/{project_owner}/{project}?_method=PATCH
Referring to your project
Note that project_owner is always case-sensitive, and that project is not the project's name but its ID, or short name. For full details of identifying objects using the API, please see the API overview.
Request body
The request body should contain a set of key-value pairs. The keys, and the values they take, are described in the following table. Enter a key-value pair if you want to re-set the existing value for the project.
Note that although you may change the name of the project, this does not affect its short name, which is immutable.
name
string
The name of the project you are editing.
billing_group
string
The ID of the billing group for the project.
List all billing groups to find your billing group ID.
description
string
A description of the project.
settings
dictionary
This dictionary contains one field, locked.
Boolean
This field can be true or false.
Set this field to true to lock down a project. Locking down a project prevents any Seven Bridges team member from viewing any information about the task.
use_interruptible_instances
Boolean
This field can be true or false. Set this field to true to allow the use of spot instances.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project you are editing.
project_owner
The owner of the project you are editing.
fields
string
Selector specifying a subset of fields to include in the response.
PATCH /v2/projects/RFranklin/sandbox HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data '{"name": "New name for my project", "description": "Updated with the results of the latest experiments"}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/projects/RFranklin/sandbox"{
"name": "New name for my project",
"description": "Updated with the results of the latest experiments",
"settings": {
"locked":true
"use_interruptible_instances":false
}
}{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/sandbox",
"id": "RFranklin/sandbox",
"name": "New name for my project",
"type": "v2",
"description": "Updated with the results of the latest experiments",
"settings": {
"locked":true
"use_interruptible_instances":false
},
"billing_group": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7"
}Get details of a project
This call returns the details of a specified project.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}Referring to your project
Note that project_owner is always case-sensitive, and that project is not the project's name but its short name. For full details of identifying objects using the API, please see the API overview.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
X-sbg-advance-access
optional
advance
Use this field to return the ID of the project root folder.
This field is a part of the advance access functionality for managing folders on the Seven Bridges Platform.
project
The short name of the project you are querying.
project_owner
The owner of the project you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
Set this to _all to view all fields, including project settings.
This example response body displays the JSON returned when the fields parameter in the request is set to _all.
GET /v2/projects/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/projects/RFranklinate/my-project"{
"href": "http://api.sbgenomics.com/v2/projects/rfranklin/rfranklin-s-demo-project",
"id": "rfranklin/rfranklin-s-demo-project",
"name": "rfranklin's Demo Project",
"type": "v2",
"description": "This project contains data, completed analyses, and results.\n\Contains WGS, WES, and two different RNA-Seq read alignments - STAR and TopHat, fusion transcript detection analysis using ChimeraScan, FASTQ quality control and more.\n\n Open it up and take a look.",
"tags": [],
"settings": {
"locked": false
"use_interruptible_instances": false
},
"permissions": {
"write": true,
"read": true,
"copy": true,
"execute": true,
"admin": true
},
"billing_group": "c567f1b8-8846-4e8d-a3d8-1d3037132310"
}Interpreting the response body
- The object
typein the response should be ignored: all projects have typev2. - The dictionary
settingscontains one Boolean field,locked. This field shows whether or not your project is locked. You can lock down a project to prevent any Seven Bridges team member from viewing information about your project. Learn more about creating a locked project.
Delete a project
This call deletes a project from the Seven Bridges Platform. It can only be successfully made if you have admin status for the project.
Warning
Deleting a project completely erases the project and any of its related data from the Seven Bridges Platform.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}Referring to your project
Note that project_owner is always case-sensitive, and project is not the project's name but its short name. For full details of identifying objects using the API, please see the API Overview
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project you are deleting.
project_owner
The owner of the project you are deleting.
DELETE /v2/projects/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 DELETE -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" 'http://api.sbgenomics.com//v2/projects/RFranklin/my-project'List members of a project
This call returns a list of the members of the specified project. For each member, the response lists:
- The member's username on the Seven Bridges Platform
- The member's permissions in the project specified
Project member permissions
For information about the permissions project members may have, see the documentation on setting permissions.
https://api.sbgenomics.com/v2/projects/{owner}/{project}/membershttps://eu-api.sbgenomics.com/v2/projects/{owner}/{id}/membershttps://gcp-api.sbgenomics.com/v2/projects/{owner}/{project}/membersX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The ID of the project you are querying.
owner
The owner of the project you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/projects/rfranklin/my-project/members 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/projects/RFranklin/my-project/members"{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members?offset=0&limit=25",
"items": [
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members/RFranklin",
"username": "RFranklin",
"email: "rfranklin@address.com",
"permissions": {
"write": true,
"read": true,
"copy": true,
"execute": true,
"admin": true
}
},
{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members/Crick",
"username": "Crick",
"email: "crick@address.com",
"permissions": {
"write": false,
"read": true,
"copy": false,
"execute": false,
"admin": false
}
}
],
"links": []
}Add a member to a project
This call adds a new user to a specified project. It can only be successfully made by a user who has admin permissions in the project.
Users may have the following permissions on the Platform:
- Read
- Write
- Copy
- Execute
- Admin
For more information, see the documentation on setting project member permissions. Note that some user permissions imply others: for example, if you give a user admin permission, then they automatically receive read, write, copy and execute permissions.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/membershttps://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/membershttps://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/membersMember permissions
Requests to add a project member must include the key permissions. However, if you do not include a value for some permission, it will be set to false by default. The exception to this rule is the read permission, which is the default permission on a project. It enables a user to read project data, including file names, but access file contents.
For more information, see the documentation on setting permissions.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The ID of the project you are adding someone to.
project_owner
The owner of the project you are adding someone to.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
Inside the body of the call you should enter a set of key-value pairs. The following table describes the values you should enter.
username
string
The Seven Bridges Platform username of the person you want to add to the project.
You should use either 'username' (recommended) or 'email'.
email
string
The email address of the person you want to add to the project.
This has to be the email address that the person used when registering for an account on the Seven Bridges Platform.
You should use either 'username' (recommended) or 'email'.
permissions
array of key-value pairs. The keys are strings, and the values are Booleans.
The possible keys are:
"write"
"read"
"copy"
"execute"
"admin"
Each key may have the values true or false.
Read permissions
All members of a project have read permissions by default. Even if you try setting read permissions to false, they will still default to true.
POST /v2/projects/rjfranklin/my-project/members HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data '{"username": "Jane-Doe", "permissions": { "read": true, "write": true, "execute": false}}' -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members"{
"username" : "Jane_Doe",
"permissions": {
"read" : true,
"write": true,
"execute": false
}
}{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members/Jane_Doe",
"username": "Jane_Doe",
"email: "jane_doe@address.com",
"permissions": {
"write": true,
"read": true,
"copy": false,
"execute": true,
"admin": false
}
}Remove a project member
This call removes a project member from a project. It can only be successfully run by a user who has admin privileges in the project.
For more information on permissions on the Seven Bridges Platform, see the documentation on setting permissions.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project_owner
required
The Seven Bridges Platform username of the user who owns the project.
project
required
The ID of the project to access.
username
required
The Seven Bridges Platform username of the user you are removing.
DELETE /v2/projects/rfranklin/my-project/members/jane_doe 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 DELETE "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members/Jane_Doe" Get a project member's permissions
This returns the permissions of a specified user within a specified project.
Users may have the following permissions on the Seven Bridges Platform:
- Read
- Write
- Copy
- Execute
- Admin
Permissions are granted at the project-level. You may, for instance, have admin permission in one project, execute permission in another, and read-only permission in a third.
For more information on permissions on the Seven Bridges Platform, see the documentation on setting permissions.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project_owner
required
The Seven Bridges Platform username of the user who owns the project.
project
required
The short name of the project to access.
username
required
The Seven Bridges Platform username of the user whose permissions you are enquiring about.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/projects/rfranklin/my-project/members/jane_doe 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/projects/RFranklin/my-project/members/Jane_Doe"{
"href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project1/members/Jane_Doe",
"username": "Jane_Doe",
"email: "janedoe@address.com",
"permissions": {
"write": true,
"read": true,
"copy": false,
"execute": true,
"admin": false
}
}Modify a project member's permissions
This call edits a user's permissions in a specified project. It can only be successfully made by a user who has admin permissions in the project.
PUT and PATCH
The Seven Bridges Platform API has two method to modify project members' permissions. This method uses the HTTP verb PATCH, and the other uses the HTTP verb PUT.
The difference between the two concerns the way that they update the information stored about the user. PATCH allows you to update just one part of the user's information --- for instance, just the value stored for the user's copy permission. On the other hand, a PUT request will fully overwrite the user's permission information. This means that when issuing a PUT request you must enter values for every key required to describe the user, even if the values for some keys are unchanged.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissionshttps://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissionshttps://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissionsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project containing the project member.
project_owner
The owner of the project containing the project member.
member
The project member whose permissions you are editing.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
Inside the body of the call you should enter a set of key-value pairs. The following table describes the values you should enter.
read
Boolean: true or false
User can view file names, metadata, and workflows. They cannot view file contents.
All members of a project have read permissions by default. Even if you try setting read permissions to false, they will still default to true.
write
Boolean: true or false
User can add, modify, and remove files and workflows in a project.
Set value to true to assign the user write permission. Set to false to remove write permission.
copy
Boolean: true or false
User can view file content, copy, and download files from a project.
Set value to true to assign the user copy permission. Set to false to remove copy permission.
execute
Boolean: true or false
User can execute workflows and abort tasks in a project.
Set value to true to assign the user execute permission. Set to false to remove execute permission.
admin
Boolean: true or false
User can modify another user's permissions on a project, add or remove people from the project and manage funding sources. They also have all of the above permissions.
Set value to true to assign the user admin permission. Set to false to remove admin permission.
PATCH /v2/projects/RFranklin/test/members/crick/permissions HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data '{"write": true}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/projects/RFranklin/test/members/crick/permissions" {
"write": true,
}{
"write": true,
"read": true,
"copy": false,
"execute": false,
"admin": false
}Overwrite a project member's permissions
This call changes a project member's permissions for a specified project.
Users may have the following permissions on the Seven Bridges Platform:
- Read
- Write
- Copy
- Execute
- Admin
For more information, see the documentation on setting project member permissions. Note that some user permissions imply others: for example, if you give a user admin permission, then they automatically receive read, write, copy and execute permissions.
PUT and PATCH
The Seven Bridges Platform API has two method to modify project members' permissions. This method uses the HTTP verb PUT, and the other uses the HTTP verb PATCH.
The difference between the two concerns the way that they update the information stored about the user. PATCH allows you to update just one part of the user's information --- for instance, just the value stored for the user's copy permission. On the other hand, a PUT request will fully overwrite the user's permission information. This means that when issuing a PUT request you must enter values for every key required to describe the user, even if the values for some keys are unchanged.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissionshttps://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissionshttps://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissionsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project containing the project member.
project_owner
The owner of the project containing the project member.
username
The Seven Bridges Platform username of the user whose permissions you are overwriting.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.
"read"
Boolean: true or false
User can view file names, metadata, and workflows. They cannot view file contents.
All members of a project have read permissions by default. Even if you try setting read permissions to false, they will still default to true.
"write"
Boolean: true or false
User can add, modify, and remove files and workflows in a project.
Set value to true to assign the user write permission. Set to false to remove write permission.
"copy"
Boolean: true or false
User can view file content, copy, and download files from a project.
Set value to true to assign the user copy permission. Set to false to remove copy permission.
"execute"
Boolean: true or false
User can execute workflows and abort tasks in a project.
Set value to true to assign the user execute permission. Set to false to remove execute permission.
"admin"
Boolean: true or false
User can modify another user's permissions on a project, add or remove people from the project and manage funding sources. They also have all of the above permissions.
Set value to true to assign the user admin permission. Set to false to remove admin permission.
PUT /v2/projects/rfranklin/my-project/members/crick/permissions HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -X PUT --data-binary "@permissions-for-crick.json" -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" 'http://api.sbgenomics.com/v2/projects/rfranklin/my-project/members/crick/permissions'{
"read": true,
"write": true,
"copy": true,
"execute": true,
"admin": false
}{
"write": true,
"read": true,
"copy": true,
"execute": true,
"admin": false
}List files (primary method)
This call returns a list of all files in a specified project with specified properties that you can access. For each file, the call returns:
- Its ID
- Its filename
The project to find files from is specified as a query parameter in the call. 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.
https://api.sbgenomics.com/v2/fileshttps://eu-api.sbgenomics.com/v2/fileshttps://gcp-api.sbgenomics.com/v2/filesAlias 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.
Since file filtering is a powerful feature, we have included some example usages.
Example 1: List all files in the project 'my-project':
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.
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.
{project_owner}/{project}
required
string
project_owner is the owner of the project you are listing files from.project is the project's short name.
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
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.
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"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: 3259c50e1ac5426ea8f1273259740f74curl -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"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?rfranklin/project=my-project&metadata.sample_id=ERR315335&metadata.library_id=HiSeqX_R HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -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"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: 3259c50e1ac5426ea8f1273259740f74curl -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"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: 3259c50e1ac5426ea8f1273259740f74curl -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"{
"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": []
}List files (secondary method)
This call lists the files in the specified project. It is an alias for the call list files and redirects to that path.
Alias call
Note that since this is an alias for another call, the call cannot be made directly from all applications. In particular, to send the call using cURL, use the cURL option -L to redirect the path of this call to https://api.sbgenomics.com/v2/files?{project_owner}/{project}.
Alternatively, to list all files, you can simply use the call list files.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/fileshttps://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/fileshttps://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/filesReferring to your project
Note that project_owner is always case-sensitive, and that project is not the project's name but its ID, or short name. For more information about identifying objects in the API, see the section on identifying objects.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project you are querying.
project_owner
The owner of the project you are querying.
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.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/projects/rfranklin/my-project/files HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -L "https://api.sbgenomics.com/v2/files?RFranklin/my-project" -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/files"{
"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": "my_reference.vcf",
"project": "RFranklin/my-project"
},
{
"href": "https://api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80",
"id": "566aad1de4b0c560b469ea80",
"name": "_1_unsorted.bam",
"project": "RFranklin/my-project"
},
{
"href": "https://api.sbgenomics.com/v2/files/568cf5f4e4b0307bc0462062",
"id": "568cf5f4e4b0307bc0462062",
"name": "unsorted.bam",
"project": "RFranklin/my-project"
}
],
"links": []
}Delete a file
This call removes a file from the Seven Bridges Platform. Files are specified by their IDs, which you can obtain by making the API call to list files.
https://api.sbgenomics.com/v2/files/{file_id}https://eu-api.sbgenomics.com/v2/files/{file_id}https://gcp-api.sbgenomics.com/v2/files/{file_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID of the file you want to delete.
DELETE /v2/files/565357a1e4b09c884b29334a 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 DELETE "https://api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a"Get file details
This call returns details about a specified file. The call returns the file's name, its tags, and all of its metadata.
Files are specified by their IDs, which you can obtain by making the API call to list files in a project .
Learn more about metadata fields and their values on the Seven Bridges Platform. You can also learn more about working with tags on the Platform.
https://api.sbgenomics.com/v2/files/{file_id}https://eu-api.sbgenomics.com/v2/files/{file_id}https://gcp-api.sbgenomics.com/v2/files/{file_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
X-SBG-Advance-Access
optional
advance
Use this field if you want to return the parent folder ID.
This field is a part of the advance access functionality for managing folders on the Seven Bridges Platform.
file_id
The ID of the file whose details you want to GET.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/files/562e449060b274321afb6091 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a"{
"href": "https://api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80",
"id": "566aad1de4b0c560b469ea80",
"name": "_1_1000G_phase1.snps.high_confidence.b37.vcf",
"size": 363,
"project": "RFranklin/my-project",
"created_on": "2015-12-11T11:01:49Z",
"modified_on": "2015-12-11T11:01:49Z",
"origin": {},
"metadata": {
"file_type": "vcf",
"file_extension": "VCF"
},
"tags": [
"my first files",
"test 1b",
"big sample"
]
}Interpreting the response body:
- The object
origindenotes the task that produced the file, if it was created by a task on the Seven Bridges Platform. - The dictionary object
metadatalists the metadata fields and values for the file. - The object
tagslists the tags for the file. Learn more about tagging your files on the Platform.
Update file details
This call updates the name, the full set metadata, and tags for a specified file.
Files are specified by their IDs, which you can obtain by making the API call to list files in a project .
Metadata
Learn more about metadata fields and their permissible values on the Seven Bridges Platform.
https://api.sbgenomics.com/v2/files/{file_id}https://eu-api.sbgenomics.com/v2/files/{file_id}https://gcp-api.sbgenomics.com/v2/files/{file_id}File names and IDs
Note that the file name is not the same as its ID. The ID is a hexadecimal string, automatically assigned to a file in a project. The file's name is a human-readable string. For information about identifying objects in the API, see the section on identifying objects.
Custom metadata fields
As well as the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the Platform. Custom metadata can be added via the command line uploader or via the API, but not through the visual interface.
Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by getting file details via the API.
The following rules apply to custom metadata fields:
- Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the Platform.
- Maximum number of key-value pairs per file is 1000, including null-value keys.
- Keys and values are UTF-8 encoded strings.
- Maximum length of a key is 100 bytes (UTF-8 encoding).
- Maximum length of a value is 300 bytes (UTF-8 encoding).
Tags
You can use this API request to add or edit previously existing tags for your file. You can tag your files on the Platform with keywords to make it easier to identify and organize files you’ve imported from public datasets or copied between projects. Learn more about tagging your files on the Platform.
In addition to editing tags on your files, you can do the following via the API:
- Add tags to a file
- View tags you've set on your files
- Filter files by tags, using list files and specifying the required
tag.
Header Fields
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID of the file whose details you want to update.
fields
string
Selector specifying a subset of fields to include in the response.
name
string
The new name of the file.
metadata
dictionary of key-value pairs. The keys and values are strings.
The metadata fields and their values that you want to update.
tags
array
The tags you want to update.
Notice that the metadata contains only the fields specified in the request body.
PATCH /v2/files/562e449060b274321afb6091 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl --data '{"metadata": {disease_type: "Acute Myeloid Leukemia"}} -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a"In the example below, I have submitted a request to change the file name to "1_1000Genomes_phase1.snps.high_confidence.b37.vcf" and to have the metadata contain only the field disease_type with value "Acute Myeloid Leukemia". This request also adds the tags test 1b and sample.
{
"name": "1_1000Genomes_phase1.snps.high_confidence.b37.vcf",
"metadata": {
"disease_type": "Acute Myeloid Leukemia"
},
"tags": ["test 1b", "sample"]
}{
"href": "https://api.sbgenomics.com/v2/files/566aad1de4b0c560b469ea80",
"id": "566aad1de4b0c560b469ea80",
"name": "1_1000Genomes_phase1.snps.high_confidence.b37.vcf",
"size": 363,
"project": "RFranklin/my-project",
"created_on": "2015-12-11T11:01:49Z",
"modified_on": "2016-01-07T12:22:12Z",
"origin": {},
"metadata": {
"disease_type": "Acute Myeloid Leukemia",
},
"tags":[
"test 1b",
"sample"
]
}Interpreting the response body:
- The object
origindenotes the task that produced the file, if it was created by a task on the Seven Bridges Platform. - The dictionary object
metadatalists the metadata fields and values for the file. - The object
tagslists the tags for the file. Learn more about tagging your files on the Platform.
Copy a file
This call copies the specified file to a new project. Files retain their metadata when copied, but may be assigned new names in their target project.
To make this call, you should have copy permission within the project you are copying from.
https://api.sbgenomics.com/v2/files/{file_id}/actions/copyhttps://eu-api.sbgenomics.com/v2/files/{file_id}/actions/copyhttps://gcp-api.sbgenomics.com/v2/files/{file_id}/actions/copyfile_ids
Recall from the API Overview that the file_id is a hexadecimal string.
You can get the file_id for an file by making the call to list files within a specified project (primary method)
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID for the file you are querying. It can be obtained by making the call to list your files (primary method).
fields
string
Selector specifying a subset of fields to include in the response.
"project"
required
string
The name of the project you want to copy the file to
"name"
string
The new name the file will have in the target project.
If its name will not change, omit this key.
{
"project": "RFranklin/my-project",
"name": "new-file"
}The response gives the full specification of the file, and its metadata.
POST v2/files/568e69ade4b0307bc0464164/actions/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data '{"project": "RFranklin/my-project", "name": "new-file"}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/files/568e69ade4b0307bc0464164/actions/copy" {
"href": "https://api.sbgenomics.com/v2/files/569637cce4b0b65fcb306ae5",
"id": "569637cce4b0b65fcb306ae5",
"name": "new-file",
"size": 68425,
"project": "RFranklin/my-project",
"created_on": "2016-01-13T11:41:00Z",
"modified_on": "2016-01-13T11:41:00Z",
"origin": {},
"metadata": {
"sample_id": "E16201_pool35_L1756",
"library_id": "hg19",
"platform_unit_id": "C18_99",
"platform": "IonTorrent",
"quality_scale": "sanger"
}
}Get downloadable URL for a file
This call returns a URL that you can use to download the specified file.
https://api.sbgenomics.com/v2/files/{file_id}/download_infohttps://eu-api.sbgenomics.com/v2/files/{file_id}/download_infohttps://gcp-api.sbgenomics.com/v2/files/{file_id}/download_infoX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fie_id
The ID of the file whose download URL you want to get.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/files/56534e57e4b093830b6e967b/download_info 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/56534e57e4b093830b6e967b/download_info"{
"url": "https://main.s3.amazonaws.com/050177a9-ecff-430c-96f8-54561a0c301e%2Btest-text.txt?response-content-disposition=attachment%3Bfilename%3Dtest-text.txt&response-content-type=application%2Foctet-stream&AWSAccessKeyId=AKIAIZUEXM5REGIZ56VA&Expires=1452345802&Signature=4v3DEiBMyiyLw%2F3VGyJUlwSyw28%3D"
}Get a file's metadata
This call returns the metadata values for the specified file.
Metadata on the Platform
Learn more about metadata fields and their values on the Seven Bridges Platform.
Files are specified by their IDs, which you can obtain by making the API call to list files in a project .
https://api.sbgenomics.com/v2/files/{file_id}/metadatahttps://eu-
api.sbgenomics.com/v2/files/{file_id}/metadatahttps://gcp-api.sbgenomics.com/v2/files/{file_id}/metadataX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID of the file whose details you want to GET.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/files/562e449060b274321afb6091/metadata HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files/565357a1e4b09c884b29334a/metadata"{
"sample_id": "E16201_pool35_L1756",
"library_id": "hg19",
"platform_unit_id": "C18_99",
"platform": "IonTorrent",
"quality_scale": "sanger"
}Modify a file's metadata
This call modifies the metadata values for the specified file.
Metadata on the Platform
Learn more about metadata fields and their values on the Seven Bridges Platform.
Files are specified by their IDs, which you can obtain by making the API call to list files in a project .
https://api.sbgenomics.com/v2/files/{file_id}/metadatahttps://eu-api.sbgenomics.com/v2/files/{file_id}/metadatahttps://gcp-api.sbgenomics.com/v2/files/{file_id}/metadataPUT and PATCH
The API has two method to modify file metadata. This method uses the HTTP verb PATCH, and the other uses the HTTP verb PUT.
- The difference between the two concerns the way that they update the information stored about the file.
PATCHallows you to update just one metadata field. On the other hand, aPUTrequest will fully overwrite the values for all metadata fields. This means that when issuing aPUTrequest you must enter values for every key required to specify the metadata, even if the values for some keys are unchanged. If you don't specify a value for a given metadata field when making thePUTrequest, then any existing value for that field will be reset.
Custom metadata fields
Apart from the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the Platform. Custom metadata can be added via the command line uploader or via the API, but not through the visual interface.
Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by getting file details via the API.
The following rules apply to custom metadata fields:
- Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the Platform.
- Maximum number of key-value pairs per file is 1000.
- Keys and values are UTF-8 encoded strings.
- Maximum length of a key is 100 bytes (UTF-8 encoding).
- Maximum length of a value is 300 bytes (UTF-8 encoding).
- Null values and keys are ignored and not counted towards the 1000 key-value pair limit.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID of the file whose metadata you want to update.
fields
string
Selector specifying a subset of fields to include in the response.
Freeform -- enter any key.
string
The value for the corresponding key
{
"sample origin": "712345"
}PATCH /v2/files/562e449060b274321afb6091/metadata HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl --data '{"foo": "bar"}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/files/5657152ee4b0298dd2cdf724/metadata"The response contains the full metadata specification for the file, including the values that you just added with the request.
{
"library_id": "12345",
"platform": "my_platform",
"sample origin": "712345"
"foo": "bar",
"my_key_1": "my_value_1",
"my_key_2": "my_value_2"
}Overwrite a file's metadata
This call changes the metadata values for the specified file.
Metadata on the Platform
Learn more about metadata fields and their values on the Seven Bridges Platform.
Files are specified by their IDs, which you can obtain by making the API call to list files in a project .
https://api.sbgenomics.com/v2/files/{file_id}/metadatahttps://eu-api.sbgenomics.com/v2/files/{file_id}/metadatahttps://gcp-api.sbgenomics.com/v2/files/{file_id}/metadataPUT and PATCH
The Seven Bridges Platform API has two method to modify file metadata. This method uses the HTTP verb PUT, and the other uses the HTTP verb PATCH.
The difference between the two concerns the way that they update the information stored about the user. PATCH allows you to update just one metadata field. On the other hand, a PUT request will fully overwrite the values for all metadata fields. This means that when issuing a PUT request you must enter values for every key required to specify the metadata, even if the values for some keys are unchanged. If you don't specify a value for a given metadata field when making the PUT request, then any existing value for that field will be reset.
Custom metadata fields
Apart from the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the Platform. Custom metadata can be added via the command line uploader or via the API, but not through the visual interface.
Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by getting file details via the API.
The following rules apply to custom metadata fields:
- Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the Platform.
- Maximum number of key-value pairs per file is 1000.
- Keys and values are UTF-8 encoded strings.
- Maximum length of a key is 100 bytes (UTF-8 encoding).
- Maximum length of a value is 300 bytes (UTF-8 encoding).
- Null values and keys are ignored and not counted towards the 1000 key-value pair limit.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
file_id
The ID of the file whose details you want to overwrite.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
In the body of the request, you should enter key-value pairs corresponding to metadata fields and their values.
Freeform -- enter any string
string
The value for the corresponding key
Since you need to specify values for all metadata fields, it can be easier to send the data as a file, using the option --data-binary in cURL.
PUT /v2/files/5655df71e4b08c5d86970945/metadata HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl --data-binary "@metadata.json" -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X PUT "https://api.sbgenomics.com/v2/files/5655df71e4b08c5d86970945/metadata"{
"foo": "bar",
"my_key_1": "my_value_1",
"my_key_2": "my_value_2",
"platform": "my_platform",
"library_id": "12345"
}{
"library_id": "12345",
"platform": "my_platform",
"foo": "bar",
"my_key_1": "my_value_1",
"my_key_2": "my_value_2"
}List current multipart uploads
This call returns the list of ongoing uploads.
https://api.sbgenomics.com/v2/upload/multiparthttps://eu-api.sbgenomics.com/v2/upload/multiparthttps://gcp-api.sbgenomics.com/v2/upload/multipartX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
GET /v2/upload/multipart HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/upload/multipart"{
"items": [
{
"href": "http://api.sbgenomics.com/v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli",
"project": "RFranklin/my-project",
"name": "1000G_phase1.indels.b37.vc",
"initiated": "2016-03-11T15:15:21Z",
"upload_id": "ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli"
},
{
"href": "http://api.sbgenomics.com/v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm",
"project": "RFranklin/my-project",
"name": "1000G_omni2.5.b37.vcf",
"initiated": "2016-03-11T16:05:28Z",
"upload_id": "X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm"
}
]
}Get details of a multipart upload
This call will return the details of an active multipart upload.
The upload is referenced by its ID as returned by a call to initialize a multipart upload or list current multipart uploads.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
upload_id
The ID of the upload. It can be obtained by initializing a new upload or by listing the ongoing multipart uploads.
list_parts
Boolean: true or false
If true, also return a list of parts that have been reported as completed for this multipart upload.
GET /v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/upload/multipart"{
"upload_id": "X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm",
"project": "RFranklin/my-project",
"name": "1000G_omni2.5.b37.vcf",
"initiated": "2016-01-01T00:00:00Z",
"parallel_uploads": true,
"part_size": 1073741824,
"uploaded_parts_count": 1,
"parts": [
{
"part_number": 1,
"response": {
"headers": {
"ETag": "43a5e128440f2b6602badfdabe610f30"
}
}
}
]
}Initialize a multipart upload
This call initializes a multipart file upload.
https://api.sbgenomics.com/v2/upload/multiparthttps://eu-api.sbgenomics.com/v2/upload/multiparthttps://gcp-api.sbgenomics.com/v2/upload/multipartX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
overwrite
Boolean: true or false
If overwrite is set to true and a file already exists under the name specified in the request, the existing file will be deleted and a new one created in its place.
Request body
In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.
project
Required
String
The name of the project you want to upload a file to.
name
Required
String
The name of the file you are about to upload. This must be unique in the project, unless you are also enabling the overwrite query parameter.
size
Integer
The size of the file that will be uploaded. This can be used to track progress of an ongoing upload, but is otherwise optional.
part_size
Integer
The preferred size for upload parts. If omitted or set to a value that is incompatible with the cloud storage provider, a default value will be used.
md5
String
32-byte hexadecimal MD5 checksum of the file. This value is currently only stored but is not used by the Platform.
POST /v2/upload/multipart HTTP/1.1
Host: api.sbgenomics.com
Content-Type: application/json
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
"project": "RFranklin/my-project",
"name": "CanFam3.1.dna_rm.toplevel.fa.gz",
"part_size": 5242880,
"size": 433759572
}curl --data '{"project": "RFranklin/my-project", "name": "CanFam3.1.dna_rm.toplevel.fa.gz", "part_size": 5242880, "size": 433759572}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/upload/multipart"{
"project": "RFranklin/my-project",
"name": "CanFam3.1.dna_rm.toplevel.fa.gz",
"size": 433759572,
"upload_id": "oSZ5rOjMQa34UykB4FiPdhkCalLVrcQjxjKPkAT69skWgOPlOvcvGaqEJ7SI1o4w",
"part_size": 5242880,
"parallel_uploads": true
}Get upload URL for a file part
This call returns the signed URL required to upload a part of a multipart upload. Once you have obtained this URL for your file part, you can make a PUT request to it with the file part as the request body.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}/part/{part_number}https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}/part/{part_number}https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}/part/{part_number}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
upload_id
The ID for the upload, returned by the call to initialize a multipart upload.
part_number
The number of the file part you are uploading. Part numbers start from 1.
Response body
The response object contains information about the URL to which you should upload the file part. The information is structured using the following key-value pairs:
method
String
The HTTP method to use when making the HTTP part upload request.
url
String
The URL to which to make the HTTP part upload request.
expires
Integer
ISO 8601 combined date and time representation in Coordinated Universal Time (UTC) by when the HTTP part upload request should be made.
headers
Object
A map of headers and values that should be set when making the HTTP part upload request.
report
Object
See the structure of the report object section below for an explanation of the report object.
success_codes
Array of Integers
A list of status codes returned by the HTTP part upload request that should be recognized as success.
A successful part upload request should be reported back to the API in a call to report an uploaded file part by passing the information collected from the report object.
Structure of the report object
This object instructs you which pieces of information need to be collected from a successful response to the HTTP part upload request.
headers
Array of Strings
A list of HTTP headers whose values should be collected from a successful response to the HTTP part upload request.
body
Object
Reserved for future use
GET /v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli/part/1 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/upload/multipart/EXAMPLE_ID/part/1"{
"method": "PUT",
"url": "https://sbg-vs2-devel.s3.amazonaws.com/aa8a1030-7e27-4da4-b42b-39658b795d61%2BCanFam3.1.dna_rm.toplevel.fa.gz?uploadId=lMllZ7WIWqHsCNj9IKV4VytwZOy0.4ZKFPDD73Cw6I745a3xFXKZLHrqDi0kZt0jTm25PYJqNfEJDF9OaJ6Xvg8vLv9K7SJ.RLiCczfy6ieGCJzNQd78vmSK3a9Bkgx2&partNumber=1&AWSAccessKeyId=AKIAJF4ANIHWSCZA724Q&Expires=1459113561&Signature=3myy2S6960C11jkmjX24WApZwNo%3D",
"expires": "2016-02-27T15:55:38Z",
"headers": {},
"report": {
"success_codes": [
200
],
"headers": [
"ETag"
]
}
}Report an uploaded part
This call allows you to report the upload of a file part.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}/parthttps://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}/parthttps://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}/partX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
upload_id
The ID for the upload, returned by the call to initialize a multipart upload.
Request body
In the body of the request, you should enter a JSON object key-value pairs describing the report. The keys, and their permitted values, are described below.
part_number
Integer
The number of the file part you are reporting. Part numbers start from 1.
response
Object
This object should contain the information collected from a successful HTTP part upload request.
See the formatting the response object section below for an explanation of its structure.
Formatting the response object
When reporting a part, the structure of the response object is different from that of the report object received when getting a part upload URL. Assuming that you have collected the information from the HTTP part upload request, you should format the response object in this call as a set of key-value mappings. The keys in these mappings are the headers and other response elements described in getting upload URL for a file part, and their values are the strings that you have collected from the HTTP part upload request.
See the example below for an illustration of how to format a part report request when the Seven Bridges Platform stores your files on Amazon S3.
headers
Object of String keys to String values
A map of header keys from the Get upload URL for a file part to their values returned by the successful HTTP part upload request you've made.
body
Object
Reserved for future use
{
"part_number": 1,
"response": {
"headers": {
"ETag": "be96ac61fa156d2d71ae61608f992554"
}
}
}POST /v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli/part HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl --data '{"part_number": 1, "response": {"headers": {"ETag": "be96ac61fa156d2d71ae61608f992554"}}}' -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli/part"Report uploaded parts
This call allows you to report the upload multiple file parts at once.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application_json
upload_id
The ID for the upload, returned by the call to initialize a multipart upload.
Request body
In the body of the request, you should enter key-value pairs describing the task. The keys, and their permitted values, are described below.
parts
Array of Objects
This key should contain an array of objects describing the individual part upload reports. Each of these objects should be formatted exactly as the whole body of the report an uploaded part call.
POST /v2/upload/multipart/EXAMPLE_ID HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
"parts": [
{
"part_number": 1,
"response": {
"headers": {
"ETag": "9f1b6da2989615a414e8b00a27d20b0c"
}
}
}
]
}curl --data '@report_parts.json' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/upload/multipart/EXAMPLE_ID"{
"parts": [
{
"part_number": 1,
"response": {
"headers": {
"ETag": "9f1b6da2989615a414e8b00a27d20b0c"
}
}
},
{
"part_number": 2,
"response": {
"headers": {
"ETag": "266f8e5c06b6cc1495646fc48b3f2f0e"
}
}
}
]
}Complete a multipart upload
This call must be issued to report the completion of a file upload.
An optional list of remaining parts may be given in the body of this request. The format of this list is the same as described in report uploaded parts.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}/completehttps://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}/completehttps://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}/completeX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
upload_id
The ID for the upload, returned by the call to initialize a multipart upload.
POST /v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm/complete HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X DELETE "https://api.sbgenomics.com/v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm/complete"{
"href": "http://api.sbgenomics.com/v2/files/36faaf29f5b4568b3c86e09d",
"path": "/Projects/e27c4f6b-5e41-4ff2-74a3-e34a70af9ace/CanFam3.1.dna_rm.toplevel.fa.gz",
"id": "36faaf29f5b4568b3c86e09d",
"project": "RFranklin/my-project",
"name": "CanFam3.1.dna_rm.toplevel.fa.gz",
"type": "file",
"size": 433759572,
"created_on": "2016-02-27T16:36:41Z",
"modified_on": "2016-02-27T16:36:41Z"
}Abort a multipart upload
This call aborts an ongoing upload.
https://api.sbgenomics.com/v2/upload/multipart/{upload_id}https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
required
application/json
upload_id
The ID for the upload, returned by a call to initialize a multipart upload or to list current multipart uploads.
DELETE /v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "content-type: application/json" -X DELETE "https://api.sbgenomics.com/v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm"Apps
These API calls below allow you to manage apps on the Seven Bridges Platform. Supported operations include listing apps in a given project, and in public apps. You can also copy apps between projects.
List all apps available to you
Get details of an app
Copy an app
Get raw CWL for an app
Add an app using raw CWL
Get raw CWL for an app revision
Get details of an app revision
List all apps available to you
This call lists all the apps available to you.
https://api.sbgenomics.com/v2/appshttps://eu-api.sbgenomics.com/v2/appshttps://gcp-api.sbgenomics.com/v2/appsPublic/private apps
Note that you can see all of the publicly available apps on the Seven Bridges Platform by setting the query parameter visibility to public. If you omit this parameter, you will see all your private apps, i.e. those in projects that you can access. Learn more about public apps in our documentation.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
project
string
Enter a project, in the form {project_owner}/{project_short_name} to restrict the results to apps from that project only.
visibility
string
Set this to public to see all public apps on the Seven Bridges Platform.
q
string
Enter one or more search terms to query apps using the q parameter. Learn more about querying below.
id
string
Use this parameter to query apps based on their ID.
Query apps
Use one or more search terms via the q parameter to query all apps that are available to you. An "and" operator is implied when using multiple search terms separated by a space. Further refine your query by specifying either the project containing the app or the project's owner.
Search terms should relate to the following app details:
- name
- label
- toolkit
- toolkit version
- category
- tagline
- description
For the query to return results, each term must match at least one of the fields that describe an app. For example, the first term can match the app's name while the second can match the app description. However, if any part of the search fails to match app details, the query is returned as null.
Example requests for querying apps
Query apps by any of the search terms
Use search terms to query apps by including them after the app parameter, as shown below.
GET /v2/apps?q=WGS SBG RNAQuery apps in a specific project
Use search terms to query apps in a specific project by entering the terms and then specifying the project name, as shown below.
GET /v2/apps?q=WGS SBG&project=username/project-nameQuery apps for a specific project owner
Use search terms to query apps belonging to a specific project owner by entering the terms and then specifying the name of the project owner, as shown below.
GET /v2/apps?q=WGS SBG&project_owner=usernameGET /v2/apps 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/apps" {
"href": "https://api.sbgenomics.com/v2/apps/",
"items": [
{
"href": "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/workflow",
"id": "RFranklin/my-project/workflow",
"name": "workflow"
},
{
"href": "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/fusion-transcript-detection-chimerascan",
"id": "RFranklin/my-project/fusion-transcript-detection-chimerascan",
"name": "fusion-transcript-detection-chimerascan"
},
{
"href": "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/somaticsniper-filters",
"id": "RFranklin/my-project/somaticsniper-filters",
"name": "somaticsniper-filters"
},
{
"href": "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/command-line-tool",
"id": "RFranklin/my-project/command-line-tool",
"name": "command-line-tool"
},
{
"href": "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/delly2-workflow",
"id": "RFranklin/my-project/delly2-workflow",
"name": "delly2-workflow"
},
]
}Get details of an app
This call returns information about the specified app. The app should be one in a project that you can access; this could be an app that has been uploaded to the Seven Bridges Platform by a project member, or a publicly available app that has been copied to the project.
https://api.sbgenomics.com/v2/apps/{app_id}https://eu-api.sbgenomics.com/v2/apps/{app_id}https://gcp-api.sbgenomics.com/v2/apps/{app_id}app_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
If the revision_number field is omitted, the latest revision of the app is returned
You can get the app_id for an app by making the call to list all apps available to you
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are querying. It can be obtained by making the call to list all apps available to you
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/apps/RFranklin/my-project/bamtools-merge-2-4-0 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/apps/RFranklin/my-project/bamtools-merge-2-4-0/0"{
"href": "https://cgc-api.sbgenomics.com/v2/apps/rfranklin/my-project/cummerbundqc/0",
"id": "rfranklin/my-project/cummerbundqc/0",
"project": "rfranklin/my-project",
"name": "CummeRbundQC",
"revision": 0,
"raw": {
"sbg:toolAuthor": "Cole Trapnell/University of Washington",
"sbg:project": "rfranklin/my-project",
"requirements": [],
"id": "https://cgc-api.sbgenomics.com/rfranklin/my-project/cummerbundqc/0/raw/",
"sbg:toolkit": "CummeRbund",
"sbg:revision": 0,
"sbg:toolkitVersion": "2.8.2",
"stdout": "",
"outputs": [
{
"outputBinding": {
"glob": "*.zip",
"sbg:metadata": {},
"sbg:inheritMetadataFrom": "#cuffdiff_zip"
},
"type": [
"null",
"File"
],
"sbg:fileTypes": "ZIP",
"description": "Downloadable zipped report.",
"id": "#archive",
"label": "Report archive"
},
{
"outputBinding": {
"glob": "*.b64html",
"sbg:metadata": {},
"sbg:inheritMetadataFrom": "#cuffdiff_zip"
},
"type": [
"null",
"File"
],
"sbg:fileTypes": "B64HTML",
"description": "Base64 encoded HTML report prepared for easy viewing.",
"id": "#html",
"label": "Report"
}
],
"inputs": [
{
"sbg:category": "Input files",
"type": [
"File"
],
"sbg:fileTypes": "ZIP",
"id": "#cuffdiff_zip",
"description": "Zipped list of output tracking, tab delimited and INFO files.",
"inputBinding": {
"prefix": "--cuffzip",
"separate": true,
"sbg:cmdInclude": true
},
"label": "Archive of Cuffdiff output files"
},
{
"sbg:category": "Basic Options",
"type": [
"null",
"float"
],
"id": "#dispersion_threshold",
"description": "Changing this parameter sets threshold for the genes that are displayed on dispersion plot, namely it removes from the plot all genes that have dispersion lower than this value.",
"sbg:toolDefaultValue": "0.01",
"inputBinding": {
"prefix": "--dispthreshold",
"separate": true,
"sbg:cmdInclude": true
},
"label": "Dispersion plot threshold"
},
{
"sbg:category": "Basic Options",
"type": [
"null",
"float"
],
"id": "#density_threshold",
"description": "Changing this parameter sets threshold for the genes that are displayed on both density plots. It removes from the plots all genes that have FPKM value lower than this value.",
"sbg:toolDefaultValue": "0.0001",
"inputBinding": {
"prefix": "--densthreshold",
"separate": true,
"sbg:cmdInclude": true
},
"label": "Density plot threshold"
},
{
"sbg:category": "Basic Options",
"type": [
"null",
"boolean"
],
"id": "#thresholds_off",
"description": "Set this parameter in case you don't want to eliminate lower expressed genes on dispersion and density plots. Be aware that this would cause plots to be stretched in order to show these low values for dispersion and FPKM.",
"sbg:toolDefaultValue": "False",
"inputBinding": {
"prefix": "--thresholdsoff",
"separate": true,
"sbg:cmdInclude": true
},
"label": "Turn off thresholds"
}
],
"hints": [
{
"class": "DockerRequirement",
"dockerImageId": "0c4541b52eb7",
"dockerPull": "images.sbgenomics.com/ana_d/cummerbund-qc:2.8.2--1.0"
},
{
"class": "sbg:CPURequirement",
"value": 8
},
{
"class": "sbg:MemRequirement",
"value": 6000
}
],
"sbg:modifiedOn": 1448366962,
"sbg:latestRevision": 0,
"sbg:id": "rfranklin/my-project/cummerbundqc/0",
"sbg:job": {
"inputs": {
"cuffdiff_zip": {
"class": "File",
"size": 0,
"path": "cuffdiff_zip.ext",
"secondaryFiles": []
},
"density_threshold": 0,
"dispersion_threshold": 0,
"thresholds_off": true
},
"allocatedResources": {
"cpu": 8,
"mem": 6000
}
},
"sbg:cmdPreview": "python /opt/cummerbund-qc.py --cuffzip cuffdiff_zip.ext --dispthreshold 0 --densthreshold 0 --thresholdsoff cuffdiff_zip.ext",
"description": "CummeRbundQC assesses the quality of a differential expression analysis performed with Cuffdiff. It accepts differential expression results in the form of a cuffdiff.zip folder as input and produces a report with charts that can be viewed on Seven Bridges platform or downloaded to your local drive. \n\nCummeRbundQC is built on top of CummeRbund v. 2.8.2. CummeRbundQC incorporates the \"Global Statistics and Quality Control\" graphs described in the CummeRbund manual. These visualizations provide an overview of the relationships among the replicates and help in detecting over-dispersion in samples.",
"sbg:links": [
{
"id": "http://bioconductor.org/packages/release/bioc/html/cummeRbund.html",
"label": "Homepage"
},
{
"id": "http://bioconductor.org/packages/release/bioc/vignettes/cummeRbund/inst/doc/cummeRbund-manual.pdf",
"label": "Manual"
},
{
"id": "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3334321/",
"label": "Publication"
}
],
"temporaryFailCodes": [],
"successCodes": [],
"sbg:contributors": [
"rfranklin"
],
"label": "CummeRbundQC",
"sbg:sbgMaintained": false,
"baseCommand": [
"python",
"/opt/cummerbund-qc.py"
],
"sbg:createdBy": "rfranklin",
"class": "CommandLineTool",
"sbg:modifiedBy": "rfranklin",
"sbg:validationErrors": [],
"sbg:revisionsInfo": [
{
"sbg:modifiedBy": "rfranklin",
"sbg:modifiedOn": 1448366962,
"sbg:revision": 0
}
],
"sbg:categories": [
"Differential-Expression",
"Plotting-and-Rendering"
],
"arguments": [],
"stdin": "",
"sbg:license": "Artistic License 2.0",
"sbg:createdOn": 1448366962
}
}Copy an app
This call copies the specified app to the specified project. The app should be one in a project that you can access; this could be an app that has been uploaded to the Seven Bridges Platform by a project member, or a publicly available app that has been copied to the project.
https://api.sbgenomics.com/v2/apps/{app_id}/actions/copyhttps://eu-api.sbgenomics.com/v2/apps/{app_id}/actions/copyhttps://gcp-api.sbgenomics.com/v2/apps/{app_id}/actions/copyapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
Note that if you omit the revision_number, the API will use the latest app revision.
You can get the app_id for an app by making the call to list all apps available to you
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are querying. It can be obtained by making the call to list all apps available to you
fields
string
Selector specifying a subset of fields to include in the response.
"project"
required
string
The name of the project you want to copy the app to
"name"
string
The new name the app will have in the target project. If its name will not change, omit this key.
POST /v2/apps/RFranklin/my-project/bamtools-merge-2-4-0/0/actions/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data '{"project": "RFranklin/my-project", "name": "new app name"}' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/apps/RFranklin/sandbox/delly2-workflow/actions/copy"{
"project": "RFranklin/my-project",
"name": "new app name"
}This call returns the full Common Workflow Language (CWL) description of the copied app. This is typically a lengthy JSON object; for conciseness, we have not included it here, but made it available on this page.
Get raw CWL for an app
This call returns information about the specified app, as raw CWL. The call differs from the call to get details of an app by returning a JSON object that is the CWL.
The app should be one in a project that you can access. This could be an app that has been uploaded to the Seven Bridges Platform by a project member, or a publicly available app that has been copied to the project.
https://api.sbgenomics.com/v2/apps/{app_id}/rawhttps://eu-api.sbgenomics.com/v2/apps/{app_id}/raw https://gcp-api.sbgenomics.com/v2/apps/{app_id}/rawapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
Note that if you omit revision_number, the API will return the latest app revision.
You can get the app_id for an app by making the call to list all apps available to you
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are querying. It can be obtained by making the call to list all apps available to you
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/apps/RFranklin/my-project/bamtools-merge-2-4-0/raw 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/apps/RFranklin/my-project/bamtools-merge-2-4-0/raw"Note that this call returns the full CWL description of the app.
{
"successCodes": [],
"sbg:homepage": "https://github.com/pezmaster31/bamtools/wiki",
"sbg:validationErrors": [],
"sbg:sbgMaintained": false,
"temporaryFailCodes": [],
"requirements": [],
"sbg:latestRevision": 0,
"description": "BamTools Merge merges multiple BAM files into a single file.",
"sbg:job": {
"inputs": {
"region": "chr1",
"input_bam_files": [
{
"path": "1.bam"
},
{
"path": "2.bam"
}
]
},
"allocatedResources": {
"cpu": 1,
"mem": 1000
}
},
"sbg:toolAuthor": "Derek Barnett, Erik Garrison, Gabor Marth, and Michael Stromberg",
"hints": [
{
"dockerImageId": "f808163d4cd3",
"class": "DockerRequirement",
"dockerPull": "images.sbgenomics.com/markop/bamtools:2.4.0"
},
{
"value": 1,
"class": "sbg:CPURequirement"
},
{
"value": 1000,
"class": "sbg:MemRequirement"
}
],
"sbg:copyOf": "djordje_klisic/public-apps-by-seven-bridges/bamtools-merge-2-4-0/0",
"sbg:createdOn": 1452181866,
"arguments": [
{
"position": 1,
"prefix": "-out",
"separate": true,
"valueFrom": "merged.bam"
}
],
"outputs": [
{
"sbg:fileTypes": "BAM",
"id": "#output_bam_file",
"outputBinding": {
"glob": "merged.bam",
"sbg:metadata": {},
"sbg:inheritMetadataFrom": "#input_bams"
},
"description": "Output BAM file.",
"type": [
"File"
],
"label": "Output BAM file"
}
],
"sbg:categories": [
"SAM/BAM-Processing"
],
"sbg:contributors": [
"RFranklin"
],
"sbg:links": [
{
"id": "https://github.com/pezmaster31/bamtools",
"label": "Homepage"
},
{
"id": "https://github.com/pezmaster31/bamtools/wiki",
"label": "Wiki"
}
],
"stdout": "",
"stdin": "",
"sbg:project": "RFranklin/my-project",
"inputs": [
{
"sbg:fileTypes": "BAM",
"id": "#input_bam_files",
"inputBinding": {
"sbg:cmdInclude": true,
"prefix": "-in",
"separate": true,
"itemSeparator": null,
"position": 0
},
"description": "The input BAM files.",
"label": "Input BAM files",
"type": [
{
"type": "array",
"items": "File"
}
],
"sbg:category": "Input & Output"
},
{
"id": "#region",
"inputBinding": {
"sbg:cmdInclude": true,
"position": 2,
"separate": true,
"prefix": "-region"
},
"description": "A region of interest (e.g. \"chr1:500..chr3:1500\"). See the documentation for more info.",
"label": "Region of interest",
"type": [
"null",
"string"
],
"sbg:category": "Input & Output"
}
],
"label": "BamTools Merge",
"sbg:createdBy": "RFranklin",
"baseCommand": [
"/opt/bamtools/bin/bamtools",
"merge"
],
"sbg:toolkitVersion": "2.4.0",
"sbg:id": "RFranklin/my-project/bamtools-merge-2-4-0/0",
"sbg:license": "The MIT License",
"sbg:revision": 0,
"sbg:cmdPreview": "/opt/bamtools/bin/bamtools merge -in 1.bam -in 2.bam -out merged.bam -region chr1",
"sbg:modifiedOn": 1452181866,
"id": "https://api.sbgenomics.com/RFranklin/my-project/bamtools-merge-2-4-0/0/raw/",
"class": "CommandLineTool",
"sbg:modifiedBy": "RFranklin",
"sbg:revisionsInfo": [
{
"sbg:modifiedBy": "RFranklin",
"sbg:modifiedOn": 1452181866,
"sbg:revision": 0
}
],
"sbg:toolkit": "BamTools"
}Add an app using raw CWL
This call allows you to add an app using raw CWL.
https://api.sbgenomics.com/v2/apps/{app_id}/rawhttps://eu-api.sbgenomics.com/v2/apps/{app_id}/rawhttps://gcp-api.sbgenomics.com/v2/apps/{app_id}/rawapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
Note that if you omit the revision_number field, the API will use the latest app revision.
You can create the {app_short_name} for your app when you upload it. It can be any string of alphanumeric characters, with no spaces. Note that the app's given name (a full human-readable string) is contained in the CWL that you POST.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-Type
Depending on the type of file you are uploading:
application/jsonfor a JSON fileapplication/yamlfor a YAML file
app_id
The ID for the app you are you want to upload. It should reference the project that you want the app to be added to, a short name for the app (containing no non-alphanumeric characters or spaces), and a revision number.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
The body of the request should be a CWL app description saved as a JSON or YAML file. For a template of this description, try making the call to get raw CWL for an app about an app already in one of your projects.
POST /v2/apps/RFranklin/my-project/my-app/raw HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data-binary '@my-app.json' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/my-app/raw"Get raw CWL for an app revision
This call returns information about the specified app revision, as raw CWL. The call differs from the call to get the details of an app revision by returning a JSON object that is the CWL description of the app revision.
The app should be one in a project that you can access. This could be an app that has been uploaded to the Seven Bridges Platform by a project member, or a publicly available app that has been copied to the project.
https://api.sbgenomics.com/v2/apps/{app_id}/rawhttps://eu-api.sbgenomics.com/v2/apps/{app_id}/rawhttps://gcp-api.sbgenomics.com/v2/apps/{app_id}/rawapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
You can get the app_id for an app by making the call to list all apps available to you
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are querying. It can be obtained by making the call to list all apps available to you
revision number
The integer that is the revision number of the app
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/apps/RFranklin/my-project/bamtools-merge-2-4-0/0/raw 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/apps/RFranklin/my-project/bamtools-merge-2-4-0/0/raw"{
"successCodes": [],
"sbg:homepage": "https://github.com/pezmaster31/bamtools/wiki",
"sbg:validationErrors": [],
"sbg:sbgMaintained": false,
"temporaryFailCodes": [],
"requirements": [],
"sbg:latestRevision": 0,
"description": "BamTools Merge merges multiple BAM files into a single file.",
"sbg:job": {
"inputs": {
"region": "chr1",
"input_bam_files": [
{
"path": "1.bam"
},
{
"path": "2.bam"
}
]
},
"allocatedResources": {
"cpu": 1,
"mem": 1000
}
},
"sbg:toolAuthor": "Derek Barnett, Erik Garrison, Gabor Marth, and Michael Stromberg",
"hints": [
{
"dockerImageId": "f808163d4cd3",
"class": "DockerRequirement",
"dockerPull": "images.sbgenomics.com/markop/bamtools:2.4.0"
},
{
"value": 1,
"class": "sbg:CPURequirement"
},
{
"value": 1000,
"class": "sbg:MemRequirement"
}
],
"sbg:copyOf": "djordje_klisic/public-apps-by-seven-bridges/bamtools-merge-2-4-0/0",
"sbg:createdOn": 1452181866,
"arguments": [
{
"position": 1,
"prefix": "-out",
"separate": true,
"valueFrom": "merged.bam"
}
],
"outputs": [
{
"sbg:fileTypes": "BAM",
"id": "#output_bam_file",
"outputBinding": {
"glob": "merged.bam",
"sbg:metadata": {},
"sbg:inheritMetadataFrom": "#input_bams"
},
"description": "Output BAM file.",
"type": [
"File"
],
"label": "Output BAM file"
}
],
"sbg:categories": [
"SAM/BAM-Processing"
],
"sbg:contributors": [
"RFranklin"
],
"sbg:links": [
{
"id": "https://github.com/pezmaster31/bamtools",
"label": "Homepage"
},
{
"id": "https://github.com/pezmaster31/bamtools/wiki",
"label": "Wiki"
}
],
"stdout": "",
"stdin": "",
"sbg:project": "RFranklin/my-project",
"inputs": [
{
"sbg:fileTypes": "BAM",
"id": "#input_bam_files",
"inputBinding": {
"sbg:cmdInclude": true,
"prefix": "-in",
"separate": true,
"itemSeparator": null,
"position": 0
},
"description": "The input BAM files.",
"label": "Input BAM files",
"type": [
{
"type": "array",
"items": "File"
}
],
"sbg:category": "Input & Output"
},
{
"id": "#region",
"inputBinding": {
"sbg:cmdInclude": true,
"position": 2,
"separate": true,
"prefix": "-region"
},
"description": "A region of interest (e.g. \"chr1:500..chr3:1500\"). See the documentation for more info.",
"label": "Region of interest",
"type": [
"null",
"string"
],
"sbg:category": "Input & Output"
}
],
"label": "BamTools Merge",
"sbg:createdBy": "RFranklin",
"baseCommand": [
"/opt/bamtools/bin/bamtools",
"merge"
],
"sbg:toolkitVersion": "2.4.0",
"sbg:id": "RFranklin/my-project/bamtools-merge-2-4-0/0",
"sbg:license": "The MIT License",
"sbg:revision": 0,
"sbg:cmdPreview": "/opt/bamtools/bin/bamtools merge -in 1.bam -in 2.bam -out merged.bam -region chr1",
"sbg:modifiedOn": 1452181866,
"id": "https://api.sbgenomics.com/RFranklin/my-project/bamtools-merge-2-4-0/0/raw/",
"class": "CommandLineTool",
"sbg:modifiedBy": "RFranklin",
"sbg:revisionsInfo": [
{
"sbg:modifiedBy": "RFranklin",
"sbg:modifiedOn": 1452181866,
"sbg:revision": 0
}
],
"sbg:toolkit": "BamTools"
}Get details of an app revision
This call allows you to obtain a particular revision of a tool, which is not necessarily the most recent version.
https://api.sbgenomics.com/v2/apps/{app_id}/{revision_number}https://eu-api.sbgenomics.com/v2/apps/{app_id}/{revision_number}https://gcp-api.sbgenomics.com/v2/apps/{app_id}/{revision_number}app_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
You can get the app_id for an app by making the call to list all apps available to you
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are querying. It can be obtained by making the call to list all apps available to you
revision_number
The integer denoting the revision of the app.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/apps/RFranklin/my-project/bamtools-merge-2-4-0/0 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/apps/RFranklin/my-project/bamtools-merge-2-4-0/0/raw"{
"href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/RSEM BAM2WIG/4",
"id": "admin/sbg-public-data/rsem-bam2wig-1-2-31/4",
"project": "admin/sbg-public-data",
"name": "RSEM BAM2WIG",
"revision": 4,
"raw": {
"id": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/rsem-bam2wig-1-2-31/4/raw/",
"sbg:modifiedOn": 1476979693,
"inputs": [
{
"description": "Can be either in SAM/BAM/CRAM format. Must be sorted.",
"label": "Sorted alignment file",
"type": [
"File"
],
"sbg:fileTypes": "BAM, SAM, CRAM",
"inputBinding":
{ "position": 0, "separate": true, "sbg:cmdInclude": true },
"sbg:stageInput": "copy",
"id": "#sorted_alignment_file"
},
{
"description": "If this is set, RSEM will not look for “ZW” tag and each alignment appeared in the BAM file has weight 1. Set this if your BAM file is not generated by RSEM.",
"label": "No fractional weight",
"sbg:category": "Options",
"type": [
"null",
"boolean"
],
"id": "#no_fractional_weight",
"inputBinding":
{ "prefix": "--no-fractional-weight", "position": 3, "separate": true, "sbg:cmdInclude": true },
"sbg:toolDefaultValue": "off"
}
],
"sbg:cmdPreview": "rsem-bam2wig /path/to/aligned_file.bam aligned_file.wiggle_plot.wig aligned_file.wiggle_plot",
"sbg:latestRevision": 4,
"sbg:revisionsInfo": [
{ "sbg:revisionNotes": null, "sbg:revision": 0, "sbg:modifiedOn": 1476979693, "sbg:modifiedBy": "admin" }
,
{ "sbg:revisionNotes": null, "sbg:revision": 1, "sbg:modifiedOn": 1476979693, "sbg:modifiedBy": "admin" }
,
{ "sbg:revisionNotes": null, "sbg:revision": 2, "sbg:modifiedOn": 1476979693, "sbg:modifiedBy": "admin" }
,
{ "sbg:revisionNotes": "Updated description.", "sbg:revision": 3, "sbg:modifiedOn": 1476979693, "sbg:modifiedBy": "admin" }
,
{ "sbg:revisionNotes": null, "sbg:revision": 4, "sbg:modifiedOn": 1476979693, "sbg:modifiedBy": "admin" }
],
"hints": [
{ "value": 1, "class": "sbg:CPURequirement" }
,
{ "value": 1000, "class": "sbg:MemRequirement" }
,
{ "dockerImageId": "67d3a6c01e92210f43c8ef809c2a245a75bf7d5a52762823cdc3b2e784de576c", "class": "DockerRequirement", "dockerPull": "images.sbgenomics.com/uros_sipetic/rsem:1.2.31" }
],
"stdin": "",
"sbg:links": [
{ "label": "RSEM Homepage", "id": "http://deweylab.github.io/RSEM/" }
,
{ "label": "RSEM Source Code", "id": "https://github.com/deweylab/RSEM" }
,
{ "label": "RSEM Download", "id": "https://github.com/deweylab/RSEM/archive/v1.2.31.tar.gz" }
,
{ "label": "RSEM Publications", "id": "https://bmcbioinformatics.biomedcentral.com/articles/10.1186/1471-2105-12-323" }
,
{ "label": "RSEM Documentation", "id": "http://deweylab.github.io/RSEM/README.html" }
],
"stdout": "",
"description": "RSEM BAM2WIG generates a wiggle plot representing the expected number of reads overlapping each position in the genome/transcript from the sorted genome/transcript BAM file output.\n\n###Common issues###\nNone",
"sbg:validationErrors": [],
"sbg:image_url": null,
"sbg:toolkitVersion": "1.2.31",
"sbg:toolkit": "RSEM",
"requirements": [
{
"id": "#cwl-js-engine",
"class": "ExpressionEngineRequirement",
"requirements": [
{ "class": "DockerRequirement", "dockerPull": "rabix/js-engine" }
]
}
],
"sbg:id": "admin/sbg-public-data/rsem-bam2wig-1-2-31/4",
"sbg:categories": [
"Converters",
"Plotting-and-Rendering",
"RNA"
],
"sbg:toolAuthor": "Bo Li, Colin Dewey",
"temporaryFailCodes": [],
"label": "RSEM BAM2WIG",
"sbg:createdBy": "admin",
"class": "CommandLineTool",
"sbg:project": "admin/sbg-public-data",
"sbg:sbgMaintained": false,
"sbg:revision": 4,
"baseCommand": [
"rsem-bam2wig"
],
"sbg:contributors": [
"admin"
],
"sbg:createdOn": 1476979693,
"successCodes": [],
"sbg:modifiedBy": "admin",
"sbg:license": "GNU General Public License v3.0 only",
"arguments": [
{
"position": 1,
"valueFrom": {
"engine": "#cwl-js-engine",
"script": "{\n var str = $job.inputs.sorted_alignment_file.path.split('/').pop().split('.')\n x = \"\"\n for (i=0; i<str.length-1; i++) {\n if (i<str.length-2)
{\n x = x + str[i] + '.'\n } else {\n x = x + str[i]\n }\n }\n return x + \".wiggle_plot.wig\"\n}",
"class": "Expression"
},
"separate": true
},
{
"position": 2,
"valueFrom": {
"engine": "#cwl-js-engine",
"script": "{\n var str = $job.inputs.sorted_alignment_file.path.split('/').pop().split('.')\n x = \"\"\n for (i=0; i<str.length-1; i++) {\n if (i<str.length-2) {n x = x + str[i] + '.'n }
else
{\n x = x + str[i]\n }
\n }\n return x + \".wiggle_plot\"\n}",
"class": "Expression"
},
"separate": true
}
],
"outputs": [
{
"description": "Output wiggle file.",
"label": "Output wiggle file",
"type": [
"null",
"File"
],
"sbg:fileTypes": "WIG",
"outputBinding":
{ "glob": "*.wig", "sbg:inheritMetadataFrom": "#sorted_alignment_file" }
,
"id": "#rsem_bam_to_wiggle_plot_file"
}
],
"sbg:job": {
"allocatedResources":
{ "mem": 1000, "cpu": 1 }
,
"inputs": {
"no_fractional_weight": false,
"sorted_alignment_file":
{ "size": 0, "path": "/path/to/aligned_file.bam", "secondaryFiles": [], "class": "File" }
}
}
}
}Add an app revision using raw CWL
This call creates a new revision for an existing app. It adds a new CWL app description, and stores it as the named revision for the specified app.
https://api.sbgenomics.com/v2/apps/{app_id}/rawhttps://eu-api.sbgenomics.com/v2/apps/{app_id}/rawhttps://gcp-api.sbgenomics.com/v2/apps/{app_id}/rawapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
For this particular call, you need to explicitly specify the app revision number.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID for the app you are you want to upload. It should reference the project that you want the app to be added to, a short name for the app (containing no non-alphanumeric characters or spaces), and a revision number.
fields
string
Selector specifying a subset of fields to include in the response.
Request body
The body of the request should be a CWL app description, saved as a JSON file. For a template of this description, try making the call to get raw app information about an app already in one of your projects.
POST /v2/apps/RFranklin/my-project/my-app/4/raw HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data-binary '@my-app.json' -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/apps/RFranklin/my-project/my-app/4/raw"Synchronize a copied app with its parent app
This call synchronizes a copied app with the source app from which it has been copied. For example, when FASTQC is copied from public apps to a project and updates are made to FASTQC in the public apps gallery (there are new revisions), this action fetches all revisions and revision notes from the updated parent app and applies them to your copied app. Once this has been done, the copied app is updated to the latest revision and includes the complete revision history of its parent app, following the logic of the git pull command.
https://api.sbgenomics.com/v2/apps/{app_id}/actions/synchttps://eu-api.sbgenomics.com/v2/apps/{app_id}/actions/synchttps://gcp-api.sbgenomics.com/v2/apps/{app_id}/actions/syncapp_ids
Recall from the apps section in the API overview that the app_id has the form {project_owner}/{project}/{app_short_name}/{revision_number}.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
app_id
The ID of the app you want to update. It should reference the project owner, the project that your app is copied to, and the app's short name (containing no non-alphanumeric characters or spaces).
fields
string
Selector specifying a subset of fields to include in the response.
{
"href": "https://api.sbgenomics.com/v2/apps/rfranklin/test-project/bamtools-index-2-4-0/1",
"id": "rfranklin/test-project/bamtools-index-2-4-0/1",
"project": "rfranklin/test-project",
"name": "BamTools Index",
"revision": 1,
"raw": {
"sbg:sbgMaintained": false,
"requirements": [
{
"class": "ExpressionEngineRequirement",
"id": "#cwl-js-engine",
"requirements": [
{
"class": "DockerRequirement",
"dockerPull": "rabix/js-engine"
}
]
}
],
"sbg:modifiedOn": 1494849814,
"outputs": [
{
"label": "Output BAM file",
"sbg:fileTypes": "BAM",
"description": "Output BAM file with index (BAI or BTI) file as a secondary file (not visible in the output list of the task).",
"id": "#output_bam_file",
"type": [
"null",
"File"
],
"outputBinding": {
"glob": {
"class": "Expression",
"engine": "#cwl-js-engine",
"script": "{\n if ($job.inputs.indexed_data === true){\n\treturn ''\n } else {\n return $job.inputs.input_bam_file.path.split(\"/\").pop()\n }\n}\n\n\n"
},
"secondaryFiles": [
".bai",
".bti"
],
"sbg:inheritMetadataFrom": "#input_bam_file"
}
},
{
"label": "Generated Index File",
"sbg:fileTypes": "BAI,BTI",
"description": "Generated index file (without the indexed data).",
"id": "#generated_index",
"type": [
"null",
"File"
],
"outputBinding": {
"glob": "{*.bai,*.bti}",
"sbg:inheritMetadataFrom": "#input_bam_file"
}
}
],
"sbg:toolAuthor": "Derek Barnett, Erik Garrison, Gabor Marth, and Michael Stromberg",
"sbg:revisionsInfo": [
{
"sbg:modifiedOn": 1494849680,
"sbg:modifiedBy": "rfranklin",
"sbg:revision": 0,
"sbg:revisionNotes": "Copy of rfranklin/bam-test/bamtools-index-2-4-0/0"
},
{
"sbg:modifiedOn": 1494849814,
"sbg:modifiedBy": "rfranklin",
"sbg:revision": 1,
"sbg:revisionNotes": "Modified output description."
}
],
"sbg:categories": [
"SAM/BAM-Processing",
"Indexing"
],
"sbg:modifiedBy": "rfranklin",
"sbg:image_url": null,
"sbg:appVersion": [
"sbg:draft-2"
],
"sbg:createdBy": "rfranklin",
"sbg:copyOf": "rfranklin/bam-test/bamtools-index-2-4-0/1",
"stdout": "",
"sbg:latestRevision": 1,
"temporaryFailCodes": [],
"sbg:job": {
"inputs": {
"bti_format": false,
"input_bam_file": {
"class": "File",
"size": 0,
"secondaryFiles": [],
"path": "input/input_bam.bam"
},
"indexed_data": false
},
"allocatedResources": {
"cpu": 1,
"mem": 1000
}
},
"successCodes": [],
"sbg:links": [
{
"label": "Homepage",
"id": "https://github.com/pezmaster31/bamtools"
},
{
"label": "Wiki",
"id": "https://github.com/pezmaster31/bamtools/wiki"
}
],
"sbg:revisionNotes": "Modified output description.",
"label": "BamTools Index",
"cwlVersion": "sbg:draft-2",
"sbg:homepage": "https://github.com/pezmaster31/bamtools/wiki",
"sbg:cmdPreview": "/opt/bamtools/bin/bamtools index -in input_bam.bam",
"stdin": "",
"sbg:id": "rfranklin/test-project/bamtools-index-2-4-0/1",
"hints": [
{
"class": "DockerRequirement",
"dockerPull": "images.sbgenomics.com/markop/bamtools:2.4.0",
"dockerImageId": "f808163d4cd3"
},
{
"class": "sbg:CPURequirement",
"value": 1
},
{
"class": "sbg:MemRequirement",
"value": 1000
}
],
"sbg:toolkitVersion": "2.4.0",
"sbg:license": "The MIT License",
"sbg:toolkit": "BamTools",
"sbg:validationErrors": [],
"class": "CommandLineTool",
"inputs": [
{
"sbg:category": "Input & Output",
"label": "Input BAM file",
"sbg:fileTypes": "BAM",
"id": "#input_bam_file",
"description": "The input BAM file.",
"type": [
"File"
],
"sbg:stageInput": "link"
},
{
"sbg:category": "Input & Output",
"description": "Create (non-standard) BamTools index file (*.BTI). Default behavior is to create standard BAM index (*.BAI).",
"type": [
"null",
"boolean"
],
"label": "BTI format",
"id": "#bti_format"
},
{
"sbg:category": "File input",
"label": "Input BAI(BAM index) file",
"sbg:fileTypes": "BAI",
"id": "#input_bai_file",
"description": "Input BAI(BAM index) file.",
"type": [
"null",
"File"
],
"sbg:stageInput": "link"
},
{
"sbg:category": "Input & Output",
"description": "Don't output indexed data file. The default value is [FALSE].",
"type": [
"null",
"boolean"
],
"label": "Don't output indexed data file",
"id": "#indexed_data"
}
],
"sbg:createdOn": 1494849680,
"arguments": [
{
"valueFrom": {
"class": "Expression",
"engine": "#cwl-js-engine",
"script": "{\n if (!(typeof $job.inputs.input_bai_file !== \"undefined\")){\n return \"-in \" + $job.inputs.input_bam_file.path.split('/').pop() \n }\n}"
},
"position": 0,
"separate": true
},
{
"valueFrom": {
"class": "Expression",
"engine": "#cwl-js-engine",
"script": "{\n if (!(typeof $job.inputs.input_bai_file !== \"undefined\"))\n if ((typeof $job.inputs.bti_format !== \"undefined\") && ($job.inputs.bti_format))\n \treturn \"-bti\" \n}"
},
"position": 1,
"separate": true
}
],
"description": "BamTools Index creates an index file (BAI or BTI) for a BAM file. If BAI file is present on the input the tool will skip indexing step and output BAM with provided BAI file.\n\n**Common issues:** Providing a BAI file on input will result in a pass-through without execution, even if a different index format is requested on the output (BTI instead of BAI).",
"sbg:contributors": [
"rfranklin"
],
"id": "https://api.sbgenomics.com/v2/apps/rfranklin/test-project/bamtools-index-2-4-0/1/raw/",
"baseCommand": [
{
"class": "Expression",
"engine": "#cwl-js-engine",
"script": "{\n if ($job.inputs.input_bai_file){\n \treturn\"echo Skipping index step because BAI file is provided on the input.\"\n }\n else{\n return \"/opt/bamtools/bin/bamtools index\"\n }\n}"
}
],
"sbg:projectName": "Test Project",
"sbg:project": "rfranklin/test-project",
"sbg:revision": 1
}
}POST v2/apps/rfranklin/test-project/bamtools-index-2-4-0/actions/sync HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl --data '{"username": "rfranklin", "permissions": { "read": true, "write": true, "execute": false}}' -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/apps/rfranklin/test-project/bamtools-index-2-4-0/actions/sync"List tasks you can access (primary method)
This call returns a list of tasks that you can access.
https://api.sbgenomics.com/v2/taskshttps://eu-api.sbgenomics.com/v2/taskshttps://gcp-api.sbgenomics.com/v2/tasksX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
status
string
You can filter the returned tasks by their status. Set the value of status to one of the following values:"QUEUED""DRAFT""RUNNING""COMPLETED""ABORTED""FAILED"
parent
string
Enter the task ID of the parent task to return all child tasks from that parent.
A parent task is a task that specifies criteria by which to batch its inputs into a series of further sub-tasks, called child tasks.
See the documentation on batching tasks for more details on how to run tasks in batches.
project
string
Enter the project ID of the project you wish to list the tasks from.
created_from
string
Enter the starting date for querying tasks created on the specified date and onwards (see below for more information).
created_to
string
Enter the ending date for querying tasks created until the specified date. You can use it in combination with the created_from to specify a time interval.
started_from
string
Enter the starting date for querying tasks started on the specified date and onwards (see below for more information).
started_to
string
Enter the starting date for querying tasks started until the specified date (see below for more information).
ended_from
string
Enter the starting date for querying tasks that ended on a specified date (see below for more information).
ended_to
string
Enter the ending date for querying tasks that ended until a specified date.
Using the timestamps
The parameters created_from, created_to, started_from, started_to, ended_from and ended_to are timestamp parameters.
They can be used to query tasks that were created, started, or ended during a specified time interval. All query parameters can be combined.
For example, querying https://api.sbgenomics.com/v2/tasks?fields=_all&started_from=2016-12-26T12:46:25&ended_to=2016-12-28 will return all tasks which ran between December 26, 2016 at 12:46:25 and December 28.
Furthermore, the timestamp query parameters can be combined with other query parameters. For example, querying https://api.sbgenomics.com/v2/tasks?fields=_all&created_from=2016-12-26T12:46:25&status=FAILED will return all tasks which were created from December 26 onwards and have failed.
Date format
All dates should be entered using the UTC format (ISO 8601). Allowed formats are:
- <yyyy-MM-dd>T<HH:mm:ss>+/-<HH:mm> (use this format to specify the UTC offset, see below)
- yyyy-MM-ddTHH:mm:ss
- yyyy-MM-dd (when this format is used, the implicit time is 00:00:00)
yyyy
4 digits for the year (e.g. 2017)
T
special character followed by hours and minutes
ss
2 digits for seconds (e.g. "25)
MM
2 digits for a month (e.g. "02" for February)
mm
2 digits for minutes (e.g. "45")
HH
2 digits for an hour (e.g. "23")
dd
2 digits for a day (e.g. "01")
-
UTC - hh:mm
+
UTC + hh:mm
UTC offset (HH:mm)
The hours and minutes should be entered the same way as for the date but are used to specify the time offset (e.g. -05:00 = UTC-5). This means you can use your local time to query but have to specify the UTC offset.
Examples:
- 2016-04-01T14:25:50+01:00 - Fri Apr 01 13:25:50 UTC 2016
- 2016-04-01T14:25:50 - Fri Apr 01 14:25:50 UTC 2016
- 2016-04-01 - Fri Apr 01 00:00:00 UTC 2016
GET /v2/tasks HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/tasks"{
"items": [
{
"href": "https://api.sbgenomics.com/v2/tasks/d14259c2-3fe3-4f87-b4eb-a54847681fc9",
"id": "d14259c2-3fe3-4f87-b4eb-a54847681fc9",
"name": "bwa run - 05-11-2015 10:30:59",
"description": ""
}
]
}Create a new draft task
This call creates a new task. You can create either a single task or a batch task by using the app's default batching, override batching, or disable batching completely.
A parent task is a task that specifies criteria by which to batch its inputs into a series of further sub-tasks, called child tasks.
See the documentation on batching tasks for more details on batching criteria.
https://api.sbgenomics.com/v2/taskshttps://eu-api.sbgenomics.com/v2/taskshttps://gcp-api.sbgenomics.com/v2/tasksX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
fields
string
Selector specifying a subset of fields to include in the response.
action
string
If set to "run", the task will be run immediately upon creation.
Request body
The request body should be a JSON object specifying the app that you want to run, and assigning input files to its input nodes. It is entered as a list of key-value pairs. The keys specify the name and description of the task to be created, the app to executed, and details of its inputs files. The keys, and their permitted values, are described below.
You can see a list of the app's input nodes on the Seven Bridges Platform on the apps page for the project. Specify the files to input to the nodes using the files' IDs, which you can obtain using the call to get files.
"name"
string
The name of the task
"description"
string
An optional description of the task
"app"
string
The specification of the app that you want to run. Recall that apps are specified by their projects, in the form {project_owner}/{project}/{app_name}
"inputs"
dictionary.
See the section on specifying task inputs for information on creating task input objects.
"batch"
Boolean
This is set to false by default. Set to true to create a batch task and specify the batch_input and batch-by criteria as described below.
string
The ID of the input on which you wish to batch. You would typically batch on the input consisting of a list of files. If this parameter is omitted, the default batching criteria defined for the app will be used.
dictionary
This specifies the criteria on which to batch. It can be in one of two formats.
If you wish to batch per item in the app's input (i.e., typically per file in a list of files) then specify a dictionary with the following format:
{ "type": "ITEM" }If you wish to batch by groups of inputs, you should specify the criteria satisfied by each group. This should be a common metadata value in one, or more, metadata fields.
To do this, specify a dictionary with the following format:
{
"type": "CRITERIA",
"criteria": [
"metadata.<field_1>", "metadata.<field_2>"
]
}
This will group inputs by shared metadata values for <field_1> and <field_2>, in that order. Arbitrarily many metadata fields may be listed, and the order in which fields are grouped will respect the order of the list.
use_interruptible_instances
Boolean
This field can be true or false. Set this field to true to allow the use of spot instances.
The response body for a batch task will contain information about the task. The content will be a little different depending on whether the task in question is a batch task (a parent task) or one task that is part of a batch (a child task).
The following key-value pairs in the response body indicate the batch status of the task:
"batch"
Boolean
Set to True if the task is a parent batch task; otherwise False.
"parent"
string
The ID of the parent task, in the case that the task is part of a batch (i.e. a child task).
"batch_group"
dictionary
Present only for child tasks.
This describes the structure of the parent task, i.e. the criteria by which tasks are batched.
- If tasks are batched per item in the input, the structure is as shown in the following example:
"batch_group": {
"value": "C18-146.fastq",
"fields": {}
}
- If tasks are batched by metadata fields, the structure is as shown in the following example:
"batch_group": {
"value": "hg19, E18127-pool40-L2355",
"fields": {
"metadata.library_id": "hg19",
"metadata.sample_id": "E18127-pool40-L2355"
}
}
"execution_status"
dictionary
For a parent task, this describes the number of child tasks in any given state, in the following form:
"execution_status": {
"message": "Running",
"queued": 1,
"running": 5,
"completed": 2,
"failed": 1,
"aborted": 0
}
For a child task or a single task (not part of a batch), the execution status lists a number of steps.
In the example, the new task is included in the body as new-task.json, shown below.
POST /v2/tasks HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data-binary "@new-task.json" -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/tasks"{ "description": "my draft task",
"name": "RFranklin, Experiment IV",
"app": "RFranklin/my-project/new-test-app",
"project": "RFranklin/my-project",
"use_interruptible_instances": false,
"inputs": {
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "example_human_known_indels.vcf"
}
}
}{
"href": "https://api.sbgenomics.com/v2/tasks/a8497170-fcc3-4605-8f1f-8346aa84306a",
"id": "a8497170-fcc3-4605-8f1f-8346aa84306a",
"name": "RFranklin, Experiment IV",
"description": "my draft task",
"status": "DRAFT",
"project": "RFranklin/my-project",
"use_interruptible_instances": false,
"app": "RFranklin/my-project/new-test-app/0",
"type": "v2",
"created_by": "RFranklin",
"start_time": "2016-01-12T19:20:10Z",
"inputs": {
"dispersion_threshold": null,
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "example_human_known_indels.vcf"
},
"density_threshold": null,
"thresholds_off": null
},
"outputs": {
"archive": null,
"html": null
}
}
Delete a task
This call deletes the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
https://api.sbgenomics.com/v2/tasks/{task_id}https://eu-api.sbgenomics.com/v2/tasks/{task_id}https://gcp-api.sbgenomics.com/v2/tasks/{task_id}Deleting tasks
Note that you can only delete draft tasks, not running tasks.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
required
The ID of the task you are deleting. See the section on specifying tasks for details.
DELETE /v2/tasks/e3d4bab1-b649-4e33-b75b-2fe2ada721ca 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 DELETE "https://api.sbgenomics.com/v2/tasks/e3d4bab1-b649-4e33-b75b-2fe2ada721ca"Get task inputs
This call returns just the inputs provided to the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
https://api.sbgenomics.com/v2/tasks/{task_id}/inputshttps://eu-api.sbgenomics.com/v2/tasks/{task_id}/inputshttps://gcp-api.sbgenomics.com/v2/tasks/{task_id}/inputsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
required
The ID of the task you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/inputs 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/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/inputs"{
"Known_SNPs": [
{
"class": "File",
"path": "566b059ae4b0c560b469eb7c",
"name": "dbsnp_137.b37.vcf"
}
],
"Known_Indels": [
{
"class": "File",
"path": "566b059ae4b0c560b469eb81",
"name": "1000G_phase1.indels.b37.vcf"
},
{
"class": "File",
"path": "566b059ae4b0c560b469eb86",
"name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
}
],
"input_file": {
"class": "File",
"path": "56796c27e4b0c560b46ab03c",
"name": "3d1b628fa0d554d5fefb71444511dcbb.bam"
},
"Target_BED": {
"class": "File",
"path": "566b059ae4b0c560b469eb7f",
"name": "exome_targets.b37.bed"
},
"Reference": {
"class": "File",
"path": "56796f07e4b0c560b46ab043",
"name": "GRCh37-lite.fa"
},
"snpEff_databse": {
"class": "File",
"path": "566b059ae4b0c560b469eb83",
"name": "snpEff_v3_3_GRCh37.71.zip"
},
"memory_per_job": 8000
}Abort a task
This call aborts the specified task. Only tasks whose status is "RUNNING" or "QUEUED" may be aborted.
https://api.sbgenomics.com/v2/tasks/{task_id}/actions/aborthttps://eu-api.sbgenomics.com/v2/tasks/{task_id}/actions/aborthttps://gcp-api.sbgenomics.com/v2/tasks/{task_id}/actions/abortX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
The ID of the task you are acting on.
fields
string
Selector specifying a subset of fields to include in the response.
POST /v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6/actions/abort" 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 POST "https://api.sbgenomics.com/v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6/actions/abort"{
"href": "https://api.sbgenomics.com/v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6",
"id": "b0bbeda6-153b-4801-92ad-82bc0e58bdb6",
"name": "Workflow run - 11-15-15 15:56:11",
"status": "Active",
"project": "RFranklin/my-project",
"use_interruptible_instances": false,
"app": "RFranklin/my-project/workflow/1",
"created_by": "RFranklin",
"executed_by": "Kate",
"start_time": "2015-11-15T15:56:11Z",
"inputs": {
"my_hardcoded_string": {
"schema": [
"null",
"string"
],
"value": null,
"errors": null,
"files": null,
"missing_files": null
}
}
}Get details of a task
This call returns details of the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
https://api.sbgenomics.com/v2/tasks/{task_id}https://eu-api.sbgenomics.com/v2/tasks/{task_id}https://gcp-api.sbgenomics.com/v2/tasks/{task_id}The task details include its creator, its start and end time, the number of jobs completed in it, and its input and output files. You can also see the status of the task.
X-SBG-Auth-Token
required
Your Seven Bridges authentication token.
task_id
required
The ID of the task you are querying
fields
string
Selector specifying a subset of fields to include in the response.
The response body for a batch task will contain information about the task. The content will be a little different depending on whether the task in question is a batch task (a parent task) or one task that is part of a batch (a child task).
Regular task response body
The example below contains an example response body from a regular (non-batch) task.
{
"href": "https://staging-api.sbgenomics.com/v2/tasks/a547a1c4-45c3-441e-857e-caf2a2df96ad",
"id": "a547a1c4-45c3-441e-857e-caf2a2df96ad",
"name": "Tengfei and Damir playing",
"status": "ABORTED",
"project": "damirk/batch-test",
"app": "damirk/batch-test/whole-exome-sequencing-gatk-2-3-9-lite/2",
"type": "v2",
"created_by": "damirk",
"executed_by": "damirk",
"start_time": "2016-04-05T12:18:14Z",
"end_time": "2016-04-07T11:04:42Z",
"batch": true,
"batch_input": "FASTQ",
"batch_by": {
"type": "CRITERIA",
"criteria": [
"metadata.sample_id",
"metadata.library_id"
]
},
"execution_status": {
"duration": '123456789',
"running_duration": '120453636',
"queued_duration": '3456789',
"message": "Batch tasks list initialization.",
"queued": 0,
"running": 0,
"completed": 0,
"failed": 0,
"aborted": 0,
"execution_duration": 0,
"system_limit": false,
"account_limit": false
},
"price": {
"currency": "USD",
"amount": "0.00",
},
"inputs": {
"Known_SNPs": [
{
"class": "File",
"path": "5702cd5a60b27cfe6e8c13bf",
"name": "dbsnp_137.b37.vcf"
}
],
<snip>
}
}Interpreting the response body
The following key-value pairs in the response body indicate the batch status of the task:
"batch"
boolean
Set to True if the task is a parent batch task; otherwise False.
"parent"
string
The ID of the parent task, in the case that the task is part of a batch (i.e. a child task).
"batch_group"
dictionary
Present only for child tasks.
This describes the structure of the parent task, i.e. the criteria by which tasks are batched.
- If tasks are batched per item in the input, the structure is as shown in the following example:
"batch_group": {
"value": "C18-146.fastq",
"fields": {}
}
- If tasks are batched by metadata fields, the structure is as shown in the following example:
"batch_group": {
"value": "hg19, E18127-pool40-L2355",
"fields": {
"metadata.library_id": "hg19",
"metadata.sample_id": "E18127-pool40-L2355"
}
}
"execution_status"
dictionary
For a parent task, this describes the number of child tasks in any given state, in the following form:
"execution_status": {
"message": "Running",
"queued": 1,
"running": 5,
"completed": 2,
"failed": 1,
"aborted": 0
}
For a child task or a single task (not part of a batch), the execution status lists a number of steps.
"errors"
array
If there are any errors related to task validation, they will be represented here in an array. Each of the errors is represented by a dictionary, containing the error type, a human readable message, and the ID of the input responsible for the input. There may also be further data, if it is available.
See below for an example of the error array, and information on interpreting it.
"errors": [
{
"type": "error/task_validation/input/schema",
"message": "Value for this input does not match the expected type.",
"input_id": "FASTQ"
},
{
"type": "error/task_validation/input/schema",
"message": "Value for this input does not match the expected type.",
"input_id": "SnpEff_Database"
},
{
"type": "error/task_validation/input/schema",
"message": "Value for this input does not match the expected type.",
"input_id": "Reference"
}
]More on task validations and validation errors
Whenever you request to create or run a task on the Platform, it will be validated against several criteria. Similarly, when you create or modify any input for a task, these will be validated.
All validations errors are stored as a high-level errors array property in the API response.
You may get the following errors if a task fails these validations:
1
error/task_validation/input/schema
Value for this input does not match the expected type.
This error arises when the input value for a task, or a single app in a task, is the wrong data type, for example, if you have submitted an array of files to an input port that expects a single file, or if you have submitted a file to an input port that expects a string.
2
error/task_validation/input/invalid_name_files
Some files on this input contain impermissible characters in their name. Please change the file names before running the task since irregular file names can often lead to certain tools failing.
This error occurs when you enter a space or other special character that can cause problems when running a command line tool.
3
error/task_validation/input/files_missing
Some files found in this input cannot be found in the project.
All of the input files need to be in the same project where the task is being run. This error occurs when some input files cannot be found in the project.
4
error/task_validation/input/secondary_files_missing
Some secondary (index) files required by this input cannot be found in the project
This error occurs when an app requires secondary files for an input, typically index files (i.e. a .BAI file for a .BAM file input) and those files cannot be found in the project.
GET /v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb 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/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb"{
"href": "https://api.sbgenomics.com/v2/tasks/f586a3fb-c9e4-4415-b22b-648a66969a37",
"id": "f586a3fb-c9e4-4415-b22b-648a66969a37",
"name": "grep run - 11-26-15 14:14:14",
"status": "COMPLETED",
"project": "RFranklin/test",
"use_interruptible_instances": false,
"app": "RFranklin/my-project/grep/5",
"type": "v2",
"batch": false,
"created_by": "RFranklin",
"executed_by": "RFranklin",
"start_time": "2015-11-26T14:14:14Z",
"end_time": "2015-11-26T14:20:30Z",
"execution_status": {
"steps_completed": 19,
"system_limit": false,
"account_limit": false,
"instance_init": false,
"steps_total": 19,
"message": "Completed",
"duration": 0,
"queued_duration": 0,
"running_duration": 0,
"execution_duration": 0
},
"price": {
"currency": "USD",
"amount": "0.23",
"breakdown": {
"storage": "0.00",
"computation": "0.23"
}
},
"inputs": {
"file_to_search": {
"class": "File",
"path": "5655df71e4b08c5d86970945",
"name": "test-text.txt"
},
"lines_of_context": 2,
"pattern_to_find": "word"
},
"outputs": {
"pattern_found": {
"path": "5657152ee4b0298dd2cdf724",
"name": "output.txt",
"class": "File"
}
}
}Modify a task
Change the details of the specified task, including its name, description, and inputs. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
Note that you can only modify tasks with a task status of DRAFT. Tasks which are RUNNING, QUEUED, ABORTED, COMPLETED or FAILEDcannot be modified in order to enable the reproducibility of analyses which have been queued for execution or has initiated executing.
See the section on task inputs for details on how to refer to a task's inputs.
https://api.sbgenomics.com/v2/tasks/{task_id}https://eu-api.sbgenomics.com/v2/tasks/{task_id}https://gcp-api.sbgenomics.com/v2/tasks/{task_id}See below for an example of the content of the request, sent here as modify-task.json.
Header Fields
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
required
The ID of the task you are querying
fields
string
Selector specifying a subset of fields to include in the response.
"name"
string
The name of the task
"description"
string
The description of the task
"inputs"
dictionary
See the section on specifying task inputs for information on creating input task objects.
"batch"
Boolean
This is set to false by default. Set to true to create a batch task and specify the batch_input and batch-by as described below.
"batch_input"
string
The ID of the input on which you wish to batch. You would typically batch on the input consisting of a list of files. If this parameter is omitted, the default batching criteria defined for the app will be used.
"batch_by"
dictionary
This specifies the criteria on which to batch. It can be in one of two formats.
If you wish to batch per item in the app's input (i.e., typically per file in a list of files) then specify a dictionary with the following format:
{ "type": "ITEM" }If you wish to batch by groups of inputs, you should specify the criteria satisfied by each group. This should be a common metadata value in one, or more, metadata fields.
To do this, specify a dictionary with the following format:
{
"type": "CRITERIA",
"criteria": [
"metadata.<field_1>", "metadata.<field_2>"
]
}
This will group inputs by shared metadata values for <field_1> and <field_2>, in that order. Arbitrarily many metadata fields may be listed, and the order in which fields are grouped will respect the order of the list.
There are two further things to note if you are editing a batch task:
If you want to change the input on which to batch and the batch criteria, you need to specify the
batch_inputandbatch_byparameters together in the samePATCHrequest.If you want to disable batching on a task, set
batchtofalse. Or, you can also set the parametersbatch_inputandbatch_bytonull.
{
"batch":false
}PATCH /v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --data-binary "@modify-task.json" -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X PATCH "https://cgc-api.sbgenomics.com/v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb"{ "description": "my draft task",
"name": "RFranklin, Experiment IV",
"app": "RFranklin/my-project/new-test-app",
"project": "RFranklin/my-project",
"inputs": {
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "example_human_known_indels.vcf"
}
}
}{
"href": "https://api.sbgenomics.com/v2/tasks/a8497170-fcc3-4605-8f1f-8346aa84306a",
"id": "a8497170-fcc3-4605-8f1f-8346aa84306a",
"name": "RFranklin, Experiment IV",
"description": "my draft task",
"status": "DRAFT",
"project": "RFranklin/my-project",
"use_interruptible_instances": true,
"app": "RFranklin/my-project/new-test-app/0",
"type": "v2",
"created_by": "RFranklin",
"start_time": "2016-01-12T19:20:10Z",
"inputs": {
"dispersion_threshold": null,
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "example_human_known_indels.vcf"
},
"density_threshold": null,
"thresholds_off": null
},
"outputs": {
"archive": null,
"html": null
}
}Get task execution details
Early release status
Note that this is a fully-functional early release feature. The call, and the format of the information returned is subject to change.
This call returns execution details of the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
The call breaks down the information into the task's distinct jobs. A job is a single subprocess carried out in a task.
The information returned by this call is broadly similar to that which can be found in the task stats and logs provided on the Platform.
https://api.sbgenomics.com/v2/tasks/{task_id}/execution_detailshttps://eu-api.sbgenomics.com/v2/tasks/{task_id}/execution_detailshttps://gcp-api.sbgenomics.com/v2/tasks/{task_id}/execution_detailsThe task execution details include the following information:
- The name of the command line job that executed
- The start time of the job
- End time of the job (if it completed)
- The status of the job (
DONE,FAILED, orRUNNING) - Information on the computational instance that the job was run on, including the provider ID, the type of instance used and the cloud service provider
- A link that can be used to download the standard error logs for the job
- SHA hash of the Docker image ('checksum')
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
required
The ID of the task you are querying
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/execution_details HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea9t6573259740f74
curl -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea9t6573259740f74" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/execution_details"{
"href": "https://api.sbgenomics.com/v2/tasks/48ed6043-d531-42be-afb1-d2d5bbae6ca3/execution_details",
"start_time": "2017-04-20T15:30:11Z",
"end_time": "2017-04-20T15:36:29Z",
"status": "COMPLETED",
"message": "Completed",
"jobs": [
{
"name": "FastQC_1_0_s",
"start_time": "2017-04-20T15:33:41Z",
"end_time": "2017-04-20T15:34:25Z",
"status": "COMPLETED",
"command_line": "fastqc --noextract --outdir . --quiet --threads 4 /sbgenomics/Projects/10e26e13-cf6a-4c44-8f58-b7352187b50e/hg00105.srr711354.fastq",
"instance": {
"id": "i-054205ac85c9debcf",
"type": "c4.2xlarge",
"provider": "AWS",
"disk": {
"size": 1024,
"unit": "GB",
"type": "amazon-gp2"
}
},
"logs": {
"cmd.log": "https://api.sbgenomics.com/v2/files/58f8d4d11c947a1eecc6d563/download_info",
"job.err.log": "https://api.sbgenomics.com/v2/files/58f8d4f41c947a1eecc6d56d/download_info",
"job.tree.log": "https://api.sbgenomics.com/v2/files/58f8d5001c947a1eecc6d58f/download_info",
"stderr": "https://api.sbgenomics.com/v2/files/58f8d4f41c947a1eecc6d56d/download_info"
},
"docker": {
"checksum": "sha256:642f70b2d64dffa562d4aea95aa0850a69ab8b09922b56b0b92e40a741cddd29"
}
},
{
"name": "SBG_Html2b64_1_0_s",
"start_time": "2017-04-20T15:35:54Z",
"end_time": "2017-04-20T15:36:27Z",
"status": "COMPLETED",
"command_line": "python /opt/sbg_html_to_b64.py --input /sbgenomics/Projects/10e26e13-cf6a-4c44-8f58-b7352187b50e/workspace/48ed6043-d531-42be-afb1-d2d5bbae6ca3/fastqc-analysis_FastQC_1_0_s/hg00105.srr711354_fastqc.zip",
"instance": {
"id": "i-054205ac85c9debcf",
"type": "c4.2xlarge",
"provider": "AWS",
"disk": {
"size": 1024,
"unit": "GB",
"type": "amazon-gp2"
}
},
"logs": {
"cmd.log": "https://api.sbgenomics.com/v2/files/58f8d55a1c947a1eecc6d5aa/download_info",
"job.err.log": "https://api.sbgenomics.com/v2/files/58f8d5781c947a1eecc6d5b4/download_info",
"job.tree.log": "https://api.sbgenomics.com/v2/files/58f8d57b1c947a1eecc6d5ce/download_info",
"stderr": "https://api.sbgenomics.com/v2/files/58f8d5781c947a1eecc6d5b4/download_info"
},
"docker": {
"checksum": "sha256:0a7b35a10596c43f6b2375e511692e09e6c3fbc3870c106b18bc4dac3bb21ea8"
}
}
]
}Run a task
This call runs (executes) the specified task. Only tasks whose status is "DRAFT" can be run.
https://api.sbgenomics.com/v2/tasks/{task_id}/actions/runhttps://eu-api.sbgenomics.com/v2/tasks/{task_id}/actions/runhttps://gcp-api.sbgenomics.com/v2/tasks/{task_id}/actions/runX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
The ID of the task you are acting on.
fields
string
Selector specifying a subset of fields to include in the response.
batch
boolean
Set this to false to disable the default batching for this task.
use_interruptible_instances
boolean
This field can be true or false.
Set this field to true to allow the use of spot instances.
POST /v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6/actions/run" 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 POST "https://api.sbgenomics.com/v2/tasks/b0bbeda6-153b-4801-92ad-82bc0e58bdb6/actions/run"{
"href": "https://api.sbgenomics.com/v2/tasks/234edb2d-a866-4828-a7c3-0aa757f991e7",
"id": "234edb2d-a866-4828-a7c3-0aa757f991e7",
"name": "new name for my task",
"description": "re-describing the task",
"status": "RUNNING",
"project": "RFranklin/my-project",
"use_interruptible_instances": false,
"app": "RFranklin/my-project/new/0",
"type": "v2",
"created_by": "RFranklin",
"executed_by": "RFranklin",
"start_time": "2016-01-12T18:39:30Z",
"execution_status": {
"message": "Initializing..."
},
"inputs": {
"dispersion_threshold": null,
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "example_human_known_indels.vcf"
},
"density_threshold": null,
"thresholds_off": null
},
"outputs": {
"archive": null,
"html": null
}
}Modify task inputs
This call enables you to modify the inputs provided to the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.
https://api.sbgenomics.com/v2/tasks/{task_id}/inputshttps://eu-api.sbgenomics.com/v2/tasks/{task_id}/inputshttps://gcp-api.sbgenomics.com/v2/tasks/{task_id}/inputsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
task_id
required
The ID of the task you are querying
fields
string
Selector specifying a subset of fields to include in the response.
Request body
In the body of the request, you should enter some or all of the key-value pairs contained in the input object for the task. For details about how to specify a task input, see the section on task inputs.
Example request body
{
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "new-file-name.vcf"
}
}GET /v2/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/inputs 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/tasks/08c5ce64-1551-4b7d-b054-63a1517bc7bb/inputs"{
"dispersion_threshold": null,
"cuffdiff_zip": {
"class": "File",
"path": "562785e6e4b00a1d67a8b1aa",
"name": "new-file-name.vcf"
},
"density_threshold": null,
"thresholds_off": null
}
List tasks in a project (secondary method)
This call lists the tasks in the specified project. It is an alias for the call to get tasks and redirects to that path.
https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/taskshttps://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/taskshttps://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/tasksAlias call
Note that since this is an alias for another call, the call cannot be made straightforwardly from all applications. In particular, to send the call using cURL, use the cURL option -L to redirect the path of this call to https://api.sbgenomics.com/v2/files?project={project_owner}/{project.
Alternatively, to list all files, you can simply use the call to get tasks.
Referring to your project
Note that project_owner is always case-sensitive, and that project is not the project's name but its ID, or short name. For full details of identifying objects using the API, please see the section on specifying objects.
X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
project
The short name of the project you are querying.
project_owner
The owner of the project you are querying.
fields
string
Selector specifying a subset of fields to include in the response.
GET /v2/projects/RFranklin/my-project/tasks HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -L "https://cgc-api.sbgenomics.com/v2/tasks?project=RFranklin/my-project" -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/tasks"{
"href": "https://api.sbgenomics.com/v2/tasks?offset=0&limit=25&project=RFranklin/my-project",
"items": [
{
"href": "https://api.sbgenomics.com/v2/tasks/39bc3e8c-6cf6-4f8f-b550-21e9633c1f4b",
"id": "39bc3e8c-6cf6-4f8f-b550-21e9633c1f4b",
"name": "test run - 12-11-15 11:02:03",
"project": "RFranklin/my-project"
},
{
"href": "https://api.sbgenomics.com/v2/tasks/db72b963-ba2e-4e9c-9d71-6eb71ed22226",
"id": "db72b963-ba2e-4e9c-9d71-6eb71ed22226",
"name": "test run - 12-11-15 11:52:45",
"project": "RFranklin/my-project"
}
],
"links": []
}
{
"href": "https://api.sbgenomics.com/v2/tasks/?offset=0&limit=25&project=RFranklin/my-project",
"items": [
{
"href": "https://api.sbgenomics.com/v2/tasks/39bc3e8c-6cf6-4f8f-b550-21e9633c1f4b",
"id": "39bc3e8c-6cf6-4f8f-b550-21e9633c1f4b",
"name": "test run - 12-11-15 11:02:03",
"project": "RFranklin/my-project"
},
{
"href": "https://api.sbgenomics.com/v2/tasks/db72b963-ba2e-4e9c-9d71-6eb71ed22226",
"id": "db72b963-ba2e-4e9c-9d71-6eb71ed22226",
"name": "test run - 12-11-15 11:52:45",
"project": "RFranklin/my-project"
}
],
"links": []
}Volumes
These API requests below allow you to mediate access between your cloud storage service provider and the Seven Bridges Platform.
Create a volume
List volumes
Get details of a volume
List the contents of a volume
Get details of a file within a volume
Update a volume
Deactivate a volume
Delete a volume
Start an import job
Get details of an import job
List import jobs
Start an export job
List export jobs
Get details of an export job
List members of a volume
Add members to a volume
Remove members from a volume
Get a volume member's permissions
Overwrite a volume members' permissions
Modify a volume members' permissions
Create a volume
This call creates a new volume. Volumes authorize the Platform to access and query objects on a specified cloud storage (Amazon Web Services or Google Cloud Storage) on your behalf.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage. These tutorials also detail how to configure your bucket.
https://api.sbgenomics.com/v2/storage/volumeshttps://eu-api.sbgenomics.com/v2/storage/volumeshttps://gcp-api.sbgenomics.com/v2/storage/volumesX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
Request body
In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.
name
required
String
The name of the volume. It must be unique from all other volumes for this user.
description
String
An optional description of this volume.
service
required
Object
This object should contain the information about the cloud service that this volume represents.
See the service object section below for an explanation of its structure.
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.
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 underlying cloud provider.
For Amazon Web Services, these credentials are:
For Google Cloud Storage, these credentials are:
String
AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.
String
AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.
String
The client email address for the Google Cloud service account to use for operations on this bucket. This can be found in the JSON containing your service account credentials.
properties
Object
Contains the properties of a specific service.
These values set the defaults for operations performed with this volume. Individual operations can override these defaults by providing a custom properties object.
sse_algorithm
applies to type: s3
String
S3 server-side encryption to use when exporting to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)
Supported values:
AES256(SSE-S3 encryption)aws:kms- null (no server-side encryption).
default: AES256
sse_aws_kms_key_id
String
Provide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS.
aws_canned_acl
applies to type: s3
S3 canned ACL to apply on the object during export.
Supported values:
- any one of S3 canned ACLs;
null(does not apply canned ACLs).
default: null
Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to list volumes.
POST /v2/storage/volumes HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/jsoncurl --data '@create-volume.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://api.sbgenomics.com/storage/volumes'{
"name": "my_s3_volume",
"service": {
"type": "s3",
"bucket": "input_files",
"prefix": "",
"credentials": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"properties": {
"sse_algorithm": "aws:kms",
"sse_aws_kms_key_id":"test_kms_key_id"
}
},
"access_mode": "RO"
}{
"name": "my_gcs_volume",
"description": "New google volume",
"service": {
"type": "gcs",
"bucket": "output_files",
"prefix": "output",
"credentials": {
"client_email": "user@service.iam.gserviceaccount.com",
"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEAsXj4E7svaB4szcOrAcraSbsGnNuTU1b/4llyspDa0lltZIKL\nfl5s3QoqbjUWqAZXkJexKus55g49ULD8BGKH2r4EF+XyKcpoon4uIFcbmYcmsUXM\nJ3ujgyL5DbWnQZ6GrqgFNRFVVz/PuvTZOd6KFCrjbbtCxfKoXQrmCwFC/4NlFR3v\n1kavU81w201Mied3e+pxjfiQKAJOoy5I7kfuH20xfzHXWR2YHdQGbzOUZyPgmzZ6\nH6Ry39b7bgLVbyk3++e13KrsTEf58rRzUHLzlcUDcGyf8iTO2vA2qzcbrbovwqJr\n7H4ZfFllDMYQ/ISj4cmi+sz/hR43LUK86emrXwIDAQABAoIBADBr2fvAMbINsZm+\njjTh/ObrAWXgvvSZIx3F2/Z+cUW9Ioyu1ZJ3/uncMTF6iKD1ggSwbqVQIq7zKaWP\ndGNZ4sk62PEQSx8924iiNsGaIqyj5FmvuoD3SeiorR0hd+3+a67RpwIQpaE1ht7y\nmSYh4riX7w9sbU6G44rnQ1azVG1UHvk5ieOD4OPvJopuc6D6ow1oJOnHE0k8v3HY\n1FpLdWCL6nSERqXOI5w+tllG4NMUmTZ2jhaBSEM4PIJVO+24TM3XFCcvhZ7ipPMF\nP5B8hV4hDA4Av1Ei7iuRZlJsH4sRrtHJE3/FZLgqHRRvt/7w4c1xnwirNghtTNMb\nXVoaS/ECgYEA15vL3l22mIoePlcCxIgVCAxhKm6TVQZsAE2EaeVsJKDl0AgCtn/1\nThMIPPGkO8jmjqHGgA+FhjoUQuCCdIuON00mUpmUxZlwI5+uknuK597/zAjd6W8s\n7p9apvBUDfod0hwF9Jfw+aUtZm6EAUNR1Odbb+bpXp1luwfcesHe4QcCgYEA0rg8\nZBBwh2DetU6wWh2JIejBH5SfRUqtEwo5WiEZhrEQLazcpX4w5uvESnT+xd7qx3yC\n/vyzqmy+YwP92Ql0vZApdQoyKGHVntY/o3HYxZD3x+7BKThUs747WjdSo8SwBkSr\nxEzLBgTqqcho6UXvYTTEAg11F5yNYzbvVf4vROkCgYEAh6XtTamIB9Bd1rrHcv5q\nvPWM7DVFXGj96fLbLAS7VRAlhgyEKG2417YBqNYejb6Hz5TYXhll2F0SAkFd0hU7\nFG/lfHJDt04hz0fXfTFc4yTZqnSpqQPZMQfw8LajK2gA+v/Gf2xYn7fcKGW/h0vj\nYB9u16hfirdcGZ+Ih3MR1mECgYEAnq1b1KJIirlYm8FYrVOGe4FxRF2/ngdA05Ck\nZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALJlQZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+CxZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MjZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALSi0sVSXpA=\n-----END RSA PRIVATE KEY-----"
}
},
"access_mode": "RW"
}{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my_volume",
"id": "rfranklin/my_volume",
"name": "my_volume",
"access_mode": "RO",
"service": {
"type": "S3",
"bucket": "sb-demo-markot-ro",
"prefix": "input-files",
"endpoint": "s3.amazonaws.com",
"credentials": {
"access_key_id": "AKIAI32ALEL3XDGMNQ2Q"
},
"properties": {
"sse_algorithm": "aws:kms",
"sse_aws_kms_key_id": "test_kms_key_id"
}
},
"created_on": "2017-07-21T08:23:39Z",
"modified_on": "2017-07-21T08:23:39Z",
"active": true
}List volumes
This call lists all the volumes you've registered.
See also get details of a volume for a detailed explanation of the fields in the response.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/volumeshttps://eu-api.sbgenomics.com/v2/storage/volumeshttps://gcp-api.sbgenomics.com/v2/storage/volumesX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
GET /v2/storage/volumes HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/jsoncurl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-Type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/volumes"{
"href": "https://api.sbgenomics.com/v2/storage/volumes?offset=0&limit=3",
"items": [
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/gcs_ro",
"id": "rfranklin/gcs_ro",
"name": "gcs_ro"
},
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/gcs_rw",
"id": "rfranklin/gcs_rw",
"name": "gcs_rw"
},
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my_s3_volume",
"id": "rfranklin/my_s3_volume",
"name": "my_s3_volume"
}
],
"links": []
}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://api.sbgenomics.com/v2/storage/volumes/{volume_id}https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}https://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
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.
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.
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 underlying cloud provider.
For Amazon Web Services, these credentials are:
For Google Cloud Storage, these credentials are:
String
AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.
String
AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.
properties
Object
Contains properties of specific service.
sse_algorithm
applies to type: s3
String
Use default AES256 server-side encryption when writing to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)
Can be:
- AES256 (default)
- null
default: AES256
GET /v2/storage/volumes/rfranklin/output HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/output"{code:javascript}
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/output",
"active": True,
"description": "task outputs bucket",
"id": "rfranklin/output",
"name": "output",
"access_mode": "RW",
"service": {
"type": "s3",
"bucket": "sbg-test-output",
"hostname": "s3.amazonaws.com",
"credentials" : {
"access_key_id": "AKIAJRC7TPMRMDKOFXGA"
}.
"prefix": "",
"sse_enabled": True
},
"created_on": "2016-06-29T11:13:10+02:00",
"updated_on": "2016-06-29T12:15:10+02:00"
}
{code}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).
https://api.sbgenomics.com/v2/storage/volumes/{volume_id}/listhttps://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}/listhttps://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}/listX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
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.
Interpreting the response body
href: Use the information contained in thehrefto make another request to obtain more details about a specific object within a volume.
GET /v2/storage/volumes/rfranklin/my-first-volume/list HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://api.sbgenomics.com/storage/volumes/rfranklin/my-first-volume/list"{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my-first-volume/list?prefix=list&limit=100",
"limit": "100",
"truncated": true,
"items": [
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my-first-volume/object?location=20.intervals",
"location": "20.intervals",
"volume": "megicivovic/Qa_test3",
"type": "s3"
},
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my-first-volume/object?location=dummy.fastq",
"location": "dummy.fastq",
"volume": "megicivovic/Qa_test3",
"type": "s3"
}
],
"prefixes": [
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/my-first-volume/list?prefix=list&limit=100",
"prefix": "list",
"volume": "rfranklin/my-first-volume"
}
]
}Get details of a file within a volume
This call lists the details of a file (object) in 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).
https://api.sbgenomics.com/v2/storage/volumes/{volume_id}/{object_id}https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}/{object_id}https://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}/{object_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
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.
Interpreting the response body
href: Use the information contained in thehrefto make another request to obtain more details about a specific object within a volume.
GET /v2/storage/volumes/rfranklin/my-first-volume/{object_id} HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://api.sbgenomics.com/storage/volumes/rfranklin/my-first-volume/{object_id}"{
"href": "https://gcp-api.sbgenomics.com/v2/storage/volumes/rfranklin/my-first-volume/object?location=20.intervals",
"location": "20.intervals",
"volume": "rfranklin/my-first-volume",
"type": "gcs",
"metadata": {
"bucket": "example-bucket",
"contentType": "binary/octet-stream",
"crc32c": "P1RVmQ==",
"etag": "CNjwxsvWvc0CEAE=",
"generation": 1466668676135000,
"id": "example-bucket/input-files/20.intervals/1466668676135000",
"kind": "storage#object",
"md5Hash": "0SgvLZ/y5a/TOHXpzkfX0A==",
"mediaLink": "https://www.googleapis.com/download/storage/*********",
"metageneration": 1,
"name": "input-files/20.intervals",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/o/input-files%2F20.intervals",
"size": 9,
"storageClass": "STANDARD",
"timeCreated": {
"value": 1466668676132,
"dateOnly": false,
"timeZoneShift": 0
},
"updated": {
"value": 1466668676132,
"dateOnly": false,
"timeZoneShift": 0
},
"timeStorageClassUpdated": "2016-06-23T07:57:56.132Z"
}
}Update a volume
This call updates the details of a specific volume.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/volumes/{volume_id}https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}https://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
volume_id
The volume that you want to update.
Request body
In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.
description
String
An optional description of this volume.
service
required
Object
This object should contain the information about the cloud service that this volume represents.
See the service object section for an explanation of its structure.
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 underlying cloud provider.
For Amazon Web Services, these credentials are:
For Google Cloud Storage, these credentials are:
String
AWS access key ID of the IAM user shared with Seven Bridges to access this bucket.
String
AWS secret access key of the IAM user shared with Seven Bridges to access this bucket.
properties
Object
Contains properties of specific service.
sse_algorithm
applies to type: s3
String
Use default AES256 server-side encryption when writing to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)
Can be:
- AES256 (default)
aws:kms- null
default: AES256
sse_aws_kms_key_id
applies to type: s3
String
Provide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS.
Response body
The response object contains information about the specified volume. The information is structured using the following key-value pairs:
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 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.
Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to list volumes.
PATCH /v2/storage/volumes/rfranklin/output HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75
Content-Type: application/jsoncurl --data '@patch-volume.json' -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-Type: application/json" -X PATCH "https://api.sbgenomics.com/storage/volumes/rfranklin/output"{
"description": null,
"service": {
"properties": {
"sse_algorithm": "AES256"
}
},
}
{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/output",
"id": "rfranklin/output",
"name": "output",
"access_mode": "RW",
"service": {
"type": "S3",
"bucket": "output_bucket",
"prefix": "outfiles",
"endpoint": "s3.amazonaws.com",
"credentials": {
"access_key_id": "AKIAJRC7TPMRMDKOFXGA"
},
"properties": {
"sse_algorithm": "AES256"
}
},
"created_on": "2016-06-30T08:14:02Z",
"modified_on": "2016-06-30T08:14:02Z",
"active": true
}Deactivate a volume
This call deactivates a volume. Note that this request is based off of the PATCH request to update a volume.
Once deactivated, you cannot import from, export to, or browse within a volume. As such, the content of the files imported from this volume will no longer be accessible on the Platform. However, you can update the volume and manage members. Note that you cannot deactivate the volume if you have running imports or exports unless you force the operation using the query parameter force=true, as described below.
Note that to delete a volume, first you must deactivate it and delete all files which have been imported from the volume to the Platform.
If you want to reactivate the volume at a later time, make this call again with the key "active" set to "true" in the request body.
https://api.sbgenomics.com/v2/storage/volumes/{volume_id}https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}https://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
volume_id
The volume that you want to update.
force
Set this to true to force-quit ongoing import or export operations on a volume you intend to deactivate
Request body
In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.
active
String
Set this to false to deactivate the volume. Note that if there are ongoing import or export operations on the volume, you must force-quit the operations using the query parameter force=true.
To reactivate a volume, set this back to true again.
Response body
The response object contains information about the specified volume. The information is structured using the following key-value pairs:
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.
created_on
String
The date and time this volume was created.
modified_on
String
The date and time this volume was last modified.
PATCH /v2/storage/volumes/rfranklin/output HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75
Content-Type: application/jsoncurl --data '@patch-volume.json' -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-Type: application/json" -X PATCH "https://api.sbgenomics.com/storage/volumes/rfranklin/output"{
"active": false
}{
"href": "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/output",
"id": "rfranklin/my-volume",
"name": "my-volume",
"access_mode": "RW",
"service": {
"type": "S3",
"bucket": "my_bucket",
"prefix": "input-files",
"endpoint": "s3.amazonaws.com",
"credentials": {
"access_key_id": "AKIAJRC7TPMRMDKOFXGA"
},
"properties": {
"sse_algorithm": "AES256"
}
},
"created_on": "2017-05-09T16:19:10Z",
"modified_on": "2017-05-24T09:27:41Z",
"active": false
}Delete a volume
This call deletes a volume you've created to refer to storage on Amazon Web Services or Google Cloud Storage.
Note that any files you've imported from your volume onto the Platform, known as an alias, will no longer be usable. If a new volume is created with the same volume_id as the deleted volume, aliases will point to files on the newly created volume instead (if those exist).
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/volumes/{volume_id}https://eu-api.sbgenomics.com/v2/storage/volumes/{volume_id}https://gcp-api.sbgenomics.com/v2/storage/volumes/{volume_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
volume_id
The ID of the volume to delete.
DELETE /v2/storage/volumes/rfranklin/output HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74curl -s -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "content-type: application/json" -X DELETE "https://api.sbgenomics.com/v2/storage/volumes/rfranklin/output"Start an import job
This call lets you queue a job to import a file from a volume into a project on the Platform. Essentially, you are importing a file from your cloud storage provider (Amazon Web Services or Google Cloud Storage) via the volume onto the Platform.
If successful, an alias will be created on the Platform. Aliases appear as files on the Platform and can be copied, executed, and modified as such. They refer back to the respective file on the given volume.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/importshttps://eu-api.sbgenomics.com/v2/storage/importshttps://gcp-api.sbgenomics.com/v2/storage/importsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
overwrite
Boolean
If this is set to True and a named file exists in the project where the alias is about to be created, the existing file will be deleted.
default: false
Request body
In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.
source
required
Object
This object should describe the source from which the file should be imported.
volume_id
required
String
Volume ID from which to import the file.
location
required
String
Volume-specific location pointing to the file to import. This location should be recognizable to the underlying cloud service as a valid key or path to the file.
Please note that if this volume was configured with a prefix parameter when it was created, the prefix will be prepended to location before attempting to locate the file on the volume.
destination
required
Object
This object should describe the Platform destination for the imported file.
project
required
String
The project in which to create the alias.
name
String
The name of the alias to create. This name should be unique to the project. If the name is already in use in the project, you should use the overwrite query parameter in this call to force any file with that name to be deleted before the alias is created.
If name is omitted, the alias name will default to the last segment of the complete location (including the prefix) on the volume. Segments are considered to be separated with forward slashes ('/').
overwrite
Boolean
Whether to overwrite the file if the file with the same name already exists in the destination.
{
"source":{
"volume":"rfranklin/input",
"location":"example_human_Illumina.pe_1.fastq"
},
"destination":{
"project":"rfranklin/my_project",
"name":"my_uploaded_example_human_Illumina.pe_1.fastq"
},
"overwrite": true
}{
"source":{
"volume":"rfranklin/tutorial_volume",
"location":"example_human_Illumina.pe_1.fastq"
},
"destination":{
"project":"rfranklin/my-project",
"name":"my_imported_example_human_Illumina.pe_1.fastq"
},
"overwrite": true
}Response body
The response object contains information about the specified volume. The information is structured using the following key-value pairs:
id
String
ID of this import job
state
String
The state of this import job. Possible values are:
PENDING: the import is queued;RUNNING: the import is running;COMPLETED: the import has completed successfully;FAILED: the import has failed.
source
Object
Import source, as passed when this job was started.
destination
Object
Import destination, as passed when this job was started.
error
Object
In case of error in the import job, standard API error is returned here.
POST /v2/storage/imports HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/jsoncurl --data '@import.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://api.sbgenomics.com/v2/storage/imports'{
"href": "https://api.sbgenomics.com/v2/storage/imports/SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN",
"id": "SbBlEwpfZll5jxgIBiqYfnJ5oBll6nXN",
"state": "PENDING",
"overwrite": true,
"source": {
"volume": "rfranklin/input",
"location": "example_human_Illumina.pe_1.fastq"
},
"destination": {
"project": "rfranklin/my_project",
"name": "my_uploaded_example_human_Illumina.pe_1.fastq"
}
}Get details of an import job
This call will return the details of an import job.
Note that when you import a file from your volume on your cloud storage provider (Amazon Web Services or Google Cloud Storage), you are creating an alias on the Platform which points to the file in your cloud storage bucket. Aliases appear as files on the Platform and can be copied, executed, and modified as such. They refer back to the respective file on the given volume.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/imports/{import_id}https://eu-api.sbgenomics.com/v2/storage/imports/{import_id}https://gcp-api.sbgenomics.com/v2/storage/imports/{import_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
import_id
The ID of the import job as returned by the call to start an import job.
Response body
The response object contains information about the status of the import job. The information is structured using the following key-value pairs:
id
String
ID of this import job
state
String
The state of this import job. Possible values are:
PENDING: the import is queued;RUNNING: the import is running;COMPLETED: the import has completed successfully;FAILED: the import has failed.
source
Object
Import source, as passed when this job was started by the call to start an import job.
destination
Object
Import destination, as passed when this job was started by the call to start an import job.
error
Object
In case of error in the import job, standard API error is returned here.
GET /v2/storage/imports/9G2EcQdEDNcfqTQN2NOGoy0pV0uHsDkR HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/jsoncurl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "Content-Type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/imports/9G2EcQdEDNcfqTQN2NOGoy0pV0uHsDkR"{
"href": "https://api.sbgenomics.com/v2/storage/imports/uWbndWHxUWBrgVE3YK9nAetAsJXxyM78",
"id": "uWbndWHxUWBrgVE3YK9nAetAsJXxyM78",
"state": "COMPLETED",
"overwrite": true,
"source": {
"volume": "rfranklin/input",
"location": "_1_27775714857613d176941a835574167_w640.jpg"
},
"destination": {
"project": "rfranklin/my_project",
"name": "imported.jpg"
},
"result": {
"href": "https://api.sbgenomics.com/v2/files/576a92eff5b481188f096b64",
"id": "576a92eff5b481188f096b64",
"name": "imported.jpg",
"size": 46102,
"project": "rfranklin/my_project",
"created_on": "2016-06-22T13:30:23Z",
"modified_on": "2016-06-22T13:30:24Z",
"storage": {
"type": "VOLUME",
"volume": "rfranklin/input",
"location": "_1_27775714857613d176941a835574167_w640.jpg"
},
"origin": {}
},
"started_on": "2016-06-22T13:30:23Z",
"finished_on": "2016-06-22T13:30:24Z"
}{
"href": "https://api.sbgenomics.com/v2/storage/imports/1KAWc6h1KEMMMa702FqdGJhp0PIm9AZ3",
"id": "1KAWc6h1KEMMMa702FqdGJhp0PIm9AZ3",
"state": "FAILED",
"overwrite": false,
"source": {
"volume": "rfranklin/input",
"location": "giphy.gif"
},
"destination": {
"project": "rfranklin/my_project",
"name": "giphy.gif"
},
"error": {
"status": 403,
"code": 9103,
"message": "Location on volume is not accessible as configured. See the documentation.",
"more_info": "http://docs.sevenbridges.com/docs/api-status-codes#9103"
},
"started_on": "2016-06-14T14:57:18Z",
"finished_on": "2016-06-14T14:57:19Z"
}List import jobs
This call lists import jobs initiated by particular user.
Note that when you import a file from your volume on your cloud storage provider (Amazon Web Services or Google Cloud Storage), you are creating an alias on the Platform which points to the file in your cloud storage bucket. Aliases appear as files on the Platform and can be copied, executed, and modified as such. They refer back to the respective file on the given volume.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/importshttps://eu-api.sbgenomics.com/v2/storage/importshttps://gcp-api.sbgenomics.com/v2/storage/importsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
GET /v2/storage/imports HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-type: application/jsoncurl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "Content-Type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/imports"{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports?offset=0&limit=25",
"items": [
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/1KAWc6h1KEMMMa702FqdGJhp0PIm9AZ3",
"id": "1KAWc6h1KEMMMa702FqdGJhp0PIm9AZ3",
"state": "FAILED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/CBp8fcTwdtIgFV4zPFcoWEmpBBd2A6h3",
"id": "CBp8fcTwdtIgFV4zPFcoWEmpBBd2A6h3",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/FLEc8t5AKZNPv0torLAb53geu4rRxfKG",
"id": "FLEc8t5AKZNPv0torLAb53geu4rRxfKG",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/GaymnitybdXPwmOSXpFOepLbI5rpiZ1i",
"id": "GaymnitybdXPwmOSXpFOepLbI5rpiZ1i",
"state": "FAILED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/RSQckISjroE1aEve1GnrRU0TWHNAFYrd",
"id": "RSQckISjroE1aEve1GnrRU0TWHNAFYrd",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/s1TL4S0tvtOtrljZ8srwB5Myk8eooU3r",
"id": "s1TL4S0tvtOtrljZ8srwB5Myk8eooU3r",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com.sbgenomics.com/v2/storage/imports/ZSdyIvvYtFKAa4YENGHYkEwHRewAgbX8",
"id": "ZSdyIvvYtFKAa4YENGHYkEwHRewAgbX8",
"state": "COMPLETED"
}
],
"links": []
} Start an export job
Advance Access
This request contains an Advance Access parameter, copy_only. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.
As we haven't fully integrated it in our main API branch, there might be slight changes to the paths or parameter names. If you are a software developer, think "beta access" but with fewer expected bugs.
We are confident, however, that the feature is ready for use by our customers and partners who are willing to slightly modify their scripts at a later date.
This call lets you queue a job to export a file from a project on the Platform into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the Platform. The volume you are exporting to must be configured for read-write access. To do this, set the access_mode parameter to RW when creating or modifying a volume.
Essentially, the call writes to your cloud storage bucket on Amazon Web Services or Google Cloud Storage via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the Platform and, if no more copies of this file exist, it will no longer count towards your total storage price on the Platform. In summary, once you export a file from the Platform to a volume, it is no longer part of the storage on the Platform and cannot be exported again.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/exportshttps://eu-api.sbgenomics.com/v2/storage/exportshttps://gcp-api.sbgenomics.com/v2/storage/exportsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
overwrite
Boolean
If true and a file exists in the given location on the volume (respecting volume prefix if given), the API will attempt to delete the existing file on the volume before exporting.
default: false
Query parameters - Advance Access
The following parameter is Advance Access. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.
copy_only
Boolean
If true, file will be copied to a volume but source file will remain on the Platform.
Request body
In the body, you should enter a list of key-value pairs. The keys, and the values they take, are described in the following table.
source
required
Object
This object should describe the source from which the file should be exported.
file
required
String
The ID of the file for export.
destination
required
Object
This object should describe the destination to which the file will be exported.
volume
required
String
The ID of the volume to which the file will be exported.
location
required
String
Volume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file.
Please note that if this volume has been configured with a prefix parameter, the value of prefix will be prepended to location before attempting to create the file on the volume.
properties
Object
Service-specific properties of the export.
These values override the defaults from the volume.
sse_algorithm
String
S3 server-side encryption to use when exporting to this bucket.
Supported values:
AES256(SSE-S3 encryption)- 'aws:kms`
- null (no server-side encryption).
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.
aws_canned_acl
String
S3 canned ACL to apply on the object on during export.
Supported values:
- any one of S3 canned ACLs;
null(do not apply canned ACLs).
default: null
Response body
The response object contains information about the status of the export job. The information is structured using the following key-value pairs:
id
String
ID of this export job
state
String
The state of this export job. Possible values are:
PENDING: the export is queuedRUNNING: the export is runningCOMPLETED: the export has completed successfullyFAILED: the export has failed
source
Object
Export source, as passed when this job was started.
destination
Object
Export destination, as passed when this job was started.
error
Object
In case of error in the export job, standard API error is returned here.
POST /v2/storage/exports HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/jsoncurl --data '@export.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://api.sbgenomics.com/v2/storage/exports'{
"destination":{
"volume":"rfranklin/output",
"location":"output.vcf"
},
"source":{
"file":"58bf04c81c94ccab8329da13"
},
"overwrite":false
}This request exports a copy of the file to your cloud storage bucket without deleting the source file from the Platform. Note that this version of the request uses the Advance Access copy_only parameter described above.
POST /v2/storage/exports?copy_only=true HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74{
"destination":{
"volume":"rfranklin/output",
"location":"output.vcf"
},
"source":{
"file":"58bf04c81c94ccab8329da13"
},
"overwrite":false
}{
"href": "https://api.sbgenomics.com/v2/storage/exports/2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
"id": "2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
"state": "PENDING",
"source": {
"file": "58bf04c81c94ccab8329da13"
},
"destination": {
"volume": "rfranklin/output",
"location": "output.vcf"
},
"started_on": "2016-06-15T19:17:39Z",
"properties": {
"sse_algorithm": "AES256"
},
"overwrite": false
}List export jobs
This call lists export jobs initiated by particular user.
Note that when you export a file from a project on the Platform into a volume, you write to your cloud storage bucket on Amazon Web Services or Google Cloud Storage.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/exportshttps://eu-api.sbgenomics.com/v2/storage/exportshttps://gcp-api.sbgenomics.com/v2/storage/exportsX-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
GET /v2/storage/exports HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-type: application/jsoncurl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "Content-Type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/exports"{
"href": "https://api.sbgenomics.com/v2/storage/exports?offset=0&limit=50",
"items": [
{
"href": "https://api.sbgenomics.com/v2/storage/exports/19K01S2JNGdsI8pSV1IeLoh2eM0A60hK",
"id": "19K01S2JNGdsI8pSV1IeLoh2eM0A60hK",
"state": "FAILED"
},
{
"href": "https://api.sbgenomics.com/v2/storage/exports/FudXgy8zXOg1UJUidCvzh7oIVRTK3LKY",
"id": "FudXgy8zXOg1UJUidCvzh7oIVRTK3LKY",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com/v2/storage/exports/gkfLPQaEuwAD1DnsO8bjWo0B8j0aJK4M",
"id": "gkfLPQaEuwAD1DnsO8bjWo0B8j0aJK4M",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com/v2/storage/exports/hcHlrTT3oyO3kitzSqJeGq7MImi0noMF",
"id": "hcHlrTT3oyO3kitzSqJeGq7MImi0noMF",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com/v2/storage/exports/z4ebtofuNMPRBZls6WC9pG7KlMgB5L0C",
"id": "z4ebtofuNMPRBZls6WC9pG7KlMgB5L0C",
"state": "COMPLETED"
},
{
"href": "https://api.sbgenomics.com/v2/storage/exports/ZltlOYd7CReLihnHse4YDQNqDrx92Xy0",
"id": "ZltlOYd7CReLihnHse4YDQNqDrx92Xy0",
"state": "FAILED"
}
],
"links": []
}Get details of an export job
This call will return the details of an export job.
When you export a file from a project on the Platform into a volume, you write to your cloud storage bucket on Amazon Web Services or Google Cloud Storage. This call obtains the details of that job.
Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.
https://api.sbgenomics.com/v2/storage/exports/{export_id}https://eu-api.sbgenomics.com/v2/storage/exports/{export_id}https://gcp-api.sbgenomics.com/v2/storage/exports/{export_id}X-SBG-Auth-Token
required
Your Seven Bridges Platform authentication token.
Content-type
required
application/json
export_id
The ID of the export job as returned by the call to start an export job.
Response body
The response object contains information about the status of the export job. The information is structured using the following key-value pairs:
id
String
ID of this export job
state
String
The state of this export job. Possible values are:
PENDING: the export is queued;RUNNING: the export is running;COMPLETED: the export has completed successfully;FAILED: the export has failed.
source
Object
Export source, as passed when this job was started by the call to start an export job .
file
String
ID of the file that was exported.
destination
Object
Export destination, as passed when this job was started by the call to start an export job.
volume
String
ID of the volume where to export.
`location
String
Location on the volume where the file should be exported.
started_on
String
Time when the export job was started.
finished_on
String
Time when the export job was finished.
properties
Object
Contains properties related to the export, including:
- "sse_algorithm" - algorithm used for S3 encryption
- "aws_storage_class" - storage class (STANDARD or GLACIER)
- "aws_canned_acl" - ACL which is set on the S3 bucket
overwrite
Boolean
Whether the file should be overwritten in the destination.
GET /v2/storage/exports/gW26LlICb9MmJkalaWEeI3HvJkbgvIh8 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-type: application/jsoncurl -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "Content-Type: application/json" -X GET "https://api.sbgenomics.com/v2/storage/exports/gW26LlICb9MmJkalaWEeI3HvJkbgvIh8"{
"href": "https://api.sbgenomics.com/v2/storage/exports/2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
"id": "2fzgXdc7zqeYFMiVvTCZdLBKgUpKdUhn",
"state": "COMPLETED",
"source": {
"file": "576159f7f5b4e1de6ae9b5f0"
},
"destination": {
"volume": "rfranklin/output",
"location": "output.vcf"
},
"started_on": "2016-06-15T19:17:39Z",
"finished_on": "2016-06-15T19:17:41Z",
"properties": {
"sse_algorithm": "AES256",
"aws_storage_class": "STANDARD",
"aws_canned_acl": "public-read"
},
"overwrite": false
} {
"href": "https://api.sbgenomics.com/v2/storage/exports/19K01S2JNGdsI8pSV1IeLoh2eM0A60hK",
"id": "19K01S2JNGdsI8pSV1IeLoh2eM0A60hK",
"state": "FAILED",
"error": {
"status": 409,
"code": 9107,
"message": "Location on volume already contains a file. Check the documentation.",
"more_info": "http://docs.sevenbridges.com/docs/api-status-codes#9107"
},
"source": {
"file": "57679b78f5b42122e7fde6a9"
},
"destination": {
"volume": "rfranklin/output",
"location": "_4_s3_file.jpg"
},
"started_on": "2016-06-22T13:38:57Z",
"finished_on": "2016-06-22T13:38:57Z",
"properties": {
"sse_algorithm": "AES256",
"sse_aws_kms_key_id": "6762ec77-01e3-42cc-ba3f-de371ec2359b",
"aws_canned_acl": "public-read"
},
"overwrite": false
}List members of a volume
This call returns the members 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).