The Seven Bridges Knowledge Center

The Seven Bridges Platform is a simple solution for doing bioinformatics at industrial scale. But sometimes, everyone needs a little help.

Get Started    What's new?
Suggest Edits

API Overview

 

The API uses the REST architectural style to read and write information about projects on the Seven Bridges Platform. The API can be used to integrate the Seven Bridges Platform with other applications, and to automate most procedures on it, such as uploading files, querying metadata, and executing analyses.

In addition, Seven Bridges provides both a Python library as well as an R library to allow your scripts to interact with the Platform via this API.

API paths

The paths are structured into the following endpoints, which cover different categories of activity on the Platform:

General API information

Format

API requests are made over HTTP, and information is received and sent in JSON format. For this reason, you should set both the accept and the content header of the request to application/json.

Responses also include Platform-specific error codes, in addition to standard HTTP codes. Information about each code is available on the page API status codes.

Generic query parameters

All API calls take the optional query parameter fields. This parameter enables you to specify the fields you want to be returned when listing resources (e.g. all your projects) or getting details of a specific resource (e.g. a given project).

The fields parameter can be used in the following ways:

  1. No fields parameter specified: calls return default fields. For calls that return complete details of a single resource, this is all their properties; for calls that list resources of a certain type, this is some default properties.
  2. The fields parameter can be set to a list of fields: for example, to return the fields id, name and size for files in a project, you may issue the call GET /v2/files?project=john_doe/project1&fields=id,name,size. The same goes for a call to get details of a specific file.
  3. The fields parameter can be used to exclude a specific file: if you wish to omit certain field from the response, do so using the fields parameter with the prefix !: for example, to get the details of a file without listing its metadata, issue a call GET /v2/files/564a31c1e4b0ef12181758b0?fields=!metadata. The entire metadata field will be removed from the response.
  4. The fields parameter can be used to include or omit certain nested fields, in the same way as listed in 2 and 3 above: for example, you can use metadata.sample_id or origin.task for files.
  5. To see all fields for a resource, specify fields=_all. This returns all fields for each resource returned. Note that if you are getting the details of a specific resource, the use of fields=_all won't return any more properties than would have been shown without this parameter – the use case is instead for when you are listing details of many resources. Please use with care if your resource has particularly large fields; for example, the raw field for an app resource contains the complete CWL specification of the app which can result in bulky response if listing many apps.
  6. Negations and nesting can be combined freely, so, for example, you can issue GET /v2/files?fields=id,name,status,!metadata.library,!origin or GET /v2/tasks?fields=!inputs,!outputs.

Identifying projects, users, apps, files, tasks and inputs

Project short names

Projects on the Seven Bridges Platform have both given names, which you will see in visual interfaces, like the Projects drop-down menu on the visual interface, and short names, which are human-readable IDs derived from the given names. To refer to a project in an API call, you should use its short name.

Project short names are based on the name you give to a project when you create it. The short name is derived from the project name by:

  • Formatting the name in lower case
  • Omitting special characters, that are not letters, numbers, spaces or underscores
  • Replacing spaces with hyphens
  • Replacing underscores with hyphens
  • Adding _1 to any name that is already assigned to one of your projects.

For example, if I name my project 'RFranklin's experiments', it would be automatically assigned the shortname 'rfranklins-experiments'.
You can optionally override an auto-assigned short names to one of your choice, when you create a project. However, once the project has been created, its short name will be immutable. To create your own project short name, first create a project, using the drop-down menu at the top of the screen. Then, click the pencil icon on the Create a project pop-out window.

To check a project's **short name**, or a task or file's ID, you can inspect the URL when you click on the object in the browser.

To check a project's short name, or a task or file's ID, you can inspect the URL when you click on the object in the browser.

Access Public Reference Files via the API

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.

Users

Seven Bridges Platform Users are referred to in the API by their usernames. These are chosen by the user at the point at which they sign up for the Platform. Usernames are unique and immutable. They are also case sensitive, so it is advisable to user lower case strings for your username to avoid ambiguity.

Uniqueness of project names

Every project is uniquely identified by {project_owner_username}/{shortname}.

Apps

Apps (tools and workflows) in projects can be accessed using the API. Like projects, apps have both given names, which are assigned by the users who create them, and short names An app's short name is derived by the same process as a project's short name.

Each app is identified with reference to the project it is contained in and its short name, using the format: {project_owner}/{project}/{app_short_name}/{revision_number}.

For instance, RFranklin/my-project/bamtools-merge-2-4-0/0 identifies an app.

Tasks

Tasks are referred to in the API calls by IDs. These are hexadecimal strings (UUIDs) assigned to tasks. You can retrieve them by making the API call to GET tasks.

Tasks have the following statuses: DRAFT, RUNNING, QUEUED, ABORTED, COMPLETED or FAILED.

Files

Files are referred to in API calls by IDs. These are hexadecimal strings assigned to files. You can retrieve them by making the API call to GET files.

Note that file IDs are dependent on the project the file is stored in. If you copy a file to a different project, it will have a new ID in this project.

In calls that return CWL descriptions of tasks, such as the call to GET task details, files are identified by their path objects. The file path is identical to the file ID.

Inputs

Task inputs are specified as dictionaries. They pair apps to be executed in the task with the objects that will be inputted to them.

The format for an input is:
{app_id}: {object}

The {app_id} is defined above. The value of {object} is obtained as follows:
If the object to be inputted to the task is not a file (but an integer, boolean, etc) then simply enter that value as {object}.
If the object to be inputted to the task is a file, then {object} is a dictionary, with the format:

{
   "class": "File",
   "path": "file_id",
   "name": "file_name.ext"
}

When multiple files are used as inputs, enter a list of {object}s, like this:

[
  {
  	 "class": "File",
 	  "path": "file_id",
 	  "name": "file_name.ext"
	}
	{
 	  "class": "File",
 	  "path": "file_id",
 	  "name": "file_name.ext"
	}
]

The following are all examples of inputs:

  1. An input integer:
"Offset": {2}
  1. An input file for the known indels:
{
        "cuffdiff_zip": {
            "class": "File",
            "path": "562785e6e4b00a1d67a8b1aa",
            "name": "example_human_known_indels.vcf"
        }
    }

3: File inputs for a Whole Exome Sequencing workflow, in the form of FASTQ reads:

"Reads_FASTQ": [
    {
      "class": "File",
      "path": "5602a18fe4b03d3ad9f1547b",
      "name": "WES_human_Illumina.pe_1.fastq"
    },
    {
      "class": "File",
      "path": "5602a18fe4b03d3ad9f15481",
      "name": "WES_human_Illumina.pe_2.fastq"
    }
  ]

Task inputs

For more examples of task inputs, use the call to GET task inputs for some of the tasks you initiate on the Seven Bridges Platform visual interface.

For finding which app receives which inputs and their format, you can review the app's page on the Seven Bridges Platform visual interface. For example Whole Exome Sequencing GATK 2.3.9.-lite

Authentication

To set your Platform credentials on the API, you will need an authentication token from the developer dashboard.

If you run the Platform on Amazon Web Services (AWS), click here to go to the developer dashboard.
If you run the Platform on the Google Cloud Platform (GCP), click here to go to the developer dashboard.

All API requests need to have the HTTP header X-SBG-Auth-Token which you should set to your authentication token. The only call which is exempt from this is the '/' call to list all request paths.

Rate limits

All API calls are rate-limited, which means that you can only perform a limited number of requests hourly. All rate limit information is returned to the user in the following HTTP headers:

  1. The header X-RateLimit-Limit represents the rate limit - currently this is 1000 requests per five minutes.
  2. The header X-RateLimit-Remaining represents your remaining number of calls before hitting the limit.
  3. The header X-RateLimit-Reset - represents the time in Unix timestamp when the limit will be reset

Response pagination

All API calls take the pagination query parameters limit and offset to control the number of items returned in a response. These are useful if you are returning information about a resource with many items, such as a list of many files in a project.

Filtering

In addition to controlling the number of items returned using the pagination query parameters, if you are requesting information about files using the call to GET files you can filter items returned by filename, metadata, or originating task.

Specify the number of items to return in a response

You can control how many items are returned by an API call using the query parameter limit. If you do not specify a value for limit in a call, a maximum of 50 items will be returned by the call by default.

The maximum value for the query parameter limit is 100.

Example 1:
Suppose you have 70 files in the project my-project, and you issue the call to GET files as follows:

GET /v2/files?project=my-project HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

Since no value for limit was specified, this call will return details of 50 of the files, along with a URL to return the next 20.

Example 2:
Again, suppose you have a project my-project with 70 files in it. The following call will return details of all 70 files"

GET /v2/files?project=my-project?limit=70 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

Specify the starting point for items to return in a response

You can control the starting point at which to start returning items in an API call using the query parameter offset. If you do not specify a value for offset then the default starting point will be the first item in the specified resource.

Example 1:
Suppose you have a project called my-project containing 70 files, and you want to return their details, starting with the 30th file. To do this, issue the call to GET /files with a query parameter offset specified as follows:

GET /v2/files?project=my-project?offset=30 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

Calls made with the offset query parameter additionally return the header X-Total-Matching-Query which signifies the total number of results.

Example 2:
An example of a call made using both pagination parameters is as follows:

GET v2/projects?limit=2&offset=2 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This returns the following body in JSON:

{
 "href": "https://api.sbgenomics.com/v2/projects/",
 "items": [
 {
 "href": "https://api.sbgenomics.com/v2/projects/john_doe/project1",
 "id": "john_doe/project1",
 "name": "project1"
 },
 {
 "href": "https://api.sbgenomics.com/v2/projects/john_doe/project2",
 "id": "john_doe/project2",
 "name": "Project 2"
 }
 ],
 "links": [
 {
 "href": "http://api.sbgenomics.com/v2/projects/?offset=4?limit=2",
 "rel": "next",
 "method": "GET"
 }
 ]
}

The headers returned include X-Total-Matching-Query which lists the total number of results.
The body of the response includes the array links, which indicate how to get the next or previous set of results.

Suggest Edits

API tutorials

 
Suggest Edits

Introduction to the API tutorial

 

Who is this for?

You'll find this tutorial especially helpful if you have only used the visual interface of the Seven Bridges Platform but would like to explore beyond the limits of the visual interface.

You've signed up for the Seven Bridges Platform. Now what? You start by accessing the visual interface of the Platform. You find the visual interface adequate for most of your needs. Then, you're tasked with a time-intensive task—such as uploading or copying hundreds or thousands of files—and you wonder, is there a way to automate this?

This feature depends on your cloud infrastructure provider: Platform API paths differ for cloud infrastructures

To use this feature, you should know which cloud infrastructure provider you run the Seven Bridges Platform on: Amazon Web Services in the US (AWS US East); Amazon Web Services in Frankfurt, Germany (AWS EU) or Google Cloud Platform.

If you didn't choose a cloud provider when you signed up for the Platform, you will be using AWS US East.

If you signed up from early 2016, you will have had the option to select your cloud provider from AWS and Google Cloud Platform. If you signed up from early 2017, you will have had the additional option to select AWS EU as your cloud provider.

You can find the paths of each API request for all the Platform's infrastructure options in the API documentation. The paths are shown in tabbed code boxes: click the tab corresponding to your infrastructure option to see your path.

Yes, via the API (Application Programming Interface).

This tutorial contains sequential directions, so we recommend that you read everything in order.

However, if you're ready to work with the API on your own, you can visit our API Overview page.

What's covered in this tutorial?

We'll be covering two topics in this tutorial. First, we'll provide background information on what an API is and how to use it. Second, we will walk you through a making a simple API call to list all of the projects associated with your Seven Bridges Platform account by using Postman.

We've structured this tutorial so that the information and walkthrough portions are staggered. That is, after most information sections is a walkthrough portion, Try this. We've highlighted the titles of the walkthrough portions in red to make them stand out.

Overview of APIs

The Application Programming Interface (API) is a means to interact with our server and its data. An API is a programmatic interface for accessing and manipulating resources: just as the Platform's visual interface allows you to create projects, run tasks, and manage project members by clicking buttons and entering data to web forms, the Application Programming interface allows these procedures to be carried out programatically. This means that a computer program can now create projects, run tasks, manage project members, and so on. It does this by issuing requests to, and returning data from, the servers.

You can interact with the API using various clients, such as an API client like Postman, a programming language like Python, or through your terminal by using a command line program like cURL. These clients use the API to access the data. Then, the client displays the data pulled by the API to the user.

For instance, if you use Postman as your client, Postman will use the API to pull data. Then, Postman will display the data to the user.

We'll learn more about how to use Postman with the Seven Bridges API below.

The Seven Bridges API

The Seven Bridges API can be used to integrate the Platform with other applications, and to automate most procedures on it, such as uploading files, querying metadata, and executing analyses. The API uses the Representational State Transfer (REST) architectural style to read and write information about projects on the Seven Bridges Platform. This means calls are made using HTTP.

You're probably familiar with HTTP as the part of a web page's URL. In fact, HTTP is the foundation behind data communication on the World Wide Web—it's a protocol for fetching data from web servers and allows applications to talk to one another on the web. So, when you enter the "http" in the beginning of an URL into a web browser, you're telling the browser to talk to the server and that the following commands (the rest of the URL) uses HTTP protocol.
When you use a client to talk to the API, you'll be using HTTP.

How do clients talk to the API?

Clients use the API to make a request of the server. Then, the server returns a response via the API to the client. Depending on the type of request, the response is either the requested data or a confirmation that the requested action was performed.

Try this: Use Postman to talk to the API

While you can use various clients to interact with the Seven Bridges API, we recommend using Postman to learn how the API works and how easy it is to use our powerful API. Postman, a free API-request client, has a visual interface you can use to type out your HTTP requests. It also returns the response in the same visually-pleasing format of the examples in our API documentation.

Using the API

Postman is a great tool for users to learn how the API works as well as for developers to test the API. However, to take full advantage of the automation which makes the Seven Bridges API so powerful, we recommend using R, Bash, or Python.

Once you're familiar with the API, you can also consult our Python library and our R library. We also host various recipes and tutorials in the okAPI repository.

Before we go into the specifics of an API request, let's install Postman.

System requirements

Postman requires Chrome or OS X to run.

To get started:

  1. Go to https://www.getpostman.com/.
  2. Then, choose between Postman for Chrome or Postman as a Mac App and follow the installation instructions.
  3. Once your download has finished, launch Postman, as shown below.

You can use various clients to talk to the Seven Bridges API. This tutorial provides examples and directions specific to using Postman, but you can also take away major points and apply them to other clients.

Parts of an API request

Time to talk to the API! But how?

You need to use Postman to use the API to make a request of the server. Then, the server returns a response via the API to Postman. Let's first walk through the different parts of an API request. We'll return to responses below.

In basic terms, an API request consists of four parts:

You need these parts to make the request work properly. Generally, you need all four parts. However, certain types of requests, such as GET requests do not have a body. We'll learn more about this in the section on methods below.

We'll learn about query parameters, an optional fifth part of an API request, in the section on modifying your API request below.

