API Reference

The BaseSpace API is a set of REST service endpoints that answer queries on resources and return responses in JSON format. This page describes the V1 API; for information about V2 API, see V2 API Reference.

The API follows a different pattern whether an app is requesting an individual resource or a collection of resources.

OAuth Process

Before an application can access a user's data, the user must authorize access for an application. This is done by using the OAuth 2.0 process. An app can be launched in a two ways:

  • From the app store or without a context
  • From a Project, Sample, or AppResult which is called App triggering

When an app is triggered with a context, it will use the App Triggering Guide. If it then requires more access to a user's data, it will need to go through the Obtaining Access Tokens step to get a new authorization_code with a new scope.

An app may also be launched without a context, in which case it would need to first redirect the user to the OAuth dialog with the required access scope and after the user grants access the app would receive the authorization_code as a url parameter in the redirect.

The authorization_code is then exchanged for an access_token, this access_token ispassed with each API request.

More information about these processes can be found in the Obtaining Access Tokens and App Triggering portions of this site.

Using the Access Token

Use the access_token associated with the user for each request you make to the API on behalf of that user.

We allow three techniques for including the access_token in your request:

  • In the header x-access-token
  • In the header Authorization. The value must take the form: Bearer {access_token} (with a space between Bearer and the code).
  • With the query parameter access_token.

Make sure that you’re not sending the BaseSpace session cookie IComLogin with the request when using an access_token.

Note: Access tokens do not expire automatically.

URI format

The BaseSpace API encodes the version of the API in the resource URI. This guarantees that a given API will always behave the same, even if we introduce newer APIs. Example:

/v1pre3/users/current

This path refers to API version v1pre3.

Individual Resource Requests

Requests for an individual resource often encode the resource identifier (Id) or other parameters as part of the resource path within curly braces {}. For example,

/v1pre3/project/{Id}

This will request information about an individual project by its Id. Keep in mind though that although some Id's will appear numeric, treat them as an opaque string.

Resource Collection Requests

Requests for collections do not contain a resource identifer in the last position, but may contain one earlier. For example:

/v1pre3/projects/{Id}/samples

returns a list of samples in the specified project, whereas:

/v1pre3/users/{Id}/projects

returns a list of all projects accessible by the user.

For requests returning collections, these query parameters are common:

  • Offset: The starting point of the collection to read, there is no maximum value for Offset. Default: 0

  • Limit: The maximum number of items to return. This value may be less than requested if the request size was reduced by the server. Default: 10, Range: 0-1024, the implicit Range of Limit for the Files resource is 0-1000.

  • SortDir: The way to sort the resulting collection, either ascending or descending. Default: 'Asc', Can be 'Asc' or 'Desc'

  • SortBy: The field to use to sort the resulting collection. This value can have multiple possibilities depending on the result type

The response will also contain these fields unless noted otherwise:

  • DisplayedCount: The number of items returned
  • TotalCount: The total number of items in the collection

Common Response Elements

These are included for all response types. In addition to Resource Collection Requests if applicable.

  • Response - The main response object

    • Items: If a list is returned, it is contained within this response element
    • Id: Id of the resource
    • Name: Name of the selected resource
    • Href: Location of the resource in the API
    • DateCreated: When this resource was created
    • UserOwnedBy: Information about the User who owns this resource
    • Status: The status of the resource, if it is inside of an appsession it is the status of the AppSession
    • HrefBaseSpaceUI: The location of this resource in the BaseSpace User Interface
    • Properties: The Properties of this resource. Some Properties are standard in BaseSpace and some are custom Properties created by Users or Apps.
  • ResponseStatus - Empty for responses with a 200 response code. For error cases, contains human-readable description of the error. The documentation on the error cases is not yet complete.

  • Notifications - An array of notifications. Documentation on this element is not complete.

Available Permissions

  • BROWSE - The ability to see resource metadata, but not download or change any content
  • READ - The ability to read or download this resource. In most cases BROWSE is included within READ.
  • CREATE - The ability to add to this resource.
  • WRITE - The ability to add to or change this resource. In most cases BROWSE and READ are included within WRITE.

For more information about the available permissions, please refer to the BaseSpace Permissions.

API Rate Limitations

There are some limitations on how many requests can be made to certain API endpoints.

All API responses that match an API Rate Limiting rule will include usage and limit information in the form of custom headers of the API response. If a request doesn't match any rate limiting rules, then the headers are NOT included in the response.

It's important to note that the rate limit information applies only to API requests that match the specified limit rule/policy and not globally since different API requests may have different rate limits.

The following headers are now provided in the response from each API endpoint that is subject to rate limitations. These limitations are tied to each user, the user is found from the access token that is used to make the request.

Header Name Description
X-RateLimit-Policy The name of the policy/rule that applied for this API request
X-RateLimit-Limit For the applicable policy, the maximum number of requests that the user is permitted to make in the current rate limit window before usage is restricted
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The UTC date/time when the rate limit usage for this policy will be reset
X-Retry-After This is included when the request is rejected. It will return the number of seconds that the client should wait before retrying this request

If an API request exceeds the rate limit, the response returns an error with status code 429 (Too Many Requests). These limitations are per day.


API Resources and Methods

The following sections cover the resources supported by the BaseSpace API. The usage is illustrated by example output for each request.

OAuthv2 Token

The OAuthv2 Token is the access_token that the authorization_code is exchanged for after a user grants an app permission to data. Please refer to Obtaining Access Tokens for more information about these authorization methods.

GET: oauthv2/token/current

This request must be authenticated with an access_token and is used to see the current permissions on the access token that is specified in the above call.

Query Parameters

  • access_token: The token that is passed by the app when making a call to the user's data. The response will contain the permissions tied to the specified access_token.

For example, to find details about the access_token with Id c0d5d22251c2461d891813a3378f7de2, we can use the folliwng request:

GET http://api.basespace.illumina.com/v1pre3/oauthv2/token/current?access_token={token}

{
    "Response": {
        "AccessToken": "{token}",
        "Application": {
        "Id": "565566",
        "Href": "v1pre3/applications/565566",
        "Name": "Example App",
        "ShortDescription": "Short Description",
        "DateCreated": "2014-05-06T23:41:43.0000000",
        "IsBillingActivated": false
        },
        "UserResourceOwner": {
        "Email": "johndoe@gmail.com",
        "DateLastActive": "2014-07-28T22:38:06.0000000",
        "DateCreated": "2012-08-14T18:44:45.0000000",
        "HrefRuns": "v1pre3/users/123/runs",
        "HrefProjects": "v1pre3/users/123/projects",
        "Id": "569571",
        "Href": "v1pre3/users/123",
        "Name": "John Doe",
        "GravatarUrl": "https://secure.gravatar.com/avatar/300fb1f0db0919def56fdbe4f1a19525.jpg?s=20&d=https%3a%2f%2fbasespace.illumina.com%2fpublic%2fimages%2fDefaultCustomerGravatar.png&r=PG"
        },
        "Status": "ACTIVE",
        "DateCreated": "2014-05-06T23:41:43.0000000",
        "Scopes": [
        "CREATE GLOBAL",
        "BROWSE GLOBAL",
        "CREATE PROJECTS",
        "READ PROJECT 2"
        ]
    },
    "ResponseStatus": {},
    "Notifications": []
}

POST: oauthv2/token

This request must be authenticated with your client_id and client_secret. You may provide these credentials encoded via the standard Authorization header or in the body (but not both).

The request should have the standard content-type of application/x-www-form-urlencoded used for form POSTs.

Response Elements

  • access_token: The token that is passed by the app when making a call to the user's data

Query Parameters:

  • code (required): The authorization_code from the previous step.
  • redirect_uri (required): The redirect_uri for the application that you’ve provided in the previous step.
  • grant_type (required): Must be the value authorization_code
  • client_id: If not using the Authorization header
  • client_secret: If not using the Authorization header

Example curl request using the Authorization header approach:

curl -v -u {YOUR CLIENT_ID}:{YOUR CLIENT_SECRET} \
-d "code={YOUR AUTHORIZATION CODE}" \
-d "redirect_uri={YOUR REDIRECT_URI}" \
-d "grant_type=authorization_code" \
https://api.basespace.illumina.com/v1pre3/oauthv2/token

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 07 Mar 2012 14:50:42 GMT
Content-Length: 105

{
    "access_token":"{YOUR ACCESS TOKEN}"
}

If you get a status code 200 response, the JSON document will include your access_token. Otherwise, the response will include an error_code and an error_description to help you figure out the problem.

POST: oauthv2/deviceauthorization

This request is the authorization flow for non Web-based apps. Please refer to Obtaining Access Tokens for more information about this authorization method.

Response Elements:

  • verification_uri: This URI is to be displayed to the user for performing the access grant. There, the user will type the user_code.

  • verification_with_code_uri: If your app is able to open a browser window automatically, this URI may be used. It's same as above except it eliminates the need for the user to type in a code.

  • user_code: This code may be given to the user to type in manually into the verification_uri above.

  • expires_in: This is the time in seconds during which the full flow must complete.

  • device_code: This code is used for the next step of retrieving an access_token. There's no need to share this with the user.

  • interval: This is the minimum time to pause between polling requests in the next step.

Query Parameters:

  • client_id (required): available in the application management screen
  • response_type (required): must be the value device_code
  • scope (optional): the set of permissions and resources being requested. Refer to BaseSpace Permissions.

Example curl request:

curl -v \
-X POST \
-d "response_type=device_code" \
-d "client_id={YOUR CLIENT ID}" \ 
-d "scope=browse global" \
https://api.basespace.illumina.com/v1pre3/oauthv2/deviceauthorization

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 28 Jun 2012 14:52:37 GMT
Content-Length: 250

{
    "verification_uri":"https://basespace.illumina.com/oauth/device",
    "verification_with_code_uri":"https://basespace.illumina.com/oauth/device?code=b9bac",
    "user_code":"b9bac",
    "expires_in":1800,
    "device_code":"dd0e45ebc98c440cb8e369a85be0344a",
    "interval":1
}

Then use the POST: oauthv2/token method to exchange the device_code for the access_token.

Users

The User resource is provided so that an app can get basic information about the user that is using the application.

Response Elements in addition to Common Response Elements excluding Properties

  • Email: Current user's email address
  • HrefRuns: The runs that the user owns or has access to
  • HrefProjects: The projects that the user owns or has access to

GET: users/current

GET https://api.basespace.illumina.com/v1pre3/users/current
{
   "Response":{
      "Email":"jdoe@domain.com",
      "GravatarUrl": "https://secure.gravatar.com/avatar.....",
      "DateLastActive":"2012-03-20T19:57:56.0000000",
      "DateCreated":"2011-12-17T00:50:29.0000000",
      "HrefRuns":"v1pre3/users/1001/runs",
      "HrefProjects":"v1pre3/users/1001/projects",
      "Id":"1001",
      "Href":"v1pre3/users/1001",
      "Name":"John Doe"
   },
   "ResponseStatus":{
   },
   "Notifications":[
   ]
}   

Runs

Processing a flow cell on a sequencing instrument produces a variety of files, collectively referred to as a Run. A Run contains logfiles, instrument health data, and run metrics as well as the base call and other information used in secondary analysis.

Response Elements in addition to Common Response Elements

  • HrefFiles: The location of the run's files in the API
  • HrefSamples: The location of the run's samples in the API
  • UserUploadedBy: Information about the user who uploaded the run
  • DateUploadCompleted: The date when the upload was completed
  • DateUploadStarted: The date when the upload was started
  • ExperimentName: The name of the experiment, set by the user who uploads the run
  • Status: The status of the Run

GET: runs/{Id}

Retrieve a specific run by its Id

Permissions

  • BROWSE access to the Run

To retrieve the run with Id 1019:

