The BaseSpace Search API is a set of REST service endpoints that further expand the functionality of the BaseSpace API by enabling the developer with the ability to search through the API in order to create more filtered results.
In order to use the Search API, you will need to include a valid
access_token with the request.
For information about how to get Access Tokens, please view the [api-reference#OAuthProcess) documentation.
For information about how to use Access Tokens with your Search queries, please view the API Reference - Using the Access Token documentation.
More information about these processes can be found in the [/docs/content/documentation/authentication/obtaining-access-tokens) and App Triggering portions of this site.
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:
This path refers to API version
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:
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:
1024, the implicit Range of
Limit for the Files resource is
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
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.
BROWSE GLOBALaccess (requires access token)
x-access-token: The access_token that has browse global level of permission to the user's data
scope: The scope that you wish to have applied to the search query, possible values are
query: A query that you wish to apply to the search query, this is to further narrow the search results. There is a table below which shows all possible queries for the different resources above.
This section describes the possible values for
query when using the Search API.
|Resource (`scope` value)||Possible values for `query`|
Each of these queryable items are objects, so in the query string you will have to go through the JSON for these resources and specify the value you would like to query, e.g. to search for a Project with a certain Name or Id you would type (
projects.name:<projectname>) and (
projects.id:<projectid>) respectively. The information available for each resource is available in the BaseSpace API Reference documentation.
For questions about the query syntax or for more advanced queries, please view the following page: http://lucene.apache.org/core/294/queryparsersyntax.html. This is the Query syntax for elastic search queries.
Some examples of search queries in BaseSpace.
Search for a resource by name, in this example we are searching for a Run with
140609 in its name:
Search for all Samples in Project with Id 2:
Search for all Samples in Project with Id
4 and for which the Genome is