The path

The path specifies the object for the request. Basically, the path is a URI which points to a unique resource on the Platform that will be the recipient of the request. For example, the path https://api.sbgenomics.com/v2/projects specifies projects on the Platform as the object of the request.

URI versus URL

A URI (Uniform Resource Identifier) identifies a physical or abstract resource. It can be a name or locator, or both.

In fact, it's related to a more familiar concept: the URL. A URL (Uniform Resource Locator) is a kind of URI which identify the location of a resource. For instance, a URL can actually locate the resource by describing its network location.

We've cultivated a list of API requests in the API documentation on our Knowledge Center, as shown below. You can click on API Reference in the left sidebar to see all the requests you can make.

On each of these pages, you'll see the path at the top of the page, as shown below.

Here, there are two tabs you can select: Path for Amazon Web Services users and Path for Google Cloud Platform users. Select the option for the Platform you use.

Seven Bridges Platform deployments

The Seven Bridges Platform was originally deployed on Amazon Web Services (AWS). On January 15, 2016, the Platform was deployed on Google's cloud infrastructure, the Google Cloud Platform (GCP).

To determine which cloud provider you're using, look at the URL you use to access the visual interface. If the url is https://igor.sbgenomics.com, you are using the Platform on AWS. If the URL is https://gcp.sbgenomics.com/, you are using the Platform on GCP.

To learn more about the differences between AWS and GCP for Platform users, read our blog post.

In the screenshot above, you can see the path you should use on the Google Cloud Platform, https://gcp-api.sbgenomics.com/v2/projects.

Below, you can see the path for Amazon Web Services for the same request.

As you can see, the path you should use on Amazon Web Services is https://api.sbgenomics.com/v2/projects.

Try this: Enter the Path in Postman

Once you've located the path, paste it into the Enter request URL box on Postman, as shown below. For this tutorial, we'll be making a request for projects. Specifically, to get a list of all projects of which you are a member.

Now you've specified the path. Next, we'll set the method.

The method

The method specifies the type of request. It describes the type of action that you want to take via the API.

Possible methods for the Seven Bridges API are:

We've used colored buttons next to the API title in the sidebar and the documentation page to highlight the method, as shown below.

Try this: Enter the method in Postman

Since we want to use Postman to ask the API to list all of the projects you are a member of, this is a request for information. So it's a GET request.

As you can see above, the method is also shown next to the page title, List all your projects.
To enter the method, click the GET button next to the path. This will pull up a drop-down menu, as below. Make sure GET is selected.

Now you've selected the method. Next, we will specify the headers.

Headers

Headers specify the metadata for an API request. They provide required operating parameters for the API request.

In the picture below, you'll see some of the headers for Seven Bridges API requests.

The required headers for each API call are listed in two places, as detailed below. Be sure to include all required headers for your API request to work.

  1. Required headers for all API calls are listed in the API Overview. These include:
Key
Value

Content-type

application/json

Accept

application/json

  1. Required headers for individual requests are listed in the relevant documentation page under the Request section, as shown below.

Almost all API requests will require your Seven Bridges authentication token. This acts as a security measure regulating your access to your projects. Learn more about obtaining your authentication token.

Try this: Enter headers in Postman


First, locate the required headers in our
API documentation. Then, click on the Headers tab in Postman, and input the headers.

For the API request to list all your projects, you need the following headers:

  • X-SBG-Auth-Token - enter your authentication token
  • Content-type - enter application/json
  • Accept - enter application/json

Enter them into the Headers tab, as shown below.

Now, you're ready to enter the body of the request.

The body

This specifies the data you wish to send to the Platform. In the case of a GET request, where you're obtaining information, there would be no body. However, when you send data to the Platform via a POST, PUT, or PATCH request, you will need to provide the data in the body of the request.
In our API documentation, we've provided the required keys and values for each request body, as shown below for the create a new project request.

For each API request with a body, we've also provided an example request body in the documentation, as shown below.

Try this: Enter a request body in Postman

The API call to list all your projects is a GET request. This means the request doesn't have a body because you are asking for information from the Platform rather than sending data to the Platform.

Try this: Send your request

Now that your request is fully prepared, you can send your request in Postman by clicking the blue SEND button in the upper right hand corner, as shown below.

The API responds to you

Now that you've successfully sent your request to list all of your projects, Postman will display a response to your request, as shown below.

As you requested, you can see a list of all the projects of which you are a member. Your GET request returns the "href" (path) of each project, the "id" (project owner and short name of the project), and the "name" (project's name, as displayed on the visual interface).

If you run into an error, you'll receive a 4 digit error code and information specific to the Platform in the body of the response.

Congratulations! You've successfully completed an API request to list your projects. At this point, you can continue to our API documentation to test out other requests. Or, you can continue on this page to find out how to further customize your API requests.

Optional: Query parameters

Each Seven Bridges API request can take one or more optional query parameters which further filter your request. For instance, the fields parameter is accepted by all requests. With the fields parameter, you can specify that only certain fields are returned in the response body, such as id or name.

The API documentation includes details on accepted parameters for each request, as shown below for the request to list all your projects.

Try this: Enter optional parameters in Postman

Let's return to our request to list all of your projects and try to add the fields parameter to our request in Postman. We want the API request to only return the path (href) of the projects.

Input the path, method, and headers as you did above.

You can add query parameters by typing ? followed by the name for the parameter (ex: fields) followed by = and a value (ex: href). In the example below, we've appended ?fields=href to the end of the path https://api.sbgenomics.com/v2/projects.

Click Send when you've finished modifying your API request.

As you can see below, the response returned by your modified request only contains the paths for each project.

And, that's it! You've not only completed a successful API request, but you've also modified it by specifying optional query parameters.

Next step

In this tutorial, we used Postman to learn how the API works. However, to take full advantage of the automation which makes the Seven Bridges API so powerful, we recommend using R, Bash, or Python.

For more information, you can also consult okAPI, our repository of API recipes, or the Seven Bridges Python bindings library, which provides a set of Python terms for interacting with the Seven Bridges API.



In a nutshell...

In this tutorial, you learned:

  • An API is a way to interact with our servers and its data.
  • The four parts of an API request (the path, the method, the headers, and the body)
  • How to modify an API request with query parameters

Suggest Edits

API Quickstart

 

Overview

To introduce you to capabilities of the Seven Bridges API, this QuickStart walks you through the process of a Whole Exome Sequencing Analysis. This tutorial is ideal for familiarizing yourself with the various Seven Bridges API requests.

If you wish to learn the basics behind APIs, please see our Introduction to the API tutorial.

Alternatively, to make use of the Seven Bridges' Python API library, you can consult our Jupyter notebook Quickstart tutorial.

Prerequisites

You will need an account on the Seven Bridges Platform in order to obtain your authentication token. Almost all API requests require your Seven Bridges authentication token. This acts as a security measure regulating your access to your projects. Learn more about obtaining your authentication token.

Procedure

We'll start by creating a project and populating it with files. Then, we'll use one of the Seven Bridges Whole Exome Sequencing workflows, Whole Exome Sequencing GATK 2.3.9.-lite, to carry out the analysis. Finally, we'll examine our results.

All necessary tools and data will be available on the Platform.

Note that the HTTP requests on this page use the base API path for Amazon Web Services (AWS) deployment of the Platform, https://api.sbgenomics.com/v2. If you are running the Platform on the Google Cloud Platform, simply replace the base path with https://gcp-api.sbgenomics.com/v2

Find your billing group

To start an analysis, we must first create a project. To do this, we need to obtain following information:

Your authentication token acts as a security measure so only you can access your projects and resources on the Platform. The billing group ID designates which funding resource to charge for the analyses you run in the project you're about to create. Learn more about billing groups on the Platform.

Keep in mind, when you signed up for the Seven Bridges Platform, your account was automatically credited with $100 in free funds (your Pilot Funds) to use for data analyses. We will use this billing group in this tutorial.

Use the API request to list your billing groups, as shown in the HTTP request below. Be sure to insert your authentication token for X-SBG-Auth-Token.

GET /v2/billing/groups HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This request returns a list of the billing groups you are part of, as shown below:

{
  "href": "https://api.sbgenomics.com/v2/billing/groups/",
  "items":
    {
      "id": "70c12809-9ef2-485c-9d77-dfb8c9618fd6",
      "href": "https://api.sbgenomics.com/v2/billing/groups/70c12809-9ef2-485c-9d77-dfb8c9618fd6",
      "name": "Pilot Funds (rfranklin)"
    },
  "links": []
}

Copy the value for id (in this case 70c12809-9ef2-485c-9d77-dfb8c9618fd6) to your clipboard. We will use this in the next step when creating a project.

Create a project

Projects are the core building blocks of the Platform. Each project corresponds to a distinct scientific investigation, serving as a container for its data, analysis tools, results, and team of collaborators.

To create a project, make the API request to create a new project, as shown in the HTTP request shown below. Be sure to paste in your authentication token for the X-SBG-Auth-Token key.

This request also requires a request body. Provide a name for your project and an optional description. Here, you should also paste in the billing_group id you obtained in the previous step.

POST /v2/projects HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
content-type: application/json
{
    "name":"API Quickstart project",
    "description":"project for the API",
    "billing_group":"70c12809-9ef2-485c-9d77-dfb8c9618fd6"
}

You'll see a response body, as shown below, containing the name of your project, its URL (href), your project id, and your project's billing_group.

Note down the project id. We will use this throughout the tutorial to designate our project. The project id consists of two parts: your username followed by your project's short name.

{
  "href": "https://api.sbgenomics.com/v2/projects/rfranklin/api-quickstart-project",
  "id": "rfranklin/api-quickstart-project",
  "name": "API Quickstart project",
  "type": "v2",
  "description": "project for the API",
  "tags": [],
  "billing_group": "70c12809-9ef2-485c-9d77-dfb8c9618fd6"
}

Now that you've successfully created a project, we can add data to the project for analysis.

Add files to your project

In this tutorial, we'll analyze publicly available data that is hosted in the Public Reference Files repository on the Seven Bridges Platform. This repository contains reference files, datasets, and other frequently-used genomic data that you might find useful.

For this analysis, we want to use two paired-end files that contain Whole Exome Sequencing data.

Find your files

To find these files, we will make the API request to list all files in a project, as shown below.

We'll need to pass along two query parameters to locate the files. First, we have to specify the project containing the files. In this case, 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. Following the path, you can pass this query parameter using project=admin/sbg-public-data.

Then, we want to filter the results by metadata. Learn more about the API keys for metadata fields on the Platform. In this instance, we want to find two files produced by an experimental strategy of Whole Exome Sequencing. We can append this query parameter to our previous parameter using an & followed by metadata.experimental_strategy=WXS.

The entire HTTP request is shown below:

GET /v2/files?project=admin/sbg-public-data&metadata.experimental_strategy=WXS
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

In the response returned, you will see a list of files along with their id, name, and the project to which they belong, as shown below.

For this tutorial, let's choose the two paired end files, C835.HCC1143.2.converted.pe_1.fastq and C835.HCC1143.2.converted.pe_2.fastq. Copy the id for each file to your clipboard. We will use this in the next step when copying the files.

{
  "href": "https://api.sbgenomics.com/v2/files?metadata.experimental_strategy=WXS&offset=0&limit=18&project=admin/sbg-public-data",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6fb507c17526744870d",
      "id": "5772b6fb507c17526744870d",
      "name": "merged-normal.bam",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6e8507c1752674486f5",
      "id": "5772b6e8507c1752674486f5",
      "name": "C835.HCC1143_BL.4.converted.pe_1.fastq",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6e8507c1752674486f6",
      "id": "5772b6e8507c1752674486f6",
      "name": "C835.HCC1143_BL.4.converted.pe_2.fastq",
      "project": "admin/sbg-public-data"
    },
    <snip>
  ],
  "links": []
}

For brevity, we have omitted part some of the returned files.

Once we've obtained the file ids (5772b6e8507c1752674486f5 and 5772b6e8507c1752674486f6), we can copy these files into our project.

Copy files to a project

To copy files into a project, make the API request to batch copy files, as shown below.

In the body of the request, you can specify the target project for the copied files. In this tutorial, we want to copy the files to the project we created above, whose project id consists of your username followed by the project's short name. In the example request below, we've input the project id rfranklin/api-quickstart-project as the relevant value for the project key.

We also want to pass along the file ids you obtained in the step above in the body of the request. We can input the ids as a list of values for the file_ids key, as shown below.

POST /v2/action/files/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/api-quickstart-project",
    "file_ids": ["5772b6e8507c1752674486f5","5772b6e8507c1752674486f6"]
}

The response body, as shown below, will indicate if your request was successful. The response contains the original ids of your copied files and its status.

The response body also contains two other fields: new_file_id and new_file_name. These indicate the new id and the new name assigned to the copy of the file within your project. You can use this id in future API requests to refer to the copy of the file within your project as opposed to the original file.

{
  "5772b6e8507c1752674486f5": {
    "status": "OK",
    "new_file_id": "57a47767e4b08370afe7e21f",
    "new_file_name": "C835.HCC1143_BL.4.converted.pe_1.fastq"
  },
  "5772b6e8507c1752674486f6": {
    "status": "OK",
    "new_file_id": "57a47767e4b08370afe7e221",
    "new_file_name": "C835.HCC1143_BL.4.converted.pe_2.fastq"
  }
}

The files have been successfully copied to your project. However, before we can use the files in an analysis, we should annotate them with metadata.

Modify file metadata

Metadata makes files easier to manage. File metadata includes information about the File (e.g. experimental strategy and library ID), Sample (e.g. sample ID), and General (e.g. investigation and species) . For more information on the metadata fields used on the Platform, please see the documentation on file metadata. On this page, you can also obtain the keys used to identify metadata in API requests.

We will set the platform_unit_id metadata field to 1 in this tutorial. This metadata will inform tools that these files come from the same sample, were produced by the same library, and have been sequenced on the same lane.

To change a file's metadata, make the API request to modify a file's metadata, as shown below. Note that we can only modify one file's metadata at a time. You can pass the file id in the path of the request in the format of https://api.sbgenomics.com/v2/files/{file_id}/metadata. Be sure you use the new_file_id from the step above. This ensures you modify the metadata for the file in your project.

We'll enter the metadata field you wish to modify in the body of the request.

PATCH /v2/files/57a47767e4b08370afe7e21f/metadata HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
 "platform_unit_id":"1"  
}

In the response body, you'll see the file's metadata. The metadata field we just changed, platform_unit_id is listed as a metadata field in the response.

{
  "platform_unit_id": "1",
  "reference_genome": "HG19_Broad_variant",
  "species": "Homo sapiens",
  "sample_id": "HCC1143BL",
  "case_id": "CCLE-HCC1143BL",
  "investigation": "CCLE-BRCA",
  "paired_end": "1",
  "sample_type": "EBV Immortalized Normal",
  "experimental_strategy": "WXS",
  "platform": "Illumina"
}

Now that we've modified the metadata for the first file we copied, we need to repeat this process for the second file.