GET https://api.basespace.illumina.com/v1pre3/runs/1019
{
    "Response": {
        "Name": "110512_COnfig376vm0a_0432_AFCPE151RHO",
        "Number": 0,
        "HrefFiles": "v1pre3/runs/1019/files",
        "HrefSamples": "v1pre3/runs/1019/samples",
        "UserUploadedBy": {
            "Id": "1003",
            "Href": "v1pre3/users/1003",
            "Name": "Jane Doe"
        },
        "UserOwnedBy": {
            "Id": "1003",
            "Href": "v1pre3/users/1003",
            "Name": "Jane Doe"
        },
        "DateUploadCompleted": "2011-11-11T03:30:10.0000000",
        "DateUploadStarted": "2011-11-11T03:04:58.0000000",
        "HrefBaseSpaceUI": "https://basespace.illumina.com/run/1019/2X151 Rhodobacter Resequencing",
        "Id": "1019",
        "Href": "v1pre3/runs/1019",
        "ExperimentName": "2X151 Rhodobacter Resequencing",
        "Status": "Complete",
        "DateCreated": "2011-11-11T02:56:38.0000000"
    },
    "ResponseStatus": {},
    "Notifications": []
}

GET: users/current/runs

Retrieve a list of runs accessible by the user current user

Permissions

  • BROWSE access to the runs the current user has access to

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id or DateCreated. Default: Id
  • Statuses: Optionally filter by run statuses. Multiple values may be provided separated by commas, e.g. Statuses=Running, Complete. Default: No filter. Possible values include:

    • Running: This state is active when the instrument is running.
    • Paused: This state is active when an instrument run has been paused.
    • Stopped: This state is active when an instrument run has been stopped.
    • Uploading: This state is active after an instrument run has completed but files are still uploading.
    • PendingAnalysis: This state is active after the file upload has completed and before the AppResult has started.
    • Analyzing: This state is active while an analysis is running.
    • Complete: This is the state after a successful analysis.
    • Failed: This is the state after a failed AppResult.
    • NeedsAttention: A run/appresult is placed in this state when the sample sheet has failed validation. Sample sheet validation happens after the sample sheet is uploaded.

To retrieve a list of all completed runs available to the current user, sorted by Id in ascending order with a limit of 10 and an offset of 0:

GET https://api.basespace.illumina.com/v1pre3/users/174174/runs?Statuses=complete&SortBy=Id&Offset=0&Limit=10&SortDir=Asc
{
   "Response": {
        "Items" : [
           {
                "Id": "1019",
                "Href": "v1pre3/runs/1019",
                "ExperimentName": "2X151 Rhodobacter Resequencing",
                "Status": "Complete",
                "DateCreated": "2011-11-11T02:56:38.0000000"
           },
           {
                "Id": "1021",
                "Href": "v1pre3/runs/1021",
                "ExperimentName": "2x26 Validation Human 4-Plex",
                "Status": "Complete",
                "DateCreated": "2011-11-11T02:56:48.0000000"
           }
       ],
       "SortBy":"Id",
       "DisplayedCount":2,
       "TotalCount":2,
       "Offset":0,
       "Limit":10,
       "SortDir":"Asc"
    },
   "ResponseStatus":{
   },
   "Notifications":[
   ]
}

DELETE: runs/{id}

See Trash Apis in the Trash Api section

Projects

Projects are the fundamental unit of organization in BaseSpace. Users may create projects, place items into projects, and share projects (and their contents) with other users.

Projects may contain collections of Samples and AppResults.

Response Elements in addition to Common Response Elements

  • HrefSamples: The href to the samples inside of this project
  • HrefAppResults: The href to the appresults in this project
  • TransferPending: A boolean value which determines whether the Project is being transferred. If true, the Project has been transferred to another user and is awaiting acceptance from that user. Once the user accpets the Project transfer, they will become the new Owner of the Project. If false, the Project is not being transferred.

GET: projects/{Id}

To retrieve a specific project by its Id

Permissions

  • BROWSE access to the project

Example request to access project Id 1:

GET https://api.basespace.illumina.com/v1pre3/projects/1
{
    "Response": {
        "HrefSamples": "v1pre3/projects/1/samples",
        "HrefAppResults": "v1pre3/projects/1/appresults",
        "HrefBaseSpaceUI": "https://basespace.illumina.com/project/1/HiSeq 2500",
        "Id": "1",
        "UserOwnedBy": {
            "Id": "1001",
            "Href": "v1pre3/users/1001",
            "Name": "John Doe"
        },
        "Href": "v1pre3/projects/1",
        "Name": "HiSeq 2500",
        "DateCreated": "2012-06-01T16:13:06.0000000"
    },
    "ResponseStatus": {},
    "Notifications": []
}

GET: users/current/projects

Retrieve a list of projects that the user owns or has been invited to

Permissions

  • BROWSE access to the project for it to be visible in this listing

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: Id
  • Name: The name of a Project. This call will return Projects with the given Name for the current user

To retrieve a list of projects acessible to the current user, in ascending order sorted by Id, and with a maximum of 2 results starting from the beginning of the list:

GET https://api.basespace.illumina.com/v1pre3/users/current/projects?SortBy=Id&Offset=0&Limit=2&SortDir=Asc
{
    "Response":{
        "Items":[
            {
                "Id":"52",
                "UserOwnedBy":{
                    "Id":"74074",
                    "Href":"v1pre3/users/1001",
                    "Name":"John Doe"
                },
                "Href":"v1pre3/projects/1",
                "Name":"CurrentWork",
                    "DateCreated":"2012-06-01T16:13:06.0000000"
            },
            {
                "Id":"53",
                "UserOwnedBy":{
                    "Id":"74074",
                    "Href":"v1pre3/users/1001",
                    "Name":"John Doe"
                },
                "Href":"v1pre3/projects/2",
                "Name":"FutureWork",
                        "DateCreated":"2012-06-03T16:13:06.0000000"
            }
        ],
        "DisplayedCount":2,
        "TotalCount":15,
        "Offset":0,
        "Limit":2,
        "SortDir":"Asc",
        "SortBy":"Id"
    },
    "ResponseStatus":{},
    "Notifications":[]
}

POST: projects

Create a project for the current user. Please refer to the Writing Back to BaseSpace Guide for details on creating Projects.

Permissions

  • create projects access to the user's data

Required parameters

  • Name: The name of the project

To create a new project for the user John Doe with project name Test Project 1 using cURL:

curl -v -H "x-access-token: {access token}" \
-X POST \
-d "name=Test Project 1" \
https://api.basespace.illumina.com/v1pre3/projects

The Response will be a 201 Created with the newly created Project, since a Project with that name did not already exist, with its Id which is 125125:

{
    "Response": {
        "HrefSamples": "v1pre3/projects/125125/samples",
        "HrefAppResults": "v1pre3/projects/125125/appresults",
        "HrefBaseSpaceUI": "https://basespace.illumina.com/project/125125/Test Project 1",
        "Id": "125125",
        "UserOwnedBy": {
            "Id": "1001",
            "Href": "v1pre3/users/1001",
            "Name": "John Doe"
        },
        "Href": "v1pre3/projects/125125",
        "Name": "Test Project 1",
        "DateCreated": "2012-10-03T20:22:16.7838033Z"
    },
    "ResponseStatus": {},
    "Notifications": []
}

If the user already has a Project with that name that they can write to, a 200 OK is returned with the following response:

{
    "Response": {
        "HrefSamples": "v1pre3/projects/125125/samples",
        "HrefAppResults": "v1pre3/projects/125125/appresults",
        "HrefBaseSpaceUI": "https://basespace.illumina.com/project/125125/Test Project 1",
        "Id": "125125",
        "UserOwnedBy": {
            "Id": "1001",
            "Href": "v1pre3/users/1001",
            "Name": "John Doe"
        },
        "Href": "v1pre3/projects/125125",
        "Name": "Test Project 1",
        "DateCreated": "2012-10-03T20:22:16.7838033Z"
    },
    "ResponseStatus": {},
    "Notifications": []
}

DELETE: projects/{id}

See Trash Apis in the Trash Api section

AppSessions

The instance of an application running on a set of Samples, Runs, Files, Appresults, or Projects. This resource gives information about the status of an application, which will be working on one of the above resource types. The id of a particular app session may be found within an AppResult or Sample, or will be assigned upon triggering an application. If an application has access to a given Sample or AppResult, it also has access to the associated AppSession which provides additional metadata. The app will see a reference to an AppSession for each Sample and AppResult in the API.

Response Elements in addition to Common Response Elements

  • References: The resources that are referenced by the appsession
    • Type: Type of resource that the appsession was launched from
    • Content: Shows the resource content, including the owner's information
  • Status: Status of the AppSession, the Samples or AppResults created by it will inherit this property. This parameter is REQUIRED otherwise an error will be thrown. This Status can be regularly changed by the app but in some cases BaseSpace will automatically change the Status, these scenarios are described below. Possible statuses include:
    • Pending: The AppSession's Status is set to Pending automatically when a Native app is launched. This Status applies only to Native apps. BaseSpace takes time to find a machine to run the analysis on, so until the job is started the AppSession status will remain Pending.
    • Running: The Status of the AppSession after the user has accepted the OAuth dialog. The initial Status is AwaitingAuthorization and once the user gives permission to the app the Status is automatically changed to Running.
    • Complete: Processing and file upload has finished and the data is now available to use.
    • NeedsAttention: This status indicates that processing cannot continue without user intervention. Once resolved, the status can go back to Running or Complete. A notification to the user may be sent bringing this to their attention.
    • TimedOut: The AppSession has been Running for more than 48 hours and is put into this state. The session may be resumed from this state.
    • AwaitingAuthorization: AppSessions are put into the AwaitingAuthorization state when they are created. Once a user clicks Accept on the OAuth dialog, the Status of the AppSession is changed to Running. Please refer to the API Reference for more information.
    • Aborting: Generally this status applies only to Native apps. For Native apps, in the BaseSpace UI, the user has the option to click the Stop Analysis button. If this button is clicked, the Native app will receive a message to begin the Abort process. Until the app is completely stopped and the machine that it was running on is shut down, the Status of the AppSession will be Aborting.
    • Aborted: This AppResult or Sample has been aborted and may not be resumed. Further status changes are not allowed.
  • StatusSummary: A summary of the status of the appsession, this can be regularly changed by the app
  • Application: The application that created this appsession, includes information about the application
  • ParentAppSession: When working with a multi-node Native application, the AppSession that contains all of the input form data from the user is stored as a ParentAppSession in the metadata for the AppSession that is generated for the specific node

GET: appsessions/{id}

Retrieve an appsession by its Id

Permissions

  • BROWSE access to any containing AppResults gives visibility to appsession, the clientid and clientsecret must match the appsession's application

To retrieve the appsession with id 9d2cac1f2d908dbf82b9583e072f6b47:

GET https://api.basespace.illumina.com/v1pre3/appsessions/0480cbb3c56135f3f2265f6437ceadf0
{
    "Response": {
        "References": [],
        "Id": "0480cbb3c56135f3f2265f6437ceadf0",
        "Href": "v1pre3/appsessions/0480cbb3c56135f3f2265f6437ceadf0",
        "UserCreatedBy": {
            "Id": "1001",
            "Href": "v1pre3/users/1001",
            "Name": "John Doe"
        },
        "Status": "Complete",
        "StatusSummary": "",
        "DateCreated": "2012-02-14T07:00:52.0000000"
    },
    "ResponseStatus": {},
    "Notifications": []
}

In this case the "References" field is not populated because the app was not triggered from BaseSpace. In the event that it is triggered from BaseSpace project 76076, an appsession with id d840251ab9c441639a9b2f047ded51fd would have the following response:

