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.
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:
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.
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:
x-access-tokenAuthorization. The value must take the form: Bearer {access_token} (with a space between Bearer and the code).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.
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.
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.
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 returnedTotalCount: The total number of items in the collectionThese 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 elementId: Id of the resourceName: Name of the selected resourceHref: Location of the resource in the APIDateCreated: When this resource was createdUserOwnedBy: Information about the User who owns this resourceStatus: The status of the resource, if it is inside of an appsession it is the status of the AppSessionHrefBaseSpaceUI: The location of this resource in the BaseSpace User InterfaceProperties: 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.
BROWSE - The ability to see resource metadata, but not download or change any contentREAD - 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.
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.
The following sections cover the resources supported by the BaseSpace API. The usage is illustrated by example output for each request.
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.
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": []
}
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 dataQuery 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_codeclient_id: If not using the Authorization headerclient_secret: If not using the Authorization headerExample 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.
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 screenresponse_type (required): must be the value device_codescope (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.
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 addressHrefRuns: The runs that the user owns or has access toHrefProjects: The projects that the user owns or has access toGET 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":[
]
}
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 APIHrefSamples: The location of the run's samples in the APIUserUploadedBy: Information about the user who uploaded the runDateUploadCompleted: The date when the upload was completedDateUploadStarted: The date when the upload was startedExperimentName: The name of the experiment, set by the user who uploads the runStatus: The status of the RunRetrieve a specific run by its Id
Permissions
BROWSE access to the RunTo 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": []
}
Retrieve a list of runs accessible by the user current user
Permissions
BROWSE access to the runs the current user has access toQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id or DateCreated. Default: IdStatuses: 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":[
]
}
See Trash Apis in the Trash Api section
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 projectHrefAppResults: The href to the appresults in this projectTransferPending: 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.To retrieve a specific project by its Id
Permissions
BROWSE access to the projectExample 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": []
}
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 listingQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: IdName: The name of a Project. This call will return Projects with the given Name for the current userTo 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":[]
}
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 dataRequired parameters
Name: The name of the projectTo 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": []
}
See Trash Apis in the Trash Api section
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 fromContent: Shows the resource content, including the owner's informationStatus: 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 appApplication: The application that created this appsession, includes information about the applicationParentAppSession: 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 nodeRetrieve 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 applicationTo 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.
A list of the current user's AppSessions.
Permissions
Query Parameters
AppId: The Id of the Application that created this AppSessionStatus: To Filter the list by Status of the AppSession, this query parameter can be usedTo 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: [ ]
}
Change the current status of the AppSession by its Id
Permissions
WRITE access to the referenced AppResults through its parent ProjectQuery 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.
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
access_token from the Credentials tab in the developer portalRestrictions
Only for Native Apps
Free apps are supported, paid apps are not supported yet
Header Parameters
Content-Type: This value should always be set to application/jsonx-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 toQuery 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.
See Trash Apis in the Trash Api section
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 exposedSampleNumber: The sample number of this sample within the projectExperimentName: The name of the run from which this sample was takenHrefFiles: The location of the files for this sampleAppSession: Information about the appsession that created this sampleIsPairedEnd: Designates whether or not the read is a paired end readRead1: The length of the first Read, the number of basesRead2: The length of the second Read, the number of basesNumReadsRaw: The number of Reads for this SampleNumReadsPF: The number of Reads that have passed filtersSampleId: The Id of the Sample from the samplesheet, this is specified by the user at the flow cell levelReference: 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 AppResultType: The type of resource that was output from using this Sample as an input to an application, generally AppResultContent: Gives detailed information about the AppResult(s) which used this Sample dataRetrieve 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 projectExample 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:[
]
}
Retrieve a collection of samples inside of a given project
Permissions
BROWSE access to the projectQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: IdTo 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":[]
}
See Trash Apis in the Trash Api section
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 exposedHrefFiles: The location of the files for this appresultAppSession: Information about the appsession that created this appresultReferences: 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 SamplesType: Which type of resource is used as the input, can be Project/Samples/AppResultsContent: Some detailed information about the Type described above.Retrieve a specific AppResult by its Id. There is an appsession field in the response that is further explained in the App Sessions portion of this document.
Permissions
BROWSE access to the AppResult either directly or via access to a project containing the AppResultExample 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: [ ]
}
Retrieve a list of AppResults within a specific project Id
Permissions
BROWSE access to the ProjectQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Name, or DateCreated. Default: IdTo 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":[]
}
Returns a list of the AppResults that were created by an AppSession
Permissions
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: [ ]
}
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, containedHeader Parameters
x-access-token: The access_token that an app has for this processContent-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 GuideDefining 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 AppResultHrefAppSession: 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 AppResultType: The type of resource that was used as an input to this AppResultHrefContent: Gives the location of the Type specified above. In the following example the Type is Sample and the Id of that sample is 1100.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",
"Type":"Sample",
"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:[
]
}
See Trash Apis in the Trash Api section
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 isSource: The source from which this genome was uploadedBuild: Tracks the version or build of the genomeRetrieve 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: IdTo 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":[]
}
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":[]
}
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 fileHrefContent: There in the API the content of the file is locatedHrefCoverage: The location in the API of the coverage for this fileSize: The size, in bytes, of this filePath: The path to this file in the BaseSpace UIHrefVariants: The location in the API of the variants for this fileContentType: The type of content contained within this fileOriginalScope: 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.Retrieve information about a given file by its Id
Permissions
BROWSE access to the Run, Sample, or AppResult to which the file belongsRetrieve 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":[
]
}
Retrieve a collection of files belonging to a given run Id
Permissions
BROWSE access to the Run to which the files belongQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: IdExtensions: 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":[
]
}
Retrieve a collection of files belonging to a given sample Id
Permissions
BROWSE access to the Sample to which the files belongQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: IdExtensions: 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": [
]
}
Retrieve a list of files within a given AppResult by its Id
Permissions
BROWSE access to the AppResult to which the file belongsQuery parameters in addition to Resource Collection Requests
SortBy: Order the results by a given field. Possible value: Id, Path or DateCreated. Default: IdExtensions: 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": [
]
}
Download the contents of a file
Permissions
READ access to the Run, Sample, or AppResult to which the file belongsQuery 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.
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 belongsHeader 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 AppResultDirectory: 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":[]
}
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 fileParameters and Restrictions
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":[]
}
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 changedQuery 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.
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: jsonRetrieve a variant set
Permissions
BROWSE access to the variantset by IdTo 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":[]
}
Retrieve variants in a specific chromosome
Permissions
READ access to the AppResult to which the source file belongsQuery 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":[
]
}
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 readsBucketSize: The length of bases over which the meancoverage will be calculated, essentially the bases per binMaxCoverage: The maximum coverage value for a chromosome CoverageGranularity: The granularity of the overall coverage data, 128 bases per binRetrieve coverage data in a specific chromosome
Permissions
READ access to the sample to which the source file belongsQuery 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.
Retrieve metadata about the coverage in a chromosome
Permissions
READ access to the sample to which the source file belongsTo 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.
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.sampleappresultrunappsessionprojectIt'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:
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":[]
}
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[].
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 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.
This section covers apis responsible for moving items in and out of the trash, and emptying the trash for the current user.
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:
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": "Jane Doe",
"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": "my old project",
"Href": "v1pre3/trash/12341234",
"DateDeleted": "2016-11-05T00:42:46.3637060Z",
"TotalSize": 0,
"DeletedProject": {
"Id": "123",
"UserOwnedBy": {
"Id": "10000001",
"Href": "v1pre3/users/11012",
"Name": "Jane Doe",
"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": "my old project",
"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.
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: 10Offset: Number of items to skip in the resultset. Default: 0SortBy: 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": "Jane Doe",
"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": "Jane Doe",
"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": "Jane Doe",
"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": "Jane Doe",
"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 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": "John Doe",
"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": "John Doe",
"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": "John Doe",
"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": []
}
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": "John Doe",
"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": "John Doe",
"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": "John Doe",
"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": []
}
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