Adding metadata for multiple files

While this process is manageable for a smaller number of files, it grows cumbersome if you are processing numerous files. In this case, you can use a programming language like Python, R, or bash to write a for loop around this process.

Our API Quickstart tutorial using the sevenbridges-python library introduces this method.

Next, we will add reference files to our project.

Add reference files to your project

Many bioinformatics tools require certain data, such as reference genomes or annotation files, to execute properly. The Whole Exome Sequencing GATK 2.3.9.-lite workflow uses a reference genome and annotation files (known indels and snps) to map Exome-seq reads. We'll need to have these reference files in our QuickStart project to be able to use them while setting up our task.
For this analysis, we need to supply the workflow with the following six reference files:

  • dbsnp_137.b37.vcf
  • 1000G_phase1.indels.b37.vcf
  • Mills_and_1000G_gold_standard.indels.b37.sites.vcf
  • exome_targets.b37.bed
  • snpEff_v3_6_GRCh37.75.zip
  • human_g1k_v37_decoy.fasta

See the table below for more information about each file.

API key
Input files
File type

Known_SNPs

dbsnp_137.b37.vcf

VCF files contain databases of the known genetic variants - SNPs and indels.

Known_Indels

Mills_and_1000G_gold_standard.indels.b37.sites.vcf

1000G_phase1.indels.b37.vcf

VCF files contain databases of the known genetic variants - SNPs and indels.

Target_BED

exome_targets.b37.bed

BED files contain all target regions which are relevant for our analysis - in this case exomes. It points to the relevant locations of the FASTA file we are using for the analysis.

database

snpEff_v3_6_GRCh37.75.zip

ZIP file (snpEff) is a specific build of the snpEff database which contains annotations of the genetic variants and their supposed effects.

input_tar_with_reference

human_g1k_v37_decoy.fasta

FASTA file is a reference genome which we will use for the alignment of the FASTQ files.

Find reference files

To find these files, we will make the API request to list all files in a project, as shown below.

This process is similar to finding the data files above: in this query, we'll need pass along the query parameter to designate the Public Reference Files repository,
project=admin/sbg-public-data.

Then, we want to filter the results by the name query parameter. We can append this query parameter to our previous parameter using an & followed by the name of the file, such as dbsnp_137.b37.vcf.

You can search for multiple files by their names with the same API request by including the field name multiple times. 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.

The entire HTTP request is shown below:

GET /v2/files?project=admin/sbg-public-data&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf&name=exome_targets.b37.bed&name=snpEff_v3_6_GRCh37.75.zip&name=human_g1k_v37_decoy.fasta HTTP/1.1 
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

In the response, you will see information about each file as well as the file's id. Copy each id (for example, 5772b6cd507c1752674486d8) to your clipboard. We will use these ids in the next step.

{
  "href": "https://api.sbgenomics.com/v2/files?offset=0&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf&name=exome_targets.b37.bed&name=snpEff_v3_6_GRCh37.75.zip &name=human_g1k_v37_decoy.fasta&limit=6&project=admin/sbg-public-data",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6cd507c1752674486d8",
      "id": "5772b6cd507c1752674486d8",
      "name": "dbsnp_137.b37.vcf",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6d8507c1752674486e6",
      "id": "5772b6d8507c1752674486e6",
      "name": "human_g1k_v37_decoy.fasta",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/578cf949507c17681a3117dc",
      "id": "578cf949507c17681a3117dc",
      "name": "exome_targets.b37.bed",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/578cf947507c17681a3117ce",
      "id": "578cf947507c17681a3117ce",
      "name": "1000G_phase1.indels.b37.vcf",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6c9507c1752674486d4",
      "id": "5772b6c9507c1752674486d4",
      "name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6df507c1752674486ed",
      "id": "5772b6df507c1752674486ed",
      "name": "snpEff_v3_6_GRCh37.75.zip",
      "project": "admin/sbg-public-data"
    }
  ],
  "links": []
}

Pro-tip

To display only the id and name fields in the response, you can specify fields as a query parameter by using fields=id,name.

Copy reference files to your project

To copy files into a project, make the API request to batch copy files, as shown below. This is the same method we used to copy our data files into our project.
In the body of the request, you can specify the target project for the copied files, such as rfranklin/api-quickstart-project, as a value for the project key.

We also want to pass along the file ids you obtained in the step above in the body of the request. We can input the ids as a list of values for the file_ids key, as shown below.

POST /v2/action/files/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/api-quickstart-project",
    "file_ids": [
        "5772b6cd507c1752674486d8",
        "578cf947507c17681a3117ce",
        "5772b6c9507c1752674486d4",
        "578cf949507c17681a3117dc",
        "5772b6df507c1752674486ed",
        "5772b6d8507c1752674486e6",
        "5772b6df507c1752674486ed"
    ]
}

The response body contains the new_file_id for each of the copied reference files. These indicate the new id assigned to the copy of the file within your project. You can use this id in future API requests to refer to the copy of the file within your project as opposed to the original file.

{
  "5772b6df507c1752674486ed": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e541",
    "new_file_name": "snpEff_v3_6_GRCh37.75.zip"
  },
  "5772b6cd507c1752674486d8": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e539",
    "new_file_name": "dbsnp_137.b37.vcf"
  },
  "5772b6d8507c1752674486e6": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e543",
    "new_file_name": "human_g1k_v37_decoy.fasta"
  },
  "578cf949507c17681a3117dc": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e53f",
    "new_file_name": "exome_targets.b37.bed"
  },
  "578cf947507c17681a3117ce": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e53b",
    "new_file_name": "1000G_phase1.indels.b37.vcf"
  },
  "5772b6c9507c1752674486d4": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e53d",
    "new_file_name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
  },
  "5772b6df507c1752674486ed": {
    "status": "OK",
    "new_file_id": "57a4b564e4b08370afe7e541",
    "new_file_name": "snpEff_v3_6_GRCh37.75.zip"
  }
}

We have populated our project with the requisite data and reference files. Now, we can add a workflow to our project.

Add a public workflow to your project

We'll use the workflow, Whole Exome Sequencing GATK 2.3.9.-lite, which is based on the free version of the GATK tool developed by the Broad Institute.

This workflow is one of Seven Bridges' many open source workflows available to all users on the Platform. These workflows have been tested to run efficiently in the cloud environment by the Seven Bridges bioinformatics team.

Find a public workflow

To find a public workflow on the Platform, make the API request to list all apps (i.e. tools and workflows) available to you, as shown below.

You can filter for public workflows by adding the parameter visibility=public. Since this will return many results, we want to see as many results as we can on one page. To set the pagination, we use the query parameter limit=100 to display 100 results per page. The maximum allowable limit per page is 100.

GET /v2/apps?visibility=public&limit=100 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This query returns the following response:

{
  "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=0&limit=100",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/sbg-split-bed/3",
      "id": "admin/sbg-public-data/sbg-split-bed/3",
      "project": "admin/sbg-public-data",
      "name": "SBG Split BED"
    },
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/sbg-untar-fasta/8",
      "id": "admin/sbg-public-data/sbg-untar-fasta/8",
      "project": "admin/sbg-public-data",
      "name": "SBG Untar fasta"
    },
    <snip>
  ],
  "links": [
    {
      "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=100&limit=100",
      "rel": "next",
      "method": "GET"
    }
  ]
}

For brevity, we have omitted part some of the returned apps.

Scrolling through this list of apps, you'll see that Whole Exome Sequencing GATK 2.3.9.-lite isn't on this list of the first 100 results. To page through to the next 100 results, you can user the parameter offset=100 which starts listing the next 100 results starting from the 101st result, as shown below.

GET /v2/apps?visibility=public&limit=100&offset=100 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

You'll see the following response. Locate and copy the id of the Whole Exome Sequencing GATK 2.3.9.-lite workflow. We'll use this in the next step.

{
  "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=100&limit=100",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/chimera-1-12-0/4",
      "id": "admin/sbg-public-data/chimera-1-12-0/4",
      "project": "admin/sbg-public-data",
      "name": "Chimera"
    },
    <snip>
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/whole-exome-sequencing-gatk-2-3-9-lite/56",
      "id": "admin/sbg-public-data/whole-exome-sequencing-gatk-2-3-9-lite/56",
      "project": "admin/sbg-public-data",
      "name": "Whole Exome Sequencing GATK 2.3.9.-lite"
    },
    <snip>
    {
      "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=0&limit=100",
      "rel": "prev",
      "method": "GET"
    }
  ]
}

We've located the id for the Whole Exome workflow, and now we can copy it into our project.

Copy a public app into a project

We can use the id we obtained above to copy the workflow into our project.
To copy a workflow, make the API request to copy an app, as shown below. Be sure to pass the app's id in the path of the request.
In the body of the request, include the name of the project you want to copy the public app into, such as rfranklin/api-quickstart-project.

POST /v2/apps/admin/sbg-public-data/whole-exome-sequencing-gatk-2-3-9-lite/56/actions/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/api-quickstart-project"
}

This call returns the name and the id of the app within your project. Copy this id as we'll need it in the next step.

The response body also contains the full Common Workflow Language description of the copied app. This is typically a lengthy JSON object (raw), which we have omitted in part below for brevity. Keep this JSON handy for the next step, as it include information about setting up inputs for the workflow.

{
  "href": "https://api.sbgenomics.com/v2/apps/rfranklin/api-quickstart-project/Whole Exome Sequencing GATK 2.3.9.-lite/0",
  "id": "rfranklin/api-quickstart-project/whole-exome-sequencing-gatk-2-3-9-lite/0",
  "project": "rfranklin/api-quickstart-project",
  "name": "Whole Exome Sequencing GATK 2.3.9.-lite",
  "revision": 0,
  <snip>
  "inputs": [
      {
        "sbg:suggestedValue": [
          {
            "path": "578cf947507c17681a3117ce",
            "class": "File",
            "name": "1000G_phase1.indels.b37.vcf"
          },
          {
            "path": "5772b6c9507c1752674486d4",
            "class": "File",
            "name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
          }
        ],
        "sbg:y": 938.3340420723234,
        "sbg:x": 276.4287550222375,
        "sbg:includeInPorts": true,
        "label": "Known Indels",
        "type": [
          "null",
          {
            "type": "array",
            "items": "File"
          }
        ],
        "id": "#Known_Indels"
      }
    ]
<snip>
}

If you ever need to obtain the CWL description of an app, you can make the API request to get details of an app.

We're now ready to set up a task.

Create a draft task

An app execution is called a task. Each task is associated with a set of input files and chosen settings for the tool(s) in the app. The first step to executing a task is to set up a draft task. In this step, you specify the inputs for your task.

To set up a draft task, make the API request to create a draft task, as shown below.

In the body of the request, provide a name for your task. Then, specify the workflow you're running by including its id, which we obtained in the step above. Referencing the inputs in the step above, add the inputs for your workflow, including your reference and data files.

POST /v2/tasks HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{   "description": "an api task to demonstrate the quickstart",
    "name": "api task WES",
    "app": "rfranklin/api-quickstart-project/whole-exome-sequencing-gatk-2-3-9-lite/0",
    "project": "rfranklin/api-quickstart-project",
    "inputs": {
    "Known_SNPs": [
      {
        "path": "57a4b564e4b08370afe7e539",
        "class": "File",
        "name": "dbsnp_137.b37.vcf"
      }
    ],
    "Known_Indels": [
      {
        "path": "57a4b564e4b08370afe7e53b",
        "class": "File",
        "name": "1000G_phase1.indels.b37.vcf"
      },
      {
        "path": "57a4b564e4b08370afe7e53d",
        "class": "File",
        "name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
      }
    ],
    "database":
      {
        "path":"57a9f075e4b046f332565ff3",
        "class": "File",
        "name": "GRCh37.75.zip"
      },
    "Target_BED":
      {
        "path": "57a4b564e4b08370afe7e53f",
        "class": "File",
        "name": "exome_targets.b37.bed"
      },
    "FASTQ": [
      {
        "path": "57a47767e4b08370afe7e21f",
        "class": "File",
        "name": "C835.HCC1143_BL.4.converted.pe_1.fastq"
      },
      {
        "path": "57a47767e4b08370afe7e221",
        "class": "File",
        "name": "C835.HCC1143_BL.4.converted.pe_2.fastq"
      }
    ],
    "input_tar_with_reference":
      {
        "path":"57a9f075e4b046f332565ff1",
        "class": "File",
        "name": "human_g1k_v37_decoy.fasta.tar"
      }
    }
}

The response body will indicate if your draft task was successfully created. You'll also see the id for your draft task. Copy this to your clipboard, as we'll use it in the next step.

Note that you'll also see error messages if you've made a mistake in entering your inputs.

{
  "href": "https://api.sbgenomics.com/v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7",
  "id": "66a9a568-d8c5-4c43-b54c-361ee4f8d6b7",
  "name": "api task WES",
  "description": "an api task to demonstrate the quickstart",
  "status": "DRAFT",
  "project": "rfranklin/api-quickstart-project",
  "app": "rfranklin/api-quickstart-project/whole-exome-sequencing-gatk-2-3-9-lite/0",
  "type": "v2",
  "created_by": "rfranklin",
  "start_time": "2016-08-09T15:50:51Z",
  "batch": false,
<snip>
}

Now, we're ready to run the task.

Run a task

To run a task on the Platform, you'll need your draft task's id, obtained in the step above. Then, make the API request to run a task, as shown below.

POST /v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7/actions/run" HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

Your response body will contain information about your task as well as its status. When your task is first started, the status displays as QUEUED. Learn more about what happens when you run a task.

{
  "href": "https://api.sbgenomics.com/v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7",
  "id": "66a9a568-d8c5-4c43-b54c-361ee4f8d6b7",
  "name": "api task WES new",
  "description": "an api task to demonstrate the quickstart",
  "status": "QUEUED",
  "project": "rfranklin/api-quickstart-project",
  "app": "rfranklin/api-quickstart-project/whole-exome-sequencing-gatk-2-3-9-lite/0",
  "type": "v2",
  "created_by": "rfranklin",
  "executed_by": "rfranklin",
  "start_time": "2016-08-09T15:17:01Z",
  "batch": false,
  "execution_status": {
    "message": "In queue"
  },
  "errors": [],
  "warnings": [],
  "inputs": {
    "Known_SNPs": [
      {
        "path": "57a4b564e4b08370afe7e539",
        "class": "File",
        "name": "dbsnp_137.b37.vcf",
        "size": 8436107210
      }
    ],
    <snip>
  },
  "outputs": {
    "summary": null,
    "summary_metrics": null,
    "raw_vcf": null,
    "summary_text": null,
    "plot_pdf": null,
    "recalibrated_bam": null,
    "b64html": null,
    "annotated": null
  }
}

Check the status of your task

You can check the status of your task by making the API request to get execution details, as shown below. Be sure to include your task's id in the path.

GET /v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7/execution_details HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea9t6573259740f74