GET https://api.basespace.illumina.com/v1pre3/appsessions/d840251ab9c441639a9b2f047ded51fd
{
    "Response": {
        "References": [
            {
                "Rel": "Input",
                "Type": "Project",
                "Href": "v1pre3/projects/76076",
                "HrefContent": "v1pre3/projects/76076",
                "Content": {
                    "Id": "76076",
                    "UserOwnedBy": {
                        "Id": "74074",
                        "Href": "v1pre3/users/74074",
                        "Name": "BaseSpace Illumina"
                    },
                    "Href": "v1pre3/projects/76076",
                    "Name": "Project_BacillusCereus",
                    "DateCreated": "2012-08-21T07:31:37.0000000"
                }
            }
        ],
        "Id": "d840251ab9c441639a9b2f047ded51fd",
        "Href": "v1pre3/appsessions/d840251ab9c441639a9b2f047ded51fd",
        "Application": {
            "Id": "3003",
            "Href": "v1pre3/applications/3003",
            "Name": "BaseMaker 5000",
            "HomepageUri": "http://www.yourapphomepageuri.com/",
            "ShortDescription": "Just an app...",
            "DateCreated": "2012-06-04T20:23:02.0000000"
        },
        "UserCreatedBy": {
            "Id": "37037",
            "Href": "v1pre3/users/37037",
            "Name": "John Doe"
        },
        "Status": "Running",
        "StatusSummary": "",
        "DateCreated": "2012-09-04T08:44:38.0000000"
    },
    "ResponseStatus": {},
    "Notifications": []
}

The "Reference" field is populated with the context, in BaseSpace, from which the application was launched. More information about launching an app from BaseSpace can be found in the App Triggering guide.

GET: users/current/appsessions

A list of the current user's AppSessions.

Permissions

  • A valid access token for the User.

Query Parameters

  • AppId: The Id of the Application that created this AppSession
  • Status: To Filter the list by Status of the AppSession, this query parameter can be used

To list all of the AppSessions that the current user has created with Application Id 75075:

GET http://api.basespace.illumina.com/v1pre3/users/current/appsessions?AppId=75075
{
    Response: {
        Items: [
            {
                Id: "f4447f1619b6471cace779cb97fa2c75",
                Href: "v1pre3/appsessions/f4447f1619b6471cace779cb97fa2c75",
                Application: {
                    Id: "75075",
                    Href: "v1pre3/applications/75075",
                    Name: "hoth test purchase app",
                    HomepageUri: "http://google.com",
                    ShortDescription: "this is for testing purchases",
                    DateCreated: "2013-04-03T20:50:44.0000000"
                },
                UserCreatedBy: {
                    Id: "17017",
                    Href: "v1pre3/users/17017",
                    Name: "John Doe",
                    GravatarUrl: "gravatarurl.com"
                },
                Status: "TimedOut",
                StatusSummary: "",
                DateCreated: "2013-04-10T17:23:55.0000000"
            },
            {
                Id: "29f1928e34f545669afa93b9e86b9c12",
                Href: "v1pre3/appsessions/29f1928e34f545669afa93b9e86b9c12",
                Application: {
                    Id: "75075",
                    Href: "v1pre3/applications/75075",
                    Name: "hoth test purchase app",
                    HomepageUri: "http://google.com",
                    ShortDescription: "this is for testing purchases",
                    DateCreated: "2013-04-03T20:50:44.0000000"
                },
                UserCreatedBy: {
                    Id: "17017",
                    Href: "v1pre3/users/17017",
                    Name: "John Doe",
                    GravatarUrl: "gravatarurl.com"
                },
                Status: "TimedOut",
                StatusSummary: "",
                DateCreated: "2013-04-10T17:25:21.0000000"
            },
            {
                Id: "83a55266de144e01adbc2397d60ef3c0",
                Href: "v1pre3/appsessions/83a55266de144e01adbc2397d60ef3c0",
                Application: {
                    Id: "75075",
                    Href: "v1pre3/applications/75075",
                    Name: "hoth test purchase app",
                    HomepageUri: "http://google.com",
                    ShortDescription: "this is for testing purchases",
                    DateCreated: "2013-04-03T20:50:44.0000000"
                },
                UserCreatedBy: {
                    Id: "17017",
                    Href: "v1pre3/users/17017",
                    Name: "John Doe",
                    GravatarUrl: "gravatarurl.com"
                },
                Status: "TimedOut",
                StatusSummary: "",
                DateCreated: "2013-04-23T00:03:23.0000000"
            }
        ],
        DisplayedCount: 10,
        TotalCount: 178,
        Offset: 0,
        Limit: 10,
        SortDir: "Asc",
        SortBy: "Name"
    },
    ResponseStatus: { },
    Notifications: [ ]
}

POST: appsessions/{id}

Change the current status of the AppSession by its Id

Permissions

  • WRITE access to the referenced AppResults through its parent Project

Query Parameters

  • Status: Status of the AppSession, the Samples or AppResults created will inherit this value. This parameter is REQUIRED otherwise an error will be thrown. Possible statuses include:

    • Running: The initial status upon AppResult or Sample creation indicating that the app is processing or uploading data.
    • Complete: Processing and file upload has finished and the data is now available to use.
    • NeedsAttention: This status indicates that processing cannot continue without user intervention. Once resolved, the status can go back to Running or Complete. A notification to the user may be sent bringing this to their attention.
    • TimedOut: An AppSession is automatically changed to this status when it has been in the Running state for more than 72 hours, this status can be changed at a later time.
    • Aborted: This AppResult or Sample has been aborted and may not be resumed. Further status changes are not allowed.
  • StatusSummary: A brief summary of what is currently happening with the AppResult or Sample that will be displayed for the user next to the status. This may be updated multiple times. This field has a limit of 128 characters.

To change the status of AppResult with AppSession id 9d2cac1f2d908dbf82b9583e072f6b47 to complete with a brief statussummary using cURL:

curl -v -H "x-access-token: {access token}" \
-d "status=complete" \
-d "statussummary=Processing and file upload complete." \
https://api.basespace.illumina.com/v1pre3/appsessions/9d2cac1f2d908dbf82b9583e072f6b47

If successful, a 200 OK is returned with a JSON AppResult object.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 30 Aug 2012 9:30:46 GMT

{
  "Response":{
    "References": [],
    "Id":"9d2cac1f2d908dbf82b9583e072f6b47",
    "Href":"v1pre3/appsessions/9d2cac1f2d908dbf82b9583e072f6b47",
    "UserCreatedBy":{
      "Id":"74074",
      "Href":"v1pre3/users/74074",
      "Name":"John Doe"
    },
    "Status":"Complete",
    "StatusSummary":"Processing and file upload complete.",
    "DateCreated":"2012-08-21T05:43:17.0000000"
  },
  "ResponseStatus":{},
  "Notifications":[]
}

Note: AppSessions in the Running status will change to the TimedOut status and will not display for the User in the UI after 72 hours if the status of the AppSession is not changed to Complete in that time.

POST: applications/{id}/appsessions

This is the App Launch API for BaseSpace. Using this API will allow you to launch any Native apps you have access to.

Allows you to create a new AppSession for a Native app and automatically launch the app with parameters provided.

This API is an ALPHA release, it is subject to change and there may be some issues with it. Please do not hesitate to reach out to us with your questions and feedback.

This API is subject to API Rate Limitations, they are described in detail in the section above.

Permissions

  • Requires a private access_token from the Credentials tab in the developer portal
  • Access to launch the specified application

Restrictions

  • Only for Native Apps

  • Free apps are supported, paid apps are not supported yet

  • The analysis is always started immediately after a successful POST request

Header Parameters

  • Content-Type: This value should always be set to application/json
  • x-access-token: This needs to be provided if you are launching the app programmatically. If you are launching it via a browser tool, simply log into BaseSpace and then launch with the browser tool (e.g. Postman for Chrome.) This access token must be a private access token which can be found in the Credentials tab for any of your apps, with one private token you can launch any apps you have access to

Query Parameters

  • Name: The Name of the AppSession, this will be displayed to the user in the UI. This field has a limit of 128 characters

  • StatusSummary: A brief summary of what is currently happening with the AppResult or Sample that will be displayed for the user next to the status. This may be updated multiple times. This field has a limit of 128 characters

  • AutoStart: boolean (true or false) value that determine if the app should be launched immediately or if it should simply be simulated. If false, the application will not be launched but the response will contain JSON from a simulated AppSession created with the data provided. Should be set to true in most cases

  • AgentId: Optional field for published apps that can be used to do local testing. The AgentId can be found in the "Native Settings" tab for your application in the developer portal. This is analogous to using the Send to Local Agent button.

  • Properties: An array of Properties that define all of the input form parameters for the active form for the app specified. This array is analogous to filling out the input form for an app

To launch the Isaac WGS v2 app with Id 278278, this app is published in BaseSpace:

curl -v -H "x-access-token: {access token}" \
-H "Content-Type: application/json" \

Provide the following JSON with the POST:

{
  "Name": "Api Launch Isaac WGS v2",
  "StatusSummary": "AutoLaunch",
  "AutoStart": true,
  "Properties":
  [
    {
      "Name": "Input.project-id",
      "Type": "project",
      "Content": "v1pre3/projects/123 "
    },        
    {
      "Name": "Input.sample-id",
      "Type": "sample[]",
      "items": [ "v1pre3/samples/123 " ]
    },     
    {
      "Name": "Input.FlagPCRDuplicates-id",
      "Type": "string[]",
      "items": [ ]
    },     
    {
      "Content": "RefSeq",
      "Name": "Input.AnnotationSource",
      "Type": "string"
    },
    {
      "Name": "Input.genome-id",
      "Type": "string",
      "Content": "Human"
    },
    {
      "Name": "Input.GQX-id",
      "Type": "string",
      "Content": "30"
    },
    {
      "Content": "10",
      "Name": "Input.StrandBias-id",
      "Type": "string"
    }

  ]
}

https://api.basespace.illumina.com/v1pre3/applications/278278/appsessions

The values that you provide in the Properties array depend on the input form for the app that is being launched. In order to launch an app, you will be required to know the input form's fields for that app in order to pass the correct parameters to launch the app. All of the required input form fields must be provided in order for the app to launch.

If successful, the analysis will be created an automatically started. The user will then see the analysis pop up in the BaseSpace UI. It is very important to provide all of the input form field names as they are listed in the input form (append Input. or Output. appropriately.) BaseSpace will automatically create properties for Input.Projects, Input.Samples, and Input.AppResults when the types of project, sample, and appresult are provided in the Properties JSON array.

In the above template, we are simply setting allof the required fields for the Isaac v2 application. The input Sample Id is 123 and the selected Project's Id is 123, so the respective Hrefs are v1pre3/samples/123 and v1pre3/projects/123. This template is available in the Python SDK Overview. We're planning to release more app launch templates at a later stage but if there are any you particularly want to see, please post them to the basespace-developers Google group.

In the example above, we used the Isaac WGS V2 application that is available in BaseSpace. This application has some fields defined in its input form which match the Properties we POSTed above, you can see these fields when you click on the Launch button for this app. The input form for this app has some required and optional fields, which still applies to the Properties array being provided via this API.

DELETE: appsessions/{id}

See Trash Apis in the Trash Api section

Samples

Samples are the result of demultiplexing the output of a sequencing instrument flow cell run. A Sample in BaseSpace contains metadata about how it was produced (i.e. from the sample sheet) and a collection of Files representing all the reads in compressed FASTQ format.

Response Elements in addition to Common Response Elements

  • HrefGenome: The genome to which this sample was referenced, this field is optional and if it is empty it will not be exposed
  • SampleNumber: The sample number of this sample within the project
  • ExperimentName: The name of the run from which this sample was taken
  • HrefFiles: The location of the files for this sample
  • AppSession: Information about the appsession that created this sample
  • IsPairedEnd: Designates whether or not the read is a paired end read
  • Read1: The length of the first Read, the number of bases
  • Read2: The length of the second Read, the number of bases
  • NumReadsRaw: The number of Reads for this Sample
  • NumReadsPF: The number of Reads that have passed filters
  • SampleId: The Id of the Sample from the samplesheet, this is specified by the user at the flow cell level
  • Reference: The Reference field shows this Sample's relation to other Samples or AppResults in BaseSpace
    • Rel: A UsedBy value for this field means that this Sample was used by an application to produce an AppResult
    • Type: The type of resource that was output from using this Sample as an input to an application, generally AppResult
    • Content: Gives detailed information about the AppResult(s) which used this Sample data

GET: samples/{Id}

Retrieve a specific sample by its Id. There is an appsession parameter in the response that is further explain in the App Sessions portion of this document.

Permissions

  • BROWSE access to the sample either directly or via access to a project

Example request to access sample Id 37037:

GET https://api.basespace.illumina.com/v1pre3/samples/37037
{
Response:{
      HrefGenome:"v1pre3/genomes/4",
      SampleNumber:1,
      ExperimentName:"Genome-in-a-Day",
      HrefFiles:"v1pre3/samples/37037/files",
      AppSession:{
         Id:"0480cbb3c56135f3f2265f6437ceadf0",
         Href:"v1pre3/appsessions/0480cbb3c56135f3f2265f6437ceadf0",
         UserCreatedBy:{
            Id:"1001",
            Href:"v1pre3/users/1001",
            Name:"John Doe"
         },
         Status:"Complete",
         StatusSummary:"",
         DateCreated:"2012-02-14T07:00:52.0000000"
      },
      IsPairedEnd:true,
      Read1:0,
      Read2:0,
      NumReadsRaw:0,
      NumReadsPF:0,
      Id:"37037",
      Href:"v1pre3/samples/37037",
      UserOwnedBy:{
         Id:"1001",
         Href:"v1pre3/users/1001",
         Name:"John Doe"
      },
      Name:"NA18507",
      SampleId:"ID 1",
      Status:"Complete",
      StatusSummary:"",
      DateCreated:"2012-02-14T15:04:52.0000000",
      References:[
         {
            Rel:"UsedBy",
            Type:"AppResult",
            Href:"v1pre3/appresults/9675",
            HrefContent:"v1pre3/appresults/9675",
            Content:{
               Id:"9675",
               Href:"v1pre3/appresults/9675",
               UserOwnedBy:{
                  Id:"1001",
                  Href:"v1pre3/users/1001",
                  Name:"John Doe"
               },
               Name:"Resequencing",
               Status:"Complete",
               StatusSummary:"",
               DateCreated:"2012-06-01T16:12:00.0000000"
            }
         }
      ]
   },
   ResponseStatus:{

   },
   Notifications:[

   ]
}

GET: projects/{Id}/samples

Retrieve a collection of samples inside of a given project

Permissions

  • BROWSE access to the project

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: Id

To retrieve a list of samples for project Id 1, sorted by Id in descending order:

GET https://api.basespace.illumina.com/v1pre3/projects/1/samples?SortBy=Id&SortDir=Desc
{
    "Response":{
        "Items":[
            {
                "Id": "194265",
                "Href": "v1pre3/samples/194265",
                "UserOwnedBy": {
                    "Id": "1003",
                    "Href": "v1pre3/users/1003",
                    "Name": "John Doe"
                },
                "Name": "sample_72",
                "Status": "Complete",
                "StatusSummary": "",
                "DateCreated": "2012-08-10T18:32:42.0000000"
            },
            {
                "Id": "194264",
                "Href": "v1pre3/samples/194264",
                "UserOwnedBy": {
                    "Id": "1003",
                    "Href": "v1pre3/users/1003",
                    "Name": "John Doe"
                },
                "Name": "sample_71",
                "Status": "Complete",
                "StatusSummary": "",
                "DateCreated": "2012-08-10T18:32:41.0000000"
            },
            {
                "Id": "194263",
                "Href": "v1pre3/samples/194263",
                "UserOwnedBy": {
                    "Id": "1003",
                    "Href": "v1pre3/users/1003",
                    "Name": "John Doe"
                },
                "Name": "sample_70",
                "Status": "Complete",
                "StatusSummary": "",
                "DateCreated": "2012-08-10T18:32:40.0000000"
            }
        ],
        "DisplayedCount":3,
        "TotalCount":3,
        "Offset":0,
        "Limit":10,
        "SortDir":"Desc",
        "SortBy":"Id"
    },
    "ResponseStatus":{},
    "Notifications":[]  
}

DELETE: samples/{id}

See Trash Apis in the Trash Api section

AppResults

AppResults is a general term for any result that is produced from an application in BaseSpace. For example, if an app performed a resequencing workflow, the corresponding AppResult would be a collection of aligned reads (stored as BAM files) and variants (stored as VCF files). Each AppResult will contain a collection of these Files.

Every tool can produce a variety of output files, and the BaseSpace API makes these accessible via the AppResults.

Response Elements in addition to Common Response Elements

  • HrefGenome: The genome to which this appresult was referenced, this field is optional and if it is empty it will not be exposed
  • HrefFiles: The location of the files for this appresult
  • AppSession: Information about the appsession that created this appresult
  • References: Shows how and where this AppResult is referenced
    • Rel: If this parameter is Using, it means that this AppResult was created as a result of an application running on a single Sample or set of Samples
    • Type: Which type of resource is used as the input, can be Project/Samples/AppResults
    • Content: Some detailed information about the Type described above.

GET: appresults/{Id}

Retrieve a specific AppResult by its Id. There is an appsession field in the response that is further explain in the App Sessions portion of this document.

Permissions

  • BROWSE access to the AppResult either directly or via access to a project containing the AppResult

Example request to access AppResult Id 100:

GET https://api.basespace.illumina.com/v1pre3/appresults/100
{
    Response: {
        Description: "Amplicon on sample_1",
        HrefFiles: "v1pre3/appresults/100/files",
        HrefGenome: "v1pre3/genomes/4",
        AppSession: {
            Id: "18045d13d368ec128ae0e4b9f6b50873",
            Href: "v1pre3/appsessions/18045d13d368ec128ae0e4b9f6b50873",
            UserCreatedBy: {
                Id: "1003",
                Href: "v1pre3/users/1003",
                Name: "Jane Doe"
                },
            Status: "Complete",
            StatusSummary: "",
            DateCreated: "2011-11-11T03:54:53.0000000"
            },
        References: [
        {
            Rel: "Using",
            Type: "Sample",
            Href: "v1pre3/samples/1100",
            HrefContent: "v1pre3/samples/1100",
            Content: {
                Id: "1100",
                Href: "v1pre3/samples/1100",
                UserOwnedBy: {
                    Id: "1003",
                    Href: "v1pre3/users/1003",
                    Name: "Jane Doe"
                    },
                Name: "sample_1",
                SampleId: "1_1",
                Status: "Complete",
                StatusSummary: "",
                DateCreated: "2011-11-11T04:41:30.0000000"
                }
            }
        ],
        Id: "100",
        Href: "v1pre3/appresults/100",
        UserOwnedBy: {
            Id: "1003",
            Href: "v1pre3/users/1003",
            Name: "Jane Doe"
            },
        Name: "Amplicon",
        Status: "Complete",
        StatusSummary: "",
        DateCreated: "2012-06-01T16:12:00.0000000"
        },
    ResponseStatus: { },
    Notifications: [ ]
}

GET: projects/{Id}/appresults

Retrieve a list of AppResults within a specific project Id

Permissions

  • BROWSE access to the Project

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: Id

To retrieve the list of AppResults within project Id 1, sorted in ascending order by Id:

GET https://api.basespace.illumina.com/v1pre3/projects/1/appresults?SortBy=Id&SortDir=Asc
{
   "Response": {
        "Items" : [
            {
                "Id": "100",
                "Href": "v1pre3/appresults/100",
                "UserOwnedBy": {
                    "Id": "1003",
                    "Href": "v1pre3/users/1003",
                    "Name": "Jane Doe"
                },
                "Name": "Amplicon",
                "Status": "Complete",
                "StatusSummary": "",
                "DateCreated": "2012-06-01T16:12:00.0000000"
            },
            {
                "Id": "101",
                "Href": "v1pre3/appresults/101",
                "UserOwnedBy": {
                    "Id": "1003",
                    "Href": "v1pre3/users/1003",
                    "Name": "John Doe"
                },
                "Name": "Amplicon",
                "Status": "Complete",
                "StatusSummary": "",
                "DateCreated": "2012-06-01T16:12:00.0000000"
            }
       ],
       "SortBy":"Id",
       "DisplayedCount":2,
       "TotalCount":2,
       "Offset":0,
       "Limit":10,
       "SortDir":"Asc"
    },
   "ResponseStatus":{
   },
   "Notifications":[]
}

GET: appsessions/{id}/appresults

Returns a list of the AppResults that were created by an AppSession

Permissions

  • A valid access token for the user.

To list all of the AppResults for AppSession with id 9ff65b325f524802af3598f66045ae2c:

GET http://api.basespace.illumina.com/v1pre3/appsession/9ff65b325f524802af3598f66045ae2c/appresults

{
    Response: {
        Items: [
            {
                Id: "731732",
                Href: "v1pre3/appresults/731732",
                UserOwnedBy: {
                Id: "2002",
                Href: "v1pre3/users/2002",
                Name: "BaseSpace Illumina",
                GravatarUrl: "gravatarurl.com"
            },
        Name: "Picard Aln Metrics for Taq",
        Status: "Complete",
        StatusSummary: "analysis and write-back successful; deleted local files",
        DateCreated: "2013-06-04T18:23:52.0000000",
        TotalSize: 72963
            }
        ],
        DisplayedCount: 1,
        TotalCount: 1,
        Offset: 0,
        Limit: 10,
        SortDir: "Asc",
        SortBy: "Id"
    },
    ResponseStatus: { },
    Notifications: [ ]
}

POST: projects/{Id}/appresults

To create or change an AppResult within a specific project. A new appresult is created within this project. More information is available in the Writing Back to BaseSpace Guide.

Permissions

  • WRITE access to the project within which the AppResult is, or will be, contained

Header Parameters

  • x-access-token: The access_token that an app has for this process
  • Content-Type: the content type of the parameter an app is passing, for this an app will have to specify application/json and pass a JSON. More information about this is located in the Writing Back to BaseSpace Guide

Defining the JSON fields for the request body

Remember, these parameters are included in the JSON that is being passed in with the AppResult creation:

  • Name: Name of the AppResult (required)
  • Description: Brief decription of the AppResult
  • HrefAppSession: Specifies a location for the AppSession for the new AppResult. This field may only be set if the status parameter of this AppSession is neither complete nor aborted, and also the application field must match. Generally it looks like v1pre3/appsessions/{appsessionid}. If this field is not provided, a new AppSession will be implicitly created and associated with the new AppResult.
  • References: The Reference field shows this AppResult's inputs or relationship to other resources in BaseSpace.

    • Rel: Using means that some Files were used as input for this AppResult
    • Type: The type of resource that was used as an input to this AppResult
    • HrefContent: Gives the location of the Type specified above, see the following example

An example of how to create an appresult within a project with the JSON input that contains values for Name, Description, HrefAppSession, and References:

curl -v -H "x-access-token: {access token} \
-H "Content-Type: application/json" \
-X POST 
-d {
       "Name":"My AppResult",
       "Description":"My App Description"
       "HrefAppSession":"v1pre3/appsessions/{appsessionId}",
       "References":[
          {
             "Rel":"using",
             "HrefContent":"v1pre3/samples/1100"
          }
       ]
    } \
https://api.basespace.illumina.com/v1pre3/projects/{ProjectId}/appresults

If successful, a 201 Created is returned with a JSON app result object.

HTTP/1.1 201 Created
Content-Type: application/json
Date: Fri, 11 May 2012 10:23:46 GMT