The response body, as shown below, will detail your task's status, which will be either RUNNING, COMPLETED, or FAILED. The response body also details the individual jobs which comprise the task. These jobs are individually marked as RUNNING or COMPLETED.

{
  "href": "https://api.sbgenomics.com/v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7/execution_details",
  "start_time": "2016-08-09T16:06:15Z",
  "status": "RUNNING",
  "message": "Running",
  "jobs": [
    {
      "name": "SBG_Html2b64_1_s",
      "start_time": "2016-08-09T16:15:08Z",
      "end_time": "2016-08-09T16:15:40Z",
      "status": "COMPLETED",
      "command_line": "python /opt/sbg_html_to_b64.py --input /sbgenomics/Projects/351df000-e176-48e9-9f10-8de87fe5ef3d/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7/whole-exome-sequencing-gatk-2-3-9-lite_FastQC_1_s/C835.HCC1143_BL.4.converted.pe_2_fastqc.zip",
      "instance": {
        "id": "i-da0a2044",
        "type": "c3.2xlarge",
        "provider": "AWS"
      },
      "logs": {
        "cmd.log": "https://api.sbgenomics.com/v2/files/57aa01a6e4b0a376e17e8b0a/download_info",
        "job.err.log": "https://api.sbgenomics.com/v2/files/57aa01abe4b0a376e17e8b11/download_info",
        "stderr": "https://api.sbgenomics.com/v2/files/57aa01abe4b0a376e17e8b11/download_info"
      },
      "docker": {
        "checksum": "a2852b992f9b7673a151aa25fe98e1ae4f18703fb53b177b59a42dfef011c340"
      }
    },
    <snip>
    {
      "name": "BWA_INDEX",
      "start_time": "2016-08-09T16:10:56Z",
      "status": "RUNNING",
      "command_line": "/opt/bwa-0.7.13/bwa index human_g1k_v37_decoy.fasta ; tar -cf human_g1k_v37_decoy.fasta.tar human_g1k_v37_decoy.fasta *.amb *.ann *.bwt *.pac *.sa",
      "instance": {
        "id": "i-da0a2044",
        "type": "c3.2xlarge",
        "provider": "AWS"
      },
      "logs": {
        "stderr": null
      },
      "docker": {
        "checksum": "4b06d40825c9c2f2ffe3beba9b8f6267c2c4543984915593deac1a003f7b8e5b"
      }
    }
  ]
}

You'll be notified by email once your task has completed.

Get task outputs

Once your task has completed, you can get your task outputs by making the API request to get details of a task, as shown below. This call differs from the one to get execution details in that it provides details about the task rather than the process of its execution.

We can add the parameter fields=outputs to filter the response body to only display the outputs.

GET /v2/tasks/66a9a568-d8c5-4c43-b54c-361ee4f8d6b7?fields=outputs HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

The response body returns the outputs of your task, including file ids (path) in case you wish to perform further analyses on these files.

{
  "outputs": {
    "summary_metrics": {
      "path": "57850c68e4b051911c736364",
      "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.summary_metrics.txt",
      "secondaryFiles": [],
      "class": "File"
    },
    "raw_vcf": {
      "path": "578527d3e4b07c1599e31c9c",
      "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.vcf",
      "secondaryFiles": [
        {
          "path": "578527d4e4b051911c73e01d",
          "size": 998322,
          "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.vcf.idx",
          "class": "File"
        }
      ],
      "class": "File"
    },
    "summary_text": {
      "path": "578528c8e4b07c1599e31d2d",
      "name": "Sample_HCC1143.Library_Unknown.Platform_Unit_Unknown.combined.snpEff_summary.genes.txt",
      "class": "File"
    },
    "plot_pdf": {
      "path": "57850202e4b051911c72647b",
      "name": "C835.HCC1143.2.converted.realigned.pdf",
      "class": "File"
    },
    "recalibrated_bam": {
      "path": "57850b0ae4b0788896befc0b",
      "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.bam",
      "secondaryFiles": [
        {
          "path": "57850b0ae4b0788896befc0d",
          "size": 5605128,
          "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.bam.bai",
          "class": "File"
        }
      ],
      "class": "File"
    },
    "b64html": [
      {
        "path": "5784c02ce4b0c889884fddf2",
        "name": "_1_C835.HCC1143.2.converted.pe_1_fastqc.b64html",
        "class": "File"
      },
      {
        "path": "5784c02ce4b09e5c738a9cd7",
        "name": "_1_C835.HCC1143.2.converted.pe_2_fastqc.b64html",
        "class": "File"
      }
    ],
    "b64html_1": {
      "path": "578528e8e4b051911c73e0f8",
      "name": "Sample_HCC1143.Library_Unknown.Platform_Unit_Unknown.combined.snpEff_summary.b64html",
      "class": "File"
    },
    "annotated": {
      "path": "578528c8e4b0e14f48b05ac9",
      "name": "Sample_HCC1143.Library_Unknown.Platform_Unit_Unknown.combined.snpEff_annotated.vcf",
      "class": "File"
    }
  }
}

That’s it! We've executed a data analysis and obtained some results.

Suggest Edits

API Batch tutorial

 

Overview

This tutorial introduces you to performing a batch analysis using the API.
Batching allows you to run identical analyses on different data, by entering multiple input files and grouping them with specified metadata criteria. For instance, you can group input files by File, Sample, Library, Platform unit, or File segment. By using Batch Input, you can process multiple datasets with a single workflow containing the same parameter settings without having to set up the workflow multiple times. Batching creates one parent task containing multiple child tasks: one for each group of files.

Objective

In this tutorial, we'll run a batch analysis in which we align reads based on their Sample metadata.

Prerequisites

You will need an account on the Seven Bridges Platform in order to obtain your authentication token. Almost all API requests require your Seven Bridges authentication token. This acts as a security measure regulating your access to your projects. Learn more about obtaining your authentication token.

Procedure

We'll use the API to create a project and populate it with files. Then, we'll use the visual interface to modify one of the Seven Bridges RNA sequencing workflows, RNA-seq Alignment STAR, to carry out the analysis. At this point, we will use the API to specify the inputs and set the batch criteria to batch by sample. Finally, we'll examine our results.

All necessary tools and data are available on the Platform.

We will state the HTTP requests for each API call used in the procedure. But you could also write a script that makes these calls using Seven Bridges Python or R client libraries.

Step 1: Find your billing group

To start an analysis, we must first create a project. To do this, we need to obtain following information:

Your authentication token acts as a security measure so only you can access your projects and resources on the Platform. The billing group ID designates which funding resource to charge for the analyses you run in the project you're about to create. Learn more about billing groups on the Platform.

Keep in mind, when you signed up for the Seven Bridges Platform, your account was automatically credited with $100 in free funds (your Pilot Funds) to use for data analyses. We will use this billing group in this tutorial.

Use the API request to list your billing groups, as shown in the HTTP request below. Be sure to substitute your authentication token for X-SBG-Auth-Token.

GET /v2/billing/groups HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This request returns a list of the billing groups you are part of, as shown below:

{
  "href": "https://api.sbgenomics.com/v2/billing/groups/",
  "items":
    {
      "id": "70c12809-9ef2-845c-9d67-dfb8c9619fd6",
      "href": "https://api.sbgenomics.com/v2/billing/groups/70c12809-9ef2-845c-9d67-dfb8c9619fd6",
      "name": "Pilot Funds (rfranklin)"
    }
  "links": []
}

Copy the value for id (in this case 70c12809-9ef2-845c-9d67-dfb8c9619fd6) to your clipboard. We will use this in the next step when creating a project.

Step 2: Create a project

Projects on the Platform serve as the containers for the data, analytical tools, results, and team of collaborators for a distinct scientific investigation.

To create a project, make the API request to create a project, as shown in the HTTP request shown below. Be sure to paste in your authentication token for the X-SBG-Auth-Token key.

This request also requires a request body. Provide a name for your project and an optional description. Here, you should also paste in the billing_group id you obtained in the previous step.

POST /v2/projects HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
content-type: application/json
{
    "name":"Batch tutorial",
    "description":"project for batching by sample via the APi",
    "billing_group":"70c12809-9ef2-845c-9d67-dfb8c9619fd6"
}

You'll see a response body, as shown below, containing the name of your project, its URL (href), your project id, and your project's billing_group.

Note down the project id. We will use this throughout the tutorial to designate our project. The project id consists of two parts: your username followed by your project's short name.

{
  "href": "https://api.sbgenomics.com/v2/projects/rfranklin/batch-tutorial",
  "id": "rfranklin/batch-tutorial",
  "name": "Batch-tutorial",
  "type": "v2",
  "description": "project for batching by sample via the API",
  "tags": [],
  "billing_group": "70c12809-9ef2-845c-9d67-dfb8c9619fd6"
}

Now that you've successfully created a project, we can add data to the project for analysis.

Step 3: Add data files to your project

In this tutorial, we'll analyze data that is hosted in the Cancer Cell Line Encyclopedia (CCLE) public project on the Seven Bridges Platform.

Public projects are repositories for examples of specific analyses as well as the associated data and tools you need to replicate these analyses on the Platform.

For this analysis, we want to use data files contained within the CCLE project.

3a: Find your files

To find BAM files that contain RNA sequencing data within CCLE, we will make the API request to list all files in a project, as shown below.

We'll need to pass along two query parameters to locate the files. First, we have to specify the project containing the files. In this case, the CCLE public project is specified by the id of sevenbridges/cancer-cell-line-encyclopedia-ccle-1. Following the path, you can pass this query parameter using project=sevenbridges/cancer-cell-line-encyclopedia-ccle-1.

Then, we want to find BAM files with an experimental strategy of RNA-Seq. It is possible to filter by metadata fields to retrieve files with certain properties. In this tutorial, however, we already know that we want to find the following three files:

  • G30630.VM-CUB1.3.bam
  • G30603.TUHR4TKB.1.bam
  • G28034.MDA-MB-361.1.bam

Since we know the files' names, we can filter the returned files by name, using the name query parameter. We can append this query parameter to the query parameter project using an ampersand (&).

You can search for multiple files by name with the same API request, by including the field name multiple times. 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, so including the name field three times for three file names will find files matching any one of the file names.

The HTTP request to find files in the CCLE project matching our chosen file names is shown below:

GET /v2/files?project=sevenbridges/cancer-cell-line-encyclopedia-ccle-1&name=G30630.VM-CUB1.3.bam&name=G30603.TUHR4TKB.1.bam&name=G28034.MDA-MB-361.1.bam HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

In the response returned, you will see a list of files along with their id, name, and the project to which they belong, as shown below.

{
  "href": "https://api.sbgenomics.com/v2/files?offset=0&name=G30630.VM-CUB1.3.bam&name=G30603.TUHR4TKB.1.bam&name=G28034.MDA-MB-361.1.bam&limit=3&project=sevenbridges/cancer-cell-line-encyclopedia-ccle-1",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/files/57da918fe4b002eed2cb10eb",
      "id": "57da918fe4b002eed2cb10eb",
      "name": "G30603.TUHR4TKB.1.bam",
      "project": "sevenbridges/cancer-cell-line-encyclopedia-ccle-1"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/57da918fe4b002eed2cb0915",
      "id": "57da918fe4b002eed2cb0915",
      "name": "G28034.MDA-MB-361.1.bam",
      "project": "sevenbridges/cancer-cell-line-encyclopedia-ccle-1"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/57da918fe4b002eed2cb0fe7",
      "id": "57da918fe4b002eed2cb0fe7",
      "name": "G30630.VM-CUB1.3.bam",
      "project": "sevenbridges/cancer-cell-line-encyclopedia-ccle-1"
    }
  ],
  "links": []
}

Copy the id for each of the three files to your clipboard. We will use this in the next step when copying these files into our project.

3b: Copy files to a project

To copy files into a project, make the API request to batch copy files, as shown below.

In the body of the request, you can designate the target project for the copied files. As shown in the example request below, supply a project id consisting of your username followed by the project's short name for the project key.

We also want to pass along the file ids you obtained in the step above in the body of the request. We can input the ids as a list of values for the file_ids key, as shown below.

POST /v2/action/files/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/batch-tutorial",
    "file_ids":[
  		"57da918fe4b002eed2cb10eb",
      "57da918fe4b002eed2cb0915",
      "57da918fe4b002eed2cb0fe7"
    ]
}

The response body, as shown below, will indicate if your request was successful. The response contains the original ids of your copied files and the status of the response.

The response body also contains two other fields: new_file_id and new_file_name. These indicate the new id and the new name assigned to the copy of the file within your project. You can use this id in future API requests to refer to the copy of the file within your project as opposed to the original file.

{
  "57da918fe4b002eed2cb10eb": {
    "status": "OK",
    "new_file_id": "57e43957e4b002eed2cbe64d",
    "new_file_name": "G30603.TUHR4TKB.1.bam"
  },
  "57da918fe4b002eed2cb0915": {
    "status": "OK",
    "new_file_id": "57e43957e4b002eed2cbe64f",
    "new_file_name": "G28034.MDA-MB-361.1.bam"
  },
  "57da918fe4b002eed2cb0fe7": {
    "status": "OK",
    "new_file_id": "57e43957e4b002eed2cbe651",
    "new_file_name": "G30630.VM-CUB1.3.bam"
  }
}

The files have been successfully copied to your project.

Step 4: Add reference files to your project

Many bioinformatics tools require certain data, such as reference genomes or annotation files, to execute properly. Seven Bridges maintains a collection of the latest and most frequently used reference genomes and annotation files in the Public Reference Files repository. The RNA-seq Alignment STAR workflow uses a reference genome and an annotation files to align reads. We'll need to have these reference files in our project to be able to use them while setting up our task.

For this analysis, we need to supply the workflow with the following two reference files:

  • HG19_Broad_variant.fasta
  • Homo_sapiens.GRCh37.75.gtf

See the table below for more information about each file.

API key
Input files
File type

genomeFastaFiles

HG19_Broad_variant.fasta

FASTA is a reference genome file which we will use for the alignment of the FASTQ files.

sjdbGTFfile

Homo_sapiens.GRCh37.75.gtf

GTF is an annotation file containing information about gene structure.

4a: Find reference files

To find the reference files above in the Public Reference Files repository, we will make the API request to list all files in a project, as shown below.

This process is similar to finding the data files above. In this case, 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. Following the path, you can pass this query parameter using project=admin/sbg-public-data.

As above, we want to filter the results by the name parameter to find HG19_Broad_variant.fasta and Homo_sapiens.GRCh37.75.gtf.

The entire HTTP request is shown below:

GET /v2/files?project=admin/sbg-public-data&name=HG19_Broad_variant.fasta&name=Homo_sapiens.GRCh37.75.gtf HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

In the response, you will see information about each file as well as the file's id. Copy each id (for example, 5772b6cd507c1752674486d8) to your clipboard. We will use these ids in the next step.