{
   Response:{
      Description:"My App Description",
      HrefFiles:"v1pre3/appresults/9675/files",
      AppSession:{
         Id:"0480cbb3c56135f3f2265f6437ceadf0",
         Href:"v1pre3/appsessions/0480cbb3c56135f3f2265f6437ceadf0",
         UserCreatedBy:{
            Id:"1001",
            Href:"v1pre3/users/1001",
            Name:"John Smith"
         },
         Status:"Complete",
         StatusSummary:"",
         DateCreated:"2012-02-14T07:00:52.0000000"
      },
      References:[
         {
            Rel:"Using",
            Type:"Sample",
            Href:"v1pre3/samples/1100",
            HrefContent:"v1pre3/samples/1100",
            Content:{
               Id:"37037",
               Href:"v1pre3/samples/1100",
               UserOwnedBy:{
                  Id:"1001",
                  Href:"v1pre3/users/1001",
                  Name:"John Smith"
               },
               Name:"NA18507",
               SampleId:"ID 1",
               Status:"Complete",
               StatusSummary:"",
               DateCreated:"2012-02-14T15:04:52.0000000"
            }
         }
      ],
      Id:"9675",
      Href:"v1pre3/appresults/9675",
      UserOwnedBy:{
         Id:"1001",
         Href:"v1pre3/users/1001",
         Name:"John Doe"
      },
      Name:"My AppResult",
      Status:"Running",
      StatusSummary:"",
      DateCreated:"2012-06-01T16:12:00.0000000"
   },
   ResponseStatus:{

   },
   Notifications:[

   ]
}

DELETE: appresults/{id}

See Trash Apis in the Trash Api section

Genomes

The Genomes resource gives access to any genomes archived in BaseSpace. A way to find detailed information, including SpeciesName and Build, about genomes in BaseSpace.

Response Elements in addition to Common Response Elements

  • SpeciesName: The name of the species whos genome this is
  • Source: The source from which this genome was uploaded
  • Build: Tracks the version or build of the genome

GET: genomes

Retrieve a list of all genomes available in BaseSpace

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, SpeciesName, or Build. Default: Id

To retrieve the list of all genomes, sorted by Id in ascending order with an offset of 5 and limit of 11:

GET https://api.basespace.illumina.com/v1pre3/genomes?SortBy=Id&Offset=5&Limit=11&SortDir=Asc&Id=current
{
    "Response":{
        "Items":[
            {
                    "Id": "6",
                    "SpeciesName": "Phix",
                    "Href": "v1pre3/genomes/6"
                },
                {
                    "Id": "7",
                    "SpeciesName": "Rhodobacter sphaeroides",
                    "Href": "v1pre3/genomes/7"
                },
                {
                    "Id": "8",
                    "SpeciesName": "Rattus norvegicus",
                    "Href": "v1pre3/genomes/8"
                },
                {
                    "Id": "9",
                    "SpeciesName": "Saccharomyces cerevisiae",
                    "Href": "v1pre3/genomes/9"
                },
                {
                    "Id": "10",
                    "SpeciesName": "Staphylococcus aureus",
                    "Href": "v1pre3/genomes/10"
                },
                {
                    "Id": "12",
                    "SpeciesName": "Bacillus Cereus",
                    "Href": "v1pre3/genomes/12"
                }
        ],
        "DisplayedCount": 6,
        "TotalCount": 11,
        "Offset": 5,
        "Limit": 11,
        "SortDir": "Asc",
        "SortBy": "Id"
    },
    "ResponseStatus":{},
    "Notifications":[]
}

GET: genomes/{Id}

Retrieve a specific genome by its Id

To retrieve a specific genome with Id 6:

GET https://api.basespace.illumina.com/v1pre3/genomes/6
{
    "Response": {
        "DisplayName": "Phix - Illumina",
            "Source": "Illumina",
            "Build": "1.0",
            "Id": "6",
            "SpeciesName": "Phix",
            "Href": "v1pre3/genomes/6"
    },
    "ResponseStatus":{},
    "Notifications":[]
}

Files

A File in BaseSpace is what one would expect - a collection of attributes (date created, size, etc) and a data stream. The BaseSpace API lets an app read any file it have access to. In addition, certain files (VCF and BAM files) have additional information available.

The Files resource is provided so that the user can access files associated with specific Runs, Samples, or AppResults.

Response Elements in addition to Common Response Elements

  • UploadStatus: The status of the upload of this file
  • HrefContent: There in the API the content of the file is located
  • HrefCoverage: The location in the API of the coverage for this file
  • Size: The size, in bytes, of this file
  • Path: The path to this file in the BaseSpace UI
  • HrefVariants: The location in the API of the variants for this file
  • ContentType: The type of content contained within this file
  • OriginalScope: A field that shows information about sample merging, generally populated with info about the origin of this file from sample merging. It gives a logical way to group these merged files together to show where exactly they came from.

GET: files/{Id}

Retrieve information about a given file by its Id

Permissions

  • BROWSE access to the Run, Sample, or AppResult to which the file belongs

Retrieve the file with Id 2150156:

GET https://api.basespace.illumina.com/v1pre3/files/2150156
{
    "Response": {
        "UploadStatus": "complete",
        "HrefContent": "v1pre3/files/2150156/content",
        "HrefCoverage": "v1pre3/coverage/2150156",
        "Id": "2150156",
        "Href": "v1pre3/files/2150156",
        "Name": "sorted.bam",
        "Size": 113337981395,
        "Path": "BySample/1/data/intensities/basecalls/Alignment/sorted.bam",
        "DateCreated": "2012-02-14T07:01:06.0000000"
    },
    "ResponseStatus": { },
    "Notifications": [ ]
}

Additional File Support

Certain types of files have additional services associated with them. Specifically, VCF (Variant Call Format) and BAM (Binary SAM) have special support in BaseSpace, as denoted by having a HrefVariants and HrefCoverage fields, respectively:

GET https://api.basespace.illumina.com/v1pre3/files/2150158
{
   "Response" : {
        "HrefContent": "v1pre3/files/2150158/content",
        "HrefVariants": "v1pre3/variantset/2150158",
        "Id": "2150158",
        "Href": "v1pre3/files/2150158",
        "Name": "genome.vcf",
        "Size": 399487274,
        "Path": "BySample/1/data/intensities/basecalls/Alignment/genome.vcf",
        "DateCreated": "2012-02-14T08:21:03.0000000"
    },
   "ResponseStatus":{
   },
   "Notifications":[
    ]
}

GET: runs/{id}/files

Retrieve a collection of files belonging to a given run Id

Permissions

  • BROWSE access to the Run to which the files belong

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: Id
  • Extensions: Filters the files associated with the Run by their extension. i.e. list all .bcl files within a specific Run. They can be .bin, .xml, .csv, .bcl, .filter, and more.

To retrieve all files associated with run Id 1021 with a limit of 5 and an offset of 15:

GET https://api.basespace.illumina.com/v1pre3/runs/1021/files?Limit=5&Offset=15

{
    "Response": {
        "Items":[
            {
                "Id":"15021",
                "Href":"v1pre3/files/15021",
                "Name":"s_1_1.bcl",
                "Size":731133,
                "Path":"data/intensities/basecalls/l001/c20.1/s_1_1.bcl",
                    "DateCreated":"2011-11-11T03:28:22.0000000"
            },
            {
                "Id":"15025",
                "Href":"v1pre3/files/15025",
                "Name":"s_1_1.bcl",
                "Size":731133,
                "Path":"data/intensities/basecalls/l001/c29.1/s_1_1.bcl",
                "DateCreated":"2011-11-11T03:28:23.0000000"
            },
            {
                "Id":"15030",
                "Href":"v1pre3/files/15030",
                "Name":"s_1_1.bcl",
                "Size":731133,
                "Path":"data/intensities/basecalls/l001/c17.1/s_1_1.bcl",
                "DateCreated":"2011-11-11T03:28:25.0000000"
            },
            {
                "Id":"15033",
                "Href":"v1pre3/files/15033",
                "Name":"s_1_1.bcl",
                "Size":731133,
                "Path":"data/intensities/basecalls/l001/c1.1/s_1_1.bcl",
                "DateCreated":"2011-11-11T03:28:27.0000000"
            },
            {
                "Id":"15038",
                "Href":"v1pre3/files/15038",
                "Name":"s_1_1.bcl",
                "Size":731133,
                "Path":"data/intensities/basecalls/l001/c30.1/s_1_1.bcl",
                "DateCreated":"2011-11-11T03:28:28.0000000"
            }
        ],
        "DisplayedCount":5,
        "TotalCount":71,
        "Offset":15,
        "Limit":5,
        "SortDir":"Asc",
        "SortBy":"Id"
    },
    "ResponseStatus":{
    },
    "Notifications":[

    ]
} 

GET: samples/{Id}/files

Retrieve a collection of files belonging to a given sample Id

Permissions

  • BROWSE access to the Sample to which the files belong

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: Id
  • Extensions: Filter result Sample files by extension. Currently the only sample files are .gz, these are FASTQ files that have been zipped.
  • Limit: Limit how many results are returned in a the list. Limit can be 0 to 1000 for this method.

To retrieve all .gz files in sample Id 32111, in ascending order sorted by Id:

GET https://api.basespace.illumina.com/v1pre3/samples/32111/files?SortBy=Build&Extensions=gz&Offset=0&Limit=10&SortDir=Asc
{
    "Response": {
        "Items": [
            {
                "Id": "1863960",
                "Href": "v1pre3/files/1863960",
                "Name": "s_G1_L001_I1_001.fastq.58.gz",
                "ContentType": "application/octet-stream",
                "Size": 149614,
                "Path": "data/intensities/basecalls/s_G1_L001_I1_001.fastq.58.gz",
                "DateCreated": "2012-02-07T23:35:55.0000000"
            },
            {
                "Id": "1863961",
                "Href": "v1pre3/files/1863961",
                "Name": "s_G1_L001_I2_001.fastq.58.gz",
                "ContentType": "application/octet-stream",
                "Size": 153010,
                "Path": "data/intensities/basecalls/s_G1_L001_I2_001.fastq.58.gz",
                "DateCreated": "2012-02-07T23:35:55.0000000"
            },
            {
                "Id": "1863962",
                "Href": "v1pre3/files/1863962",
                "Name": "s_G1_L001_R1_001.fastq.58.gz",
                "ContentType": "application/octet-stream",
                "Size": 688930,
                "Path": "data/intensities/basecalls/s_G1_L001_R1_001.fastq.58.gz",
                "DateCreated": "2012-02-07T23:35:55.0000000"
            },
            {
                "Id": "1863963",
                "Href": "v1pre3/files/1863963",
                "Name": "s_G1_L001_R2_001.fastq.58.gz",
                "ContentType": "application/octet-stream",
                "Size": 735822,
                "Path": "data/intensities/basecalls/s_G1_L001_R2_001.fastq.58.gz",
                "DateCreated": "2012-02-07T23:35:55.0000000"
            }
        ],
        "DisplayedCount": 4,
        "TotalCount": 4,
        "Offset": 0,
        "Limit": 10,
        "SortDir": "Asc",
        "SortBy": "Id"
    },
    "ResponseStatus": {

    },
    "Notifications": [

    ]
}

GET: appresults/{Id}/files

Retrieve a list of files within a given AppResult by its Id

Permissions

  • BROWSE access to the AppResult to which the file belongs

Query parameters in addition to Resource Collection Requests

  • SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: Id
  • Extensions: Filter result AppResults files by extension. Currently the only AppResults files are .bam and .vcf, other file types are supported.
  • Limit: Limit how many results are returned in a the list. Limit can be 0 to 1000 for this method.

To retrieve all bam files in appresult Id 100, in ascending order sorted by Id with a limit of 4:

GET https://api.basespace.illumina.com/v1pre3/appresults/100/files?SortBy=Id&Extensions=.bam&Offset=0&Limit=4&SortDir=Asc