{
  "href": "https://api.sbgenomics.com/v2/files?offset=0&name=HG19_Broad_variant.fasta&name=Homo_sapiens.GRCh37.75.gtf&limit=2&project=admin/sbg-public-data",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6c4507c1752674486cd",
      "id": "5772b6c4507c1752674486cd",
      "name": "Homo_sapiens.GRCh37.75.gtf",
      "project": "admin/sbg-public-data"
    },
    {
      "href": "https://api.sbgenomics.com/v2/files/5772b6c1507c1752674486c9",
      "id": "5772b6c1507c1752674486c9",
      "name": "HG19_Broad_variant.fasta",
      "project": "admin/sbg-public-data"
    }
  ],
  "links": []
}

Pro-tip:

To display only the id and name fields in the response, you can specify fields as a query parameter by using fields=id,name.

4b: Copy reference files to your project

To copy files into a project, make the API request to batch copy files, as shown below. This is the same method we used to copy our data files into our project.

In the body of the request, you can specify the target project for the copied files, such as rfranklin/batch-tutorial, as a value for the project key.

We also want to pass along the file ids you obtained in the step above in the body of the request. We can input the ids as a list of values for the file_ids key, as shown below.

POST /v2/action/files/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/batch-tutorial",
    "file_ids": [
        "5772b6c4507c1752674486cd",
        "5772b6c1507c1752674486c9"
    ]
}

The response body contains the new_file_id for each of the copied reference files. These indicate the new id assigned to the copy of the file within your project. You can use this id in future API requests to refer to the copy of the file within your project as opposed to the original file

{
  "5772b6c4507c1752674486cd": {
    "status": "OK",
    "new_file_id": "57e53cb8e4b002eed2cbf489",
    "new_file_name": "Homo_sapiens.GRCh37.75.gtf"
  },
  "5772b6c1507c1752674486c9": {
    "status": "OK",
    "new_file_id": "57e53cb8e4b002eed2cbf48b",
    "new_file_name": "HG19_Broad_variant.fasta"
  }
}

We have populated our project with the requisite data and reference files. Now, we can add a workflow to our project.

Step 5: Add a public workflow to your project

We need a workflow to analyze our data. We'll start with a publicly available workflow from the Seven Bridges Public Apps repository, RNA-seq Alignment - STAR. However, the workflow takes FASTQ inputs. Since we added BAM files from CCLE above, we'll need to modify the workflow to accept input BAM files and convert them to the FASTQ format.

5a: Find a public workflow

To find a public workflow on the Platform, make the API request to list all apps (i.e. tools and workflows) available to you, as shown below.

You can filter for public workflows by adding the parameter visibility=public. Since this will return many results, we want to see as many results as we can on one page. To set the pagination, we use the query parameter limit=100 to display 100 results per page. The maximum allowable limit per page is 100.

GET /v2/apps?visibility=public&limit=100 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This query returns the response below. For brevity, we have omitted part some of the returned apps.

{
  "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=0&limit=100",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/sbg-split-bed/3",
      "id": "admin/sbg-public-data/sbg-split-bed/3",
      "project": "admin/sbg-public-data",
      "name": "SBG Split BED"
    },
    {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/sbg-untar-fasta/8",
      "id": "admin/sbg-public-data/sbg-untar-fasta/8",
      "project": "admin/sbg-public-data",
      "name": "SBG Untar fasta"
    },
    <snip>
  ],
  "links": [
    {
      "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=100&limit=100",
      "rel": "next",
      "method": "GET"
    }
  ]
}

Scrolling through this list of apps, you'll see that RNA-seq Alignment - STAR isn't on this list of the first 100 results. To page through to the next 100 results, follow the path at the bottom of your response, "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=100&limit=100". Use this path to issue another request which lists next 100 results starting from the 101st result, as shown below.

If RNA-seq Alignment - STAR is not in the results, page through until you see the workflow. Locate and copy the id of the RNA-seq Alignment - STAR workflow. We'll use this in the next step.

{
  "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=200&limit=100",
  "items": [
    <snip>
   {
      "href": "https://api.sbgenomics.com/v2/apps/admin/sbg-public-data/rna-seq-alignment-star/16",
      "id": "admin/sbg-public-data/rna-seq-alignment-star/16",
      "project": "admin/sbg-public-data",
      "name": "RNA-seq Alignment - STAR"
    },
    <snip>
    {
      "href": "https://api.sbgenomics.com/v2/apps?visibility=public&offset=100&limit=100",
      "rel": "prev",
      "method": "GET"
    }
  ]
}

We've located the id for the RNA-seq Alignment - STAR workflow, and now we can copy the workflow into our project.

5b: Copy a workflow into a project

We can use the id we obtained above to copy the workflow into our project.

To copy a workflow, make the API request to copy an app, as shown below. Be sure to pass the app's id in the path of the request.

In the body of the request, include the name of the project you want to copy the public app into, such as rfranklin/batch-tutorial.

POST /v2/apps/admin/sbg-public-data/rna-seq-alignment-star/16/actions/copy HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
    "project":"rfranklin/batch-tutorial"
}

This call returns the name and the id of the app within your project. Copy this id as we'll need it in the next step.

The response body also contains the full Common Workflow Language description of the copied app. This is typically a lengthy JSON object (raw), which we have omitted in part below for brevity. Keep this JSON handy for the next step, as it include information about setting up inputs for the workflow.

{
  "href": "https://api.sbgenomics.com/v2/apps/rfranklin/batch-tutorial/RNA-seq Alignment - STAR/0",
  "id": "rfranklin/batch-tutorial/rna-seq-alignment-star/0",
  "project": "rfranklin/batch-tutorial",
  "name": "RNA-seq Alignment - STAR",
  "revision": 0,
  <snip>
  "inputs": [
      {
        "sbg:suggestedValue": [
          {
            "name": "Homo_sapiens.GRCh37.75.gtf",
            "class": "File",
            "path": "5772b6c4507c1752674486cd"
          }
        ],
        "id": "#sjdbGTFfile",
        "label": "sjdbGTFfile",
        "type": [
          "null",
          {
            "items": "File",
            "type": "array"
          }
        ],
        "sbg:y": 195.08331063389656,
        "sbg:x": 160.49997586011762
      },
      {
        "id": "#fastq",
        "type": [
          {
            "items": "File",
            "type": "array"
          }
        ],
        "label": "fastq",
        "sbg:includeInPorts": true,
        "sbg:y": 323.74995018542,
        "sbg:x": 164.24999140203002
      },
      {
        "sbg:suggestedValue": {
          "name": "human_g1k_v37_decoy.phiX174_Homo_sapiens.GRCh37.75_star-2.4.2a.tar",
          "class": "File",
          "path": "57bd5d15507c17b56d99b0d6"
        },
        "id": "#genomeFastaFiles",
        "label": "genomeFastaFiles",
        "type": [
          "File"
        ],
        "sbg:y": 469.9999105781354,
        "sbg:x": 167.749960079791
      }
    ],
<snip>
}

We're now ready to modify the workflow we've copied.

5c: Modify a workflow on the visual interface

After you copy a workflow from the Seven Bridges Public Apps repository to your own project, you can edit the workflow via the visual interface or by editing its CWL. To edit the workflow, let's use the Workflow Editor on the visual interface.

We want to modify the RNA-seq Alignment - STAR workflow we copied above to take BAM files as inputs.

To modify the workflow, follow the directions below. Note that the following directions apply to the visual interface of the Platform.

  1. Navigate to the Apps tab of your project and click the pencil icon next to your copied workflow. You'll be taken to the Workflow Editor, as shown below.

As shown above, the workflow has three input nodes (icons with arrows going into a half circle): sjdbGTFfile, fastq, and genomeFastaFiles. As our CCLE data is in the BAM format, we need to add the Picard SamToFastq tool so the workflow will accept BAM files by converting them to the fastq format.

  1. Click on the fastq input and select the red x above the node to delete it.
  2. Use the righthand APPS panel to search for the Picard SamToFastq tool.
  3. Drag and drop the Picard SamToFastq tool onto the Workflow Editor canvas.
  1. Connect the Picard SAMToFastq tool to the SBG FASTQ Quality Detector tool as shown below.
  1. Click on the circle on the left side of the Picard SamtoFastq tool and drag it out to the left side of the canvas. This adds an input node which accepts BAM files.
  2. Click on the input node, input_file. On the righthand panel, click on the dropdown menu below Create batch group by metadata criteria and select Sample ID. Note down the name of the input node, input_file. We'll use this information below to specify the input on which to batch when creating a draft task below
  1. Click Save in the top righthand corner and add an optional description, as shown below. Finish by clicking Save once more.

The modified RNA-seq Alignment - STAR workflow now accepts BAM inputs.

5d: Find an app in your project via the API

Now that we've modified our workflow, we will return to the API to find the id for our modified workflow. To do this, we make the API request to list all apps available in a project. As shown in the example request below, supply a project id, such as rfranklin/batch-tutorial.

GET /v2/apps?project=rfranklin/batch-tutorial HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

This call returns the name and the id of the app within your project. Copy this id as we'll need it in the next step.

{
  "href": "https://api.sbgenomics.com/v2/apps?offset=0&limit=1&project=rfranklin/batch-tutorial",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/apps/rfranklin/batch-tutorial/rna-seq-alignment-star/1",
      "id": "rfranklin/batch-tutorial/rna-seq-alignment-star/1",
      "project": "rfranklin/batch-tutorial",
      "name": "RNA-seq Alignment - STAR"
    }
  ],
  "links": []
}

We're now ready to set up a draft batch task.

Step 6: Create a draft task

An app execution is called a task. Each task is associated with a set of input files and chosen settings for the tool(s) in the app. The first step to executing a task is to set up a draft task. In this step, you specify the inputs for your task.

To set up a draft task, make the API request to create a draft task, as shown below.

In the body of the request, specify the following:

name

A name for your task.

app

The workflow you're running by including the workflow's id, which we obtained in the step above.

batch_input

The input port on which you wish to batch, such as
input_file from above.

batch_by

The criteria on which to batch for the batch_by key. This consists of a type as well as the criteria.
As shown below, we supply the first key, type, with the value, CRITERIA. We then supply the second key, criteria, with the value, metadata.sample_id. In short, we're batching by sample.

project

Your project id, such as rfranklin/batch-tutorial.

input

The reference files and data files for our workflow.

Include the class, the file's path, and the file's name. The path is the file's id in our project. We obtained these ids when we copied the files to our project.

An example request to create a draft task is as follows:

POST /v2/tasks HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{  
    "name": "api batch tutorial task",
    "app": "rfranklin/batch-tutorial/rna-seq-alignment-star/1",
    "project": "rfranklin/batch-tutorial",
    "batch_input": "input_file",
    "batch_by": {
        "type": "CRITERIA",
        "criteria": [
            "metadata.sample_id"
        ]
    },
    "inputs": {
    "input_file": [
      {
        "class": "File",
        "path": "57e43957e4b002eed2cbe64f",
        "name": "G28034.MDA-MB-361.1.bam"
      },
      {
        "class": "File",
        "path": "57e43957e4b002eed2cbe64d",
        "name": "G30603.TUHR4TKB.1.bam"
      },
      {
        "class": "File",
        "path": "57e43957e4b002eed2cbe651",
        "name": "G30630.VM-CUB1.3.bam"
      }
    ],
    "reference_or_index": {
      "class": "File",
      "path": "57e53cb8e4b002eed2cbf48b",
      "name": "HG19_Broad_variant.fasta"
    },
    "sjdbGTFfile": [
      {
        "name": "Homo_sapiens.GRCh37.75.gtf",
        "class": "File",
        "path": "57e53cb8e4b002eed2cbf489"
      }
    ]
  }
}

The response body will indicate if your draft task was successfully created. You'll also see the id for your draft task. Copy this to your clipboard, as we'll use it in the next step.

Note that you'll also see error messages if you've made a mistake in entering your inputs.

{
  "href": "https://api.sbgenomics.com/v2/tasks/e3a88ab3-829a-485c-995a-3acd817ee98c",
  "id": "e3a88ab3-829a-485c-995a-3acd817ee98c",
  "name": "api batch tutorial task",
  "status": "DRAFT",
  "project": "rfranklin/batch-tutorial",
  "app": "rfranklin/batch-tutorial/rna-seq-alignment-star/1",
  "type": "v2",
  "created_by": "rfranklin",
  "start_time": "2016-09-23T18:43:24Z",
  "batch": true,
  "batch_input": "input_file",
  "batch_by": {
    "type": "CRITERIA",
    "criteria": [
      "metadata.sample_id"
    ]
  },
  "errors": [],
  "warnings": [],
  "inputs": {
    <snip>
  }
}

Note that batch is set to true. This indicates we've created a draft batch task. The response also reiterates the criteria by which we're batching. Now, we're ready to run the task.

Step 7: Run a task

To run a task on the Platform, you'll need your draft task's id, obtained in the step above. Then, make the API request to run a task, specifying the id of the draft task, as shown below.

POST /v2/tasks/e3a88ab3-829a-485c-995a-3acd817ee98c/actions/run" HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

Your response body will contain information about your task as well as its status. Learn more about what happens when you run a task.


{
  "href": "https://api.sbgenomics.com/v2/tasks/e3a88ab3-829a-485c-995a-3acd817ee98c",
  "id": "e3a88ab3-829a-485c-995a-3acd817ee98c",
  "name": "api batch tutorial task",
  "status": "CREATING",
  "project": "rfranklin/batch-tutorial",
  "app": "rfranklin/batch-tutorial/rna-seq-alignment-star/1",
  "type": "v2",
  "created_by": "rfranklin",
  "executed_by": "rfranklin",
  "start_time": "2016-09-23T18:43:24Z",
  "batch": true,
  "batch_input": "input_file",
  "batch_by": {
    "type": "CRITERIA",
    "criteria": [
      "metadata.sample_id"
    ]
  },
  "errors": [],
  "warnings": [],
  "inputs": {
    <snip>
  },
}

Copy down the id of the parent task from the response body. You'll use this in the next step to obtain your task outputs. You'll be notified by email once your task has completed.

Step 8: Get task outputs

Once your task has completed, you can get your task outputs. First, we obtain the task ids of the child tasks. Then, we make the API request to get details of a task.

8a: List the child tasks

Before we can obtain the outputs of each child task, we have to obtain their task ids by making the API request to list tasks. To list all tasks associated with a parent task, set the parameter parent to the task id of the parent task obtained in the step above. For instance, in the example below, parent is set to e3a88ab3-829a-485c-995a-3acd817ee98c.

GET /v2/tasks?parent=e3a88ab3-829a-485c-995a-3acd817ee98c HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

The response body returns a list of the child tasks, including the id of each child task, the name of the parent task, and the project the tasks belong to. Copy the id of each child task to a clipboard. We'll use this in the next step.