{
    "Response": {
        "Items": [
            {
                "Id": "21311",
                "Href": "v1pre3/files/21311",
                "Name": "s_G1.1.anomaly.bam",
                "ContentType": "application/octet-stream",
                "Size": 45057,
                "Path": "data/intensities/basecalls/Alignment/s_G1.1.anomaly.bam",
                "DateCreated": "2011-11-11T04:41:30.0000000"
            },
            {
                "Id": "21313",
                "Href": "v1pre3/files/21313",
                "Name": "s_G1.1.chr1.bam",
                "ContentType": "application/octet-stream",
                "Size": 82557,
                "Path": "data/intensities/basecalls/Alignment/s_G1.1.chr1.bam",
                "DateCreated": "2011-11-11T04:41:30.0000000"
            },
            {
                "Id": "21315",
                "Href": "v1pre3/files/21315",
                "Name": "s_G1.1.chr10.bam",
                "ContentType": "application/octet-stream",
                "Size": 99208,
                "Path": "data/intensities/basecalls/Alignment/s_G1.1.chr10.bam",
                "DateCreated": "2011-11-11T04:41:30.0000000"
            },
            {
                "Id": "21317",
                "Href": "v1pre3/files/21317",
                "Name": "s_G1.1.chr11.bam",
                "ContentType": "application/octet-stream",
                "Size": 58453,
                "Path": "data/intensities/basecalls/Alignment/s_G1.1.chr11.bam",
                "DateCreated": "2011-11-11T04:41:30.0000000"
            }
        ],
        "DisplayedCount": 4,
        "TotalCount": 22,
        "Offset": 0,
        "Limit": 4,
        "SortDir": "Asc",
        "SortBy": "Id"
    },
    "ResponseStatus": {

    },
    "Notifications": [

    ]
}

GET: files/{Id}/content

Download the contents of a file

Permissions

  • READ access to the Run, Sample, or AppResult to which the file belongs

Query parameters

  • redirect: Whether this method should return a standard 302 redirect or a meta JSON response containing the redirect_uri. Possible values: true and meta. Default: true.

To download the file with Id 2150158:

GET https://api.basespace.illumina.com/v1pre3/files/{Id}/content

This call may redirect the app (via HTTP response code 302) to an alternate download location, such as a pre-signed URL on Amazon S3. This redirect expires on the date given by the Expires header in the response. An app may use this URI as much as necessary before this date after which an app will need to refresh it by calling the API method again. A download is not interrupted if the expiration occurs while it's in progress.

Note that Amazon S3 supports Range requests to download a segment of a file rather than the entire content. Simply add a Range header to the request to S3 as described here.

Applications may upload files to the API as part of an AppResult. Please refer to the Writing Back to BaseSpace Guide for instructions. For larger files and more reliable uploading, please refer to the Multi-Part File Upload guide.

POST: appresults/{id}/files

Change or create files within a particular AppResult, for more information refer to the Writing Back to BaseSpace Guide.

Permissions

  • WRITE access to the AppResult to which the file belongs

Header Parameters

  • Content-Type: the content type of the file being uploaded. This header is required. When downloading this file, the same Content-Type will be returned.

Query Parameters

  • Name: The name of the file as it will be in the AppResult
  • Directory: Use if the data has a directory structure. This will create a directory within the AppResult to place this file.
  • Multipart: This is a boolean value, true or false, to initiate a multipart file download. More information for this is located in the Multi-Part File Upload API.

To POST a file in an AppResult with Id 6797791 with the content type octet-stream, the name myfile.vcf, and in the directory some/path using cURL:

curl -v -H "x-access-token: {access token} \
-d @MyFile.vcf \    
-H "Content-Type: application/octet-stream" \
https://api.basespace.illumina.com/v1pre3/appresults/6797791/files?name=myfile.vcf\&directory=some/path

If successful, a 201 Created is returned with a JSON file object.

HTTP/1.1 201 Created
Content-Type: application/json
Date: Fri, 11 May 2012 10:47:21 GMT

{
  "Response":{
    "HrefContent":"v1pre3/files/1401400/content",
    "Id":"1401400",
    "Href":"v1pre3/files/1401400",
    "Name":"MyFile.vcf",
    "ContentType":"application/octet-stream",
    "Size":176418,
    "Path":"some/path/MyFile.vcf",
    "DateCreated":"2012-05-11T10:47:17.0000000"
  },
  "ResponseStatus":{},
  "Notifications":[]
}

PUT: files/{id}/parts/{number}

To upload file parts to the particular file Id. Parts may be uploaded in parallel and, in the event that the connection fails, the upload for each part may be retried. The parts will be sorted in ascending order regardless of the order of upload (i.e. part 5 can be uploaded before part 4, but will still be sorted normally once fully uploaded). Refer to the Multi-Part File Upload API for more information.

Permissions

  • WRITE access to a particular file

Parameters and Restrictions

  • File Size: Each file part is required to be no greater than 25 MB in size and no less than 5 MB, the last part of the file may be less than 5 MB.
  • Number: Each part must be numbered from 1 to 10000, when uploaded the file's parts will be sorted in ascending order.

Header Parameters

  • Content-MD5: A base64 encoded 128bit MD5 checksum may be provided prior to the upload, which will be checked by the server. By providing a computed value, an app can ensure that the checksum is matched after upload. If the server-calculated value does not match the provided value, the upload will be rejected. Although it is optional, it is highly recommended to ensure data integrity after upload.

Unique Response Parameters

  • Size: The size of the uploaded part.
  • ETag: A hex encoded MD5 digest of the uploaded part data.

To upload part 1 of a file named reportarchive.zipaa with Id 7094087 and to run a MD5 checksum using cURL:

curl -v -H "x-access-token: {access token}" \
-H "Content-MD5: 9mvo6qaA+FL1sbsIn1tnTg==" \
-T reportarchive.zipaa \
-X PUT https://api.basespace.illumina.com/v1pre3/files/7094087/parts/1

Note that the above example shows a file that has already been split into parts on the filesystem (first part being reportarchive.zipaa as generated by split command) but an app is free to use any method it wants to upload a stream of the part segment.

If successful, a 200 OK is returned with a JSON file part object.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 18 Jul 2012 15:21:12 GMT
Content-Length: 90

{
    "Response":{
        "Number":1,
        "ETag":"f66be8eaa680f852f5b1bb089f5b674e",
        "Size":10496561
    },
    "ResponseStatus":{},
    "Notifications":[]
}

POST: files/{id}

This method is used to change the upload status for a multi-part file upload. More information in the Multi-Part File Upload API.

Permissions

  • WRITE access to the particular file that will be changed

Query Parameters

  • UploadStatus: The status of the upload, to trigger completion of a multi-part file upload change this value to complete. The possible statuses are:

    • pending: The upload is pending, the parts are being currently uploaded and has not been marked as complete yet.
    • aborted: The upload has been aborted by the user.
    • complete: The multi-part file upload is complete.

To change the multi-part file upload status of file 7094087 to complete using cURL:

curl -v -H "x-access-token: {access token}" \
-X POST https://api.basespace.illumina.com/v1pre3/files/7094087?uploadstatus=complete

If successful, a 201 Created is returned with the JSON file object. The UploadStatus should be complete.

HTTP/1.1 201 Created
Content-Type: application/json
Date: Wed, 18 Jul 2012 16:20:00 GMT
Content-Length: 304
{
   "Response":{
      "UploadStatus":"complete",
      "HrefContent":"v1pre3/files/7094087/content",
      "Id":"7094087",
      "Href":"v1pre3/files/7094087",
      "Name":"reportarchive.zip",
      "ContentType":"application/zip",
      "Size":527623673,
      "Path":"reportarchive.zip",
      "DateCreated":"2012-07-18T14:51:50.0475813Z"
   },
   "ResponseStatus":{},
   "Notifications":[]
}

Upon getting this response, the file upload is complete.

Variants

The Variantset resource is provided so that an app can access variants within a vcf file. It is useful for querying the variance of a particular chromosomal region and for different genome broswers to find the variance in a particular location.

Variants are extracted from VCF files and stored in a document database to enable fast range-based queries. There are two parts: the "variant set", which contains the information in the VCF file header, and the "variants", or the data lines in the VCF file.

To find the variant id, the following steps are required:

1.  Find the Id of the appresult which the app would like to find the variants in.
2.  Use GET: appresults/{id}/files, search for the vcf extension, and find the Id of the specific vcf file within that appresult.
3.  Use GET: files/{id} and within that there will be an `HrefVariants` field which shows the Id of the variant for this appresult.

Response Elements

The response elements for the variant method are synchronous to the vcf file format. The first variant method describes the header of the vcf file while the second describes the rest of the vcf file. More information about the vcf file format can be found here.

Query parameters

  • Format: The format in which to retrieve the results. Possible value: json or vcf. Default: json

GET: variantset/{Id}

Retrieve a variant set

Permissions

  • BROWSE access to the variantset by Id

To retrieve a variant with Id 2150158:

GET https://api.basespace.illumina.com/v1pre3/variantset/2150158
{
    Metadata : {
        fileformat: "VCFv4.1",
        fileDate: "20120126",
        source: "/illumina/development/casava/CASAVA-1.8_BF01187/libexec/CASAVA-1.9.0a1_110909/makeConsensusVcf.pl --ref=/illumina/scratch/iGenomes/Homo_sapiens/UCSC/hg19/Sequence/Chromosomes/chr10.fa --snps=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/snps.txt --indels=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/indels.txt --sites=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0000/sites.txt.gz --sites=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0001/sites.txt.gz --sites=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0002/sites.txt.gz --indels=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0000/indels.removed.txt --indels=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0001/indels.removed.txt --indels=/illumina/builds/thunderbolt/500ng_H1_CT8244.casava18/Parsed_25-01-12/chr10/0002/indels.removed.txt",
        sitesMaxDepth_chr10: "121.296617413957"
        indelsMaxDepth_chr10: "123.655927166378"
    },
    Legends : {
        INFO: [
            {
                ID: "SVTYPE",
                Number: "1",
                Type: "String",
                Description: "Type of structural variant"
                },
                {
                ID: "CIGAR",
                Number: "A",
                Type: "String",
                Description: "CIGAR alignment for each alternate allele at loci containing indels other than breakends."
                }
        },
        FILTER : [
            {
                ID: "QGT20",
                Description: "Locus genotype quality is less than 20 or not computable."
            },
            {
                ID: "FILT30",
                Description: "More than 30% of bases at a site are filtered out."
            }
        ],
        FORMAT : [
            {
                ID: "GT",
                Number: "1",
                Type: "String",
                Description: "Genotype"
            },
            {
                ID: "GQ",
                Number: "1",
                Type: "Integer",
                Description: "Genotype Quality"
            }
        ],
        "Samples" : [ "SAMPLE_1" ]
    },
   "ResponseStatus":{},
   "Notifications":[]
}

GET: variantset/{Id}/variants/{Chrom}

Retrieve variants in a specific chromosome

Permissions

  • READ access to the AppResult to which the source file belongs

Query parameters in addition to the ones stated above

  • Chrom: The chromosome within which the variantset will be analyzed. The following example uses chrX.
  • StartPos: The starting position in the chromosome to search for the variant, can be any number within the range of the chromosome. No default value, must be specified and must be an integer.
  • EndPos: The ending position in the chromosome to search for the variant, can be any number within the range of the chromosome. No default value, must be specified and must be an integer.

To retrieve the variant with Id 2150158 in a specific range of chromosome chr2, specified by StartPos and EndPos:

GET https://api.basespace.illumina.com/v1pre3/variantset/2150158/variants/chr2?StartPos=1&EndPos=11000&Limit=1
{
   "Response":{
      "Items":[
         {
            "CHROM":"chr2",
            "POS":10236,
            "ID":[
               "."
            ],
            "REF":"AC",
            "ALT":"A",
            "QUAL":61,
            "FILTER":"PASS",
            "INFO":{
               "VARTYPE_DEL":[
               ],
               "CIGAR":[
                  "1M1D"
               ],
               "RU":[
                  "C"
               ],
               "REFREP":[
                  "4"
               ],
               "IDREP":[
                  "3"
               ]
            },
            "SampleFormat":{
               "SAMPLE":{
                  "GT":"0/1",
                  "GQ":"61",
                  "DPI":"12"
               }
            }
         },
    ],
      "DisplayedCount":1,
      "Offset":0,
      "Limit":1,
      "SortDir":"Asc",
      "SortBy":"Position"
   },
   "ResponseStatus":{
   },
   "Notifications":[
   ]
}

Coverage

The Coverage resource is used to provide mean read coverage depth in a particular chromosomal region, and it is returned as a histogram.

Mean read coverage depth is calculated by parsing the BAM files produced by alignments. This information is stored in "buckets" of 128 bases each.