{
  "href": "https://api.sbgenomics.com/v2/tasks?parent=e3a88ab3-829a-485c-995a-3acd817ee98c&offset=0&limit=3",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/tasks/330e9764-319c-4523-bb5b-953644a1b119",
      "id": "330e9764-319c-4523-bb5b-953644a1b119",
      "name": "api batch tutorial task",
      "project": "rfranklin/batch-tutorial"
    },
    {
      "href": "https://api.sbgenomics.com/v2/tasks/b10144f0-1cda-48e1-87f3-e66f2cf4aa2d",
      "id": "b10144f0-1cda-48e1-87f3-e66f2cf4aa2d",
      "name": "api batch tutorial task",
      "project": "rfranklin/batch-tutorial"
    },
    {
      "href": "https://api.sbgenomics.com/v2/tasks/74b642da-e647-4b91-89d0-81ae308abcbd",
      "id": "74b642da-e647-4b91-89d0-81ae308abcbd",
      "name": "api batch tutorial task",
      "project": "rfranklin/batch-tutorial"
    }
  ],
  "links": []
}

8b: Obtain the outputs of a child task

For each child task above, make the following API request to get details of a task to obtain its outputs. Be sure to pass along the child task's id, obtained in the step above, in the path. Add the parameter fields=outputs to filter the response body to only display the outputs, as shown below.

GET /v2/tasks/330e9764-319c-4523-bb5b-953644a1b119?fields=outputs HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

The response body returns the outputs of your task, including file ids (path) in case you wish to perform further analyses on these files.

{
  "outputs": {
    "log_files": [
      {
        "path": "57e58b05e4b0ebec9056ec72",
        "name": "G30603.TUHR4TKB.1.converted.pe.Log.final.out",
        "class": "File"
      },
      {
        "path": "57e58b05e4b0b3cd0ec80c15",
        "name": "G30603.TUHR4TKB.1.converted.pe.Log.out",
        "class": "File"
      },
      {
        "path": "57e58b05e4b0ebec9056ec74",
        "name": "G30603.TUHR4TKB.1.converted.pe.Log.progress.out",
        "class": "File"
      }
    ],
    "reads_per_gene": {},
    "unmapped_reads": [
      {
        "path": "57e58b06e4b0b3cd0ec80c17",
        "name": "G30603.TUHR4TKB.1.converted.pe.Unmapped.out.mate1.fastq",
        "class": "File"
      },
      {
        "path": "57e58b06e4b0ebec9056ec76",
        "name": "G30603.TUHR4TKB.1.converted.pe.Unmapped.out.mate2.fastq",
        "class": "File"
      }
    ],
    "chimeric_junctions": {},
    "sorted_bam": {
      "path": "57e58db2e4b0ebec9056f2c0",
      "name": "G30603.TUHR4TKB.1.converted.pe.Aligned.out.sorted.bam",
      "secondaryFiles": [
        {
          "path": "57e58db2e4b0b3cd0ec810ef",
          "size": 4018336,
          "name": "G30603.TUHR4TKB.1.converted.pe.Aligned.out.sorted.bam.bai",
          "class": "File"
        }
      ],
      "class": "File"
    },
    "chimeric_alignments": {},
    "transcriptome_aligned_reads": {
      "path": "57e58b06e4b0b3cd0ec80c19",
      "name": "G30603.TUHR4TKB.1.converted.pe.Aligned.toTranscriptome.out.bam",
      "class": "File"
    },
    "intermediate_genome": {},
    "splice_junctions": {
      "path": "57e58b07e4b0ebec9056ec78",
      "name": "G30603.TUHR4TKB.1.converted.pe.SJ.out.tab",
      "class": "File"
    }
  }
}

Repeat this process for the other child tasks to obtain their respective outputs.

That’s it! We've executed a batch analysis and obtained some results.

Suggest Edits

okAPI recipes

 

Who is this for?

The API recipes and tutorials linked to from this page are intended for users who have some familiarity with Jupyter notebooks and want to use the API to extend and automate their analysis. Please also see our Introduction to the API tutorial for some basics on using our API.

okAPI repository

You can find Python example scripts as recipes (which allow you to perform specific tasks) or tutorials (which will walk you through entire analyses) for invoking the API on the Seven Bridges Github repository, okAPI. These recipes and tutorials make use of our Python library.

We recommend that you start with our A Quickstart guide to the API. This parallels the QuickStart for the visual interface and walks you through an entire Whole Exome Sequencing analysis.

Tutorials cover:

See more tutorials on our okAPI repository.

Recipes cover (partial list):

See more recipes on our okAPI repository.

Suggest Edits

Client libraries

 

The Seven Bridges API has allowed our users to automate, extend, and customize their analysis workflows.

Many users, including Seven Bridges' own engineers, have developed wrappers for the API calls in Python, R, and bash. This allowed them to leverage scripting to complete a spectrum of analyses, ranging from batch processing of more than 5000 tasks to adapting complex processing workflows based on intermediate results.

Seven Bridges maintains official bindings for the API in Python and R. There are four key advantages of these bindings:

  • It is easier to start using the API, with a minimal onboarding curve
  • The API can be used via professionally designed and maintained software
  • The bindings are available through the expected channels
  • Seven Bridges can provide more thorough support for official bindings than bespoke wrappers created by each user

Learn more about the Seven Bridges libraries for Python and R.

Suggest Edits

R library

 

The Seven Bridges API R client is available on Github and Bioconductor.

This is an open-source project, and the source code is openly available on Github. Please report any issues to https://github.com/sbg/sevenbridges-r/issues. Tutorials and function references are available here.

Learn more about using API with the R client from our video tutorial below.

Suggest Edits

Python library

 

The Seven Bridges API Python client for the API is available from the Python Package Index at https://pypi.python.org/pypi/sevenbridges-python. Documentation is available at Readthedocs.

The code is available on Github at https://github.com/sbg/sevenbridges-python target="blank"

Suggest Edits

Store credentials to access Seven Bridges client applications and libraries

 

Overview

Seven Bridges maintains client applications and libraries which require authentication. Instead of storing your credentials separately for each client application or client library, use a unified configuration file to securely maintain your credentials and authenticate. On this page, learn about Seven Bridges client applications and libraries which require authentication, how applications and libraries check for credentials, and about using a unified configuration file.

Seven Bridges client applications and libraries

The following Seven Bridges client applications and libraries require your Seven Bridges Platform credentials to authenticate.

Application or library name
Description

sevenbridges-python is the official Seven Bridges -maintained Python bindings for the Seven Bridges API.

sevenbridges-r is the official Seven Bridges -maintained R bindings for the Seven Bridges API.

Hierarchy of credentials

Using a unified configuration file is the preferred method for storing your Seven Bridges credentials. However, Seven Bridges client applications and libraries will check for your credentials in the following order:

  • Explicit parameters passed during initialization
  • Environmental variables available on an OS level which are defined by users. Credentials can be stored using using the following environmental variables: SB_API_ENDPOINT and SB_AUTH_TOKEN.
  • Unified configuration file which stores your credentials for all Seven Bridges client applications and libraries. This is the preferred method for storing your credentials. Learn more about the unified configuration file below.
  • Application or library -specific configuration file which stores your credentials for a specific Seven Bridges client application or library.

Note that the previously used configuration file (such as .sbgrc or .sbg.auth.yml) is no longer supported by sevenbridges-r starting from version 1.5.5 and sevenbridges-python starting from version 0.7.0.

Unified configuration file

Use a unified configuration file to store all of your credentials for Seven Bridges client applications and libraries. The configuration file, credentials, is a INI-like file stored in a directory named .sevenbridges underneath your home directory. This location varies across operating systems, but would typically be:

  • (for Linux and Mac OS X) $HOME/.sevenbridges/credentials
  • (for MS Windows) %UserProfile%\.sevenbridges\credentials

The credentials configuration file should contain key-value pairs of the following form:

api_endpoint = https://api.sbgenomics.com/v2
auth_token = 2cba934ad7094809bf1700cd80751745

The above key-value pairs comprise one profile. Each profile's name precedes the relevant key-value pairs and is enclosed in brackets. The credentials file can consist of multiple profiles, as shown below. For instance, users may have multiple accounts on the same environment:

[default]
api_endpoint = https://api.sbgenomics.com/v2
auth_token = 2cba934ad7094809bf1700cd80751745

[sbpla-2]
api_endpoint = https://api.sbgenomics.com/v2
auth_token = d7090174092cba934a485cd8075bf170

[gcp]
api_endpoint = https://gcp-api.sbgenomics.com/v2
auth_token = 90d70172c409ba48934a5c750d80bf17

Note that each profile must have exactly one api_endpoint and one auth-token key with their corresponding values.

Suggest Edits

Using volumes via the API

 

If you store your files on AWS or GCP, Seven Bridges' API lets you connect your storage to the Seven Bridges Platform. Once such a connection is established, files and objects from your cloud account are available for computation on the Seven Bridges Platform. Similarly, files in your account on the Seven Bridges Platform can be copied into your connected cloud storage.

Learn more about connecting cloud storage from our documentation.

Operations on volumes are handled by the Seven Bridges API. For the API reference, see the Volumes section of the API documentation.

Suggest Edits

Return all paths

 
Suggest Edits

List all API paths

 
gethttps://api.sbgenomics.com/v2
 

This call returns all API paths, so that you don't need to rely on documentation in the terminal.

Request

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

Response

Example request

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/

Example response body

{
  "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"
}
Suggest Edits

Get my information

/user

For general information on the API, including formatting, parameters, and pagination, please see the API Overview.

 
gethttps://api.sbgenomics.com/v2
 

This call returns information about your account on the Seven Bridges Platform.

Request

https://api.sbgenomics.com/v2/user
https://eu-api.sbgenomics.com/v2/user
https://gcp-api.sbgenomics.com/v2/user

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

fields

string

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

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.

Example Request

GET /v2/user 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://cgc-api.sbgenomics.com/v2/user"

Example response body

{
  "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": ""
}
Suggest Edits

List user resources

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

username

Username of the user you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example Request

GET /v2/users/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/users/RFranklin"

Example response body

{
  "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": ""
}
 
Suggest Edits

List billing API paths

 
gethttps://api.sbgenomics.com/v2
 

This call returns a list of paths used to access billing information via the API.

Request

https://api.sbgenomics.com/v2/billing
https://eu-api.sbgenomics.com/v2/billing
https://gcp-api.sbgenomics.com/v2/billing

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

fields

string

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

Example request

GET /v2/billing HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: a42c0608d5934bdeb91d0f9e0cdddb48
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/billing"

Example response

Example response body

{
  "billing_groups_url": "https://api.sbgenomics.com/v2/billing/groups/",
  "invoices_url": "https://api.sbgenomics.com/v2/billing/invoices/"
}
Suggest Edits

List billing groups

 
gethttps://api.sbgenomics.com/v2
 

This call lists all your billing groups, including groups that are pending or have been disabled.

Request

https://api.sbgenomics.com/v2/billing/groups
 https://eu-api.sbgenomics.com/v2/billing/groups
 https://gcp-api.sbgenomics.com/v2/billing/groups

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

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.

Response

Example request

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"

Example response body

{
  "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": "Pilot Funds (RFranklin)"
    }
  ],
  "links": []
}
Suggest Edits

Get a single billing group

 
gethttps://api.sbgenomics.com/v2
 

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

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path Parameters

Name
Description

billing_group
required

ID of the billing group you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

GET /v2/billing/groups/8ccc6222-ef6f-4526-99d7-9f56b716d43a HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 97a1ad73db6349a487ef77b7655edae2
curl  -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"

Example response body

{
{
  "id": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
  "href": "https://api.sbgenomics.com/v2/billing/groups/eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7",
  "owner": "RFranklin",
  "name": "Pilot Funds (RFranklin)",
  "type": "free",
  "pending": false,
  "disabled": false,
  "balance": {
    "currency": "USD",
    "amount": 0
  }
}
Suggest Edits

Get breakdown for a billing group

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdown
https://eu-api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdown
https://gcp-api.sbgenomics.com/v2/billing/groups/{billing_group}/breakdown

Billing periods

The spending will be shown for the current billing period, unless the billing group specified is a free billing group (i.e. pilot funds that you are using the Seven Bridges Platform with), in which case all spending on the account will be shown.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

billing_group

The ID of the billing group.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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"
  }
}
Suggest Edits

List invoices

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/billing/invoices
https://eu-api.sbgenomics.com/v2/billing/invoices
https://gcp-api.sbgenomics.com/v2/billing/invoices

Header Fields

Name
Description

X-SBG-Auth-Token
required

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

GET v2/billing/invoices 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 -H "Accept: application/json"

Example response body

{
    "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"
            }
        }
    ]
}
Suggest Edits

Get a specific invoice

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

invoice_id

The ID of the invoice you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
    "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"
    }
}
 
Suggest Edits

List all your projects

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects
https://eu-api.sbgenomics.com/v2/projects
https://gcp-api.sbgenomics.com/v2/projects

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

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.

Response

Example request

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"

Example response body

{
  "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": []
}
Suggest Edits

List projects owned by a particular user

 
gethttps://api.sbgenomics.com/v2
 

List the projects owned by and accessible to a particular user. Each project's ID and URL will be returned.

Request

https://api.sbgenomics.com/v2/projects/{owner}
https://eu-api.sbgenomics.com/v2/projects/{owner}
https://gcp-api.sbgenomics.com/v2/projects/{owner}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

owner

The owner whose projects you want to query.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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"
    }
  ]
}
Suggest Edits

Create a new project

 
posthttps://api.sbgenomics.com/v2
 

This call creates a new project.

Request

https://api.sbgenomics.com/v2/projects
https://eu-api.sbgenomics.com/v2/projects
https://gcp-api.sbgenomics.com/v2/projects

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

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.

Key
Datatype of value
Description of value

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 one field, locked.

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.

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.

Response

Example request

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"

Example request body

{
	"name": "My New Project", 
  "description": "A project for testing my apps", 
  "billing_group": "1f0c2751-694c-4e98-b863-06b68f5a61ca",
  "settings":{
    "locked": true
  }
}

Example response body

{
  "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
  },
  "billing_group": "1f0c2751-694c-4e98-b863-06b68f5a61ca"
}

Interpreting the response body

  • The response will include an empty list [] for the object tags. This is a legacy feature of the API, and should be ignored.
  • The field locked is set to true, 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.
Suggest Edits

Delete a project

 
deletehttps://api.sbgenomics.com/v2
 

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.

Request

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

project

The short name of the project you are deleting.

project_owner

The owner of the project you are deleting.

Response

Example request

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'
Suggest Edits

Get details of a project

 
gethttps://api.sbgenomics.com/v2
 

This call returns the details of a specified project.

Request

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.

Header Fields

Name
Description

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.

Path parameters

Name
Description

project

The short name of the project you are querying.

project_owner

The owner of the project you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Set this to _all to view all fields, including project settings.

Response

This example response body displays the JSON returned when the fields parameter in the request is set to _all.

Example request

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"

Example response body

{
  "href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project",
  "description": "project description goes here",
  "id": "RFranklin/my-project",
  "name": "My Project",
  "type": "v2",
  "settings": {
    "locked": false
  },
  "billing_group": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7"
}

Interpreting the response body

  • The object type in the response should be ignored: all projects have type v2.
  • The dictionary settings contains 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.

Suggest Edits

Edit a project

 
patchhttps://api.sbgenomics.com/v2
 

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.