To enable interactive applications, such as genome browsers, that display coverage histogram plots, the API supports aggregate queries at various "zoom levels". These zoom levels are calculated automatically based on the size of the range quested, to keep the result set below approximately 2000 entries.

Given a start and stop position, the API determines how many values will be returned. The number of returned values will never be more than 2048 in a single request.

Response Elements

  • MeanCoverage: The averaged coverage data for a particular bucketsize over all reads
  • BucketSize: The length of bases over which the meancoverage will be calculated, essentially the bases per bin
  • MaxCoverage: The maximum coverage value for a chromosome
  • CoverageGranularity: The granularity of the overall coverage data, 128 bases per bin

GET: coverage/{Id}/{Chrom}

Retrieve coverage data in a specific chromosome

Permissions

  • READ access to the sample to which the source file belongs

Query parameters

  • Chrom: The chromosome within which the variantset will be analyzed. The following example uses chr2.
  • StartPos: The starting position in the chromosome to search for the variant, can be any number within the range of the chromosome. No default value, must be specified and must be an integer.
  • EndPos: The ending position in the chromosome to search for the variant, can be any number within the range of the chromosome. No default value, must be specified and must be an integer.

To retrieve the coverage of the chrX chromosome within file 2150156, starting at 1 and ending at 20000:

GET https://api.basespace.illumina.com/v1pre3/coverage/2150156/chrX?startPos=1&endPos=20000
{
    "Response": {
        "MeanCoverage": [
            12,
            10,
            ....
            0,
            0
        ],
        "Chrom": "chrX",
        "StartPos": 1,
        "EndPos": 20096,
        "BucketSize": 16
    },
    "ResponseStatus": { },
    "Notifications": [ ]
}

The response contains the actual start and stop positions, rounded to the nearest interval supported by the underlying data. The underlying data is stored at the granularity of 128 bases, so responses to requests for zoom levels below 7 will contain repetitive data.

Each value returned represents the mean coverage depth for a number of base positions indicated by BucketSize. In the above example, bases 20096-20112 have mean coverage of 12, while 20112-20128 have coverage of 10.

The chromosomes with available coverage must match the names in the BAM file.

GET: coverage/{Id}/{Chrom}/meta

Retrieve metadata about the coverage in a chromosome

Permissions

  • READ access to the sample to which the source file belongs

To query coverage metadata in chromosome chrX:

GET https://api.basespace.illumina.com/v1pre3/coverage/2150156/chrX/meta
{
    "Response": {
        "MaxCoverage": 9968,
        "CoverageGranularity": 128
    },
    "ResponseStatus": { },
    "Notifications": [ ]
}

In the above case, chromosome chrX has a maximum coverage value of 9968 and is stored natively in bins with granularity of 128 bases per bin.

Properties

A property is a lightweight storage mechanism of metadata for many of the resources available via the API. Each property has a unique name within its parent resource.

Properties may be written to the following resources if the client has WRITE access to the resource: Samples, AppResults, Runs, AppSessions, and Projects.

Note: Properties are available as a pre-release at the moment in BaseSpace.

Several basic property types are supported:

  • string: store text up to 64kb in length.
  • map: a list of key/value pairs. The key name must be unique within the map. The value is an array of strings.
  • resource reference: this allows referencing another BaseSpace resource such as specific input to an appsession. The supported reference types are:
    • sample
    • appresult
    • run
    • appsession
    • project

It's also possible to store any of the above types as an array. Arrays are represented with the above type name followed by []. Examples: sample[], map[], string[].

Properties may be written to the following resources if the client has WRITE access to the resource: samples, appresults, runs, appsessions, projects.

The existing concept of References as used within AppSessions, Samples, and AppResults will be obsoleted and replaced with properties. Full backwards compatibility is being provided for the current v1pre3 version.

Pre-release notes:

  • The BaseSpace UI does not yet display or allow interaction with properties. This will be available in an upcoming release.
  • Other than enforcing length, valid characters, and the inclusion of at least one namespace in a property name, any property name may be used. We will be introducing restrictions around certain property namespaces in upcoming releases and these will be described here.

GET: {resource}/{id}/properties

Retrieve the properties associated with a resource, e.g. GET: appsessions/{id}/properties.

Note that properties are also included as part of the full resource representation, e.g. GET: appsessions/{id}.

Permissions

BROWSE access to the resource

Query parameters are covered by Resource Collection Requests

GET https://api.basespace.illumina.com/v1pre3/appsessions/123/properties
{
    "Response":
        {
            "Items":
                [
                    {
                        "Type":"string",
                        "Href":"v1pre3/appsessions/123/properties/mytestapp.metrics.magicnumber",
                        "Name":"mytestapp.metrics.magicnumber",
                        "Description":"",
                        "Content":"42"
                    },
                    {
                        "Type":"appresult[]",
                        "Href":"v1pre3/appsessions/123/properties/mytestapp.inputs.appresults",
                        "Name":"mytestapp.inputs.appresults",
                        "Description":"",
                        "ItemsDisplayedCount":2,
                        "ItemsTotalCount":2,
                        "HrefItems":"v1pre3/appsessions/123/properties/mytestapp.inputs.appresults/items",
                        "Items":
                            [
                                { 
                                    /* AppResult included here */
                                },
                                {
                                    /* AppResult included here */
                                }
                            ]
                    },
                    {
                        "Type": "map",
                        "Href": "v1pre3/projects/592593/properties/mytestapp.inputs.metrics",
                        "Name": "mytestapp.inputs.metrics",
                        "Description": "Graph data for energydrinks vs productivity levels",
                        "Content": [
                        {
                            "Key": "label.x-axis",
                            "Values": [ "energydrinks" ]
                        },
                        {
                            "Key": "label.y-axis",
                            "Values": [ "productivity" ]
                        },
                        {
                            "Key": "series.x-axis",
                            "Values": [ "0", "1", "2", "3", "4" ]
                        },
                        {
                            "Key": "series.y-axis",
                            "Values": [ "5", "7", "8", "4", "1" ]
                        }
                        ]
                    }
                  ],
            "DisplayedCount":3,
            "TotalCount":3,
            "Offset":0,
            "Limit":1024,
            "SortDir":"Asc",
            "SortBy":"Name"
        }
    ,"ResponseStatus":{},
    "Notifications":[]
}

POST: {resources/id}/properties

Create or update the content of one or more properties associated with a resource.

Permissions

WRITE access to the resource

To create or update the mytestapp.metrics.magicnumber property, which is a single-value litereal, and the mytestapp.inputs.appresults property, which contains multiple resource references:

curl -v -H "x-access-token: {access token} 
-H "Content-Type: application/json" 
-X POST -d
{
    "Properties":
    [
        {
            "Type": "string",
            "Name": "mytestapp.metrics.magicnumber",
            "Description": "",
            "Content": "42"
        },
        {
            "Name": "mytestapp.inputs.appresults",
            "Type": "appresult[]",
            "Description": "",
            "Items": [
                "appresults/3006",
                "appresults/3005"
            ]
        },
        {
            "Name": "mytestapp.inputs.samples",
            "Type": "sample[]",
            "Description": "",
            "Items": [
                "samples/1001",
                "samples/2002"
            ]
        },
        {
            "Name": "mytestapp.inputs.metrics",
            "Description": "Graph data for energydrinks vs productivity levels",
            "ContentMap": [
                {
                    "Key": "label.x-axis",
                    "Values": [ "energydrinks" ]
                },
                {
                    "Key": "label.y-axis",
                    "Values": [ "productivity" ]
                },
                {
                    "Key": "series.x-axis",
                    "Values": [ "0", "1", "2", "3", "4" ]
                },
                {
                    "Key": "series.y-axis",
                    "Values": [ "5", "7", "8", "4", "1" ]
                }
            ]
        }
    ]
}
https://api.basespace.illumina.com/v1pre3/{resource/id}/properties

The response code is 201 Created if one or more properties were added otherwise 200 Ok if only changes to property content (those having the same name) were performed.

The response body will contain any added and updated properties. This output is formatted in the same way as GET: {resource/id}/properties described above.

The type is very important, the following types will attach the related resources' metadata to the Properties Items array: file, file[], run, run[], sample, sample[], appresult, and appresult[].

GET: {resources}/{id}/properties/{name}/items

Retrieve the items associated with the given multi-value property.

Permissions

BROWSE access to the resource

Query parameters are covered by Resource Collection Requests

To retrieve details about the items associated with a property:

GET https://api.basespace.illumina.com/v1pre3/appsessions/123/properties/mytestapp.inputs.appresults/items 
{
    "Response":
        {
            "Type":"appresult[]",
            "Items":
                [
                    {
                        "Id":"4cdd018951c7437fb473c75d6db55bc0",
                        "Content":
                            {
                                /* AppResult included here */  
                            }                        
                    },
                    {
                        "Id":"2354e0e8e21f4d42bdf3705bef4fa514",
                        "Content":
                            {
                                /* AppResult included here */                                  
                            }
                    }
                ],
            "DisplayedCount":2,
            "TotalCount":2,
            "Offset":0,
            "Limit":50,
            "SortDir":"Asc",
            "SortBy":"DateCreated"
        },
    "ResponseStatus":{},
    "Notifications":[]
}

DELETE: {resource}/{id}/properties/{name}

Delete a property associated with a resource.

Permissions

WRITE access to the resource

Example request:

curl -v -H "x-access-token: {access token} -X DELETE https://api.basespace.illumina.com/v1pre3/appsessions/123/properties/mytestapp.inputs.appresults

This will delete the property mytestapp.inputs.appresults associated with appsession 123.

Trash Apis

This section covers apis responsible for moving items in and out of the trash, and emptying the trash for the current user.

DELETE: {resource}/{id}

Delete a resource (run, project, sample, appresult, appsession) on behalf of the current user. This moves the resource to the user's trash, where it can be either emptied (and gone forever), or restored. Resource can be one of the following:

  • runs
  • projects
  • appsessions
  • appresults
  • samples

It returns the trash response with the details of the item in the trash.

Permissions

MOVETOTRASH GLOBAL global permission granted by the user.

Query Parameters

  • Preserve=metadata: Performs a delete of just the files for this resource. The resource will remain visible in the api, but the files will not. Currently only supported for runs.

Example request:

curl -v -H x-access-token: {access token} -X DELETE https://api.basespace.illumina.com/v1pre3/projects/123

Example response:

{
    "Response": {
    "IncludedSamples": [],
    "IncludedAppResults": [],
    "IncludedAppSessions": [],
    "UserDeletedBy": {
        "Id": "10000001",
        "Href": "v1pre3/users/10000001",
        "Name": "Hillary Clinton",
        "DateCreated": "2012-11-27T01:27:14.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/xyzabc.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
    },
    "Id": "12341234",
    "Name": "Secret Emails",
    "Href": "v1pre3/trash/12341234",
    "DateDeleted": "2016-11-05T00:42:46.3637060Z",
    "TotalSize": 0,
    "DeletedProject": {
        "Id": "123",
        "UserOwnedBy": {
        "Id": "10000001",
        "Href": "v1pre3/users/11012",
        "Name": "Hillary Clinton",
        "DateCreated": "2012-11-27T01:27:14.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/xyzabc.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
        },
        "Href": "v1pre3/projects/123",
        "Name": "Secret Emails",
        "Description": "",
        "DateCreated": "2016-11-05T00:42:24.0000000",
        "DateModified": "2016-11-05T00:42:46.3637060Z",
        "HasCollaborators": false,
        "IsDeleted": true,
        "TotalSize": 0
    },
    "IsVisibleInTrash": true,
    "ChildCount": 0,
    "HrefPostRestoreFromTrash": "v1pre3/trash/12341234/RestoreFromTrash",
    "Includes": [
        "FILEDATA",
        "METADATA"
    ]
    },
    "ResponseStatus": {},
    "Notifications": []
}

This will delete the project 123 and it will be in the trash.

GET users/current/trash

Lists the current user's items that are in their trash.

Permissions

MOVETOTRASH GLOBAL global permission granted by the user.