Request

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.

Key
Datatype of value
Description of value

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.

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.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

project

The short name of the project you are editing.

project_owner

The owner of the project you are editing.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example request body

{
    "name": "New name for my project",
    "description": "Updated with the results of the latest experiments",
  	"settings": {
        "locked":true
    }
}

Example response body

{
  "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
    },
  "billing_group": "eb5fdee2-36c3-41d1-b179-d9f5d0a0f6f7"
}
Suggest Edits

List members of a project

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects/{owner}/{project}/members
https://eu-api.sbgenomics.com/v2/projects/{owner}/{id}/members
https://gcp-api.sbgenomics.com/v2/projects/{owner}/{project}/members

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

project

The ID of the project you are querying.

owner

The owner of the project you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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",
      "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",
      "permissions": {
        "write": false,
        "read": true,
        "copy": false,
        "execute": false,
        "admin": false
      }
    }
  ],
  "links": []
}
Suggest Edits

Add a member to a project

 
posthttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members
https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members
https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

project

The ID of the project you are adding someone to.

project_owner

The owner of the project you are adding someone to.

Query parameters

Name
Data type
Description

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.

Key
Datatype of value
Description of value

username

string

The Seven Bridges Platform username of the person you want to add to the project

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.

Response

Example request

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"

Example request body

{
    "username" : "Jane_Doe",
    "permissions": {
        "read" : true,
        "write": true,
        "execute": false
    }
}

Example response body

{
    "href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project/members/Jane_Doe",
    "username": "Jane_Doe",
    "permissions": {
        "write": true,
        "read": true,
        "copy": false,
        "execute": true,
        "admin": false
    }
}
Suggest Edits

Remove a project member

 
deletehttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Response

Example request

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" 
Suggest Edits

Get a project member's permissions

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
    "href": "https://api.sbgenomics.com/v2/projects/RFranklin/my-project1/members/Jane_Doe",
    "username": "Jane_Doe",
    "permissions": {
        "write": true,
        "read": true,
        "copy": false,
        "execute": true,
        "admin": false
    }
}
Suggest Edits

Modify a project member's permissions

 
patchhttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissions
https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissions
https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{member}/permissions

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

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.

Key
Data type of value
Description of value

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 copy permission. Set to false to remove copy 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 copy permission. Set to false to remove copy 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 copy permission. Set to false to remove copy permission.

Response

Example request

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" 

Example request body

{
      "write": true,
}

Example response body

{
  "write": true,
  "read": true,
  "copy": false,
  "execute": false,
  "admin": false
}
Suggest Edits

Overwrite a project member's permissions

 
puthttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissions
https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissions
https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/members/{username}/permissions

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

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.

Key
Data type of value
Description of value

"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 copy permission. Set to false to remove copy 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 copy permission. Set to false to remove copy 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 copy permission. Set to false to remove copy permission.

Response

Example request

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'

Example request body

{
  "read": true,
  "write": true,
  "copy": true,
  "execute": true,
  "admin": false
}

Example response body

{
  "write": true,
  "read": true,
  "copy": true,
  "execute": true,
  "admin": false
}
Suggest Edits

Files and metadata

 
Suggest Edits

List files (primary method)

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/files
https://eu-api.sbgenomics.com/v2/files
https://gcp-api.sbgenomics.com/v2/files

Alias call

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

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.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query Parameters

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

Name
Data type
Description

{project_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

tag

string

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

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

List files in the Public Reference Files repository

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

Limit your results

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

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

Response

Example requests

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

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: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=my-project&metadata.sample_id=ERR315335&origin.task=1262d968-1fda-4f06-a755-917a53a03e7e"

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

GET /v2/files?project=rfranklin/my-project&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=my-project&name=dbsnp_137.b37.vcf&name=1000G_phase1.indels.b37.vcf&name=Mills_and_1000G_gold_standard.indels.b37.sites.vcf"

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

GET /v2/files?project=rfranklin/my-project&tag=test1b&tag=my_first_project&fields=_all HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sbgenomics.com/v2/files?project=franklin/my-project&tag=test1b&tag=my_first_project"

Example response body

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

List files (secondary method)

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/projects/{project_owner}/{project}/files
https://eu-api.sbgenomics.com/v2/projects/{project_owner}/{project}/files
https://gcp-api.sbgenomics.com/v2/projects/{project_owner}/{project}/files

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 more information about identifying objects in the API, see the section on identifying objects.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "href": "https://api.sbgenomics.com/v2/files/?offset=0&limit=25&project=RFranklin/my-project",
  "items": [
    {
      "href": "https://api.sbgenomics.com/v2/files/568cf5dce4b0307bc0462060",
      "id": "568cf5dce4b0307bc0462060",
      "name": "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": []
}
Suggest Edits

Delete a file

 
deletehttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID of the file you want to delete.

Response

Example request

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"
Suggest Edits

Get file details

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

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.

Path parameters

Name
Description

file_id

The ID of the file whose details you want to GET.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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 origin denotes the task that produced the file, if it was created by a task on the Seven Bridges Platform.
  • The dictionary object metadata lists the metadata fields and values for the file.
  • The object tags lists the tags for the file. Learn more about tagging your files on the Platform.
Suggest Edits

Update file details

 
patchhttps://api.sbgenomics.com/v2
 

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.

Request

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:

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID of the file whose details you want to update.

Query parameters

Name
Data type
Description

fields

string

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

Request body

You should enter the body as key-value pairs, with the following format:

Key
Datatype of value
Description of value

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.

Response

Notice that the metadata contains only the fields specified in the request body.

Example request

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"

Example request body

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"]
}

Example response body

{
  "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 origin denotes the task that produced the file, if it was created by a task on the Seven Bridges Platform.
  • The dictionary object metadata lists the metadata fields and values for the file.
  • The object tags lists the tags for the file. Learn more about tagging your files on the Platform.
Suggest Edits

Add tags to a file

 
puthttps://api.sbgenomics.com/v2
 

This call allows you to tag files on the Platform. 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.

In addition to tagging your files, you can do the following via the API:

Request

https://api.sbgenomics.com/v2/files/{file_id}/tags
https://eu-api.sbgenomics.com/v2/files/{file_id}/tags
https://gcp-api.sbgenomics.com/v2/files/{file_id}/tags

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token 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.

Key
Datatype of value
Description of value

tags
required

String

Keywords which help you identify your files at a glance.

Response

Example request

PUT v2/files/568e69ade4b0307bc0464164/tags HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json
curl --data '{"tags": ["test 1b", "my first project", "CCLE"}'  -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X POST "https://api.sbgenomics.com/v2/files/568e69ade4b0307bc0464164/tag"

Example request body

["test 1b","my first project","CCLE"]

Example response body

[
    "test 1b",
    "my first project",
    "CCLE"
]
Suggest Edits

Copy a file

 
posthttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/files/{file_id}/actions/copy
https://eu-api.sbgenomics.com/v2/files/{file_id}/actions/copy
https://gcp-api.sbgenomics.com/v2/files/{file_id}/actions/copy

file_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)

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID for the file you are querying. It can be obtained by making the call to list your files (primary method).

Query parameters

Name
Data type
Description

fields

string

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

Request body

The body should contain the following key-value pairs:

Key
Datatype of value
Description of value

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

Example request body

{
  "project": "RFranklin/my-project", 
  "name": "new-file"
}

Response

The response gives the full specification of the file, and its metadata.

Example request

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" 

Example response body

{
  "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"
	}
}
Suggest Edits

Get downloadable URL for a file

 
gethttps://api.sbgenomics.com/v2
 

This call returns a URL that you can use to download the specified file.

Request

https://api.sbgenomics.com/v2/files/{file_id}/download_info
https://eu-api.sbgenomics.com/v2/files/{file_id}/download_info
https://gcp-api.sbgenomics.com/v2/files/{file_id}/download_info

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

fie_id

The ID of the file whose download URL you want to get.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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"
}
Suggest Edits

Get a file's metadata

 
gethttps://api.sbgenomics.com/v2
 

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 .

Request

https://api.sbgenomics.com/v2/files/{file_id}/metadata
https://eu-
api.sbgenomics.com/v2/files/{file_id}/metadata
https://gcp-api.sbgenomics.com/v2/files/{file_id}/metadata

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID of the file whose details you want to GET.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "sample_id": "E16201_pool35_L1756",
  "library_id": "hg19",
  "platform_unit_id": "C18_99",
  "platform": "IonTorrent",
  "quality_scale": "sanger"
}
Suggest Edits

Modify a file's metadata

 
patchhttps://api.sbgenomics.com/v2
 

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.

Request

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}/metadata
https://eu-api.sbgenomics.com/v2/files/{file_id}/metadata
https://gcp-api.sbgenomics.com/v2/files/{file_id}/metadata

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID of the file whose metadata you want to update.

Query parameters

Name
Data type
Description

fields

string

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

Request body

Enter a dictionary of key-value pairs to the request body.

Key
Datatype of value
Description of value

Freeform -- enter any key.

string

The value for the corresponding key

{
  "sample origin": "712345"
}

Response

Example request

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"

Example request body

Example response body

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"
}
Suggest Edits

Overwrite a file's metadata

 
puthttps://api.sbgenomics.com/v2
 

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 .

Request

https://api.sbgenomics.com/v2/files/{file_id}/metadata
https://eu-api.sbgenomics.com/v2/files/{file_id}/metadata
https://gcp-api.sbgenomics.com/v2/files/{file_id}/metadata

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

file_id

The ID of the file whose details you want to overwrite.

Query parameters

Name
Data type
Description

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.

Key
Datatype of value
Description of value

Freeform -- enter any string

string

The value for the corresponding key

Response

Example request

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"

Example request body

{
    "foo": "bar",
    "my_key_1": "my_value_1",
    "my_key_2": "my_value_2",
    "platform": "my_platform",
    "library_id": "12345"
}

Example response body

{
  "library_id": "12345",
  "platform": "my_platform",
  "foo": "bar",
  "my_key_1": "my_value_1",
  "my_key_2": "my_value_2"
}
Suggest Edits

Upload files

 
Suggest Edits

List current multipart uploads

 
gethttps://api.sbgenomics.com/v2
 

This call returns the list of ongoing uploads.

Request

https://api.sbgenomics.com/v2/upload/multipart
https://eu-api.sbgenomics.com/v2/upload/multipart
https://gcp-api.sbgenomics.com/v2/upload/multipart

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Response

Example request

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"

Example response body

{
  "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"
    }
  ]
}
Suggest Edits

Get details of a multipart upload

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Path parameters

Name
Description

upload_id

The ID of the upload. It can be obtained by initializing a new upload or by listing the ongoing multipart uploads.

Query parameters

Name
Datatype
Description

list_parts

Boolean: true or false

If true, also return a list of parts that have been reported as completed for this multipart upload.

Response

Example request

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"

Example response body

{
  "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"
        }
      }
    }
  ]
}
Suggest Edits

Initialize a multipart upload

 
posthttps://api.sbgenomics.com/v2
 

This call initializes a multipart file upload.

Request

https://api.sbgenomics.com/v2/upload/multipart
https://eu-api.sbgenomics.com/v2/upload/multipart
https://gcp-api.sbgenomics.com/v2/upload/multipart

Only the following characters are allowed in file names:

  • alphanumeric characters (lowercase and uppercase letters of the English alphabet and numbers 0 - 9),
  • underscore (_),
  • dash (-),
  • dot (.).

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Query parameters

Name
Datatype
Description

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.

Key
Datatype of value
Description of value

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.

Response

Example request

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"

Example response body

{
  "project": "RFranklin/my-project",
  "name": "CanFam3.1.dna_rm.toplevel.fa.gz",
  "size": 433759572,
  "upload_id": "oSZ5rOjMQa34UykB4FiPdhkCalLVrcQjxjKPkAT69skWgOPlOvcvGaqEJ7SI1o4w",
  "part_size": 5242880,
  "parallel_uploads": true
}
Suggest Edits

Get upload URL for a file part

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Path parameters

Name
Description

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

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

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:

Key
Data type
Description

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.

Key
Data type
Description

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

Example request

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"

Example response body

{
  "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"
    ]
  }
}
Suggest Edits

Report an uploaded part

 
posthttps://api.sbgenomics.com/v2
 

This call allows you to report the upload of a file part.

Request

https://api.sbgenomics.com/v2/upload/multipart/{upload_id}/part
https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}/part
https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}/part

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Path parameters

Name
Description

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.

Key
Datatype of value
Description of value

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.

Key
Datatype of value
Description of value

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"
    }
  }
}

Response

Example request

POST /v2/upload/multipart/ezBaGmsWvyLwLjDdw3WNXXfs0EK4GpcHXijP37fP7o1jbdh24IAFEF7New5wYyli/part HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl --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"

Example request body

Suggest Edits

Report uploaded parts

 
posthttps://api.sbgenomics.com/v2
 

This call allows you to report the upload multiple file parts at once.

Request

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}

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application_json

Path parameters

Name
Description

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.

Key
Datatype of value
Description of value

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.

Response

Example request

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"

Example request body

{
  "parts": [
    {
      "part_number": 1,
      "response": {
        "headers": {
          "ETag": "9f1b6da2989615a414e8b00a27d20b0c"
        }
      }
    },
    {
      "part_number": 2,
      "response": {
        "headers": {
          "ETag": "266f8e5c06b6cc1495646fc48b3f2f0e"
        }
      }
    }
  ]
}
Suggest Edits

Complete a multipart upload

 
posthttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/upload/multipart/{upload_id}/complete
https://eu-api.sbgenomics.com/v2/upload/multipart/{upload_id}/complete
https://gcp-api.sbgenomics.com/v2/upload/multipart/{upload_id}/complete

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Path parameters

Name
Description

upload_id

The ID for the upload, returned by the call to initialize a multipart upload.

Response

Example request

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"

Example response body

{
  "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"
}
Suggest Edits

Abort a multipart upload

 
deletehttps://api.sbgenomics.com/v2
 

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}

Request

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Content-Type
required

application/json

Path parameters

Name
Description

upload_id

The ID for the upload, returned by a call to initialize a multipart upload or to list current multipart uploads.

Response

Example request

DELETE /v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm 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 DELETE "https://api.sbgenomics.com/v2/upload/multipart/X5FXjV7JVCdg0cidZKIOOZRvAgahy9znuHq1PMsOZ85de6x53UOcJAcCDXANVTpm"

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

Suggest Edits

List all apps available to you

 
gethttps://api.sbgenomics.com/v2
 

This call lists all the apps available to you.

Request

https://api.sbgenomics.com/v2/apps
https://eu-api.sbgenomics.com/v2/apps
https://gcp-api.sbgenomics.com/v2/apps

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

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.

project_owner

string

Enter a Seven Bridges Platform username to restrict the results to apps from that user's projects only. Note that you can only see apps within projects that you are a member of.

visibility

string

Set this to public to see all public apps on the Seven Bridges Platform.

Response

Example request

GET /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" 

Example response body

{
  "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"
    },
  ]
}
Suggest Edits

Get details of an app

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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
  }
}
Suggest Edits

Copy an app

 
posthttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/apps/{app_id}/actions/copy
https://eu-api.sbgenomics.com/v2/apps/{app_id}/actions/copy
https://gcp-api.sbgenomics.com/v2/apps/{app_id}/actions/copy

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

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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

Query parameters

Name
Data type
Description

fields

string

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

Request body

The body should contain the following key-value pairs:

Key
Datatype of value
Description of value

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

Response

Example request

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"

Example request body

{
  "project": "RFranklin/my-project", 
  "name": "new app name"
}

Example response body

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.

Suggest Edits

Get raw CWL for an app

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/apps/{app_id}/raw
https://eu-api.sbgenomics.com/v2/apps/{app_id}/raw
 https://gcp-api.sbgenomics.com/v2/apps/{app_id}/raw

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

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

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

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"
}
Suggest Edits

Add an app using raw CWL

 
posthttps://api.sbgenomics.com/v2
 

This call allows you to add an app using raw CWL.

https://api.sbgenomics.com/v2/apps/{app_id}/raw
https://eu-api.sbgenomics.com/v2/apps/{app_id}/raw
https://gcp-api.sbgenomics.com/v2/apps/{app_id}/raw

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

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.

Request

Example request

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

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 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"
Suggest Edits

Get raw CWL for an app revision

 
gethttps://api.sbgenomics.com/v2
 

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}/raw
https://eu-api.sbgenomics.com/v2/apps/{app_id}/raw
https://gcp-api.sbgenomics.com/v2/apps/{app_id}/raw

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

Request

Example request

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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

Query parameters

Name
Data type
Description

fields

string

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

Response

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

Example response body

Note that this call returns the full CWL description of the app.

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"
}
Suggest Edits

Get details of an app revision

 
gethttps://api.sbgenomics.com/v2
 

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

Request

Example request

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

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" }
}
}
}
}
Suggest Edits

Add an app revision using raw CWL

 
posthttps://api.sbgenomics.com/v2
 

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}/raw
https://eu-api.sbgenomics.com/v2/apps/{app_id}/raw
https://gcp-api.sbgenomics.com/v2/apps/{app_id}/raw

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

For this particular call, you need to explicitly specify the app revision number.

Request

Example request

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

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.

Query parameters

Name
Data type
Description

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"
Suggest Edits

List tasks you can access (primary method)

 
gethttps://api.sbgenomics.com/v2
 

This call returns a list of tasks that you can access.

Request

https://api.sbgenomics.com/v2/tasks
https://eu-api.sbgenomics.com/v2/tasks
https://gcp-api.sbgenomics.com/v2/tasks

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

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:

  1. <yyyy-MM-dd>T<HH:mm:ss>+/-<HH:mm> (use this format to specify the UTC offset, see below)
  2. yyyy-MM-ddTHH:mm:ss
  3. yyyy-MM-dd (when this format is used, the implicit time is 00:00:00)
Parameter
Description

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:

  1. 2016-04-01T14:25:50+01:00 - Fri Apr 01 13:25:50 UTC 2016
  2. 2016-04-01T14:25:50 - Fri Apr 01 14:25:50 UTC 2016
  3. 2016-04-01 - Fri Apr 01 00:00:00 UTC 2016

Response

Example request

GET /v2/tasks 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"

Example response body

{
  "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": "",
      "status": "Completed"
    }
  ]
}
Suggest Edits

Create a new draft task

 
posthttps://api.sbgenomics.com/v2
 

This call creates a new task.

Request

https://api.sbgenomics.com/v2/tasks
https://eu-api.sbgenomics.com/v2/tasks
https://gcp-api.sbgenomics.com/v2/tasks

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Query parameters

Name
Data type
Description

fields

string

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

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.

Batch tasks

This API call can be used to create and run batch tasks. You can either use 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.

Key
Datatype of value
Description of value

"name"

string

The name of the task

"description"

string

An optional description of the task

"project"

string

The short name of the project that you want to create the task in

"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_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.

  1. 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" }

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

Response

See a list of Seven Bridges Platform-specific response codes that may be contained in the body of 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).
The following key-value pairs in the response body indicate the batch status of the task:

Key
Datatype of value
Description

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

  1. 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": {} }

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

Example request

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"

Example request body

{   "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"
        }
    }
}

Example response body

{
  "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",
  "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
  }
}
Suggest Edits

Delete a task

 
deletehttps://api.sbgenomics.com/v2
 

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.

Request

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.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id
required

The ID of the task you are deleting. See the section on specifying tasks for details.

Response

Example request

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"
Suggest Edits

Get task inputs

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/tasks/{task_id}/inputs
https://eu-api.sbgenomics.com/v2/tasks/{task_id}/inputs
https://gcp-api.sbgenomics.com/v2/tasks/{task_id}/inputs

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id
required

The ID of the task you are querying.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
    "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
}
Suggest Edits

Abort a task

 
posthttps://api.sbgenomics.com/v2
 

This call aborts the specified task. Only tasks whose status is "RUNNING" or "QUEUED" may be aborted.

Request

https://api.sbgenomics.com/v2/tasks/{task_id}/actions/abort
https://eu-api.sbgenomics.com/v2/tasks/{task_id}/actions/abort
https://gcp-api.sbgenomics.com/v2/tasks/{task_id}/actions/abort

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id

The ID of the task you are acting on.

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
  "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",
  "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
    }
  }
}
Suggest Edits

Get details of a task

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

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.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges authentication token.

Path parameters

Name
Description

task_id
required

The ID of the task you are querying

Query parameters

Name
Data type
Description

fields

string

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

Response

See a list of Seven Bridges Platform-specific response codes that may be contained in the body of 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).
The following key-value pairs in the response body indicate the batch status of the task:

Key
Datatype of value
Description

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

  1. 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": {} }

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

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:

No.
Validation error type
Validation message
Comment

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.

Example request

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"

Example of the `"errors"` array, contained in the response body:

"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"
    }
  ]

Example response body for a non-batch task (i.e. one initiated with the `batch` query parameter set to `false`.

{
  "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",
  "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": 1,
    "steps_total": 1,
    "message": "Running"
  },
  "price": {
    "currency": "USD",
    "amount": "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"
    }
  }
}

Example response body for a batch task (i.e. a parent 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": {
        "message": "Aborted",
        "queued": 0,
        "running": 0,
        "completed": 0,
        "failed": 0,
        "aborted": 0
    },
    "price": {
        "currency": "USD",
        "amount": "0.00"
    },
    "inputs": {
        "Known_SNPs": [
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13bf",
                "name": "dbsnp_137.b37.vcf"
            }
        ],
        "Known_Indels": [
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13b7",
                "name": "1000G_phase1.indels.b37.vcf"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13c2",
                "name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
            }
        ],
        "Target_BED": {
            "class": "File",
            "path": "5702cd5a60b27cfe6e8c13c7",
            "name": "exome_targets.b37.bed"
        },
        "SnpEff_Database": {
            "class": "File",
            "path": "5702cd5a60b27cfe6e8c13c8",
            "name": "snpEff_v3_6_GRCh37.75.zip"
        },
        "Reference": {
            "class": "File",
            "path": "5702cd5a60b27cfe6e8c13b8",
            "name": "human_g1k_v37_decoy.fasta"
        },
        "FASTQ": [
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13c0",
                "name": "C18-146.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13d0",
                "name": "C18-99.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13c9",
                "name": "C24-141.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13c1",
                "name": "C27-190.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13bb",
                "name": "C28-139.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13ca",
                "name": "C29-97.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13bd",
                "name": "C30-101.fastq"
            },
            {
                "class": "File",
                "path": "5702cd5a60b27cfe6e8c13cf",
                "name": "C30-126.fastq"
            }
        ]
    }
}
Suggest Edits

Modify a task

 
patchhttps://api.sbgenomics.com/v2
 

This call allows you to change the 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.

You can change a task's name, description, and inputs.

Specifying task inputs

See the section on task inputs for details on how to refer to a task's inputs.

Request

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}

Modifying tasks

Note that you can only modify tasks with a task status of DRAFT, not those with statuses RUNNING, QUEUED, ABORTED, COMPLETED or FAILED. This feature is to enable reproducibility of any analysis that has been queued for execution or has initiated executing.

See below for an example of the content of the request, sent here as modify-task.json.

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id
required

The ID of the task you are querying

Query parameters

Name
Data type
Description

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, as explained below:

Key
Datatype of value
Description of value

"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_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.

  1. 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" }

  2. 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_input and batch_by parameters together in the same PATCH request.

If you want to disable batching on a task, set the parameters batch_input and batch_by to the JSON null value, as follows:

{
    "batch_input": null,
    "batch_by" : null    
}

Response

Example request

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"

Example request body

{
  "name": "new name for my task",
  "description": "re-describing the task",
  "inputs": {

        "cuffdiff_zip": {
            "class": "File",
            "path": "562785e6e4b00a1d67a8b1aa",
            "name": "example_human_known_indels.vcf"
        }
}

Example response body

{
  "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": "DRAFT",
  "project": "RFranklin/my-project",
  "app": "RFranklin/my-project/new/0",
  "type": "v2",
  "created_by": "RFranklin",
  "start_time": "2016-01-12T18:39:30Z",
  "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
  }
}
Suggest Edits

Get task execution details

 
gethttps://api.sbgenomics.com/v2
 

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.

Request

https://api.sbgenomics.com/v2/tasks/{task_id}/execution_details
https://eu-api.sbgenomics.com/v2/tasks/{task_id}/execution_details
https://gcp-api.sbgenomics.com/v2/tasks/{task_id}/execution_details

The 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, or RUNNING)
  • 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')

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id
required

The ID of the task you are querying

Query parameters

Name
Data type
Description

fields

string

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

Response

Example request

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"

Example response body

{
	"href": "https://api.sbgenomics.com/v2/tasks/a2bb05fd-46db-4035-a270-c88297fb2b7c/execution_details",
	"start_time": "2016-03-23T14:41:59Z",
	"status": "RUNNING",
	"message": "Waiting for computational resources...",
	"jobs": [{
		"name": "SBG_FASTQ_Quality_Detector/0",
		"start_time": "2016-03-23T15:12:09Z",
		"end_time": "2016-03-23T15:12:45Z",
		"status": "DONE",
		"command_line": "python /opt/sbg_fastq_quality_scale_detector.py --fastq /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/C18-146.fastq",
		"instance": {
			"id": "i-e3f1af60",
			"type": "c3.2xlarge",
			"provider": "AWS"
		},
		"docker": {
			"checksum": "ff9c104102ff5cdec283210ef0dc4a8347136aa9e77661803165da780958d7a5"
		},
		"logs": {

			"stderr": "https://api.sbgenomics.com/v2/files/56e2b26760c283d0531b21f1/download_info"
		}
	}, {
		"name": "BWA_MEM_Bundle",
		"start_time": "2016-03-23T15:14:38Z",
		"status": "RUNNING",
		"command_line": "python /opt/scripts/bwa_mem_bundle.py bwa mem -t 8 -M --output_format SortedBAM --remove_dups MarkDuplicates --total_memory 15 --filter_sec -R '@RG\tID:1\tLB:hg19\tPL:IonTorrent\tPU:C18-146\tSM:E18495-pool40a-L2888' /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/human_g1k_v37_decoy.fasta /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/a2cc05fd-46db-4035-a270-c66297fb2b7c/whole-exome-sequencing-gatk-2-3-9-lite_SBG_FASTQ_Quality_Converter_0_s/C18-146.std.fastq",
		"instance": {
			"id": "i-e3f1af60",
			"type": "c3.2xlarge",
			"provider": "AWS"
		},
		"docker": {
			"checksum": "559257ac23e82b5d7115c63101297b8b44dd8962a11688c22e1cb2280fed3947"
		},
		"logs": {
			"stderr": null
		}
	}, {
		"name": "FastQC/0",
		"start_time": "2016-03-23T15:12:08Z",
		"end_time": "2016-03-23T15:13:14Z",
		"status": "DONE",
		"command_line": "fastqc --noextract --outdir . --quiet --threads 4 /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/C18-146.fastq",
		"instance": {
			"id": "i-e3f1af60",
			"type": "c3.2xlarge",
			"provider": "AWS"
		},
		"docker": {
			"checksum": "b5a75cf9ae8b0b0e5b465ffb037bbd909205bbc646225cf24564e3132fca5ae3"
		},
		"logs": {
			"stderr": "https://api.sbgenomics.com/v2/files/56f2b28560b2e9392b02825f/download_info"
		}
	}, {
		"name": "SBG_FASTQ_Quality_Converter/0",
		"start_time": "2016-03-23T15:12:54Z",
		"end_time": "2016-03-23T15:13:26Z",
		"status": "DONE",
		"command_line": "python /opt/sbg_fastq_quality_converter.py -f /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/a2cc05fd-46db-4035-a270-c66297fb2b7c/whole-exome-sequencing-gatk-2-3-9-lite_SBG_FASTQ_Quality_Detector_0_s/C18-146.fastq -s auto",
		"instance": {
			"id": "i-e3f1af60",
			"type": "c3.2xlarge",
			"provider": "AWS"
		},
		"logs": {
			"output.log": "https://api.sbgenomics.com/v2/files/56f2b443tdd83c6735c9d/download_info",
			"stderr": "https://api.sbgenomics.com/v2/files/56f2b29460b23d83c6735c9d/download_info"
		}
	}, {
		"name": "SBG_Html2b64/0",
		"start_time": "2016-03-23T15:13:25Z",
		"end_time": "2016-03-23T15:13:58Z",
		"status": "DONE",
		"command_line": "python /opt/sbg_html_to_b64.py --input /sbgenomics/Projects/e88733b6-3a43-44ff-b882-9f75d02f397c/a2cc05fd-46db-4035-a270-c66297fb2b7c/whole-exome-sequencing-gatk-2-3-9-lite_FastQC_0_s/C18-146_fastqc.zip",
		"instance": {
			"id": "i-e3f1af60",
			"type": "c3.2xlarge",
			"provider": "AWS"
		},
		"docker": {
			"checksum": "a657c637fc53126eeb33b69cbde52252a330a224795c48fec74499a71eb4dd54"
		},
		"logs": {
			"stderr": "https://api.sbgenomics.com/v2/files/56f2b2b360b283d0531b220e/download_info"
		}
	}]
}
Suggest Edits

Run a task

 
posthttps://api.sbgenomics.com/v2
 

This call runs (executes) the specified task. Only tasks whose status is "DRAFT" can be run.

Request

https://api.sbgenomics.com/v2/tasks/{task_id}/actions/run
https://eu-api.sbgenomics.com/v2/tasks/{task_id}/actions/run
https://gcp-api.sbgenomics.com/v2/tasks/{task_id}/actions/run

Header Fields

Name
Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name
Description

task_id

The ID of the task you are acting on.

Query parameters

Name
Data type
Description

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.

Response

Example request

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"

Example response body

{
  "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",
  "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,