Query Parameters

  • Limit: Limit the maximum number of items after the offset. Default: 10
  • Offset: Number of items to skip in the resultset. Default: 0
  • SortBy: Order the results by a given field. Possible value: DateDeleted and TotalSize.
  • SortDir: What direction to sort results by. Possible values: Asc and Desc.

Example request:

curl -v -H x-access-token: {access token} -X DELETE https://api.basespace.illumina.com/v1pre3/users/current/trash

Example response:

{
    "Response": {
    "Items": [
        {
        "Id": "271273",
        "Name": "CAmpliconCancerPanel_111412",
        "Href": "v1pre3/trash/271273",
        "DateDeleted": "2016-11-07T23:06:19.0000000",
        "TotalSize": 1846270973,
        "DeletedProject": {
            "Id": "222333",
            "UserOwnedBy": {
            "Id": "333444",
            "Href": "v1pre3/users/333444",
            "Name": "Hillary Clinton",
            "DateCreated": "2012-11-27T01:27:14.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
            },
            "Href": "v1pre3/projects/222333",
            "Name": "CAmpliconCancerPanel_111412",
            "Description": "",
            "DateCreated": "2012-11-15T22:11:48.0000000",
            "DateModified": "2016-11-07T23:06:21.0000000",
            "HasCollaborators": false,
            "IsDeleted": true,
            "TotalSize": 0
        },
        "IsVisibleInTrash": true,
        "ChildCount": 348,
        "HrefPostRestoreFromTrash": "v1pre3/trash/271273/RestoreFromTrash",
        "Includes": [
            "FILEDATA",
            "METADATA"
        ]
        },
        {
        "Id": "271271",
        "Name": "new test project",
        "Href": "v1pre3/trash/271271",
        "DateDeleted": "2016-11-07T22:17:49.0000000",
        "TotalSize": 0,
        "DeletedProject": {
            "Id": "4445555",
            "UserOwnedBy": {
            "Id": "333444",
            "Href": "v1pre3/users/333444",
            "Name": "Hillary Clinton",
            "DateCreated": "2012-11-27T01:27:14.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
            },
            "Href": "v1pre3/projects/4445555",
            "Name": "new test project",
            "Description": "",
            "DateCreated": "2014-11-20T08:44:48.0000000",
            "DateModified": "2016-11-07T22:17:49.0000000",
            "HasCollaborators": false,
            "IsDeleted": true,
            "TotalSize": 0
        },
        "IsVisibleInTrash": true,
        "ChildCount": 1,
        "HrefPostRestoreFromTrash": "v1pre3/trash/271271/RestoreFromTrash",
        "Includes": [
            "FILEDATA",
            "METADATA"
        ]
        },
        {
        "Id": "270270",
        "Name": "x",
        "Href": "v1pre3/trash/270270",
        "DateDeleted": "2016-11-05T00:42:46.0000000",
        "TotalSize": 0,
        "DeletedProject": {
            "Id": "6667777",
            "UserOwnedBy": {
            "Id": "333444",
            "Href": "v1pre3/users/333444",
            "Name": "Hillary Clinton",
            "DateCreated": "2012-11-27T01:27:14.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
            },
            "Href": "v1pre3/projects/6667777",
            "Name": "x",
            "Description": "",
            "DateCreated": "2016-11-05T00:42:24.0000000",
            "DateModified": "2016-11-05T00:42:46.0000000",
            "HasCollaborators": false,
            "IsDeleted": true,
            "TotalSize": 0
        },
        "IsVisibleInTrash": true,
        "ChildCount": 0,
        "HrefPostRestoreFromTrash": "v1pre3/trash/270270/RestoreFromTrash",
        "Includes": [
            "FILEDATA",
            "METADATA"
        ]
        },
        {
        "Id": "261263",
        "Name": "test delete multi",
        "Href": "v1pre3/trash/261263",
        "DateDeleted": "2016-10-13T23:08:03.0000000",
        "TotalSize": 0,
        "DeletedProject": {
            "Id": "33332222",
            "UserOwnedBy": {
            "Id": "333444",
            "Href": "v1pre3/users/333444",
            "Name": "Hillary Clinton",
            "DateCreated": "2012-11-27T01:27:14.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
            },
            "Href": "v1pre3/projects/33332222",
            "Name": "test delete multi",
            "Description": "",
            "DateCreated": "2016-10-13T23:05:55.0000000",
            "DateModified": "2016-10-13T23:08:03.0000000",
            "HasCollaborators": false,
            "IsDeleted": true,
            "TotalSize": 0
        },
        "IsVisibleInTrash": true,
        "ChildCount": 0,
        "HrefPostRestoreFromTrash": "v1pre3/trash/261263/RestoreFromTrash",
        "Includes": [
            "FILEDATA",
            "METADATA"
        ]
        }
    ],
    "DisplayedCount": 4,
    "TotalCount": 4,
    "Offset": 0,
    "Limit": 25,
    "SortDir": "Desc",
    "SortBy": "DateDeleted"
    },
    "ResponseStatus": {},
    "Notifications": []
}

GET: trash/{id}

Get the details of an item in the trash.

Permissions

MOVETOTRASH GLOBAL global permission granted by the user.

Example Request:

curl -v -H x-access-token: {access token} -X GET https://api.basespace.illumina.com/v1pre3/trash/123456

Example Response:

{
    "Response": {
    "IncludedSamples": [],
    "IncludedAppResults": [],
    "IncludedAppSessions": [
        {
        "Id": "9998888",
        "Name": "BWA Enrichment 11/20/2014 12:44:44",
        "Href": "v1pre3/appsessions/9998888",
        "Application": {
            "Id": "196196",
            "Href": "v1pre3/applications/196196",
            "Name": "BWA Enrichment",
            "CompanyName": "Illumina, Inc",
            "VersionNumber": "1.0.0",
            "HomepageUri": "http://support-test.illumina.com/help/BaseSpace_App_enr_BWA_help/BWAEnrichmentHelp.htm",
            "ShortDescription": "The core algorithms in the BWA Enrichment workflow are the BWA Genome Alignment Software and the GATK Variant Caller.",
            "DateCreated": "2013-08-13T06:16:20.0000000",
            "DatePublished": "0001-01-01T00:00:00.0000000",
            "PublishStatus": "Published",
            "IsBillingActivated": false,
            "Category": "Instance",
            "Classifications": [
            "TargetedSequencing"
            ],
            "AppFamilySlug": "illumina-inc.bwa-enrichment",
            "AppVersionSlug": "illumina-inc.bwa-enrichment.1.0.0",
            "Features": [],
            "LockStatus": "Unlocked"
        },
        "UserCreatedBy": {
            "Id": "222111",
            "Href": "v1pre3/users/11012",
            "Name": "Donald Trump",
            "DateCreated": "0001-01-01T00:00:00.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
        },
        "Completed": "2014-11-20T08:57:27.0000000",
        "IsDeleted": true
        }
    ],
    "UserDeletedBy": {
        "Id": "222111",
        "Href": "v1pre3/users/11012",
        "Name": "Donald Trump",
        "DateCreated": "0001-01-01T00:00:00.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
    },
    "Id": "271271",
    "Name": "new test project",
    "Href": "v1pre3/trash/271271",
    "DateDeleted": "2016-11-07T22:17:49.0000000",
    "TotalSize": 0,
    "DeletedProject": {
        "Id": "2033031",
        "UserOwnedBy": {
        "Id": "222111",
        "Href": "v1pre3/users/11012",
        "Name": "Donald Trump",
        "DateCreated": "0001-01-01T00:00:00.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
        },
        "Href": "v1pre3/projects/2033031",
        "Name": "new test project",
        "Description": "",
        "DateCreated": "2014-11-20T08:44:48.0000000",
        "DateModified": "2016-11-07T22:17:49.0000000",
        "HasCollaborators": false,
        "IsDeleted": true,
        "TotalSize": 0
    },
    "IsVisibleInTrash": true,
    "ChildCount": 1,
    "HrefPostRestoreFromTrash": "v1pre3/trash/271271/RestoreFromTrash",
    "Includes": [
        "FILEDATA",
        "METADATA"
    ]
    },
    "ResponseStatus": {},
    "Notifications": []
}

POST trash/{Id}/restorefromtrash

Restores an item from the trash back to active.

Permissions

MOVETOTRASH GLOBAL global permission granted by the user.

Example Request:

curl -v -H x-access-token: {access token} -X POST https://api.basespace.illumina.com/v1pre3/trash/123456/restorefromtrash

Example Response:

{
    "Response": {
    "IncludedSamples": [],
    "IncludedAppResults": [],
    "IncludedAppSessions": [
        {
        "Id": "9998888",
        "Name": "BWA Enrichment 11/20/2014 12:44:44",
        "Href": "v1pre3/appsessions/9998888",
        "Application": {
            "Id": "196196",
            "Href": "v1pre3/applications/196196",
            "Name": "BWA Enrichment",
            "CompanyName": "Illumina, Inc",
            "VersionNumber": "1.0.0",
            "HomepageUri": "http://support-test.illumina.com/help/BaseSpace_App_enr_BWA_help/BWAEnrichmentHelp.htm",
            "ShortDescription": "The core algorithms in the BWA Enrichment workflow are the BWA Genome Alignment Software and the GATK Variant Caller.",
            "DateCreated": "2013-08-13T06:16:20.0000000",
            "DatePublished": "0001-01-01T00:00:00.0000000",
            "PublishStatus": "Published",
            "IsBillingActivated": false,
            "Category": "Instance",
            "Classifications": [
            "TargetedSequencing"
            ],
            "AppFamilySlug": "illumina-inc.bwa-enrichment",
            "AppVersionSlug": "illumina-inc.bwa-enrichment.1.0.0",
            "Features": [],
            "LockStatus": "Unlocked"
        },
        "UserCreatedBy": {
            "Id": "222111",
            "Href": "v1pre3/users/11012",
            "Name": "Donald Trump",
            "DateCreated": "0001-01-01T00:00:00.0000000",
            "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
            "ExternalDomainId": "xyzabc"
        },
        "Completed": "2014-11-20T08:57:27.0000000",
        "IsDeleted": false
        }
    ],
    "UserDeletedBy": {
        "Id": "222111",
        "Href": "v1pre3/users/11012",
        "Name": "Donald Trump",
        "DateCreated": "0001-01-01T00:00:00.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
    },
    "Id": "271271",
    "Name": "new test project",
    "Href": "v1pre3/trash/271271",
    "DateDeleted": "2016-11-07T22:17:49.0000000",
    "TotalSize": 0,
    "DeletedProject": {
        "Id": "2033031",
        "UserOwnedBy": {
        "Id": "222111",
        "Href": "v1pre3/users/11012",
        "Name": "Donald Trump",
        "DateCreated": "0001-01-01T00:00:00.0000000",
        "GravatarUrl": "https://secure.gravatar.com/avatar/50c49d02d7f932b903cd88f971ece3e6.jpg?s=20&d=mm&r=PG",
        "ExternalDomainId": "xyzabc"
        },
        "Href": "v1pre3/projects/2033031",
        "Name": "new test project",
        "Description": "",
        "DateCreated": "2014-11-20T08:44:48.0000000",
        "DateModified": "2016-11-07T22:17:49.0000000",
        "HasCollaborators": false,
        "IsDeleted": false,
        "TotalSize": 0
    },
    "IsVisibleInTrash": false,
    "ChildCount": 1,
    "HrefPostRestoreFromTrash": "v1pre3/trash/271271/RestoreFromTrash",
    "Includes": [
        "FILEDATA",
        "METADATA"
    ]
    },
    "ResponseStatus": {},
    "Notifications": []
}

DELETE users/current/trash

Empties the user's trash. This is NOT reversible. All items will be marked for deletion and purged once this request is made.

Permissions

  • EMPTY TRASH - permission to empty the user's current trash granted by the user.

Example Request:

curl -v -H x-access-token: {access token} -X DELETE https://api.basespace.illumina.com/v1pre3/users/current/trash

Example Response:

200 OK