developer.cytobank.org
Open in
urlscan Pro
54.160.145.202
Public Scan
URL:
https://developer.cytobank.org/
Submission: On October 10 via automatic, source certstream-suspicious — Scanned from DE
Submission: On October 10 via automatic, source certstream-suspicious — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
Public
Documentation Settings
Environment
No Environment
Layout
Double Column
Language
cURL
CYTOBANK API ENDPOINT REFERENCE
* Introduction
* Documentation Overview
* Rate Limiting
* Error Codes and Messages
Advanced Analyses
Attachments
Authentication
Compensations
DROP
Experiments
FCS Files
Gates and Populations
Panels
Sample Tags
Scales
Sharing
Statistics
Users
Cytobank API Endpoint Reference
The Cytobank API is a RESTful JSON web API that extends use of basic and
advanced functionality of the Cytobank Cloud to any software application. Learn
more about the Cytobank API.
This v1 API endpoint reference documentation provides information and low-level
instructions for access to each API endpoint via HTTP request. Higher level
wrappers in programming languages such as R are available here.
If an endpoint can't be found on this page it doesn't exist yet. The Cytobank
API is under continuous development. Look for exciting releases in the near
future. Get in contact with Cytobank Support to request additional endpoints or
get beta access to new API functionality.
DOCUMENTATION OVERVIEW
Cytobank API endpoints are divided into different groups in this reference
guide. These groups logically separate the different functionalities of Cytobank
and the API endpoints that serve them. In order to find a functionality of
interest, first consult the groups on the left for relevance. Click to expand a
group in order to see the API endpoints inside it. Make sure to start with the
Authentication section.
View an endpoint in this documentation for directions on how to access it via
HTTP request and to read useful supporting information. The HTTP method (e.g.
POST, GET, etc.), headers, example body, and example responses are shown where
relevant.
CODE SNIPPETS
Code snippets in a variety of programming languages are shown for each request.
The language shown can be adjusted at the top right of this page. Copy the
snippets and execute them in the desired language in order to try the API in a
simple context. Please note that code snippets are automatically generated and
it's possible that not every snippet will work in every language. The exception
to this are requests in cURL, which are all expected to work.
REPLACING BRACKETED VARIABLES
Capitalized variables in double brackets, {{LIKE_THIS}}, should be replaced with
actual values if examples from this documentation are being used directly. These
bracketed variables appear throughout the documentation. For example:
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/authenticate
...would become...
https://YourCytobank.cytobank.org/cytobank/api/v1/authenticate
"username": "{{user_name}}", "password": "{{userpassword}}"
...would become...
"username": "YourUsername", "password": "YourPassword"
RATE LIMITING
Currently the Cytobank API has a default rate limit of 100 requests per 1
minute. If this rate is exceeded the server will respond with a 429 status code
and an error message about the rate limits. Requests are binned per minute
according to the clock on the server.
ERROR CODES AND MESSAGES
The Cytobank API will respond to requests with a HTTP status code and return
content via JSON. In the case of an error, a status code will be accompanied by
a useful message where possible. A variety of status codes are used and not all
will be listed here. However, at a high level, anything in the 200 range
indicates success, 400 range indicates a client-side error such as a
malformatted request or disallowed operation, and 500 range indicates a
server-side error. Keep in mind that Cytobank has a permissions framework that
the API adheres to. If an error message of Not Authorized To Access Resource is
encountered, double check the accessing account has proper access levels for the
desired operation, or clone the experiment in question to make an accessible
copy.
Advanced Analyses
Dimensionality Reduction
ANALYSIS_TYPE can be any of the following:
* tsne_cuda
* opt_sne
* umap
* visne
GET
List dim. reduction analyses of a type
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}
List all dimensionality reduction analyses in an experiment of the specified
type (tSNE-CUDA, opt-SNE, UMAP, or viSNE).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Example Request
List dim. reduction analyses of a type
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Show dim. reduction analysis details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}
Show a specific dimensionality reduction analysis in an experiment of the
specified type (tSNE-CUDA, opt-SNE, UMAP, or viSNE).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Example Request
Show dim. reduction analysis details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Create dim. reduction analysis
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/
Create a new dimensionality reduction analysis of the specified type (tSNE-CUDA,
opt-SNE, UMAP, or viSNE) with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API Dim. Reduction Experiment"
}
Example Request
Create dim. reduction analysis
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "API Dim. Reduction Experiment"
} '
PUT
Update dim. reduction analysis details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}
Create a new tSNE-CUDA analysis with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"options":
{
"autoIterations": false,
"autoLearningRate": false,
"clusteringChannels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"collapseOutliers": false,
"desiredEventsPerFile": 50000,
"desiredTotalEvents": 100000,
"earlyExaggeration": 12,
"eventSamplingMethod": "proportional",
Example Request
Update dim. reduction analysis details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"options":
{
"autoIterations": false,
"autoLearningRate": false,
"clusteringChannels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"collapseOutliers": false,
"desiredEventsPerFile": 50000,
DEL
Delete dim. reduction analysis
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}
Delete a dimensionality reduction analysis of the specified type (tSNE-CUDA,
opt-SNE, UMAP, or viSNE).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Delete dim. reduction analysis
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Copy dim. reduction analysis settings
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/copy_settings
Copy an existing dimensionality reduction analysis of the specified type
(tSNE-CUDA, opt-SNE, UMAP, or viSNE) to create a new analysis with the same
settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Copy dim. reduction analysis settings
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/copy_settings' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
PUT
Rename dim. reduction analysis
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/rename
Rename a dimensionality reduction analysis of the specified type (tSNE-CUDA,
opt-SNE, UMAP, or viSNE). This is useful for post-run modifications of an
analysis name, since the update command is not allowed after the run is started.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API Dim. Reduction Experiment - Rename"
}
Example Request
Rename dim. reduction analysis
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/rename' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
"name": "API Dim. Reduction Experiment - Rename"
}
'
POST
Run dim. reduction analysis
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/run
Run a dimensionality reduction analysis of the specified type (tSNE-CUDA,
opt-SNE, UMAP, or viSNE).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Run dim. reduction analysis
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/run' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Show dim. reduction analysis status
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/status
Show the execution status of a dimensionality reduction analysis of the
specified type (tSNE-CUDA, opt-SNE, UMAP, or viSNE).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Example Request
Show dim. reduction analysis status
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/{{ANALYSIS_TYPE}}/{{ANALYSIS_ID}}/status' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
CITRUS
CITRUS is an algorithm designed for the fully automated discovery of
statistically significant stratifying biological signatures within single cell
datasets containing numerous samples across multiple known endpoints. Learn more
about CITRUS in Cytobank.
GET
List CITRUS Analyses
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus
List all CITRUS analyses in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List CITRUS Analyses
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": [
{
"id": 415,
"name": "Completed CITRUS Run 1",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "Completed",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": 3227,
GET
Show CITRUS Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}?include_settings=1
Show a specific CITRUS analysis in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
include_settings
1
Bodyformdata
Example Request
Show CITRUS Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}?include_settings=1' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 442,
"name": "API CITRUS Experiment - Rename",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
POST
Create CITRUS
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/
Create a new CITRUS analysis with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API CITRUS Experiment"
}
Example Request
Create CITRUS
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "API CITRUS Experiment"
} '
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 442,
"name": "API CITRUS Experiment",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
PUT
Update CITRUS Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}
Update CITRUS settings. Updates can only be made before running the CITRUS
analysis. Learn more about CITRUS settings.
CHANNEL_ID is the normalizedShortNameId of the channel. This information is
available from the Panels endpoints.
The integers in the fileGrouping attribute reference the respective
{{FILE_GROUP}} from the fileGroupNames attribute in the order in which they
appear starting from 0.
POPULATION.GATE_SET_ID parameter in the gateSetId attribute is the gateSetId
attribute value of the population on which to run CITRUS. Note that this
argument is the gateSetId attribute of a population object and not the ID of the
object itself. This secondary ID is experiment-specific and will be a smaller
number. An argument of 0 corresponds to the ungated population, i.e., the raw
data with no filtering applied. Another term for a population is a "gate set"
because it's a set of gates (learn more).
The clusteringCharacterization attribute can have a value of "medians" or
"abundances".
The plotTheme attribute can have a value of "white" or "black". This corresponds
to the values of "light" and "dark" in the Cytobank web interface.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"name":"My API CITRUS Experiment - Update",
"options":
{
"clusteringChannels":[{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"statisticsChannels":[{{CHANNEL_ID_3}}],
"fileGrouping":[[{{FCS_FILE_ID_1}}, 0], [{{FCS_FILE_ID_2}}, 0], [{{FCS_FILE_ID_3}}, 0],
[{{FCS_FILE_ID_4}}, 1], [{{FCS_FILE_ID_5}}, 1], [{{FCS_FILE_ID_6}}, 1]],
"fileGroupNames":[{{FILE_GROUP_1}}, {{FILE_GROUP_2}}],
"gateSetId":{{POPULATION_ID}},
"compensationId":{{COMP_ID}},
Example Request
Update CITRUS Details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name":"My API CITRUS Experiment - Update",
"options":
{
"clusteringChannels":[{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"statisticsChannels":[{{CHANNEL_ID_3}}],
"fileGrouping":[[{{FCS_FILE_ID_1}}, 0], [{{FCS_FILE_ID_2}}, 0], [{{FCS_FILE_ID_3}}, 0],
[{{FCS_FILE_ID_4}}, 1], [{{FCS_FILE_ID_5}}, 1], [{{FCS_FILE_ID_6}}, 1]],
DEL
Delete CITRUS
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}
Delete a CITRUS analysis permanently.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Delete CITRUS
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Copy CITRUS Settings
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/copy_settings
Copy an existing CITRUS analysis to create a new CITRUS analysis with the same
settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Copy CITRUS Settings
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/copy_settings' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 444,
"name": "API CITRUS Experiment - Rename (copy)",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
PUT
Rename CITRUS
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/rename
Rename a CITRUS analysis. This is useful for post-run modifications of CITRUS
analysis name, since the update command is not allowed after the run is started.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API CITRUS Experiment - Rename"
}
Example Request
Rename CITRUS
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/rename' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "API CITRUS Experiment - Rename"
}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 442,
"name": "API CITRUS Experiment - Rename",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
POST
Run CITRUS
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/run
Run a CITRUS analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Run CITRUS
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/run' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 442,
"name": "API CITRUS Experiment - Rename",
"type": "CitrusAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
GET
Show CITRUS Status
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/status
Show a CITRUS analysis execution status.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show CITRUS Status
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/status' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrusStatus": {
"id": 442,
"name": "API CITRUS Experiment - Rename",
"status": "Running",
"progress": 23,
"startTime": "2017-01-04T00:26:40Z",
"endTime": 0,
"runtime": 0,
"progressMessage": "Finalizing analysis...",
"createdExperiment": null
GET
Download CITRUS Results
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{citrus_attachment_id}}/download
Download the results for a successful CITRUS analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Download CITRUS Results
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{citrus_attachment_id}}/download' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
FlowSOM
FlowSOM is an algorithm that speeds time to analysis and quality of clustering
with Self-Organizing Maps (SOMs) that can reveal how all markers are behaving on
all cells, and can detect subsets that might otherwise be missed. It clusters
cells (or other observations) based on chosen clustering channels (or
markers/features), generates a SOM of clusters, produces a Minimum Spanning Tree
(MST) of the clusters, and assigns each cluster to a metacluster, effectively
grouping them into a population. The FlowSOM algorithm outputs SOMs and MSTs
showing population abundances and marker expression in various formats including
pie charts, star plots, and channel-colored plots. Cytobank has extended the
functionality to automatically create a new experiment using files written out
of FlowSOM that include the original channels plus the addition of cluster and
metacluster ID channels, to allow interaction with the cluster and metacluster
output. Read the original FlowSOM publication by Van Gassen et al, Cytometry A
(2015).
GET
List FlowSOM Analyses
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom
List all FlowSOM analyses in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List FlowSOM Analyses
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"flowsom": [
{
"id": 415,
"name": "New FlowSOM Run",
"type": "FlowsomAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
GET
Show FlowSOM Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}
Show a specific FlowSOM analysis in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show FlowSOM Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}?include_settings=1' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"flowsom": {
"id": 2439,
"name": "FlowSOM Demo 1",
"type": "FlowsomAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 2939,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
POST
Create FlowSOM
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/
Create a new FlowSOM analysis with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API FlowSOM Experiment"
}
Example Request
Create FlowSOM
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw '{
"name": "API FlowSOM Analysis"
} '
Example Response
200 OK
Body
Header(0)
View More
{
"flowsom": {
"id": 2440,
"name": "New FlowSOM Analysis",
"type": "FlowsomAdvancedAnalysis",
"author": "stoo blair",
"status": "New",
"sourceExperiment": 2939,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
PUT
Update FlowSOM Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}
Update FlowSOM settings. Updates can only be made before running the FlowSOM
analysis.
REQUIRED SETTINGS:
* clusteringChannels — An array of normalizedShortNameIds corresponding to
channels shared by all FCS files specified by fcsFileIds. This information is
available from the Panels endpoints. This information is available from the
Panels endpoints.
* fcsFileIds — An array of FCS File IDs belonging to the experiment.
EVENT SAMPLING SETTINGS:
* eventSamplingMethod — Valid options are proportional, equal, or all. Defaults
to equal. If eventSamplingMethod is set to all, all events for the selected
population from all selected files will be used, without any further
subsampling.
* desiredEventsPerFile — Only applies if eventSamplingMethod is set to equal.
Defaults to 50000. It is the number of desired events to sample per file, but
if the selected population for any selected file has less total events than
the specified number, that quantity will be used instead.
* desiredTotalEvents — Only applies if eventSamplingMethod is set to
proportional. Defaults to 100000. Represents the total desired number of
events to sample amongst all selected files, whilst keeping the numbers per
file proportional to the total number of events in the selected population
for that file. If any file has less events in the selected population than
possible to make a perfectly proportional sampling to add up to the desired
total, all of the events in the file will be used instead.
OPTIONAL BASIC SETTINGS:
* clusteringMethod — Valid options are consensus, hierarchical, or kmeans.
Defaults to consensus.
* compensationId — Valid options are -1 (Uncompensated), -1 (File-internal
compensation), or the ID of an external compensation. Note that in order to
run FlowSOM, all gates must be drawn on the same compensation, and if any
gates exist in the experiment, that compensation must be selected.
* expectedClusters — Valid options are any of 9, 16, 25, 36, 49, 64, 81, 100,
121, 144, 169, 196, 225, 256, 289, 324, 361, 400. Defaults to 100.
* expectedMetaclusters — Valid options are any integer between 3 and 90
(inclusive), as long as this number is less than expectedClusters. Defaults
to 10.
* gateSetId — POPULATION_ID parameter in the gateSetId attribute is the
gateSetId attribute value of the population on which to run FlowSOM. Note
that this argument is the gateSetId attribute of a population object and not
the ID of the object itself. This secondary ID is experiment-specific and
will be a smaller number. An argument of 0 corresponds to the ungated
population, i.e., the raw data with no filtering applied. The default for
this setting is 0 (Ungated). Another term for a population is a "gate set"
because it is a set of gates (learn more).
* iterations — Can be set to any integer between 1 and 100 (inclusive).
Defaults to 10.
* normalizeScales — Can be true or false. Defaults to false.
* randomSeed — Accepts a positive integer value and sets a specific random seed
to that value. If this parameter is not specified or set to 0, autoSeed will
automatically be set to true, and a seed value will be randomly chosen, so
that afterward it can be referred to for reproducing the analysis results.
* SOMCreationMethod — Two valid options: create_new or import_existing. If
import_existing is selected, then externalSOMAnalysisId must be set to a
valid value.
* externalSOMAnalysisId — Only applies if SOMCreationMethod is set to
import_existing. It must be set to the id of a FlowsomAdvancedAnalysis
corresponding to a successfully completed FlowSOM run which has the SOM the
user wishes to import.
OPTIONAL ADVANCED OUTPUT SETTINGS:
* channelsToPlot — An array of normalizedShortNameIds corresponding to channels
to output channel-colored MST plots for. If unspecified, it will output these
plots for all clustering channels and all annotated channels.
* clusterSizeType — Valid options are relative, fixed, or both. Defaults to
relative.
* fixedClusterSize — Only applies if clusterSizeType is set to fixed or both.
Accepts integers between 1 and 40 (inclusive). Defaults to 8.
* gateSetNamesToLabel — An array of names of gateSets (populations) to label in
the population pie plots. If unspecified, it will include all populations in
these plots.
* maxRelativeClusterSize — Only applies if clusterSizeType is set to relative
or both. Accepts integers between 2 and 40 (inclusive). Defaults to 15.
* outputFileType — Valid options are pdf, png, or both. Defaults to pdf. Note
that selecting png or both will significantly increase the file size of the
results .zip.
* showBackgroundOnLegend — Can be true or false. Defaults to false.
* showBackgroundOnChannelColoredMSTs — Can be true or false. Defaults to false.
* showBackgroundOnPopulationPies — Can be true or false. Defaults to true.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"options":
{
"clusteringChannels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"clusteringMethod": "consensus",
"compensationId": {{COMP_ID}},
"desiredEventsPerFile": 50000,
"desiredTotalEvents": 100000,
"eventSamplingMethod": "proportional",
"expectedClusters": 100,
"expectedMetaclusters": 10,
Example Request
Update FlowSOM Details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"options":
{
"clusteringChannels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}],
"clusteringMethod": "consensus",
"compensationId": {{COMP_ID}},
"desiredEventsPerFile": 50000,
"desiredTotalEvents": 100000,
DEL
Delete FlowSOM
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}
Delete a FlowSOM analysis permanently.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Delete FlowSOM
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Copy FlowSOM Settings
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/copy_settings
Copy an existing FlowSOM analysis to create a new FlowSOM analysis with the same
settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Copy FlowSOM Settings
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/copy_settings' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"flowsom": {
"id": 2368,
"name": "FlowSOM Example Analysis (copy)",
"type": "FlowsomAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 2939,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
PUT
Rename FlowSOM
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/rename
Rename a FlowSOM analysis. This is useful for post-run modifications of FlowSOM
analysis name, since the update command is not allowed after the run is started.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"name": "API FlowSOM Experiment - Rename"
}
Example Request
Rename FlowSOM
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/citrus/{{CITRUS_ID}}/rename' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "API CITRUS Experiment - Rename"
}'
Example Response
200 OK
Body
Header(0)
View More
{
"flowsom": {
"id": 442,
"name": "API FlowSOM Experiment - Rename",
"type": "FlowsomAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
POST
Run FlowSOM
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/run
Run a FlowSOM analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Run FlowSOM
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/run' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"citrus": {
"id": 442,
"name": "API FlowSOM Experiment - Rename",
"type": "FlowsomAdvancedAnalysis",
"author": "Cytobank Support",
"status": "New",
"sourceExperiment": 1424,
"createdExperiment": null,
"attachment_id": null,
"canceled": false,
GET
Show FlowSOM Status
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/status
Show a FlowSOM analysis execution status.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show FlowSOM Status
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/flowsom/{{FLOWSOM_ID}}/status' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"flowsomStatus": {
"id": 442,
"name": "API FlowSOM Experiment - Rename",
"status": "Running",
"progress": 23,
"startTime": "2018-08-04T00:26:40Z",
"endTime": 0,
"runtime": 0,
"progressMessage": "Initializing FlowSOM algorithm...",
"createdExperiment": null
GET
Download FlowSOM Results
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{flowsom_attachment_id}}/download
Download the results for a successful FlowSOM analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Download FlowSOM Results
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{flowsom_attachment_id}}/download' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
SPADE
SPADE is an algorithm available in Cytobank that takes multi-parameter data,
performs clustering, and represents the clustered data as a two-dimensional
minimum spanning tree of connected clusters. Learn more about SPADE in Cytobank.
GET
List SPADE Analyses
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade
List spade tasks for an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List SPADE Analyses
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spade": [
{
"id": 187,
"name": "Running SPADE",
"status": "Running",
"createdAt": "2016-11-10T07:04:58Z",
"updatedAt": "2017-01-04T00:33:58Z",
"author": "Cytobank Support",
"sourceExperiment": 1424,
"createdExperiment": 1425
GET
Show SPADE Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}?include_settings=1
Show a specific SPADE analysis in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
include_settings
1
Bodyformdata
Example Request
Show SPADE Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}?include_settings=1' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"id": 229,
"name": "new API SPADE",
"status": "New",
"createdAt": "2017-01-04T00:39:20Z",
"updatedAt": "2017-01-04T00:39:20Z",
"author": "Cytobank Support",
"sourceExperiment": 1541,
"createdExperiment": 1542,
"settings": {
POST
Create SPADE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/
Create a new SPADE analysis with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"spade":
{
"name": "new spade task"
}
}
Example Request
Create SPADE
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"spade":
{
"name": "new API SPADE"
}
}'
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"id": 229,
"name": "new API SPADE",
"status": "New",
"createdAt": "2017-01-04T00:39:20Z",
"updatedAt": "2017-01-04T00:39:20Z",
"author": "Cytobank Support",
"sourceExperiment": 1541,
"createdExperiment": 1542,
"settings": {
PUT
Update SPADE Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/
Update SPADE settings. Updates can only be made before running the SPADE
analysis. Learn more about SPADE settings.
POPULATION.GATE_SET_ID parameter is the gateSetId attribute value of the
population on which to run SPADE. Note that this argument is the gateSetId
attribute of a population object and not the ID of the object itself. This
secondary ID is experiment-specific and will be a smaller number. An argument of
0 corresponds to the ungated population, i.e., the raw data with no filtering
applied. Another term for a population is a "gate set" because it's a set of
gates (learn more).
CHANNEL_ID parameters are the normalizedShortNameId attribute of the channels to
run SPADE on. This information can be retrieved from the Panels endpoints.
downSampledEventsTarget attribute can have a value of either "percent" or
"absoluteNumber" with a corollary numeric argument.
For analyses using fold change, all files in the experiment must be represented
within a fold change group, and only within one group. Learn more about fold
change setup.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"spade":
{
"name": "spade_update_test",
"compensationId": -2,
"targetNumberOfNodes": 200,
"population": 1,
"clusteringChannels": [1, 2, 53],
"downSampledEventsTarget": {
"percent": 20
},
Example Request
Update SPADE Details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"spade":
{
"name": "new API SPADE - Updated",
"compensationId": {{COMP_ID}},
"targetNumberOfNodes": 200,
"population": {{POPULATION.GATE_SET_ID}},
"clusteringChannels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}, {{CHANNEL_ID_3}}],
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"id": 229,
"name": "new API SPADE - Updated",
"status": "New",
"createdAt": "2017-01-04T00:39:20Z",
"updatedAt": "2017-01-04T00:51:10Z",
"author": "Cytobank Support",
"sourceExperiment": 1541,
"createdExperiment": 1542,
"settings": {
DEL
Delete SPADE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}
Delete a SPADE analysis permanently.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Delete SPADE
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Copy SPADE Settings
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/copy_settings
Copy an existing SPADE analysis to create a new SPADE analysis with the same
settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Copy SPADE Settings
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/copy_settings' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"id": 230,
"name": "Copy of new API SPADE - Rename",
"status": "New",
"createdAt": "2017-01-04T00:51:40Z",
"updatedAt": "2017-01-04T00:51:40Z",
"author": "Cytobank Support",
"sourceExperiment": 1541,
"createdExperiment": 1543
}
PUT
Rename SPADE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/rename
Rename a SPADE analysis. This is useful for post-run modifications of SPADE
analysis name, since the update command is not allowed after the run is started.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"spade":
{
"name": "new API SPADE - Rename"
}
}
Example Request
Rename SPADE
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/rename' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"spade":
{
"name": "new_spade_name"
}
}'
Example Response
200 OK
Body
Header(0)
{
"name": "new API SPADE - Rename"
}
POST
Run SPADE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/run
Run a SPADE analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Run SPADE
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/run' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spadeStatus": {
"id": 229,
"name": "new API SPADE - Rename",
"status": "Pending",
"progress": 0,
"startTime": 0,
"endTime": 0,
"runtime": 0,
"progressMessage": "Pending"
}
GET
Show SPADE Status
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/status
Show SPADE analysis execution status.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show SPADE Status
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/status' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spadeStatus": {
"id": 229,
"name": "new API SPADE - Rename",
"status": "Running",
"progress": 9,
"startTime": "2017-01-04T00:55:17Z",
"endTime": 0,
"runtime": 0,
"progressMessage": "Computing medians for file2_intact cells.fcs.density.fcs.cluster.fcs"
}
GET
Download Complete Results Package
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=full_data
Download the complete results package for a successful SPADE run. Includes all
the components that can be downloaded seperately, and more.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
full_data
Bodyformdata
Example Request
Download Complete Results Package
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=full_data' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download GML Files
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=gml
Download GML files for a successful SPADE run. The GML files represent the SPADE
tree graph structure with nodes and edges. Each node object in this file also
contains all statistical information.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
gml
Bodyformdata
Example Request
Download GML Files
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=gml' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download Global Boundaries Table
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=global_boundaries_table
Download Global Boundaries table for a successful SPADE run.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
global_boundaries_table
Bodyformdata
Example Request
Download Global Boundaries Table
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=global_boundaries_table' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download Layout Table
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=layout_table
Download Layout table for a successful SPADE run.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
layout_table
Bodyformdata
Example Request
Download Layout Table
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=layout_table' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download Statistics Table
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=statistics_table
Download Statistics tables for a successful SPADE run.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
statistics_table
Bodyformdata
Example Request
Download Statistics Table
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=statistics_table' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download Clusters Table
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=clusters_table
Download Clusters table for a successful SPADE run.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
item
clusters_table
Bodyformdata
Example Request
Download Clusters Table
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/download?item=clusters_table' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Show SPADE Bubbles
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/show_bubbles
Show current node:bubble relationships for a SPADE analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show SPADE Bubbles
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/show_bubbles' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"bubbles": [
{
"name": "CD8+",
"nodes": [
101,
105,
108,
117,
118,
POST
Set SPADE Bubbles
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/set_bubbles
Set node:bubble relationships for a SPADE analysis. This will overwrite existing
information.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"spade": {
"bubbles": [
{
"name": "CD8+",
"nodes": [
101,
105,
108,
117,
118,
Example Request
Set SPADE Bubbles
View More
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/show_bubbles' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--data-raw '{
"spade": {
"bubbles": [
{
"name": "CD8+",
"nodes": [
101,
105,
108,
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"bubbles": [
{
"name": "CD8+",
"nodes": [
101,
105,
108,
117,
118,
POST
Export SPADE Bubbles to New Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/export_bubbles_to_new_experiment
Export the given SPADE bubbles as FCS files into a new experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"spade":
{
"bubbles": ["CD8+", "CD4+"] }
}
Example Request
Export SPADE Bubbles to New Experiment
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/export_bubbles_to_new_experiment' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"spade":
{
"bubbles": ["CD8+", "CD4+"] }
}'
Example Response
200 OK
Body
Header(0)
View More
{
"experiment": {
"id": 1544,
"version": 0,
"purpose": "test",
"comments": null,
"public": false,
"deleted": false,
"sources": "",
"experimentName": "new API SPADE (Clone)",
"gateVersion": 0,
POST
Copy SPADE Results
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/copy_results
Clone a successful completed SPADE analysis. Creates a copy in the same
experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
Example Request
Copy SPADE Results
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/spade/{{SPADE_ID}}/copy_results' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw ''
Example Response
200 OK
Body
Header(0)
View More
{
"spade": {
"id": 231,
"name": "Copy of new API SPADE - Rename",
"status": "Completed",
"createdAt": "2017-01-04T00:39:20Z",
"updatedAt": "2017-01-04T01:02:18Z",
"author": "Chris Ciccolella",
"sourceExperiment": 1541,
"createdExperiment": 1545
}
viSNE
viSNE is a powerful algorithm for reducing dimensionality and finding patterns
within data. Learn more about viSNE in Cytobank.
GET
List viSNE Analyses
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne
List viSNE analyses in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List viSNE Analyses
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"visne": [
{
"id": 111,
"name": "Interface viSNE run",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"createdAt": "2017-04-13T06:07:27Z",
"updatedAt": "2017-04-13T06:12:37Z"
},
GET
Show viSNE Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}?include_settings=1
Show a specific viSNE analysis in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
include_settings
1
Bodyformdata
Example Request
Show viSNE Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}?include_settings=1' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"visne": {
"id": 112,
"name": "New API viSNE run",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"settings": {
"samplingTotalCount": 100000,
"samplingTargetType": "proportional",
"compensationId": -2,
POST
Create viSNE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/
Create a new viSNE analysis with default settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"visne":
{
"name": "visne_api_demo_day"
}
}
Example Request
Create viSNE
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"visne":
{
"name": "New API viSNE"
}
}'
Example Response
200 OK
Body
Header(0)
View More
{
"visne": {
"id": 112,
"name": "New API viSNE run",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"settings": {
"samplingTotalCount": 100000,
"samplingTargetType": "proportional",
"compensationId": -2,
PUT
Update viSNE Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}
Update viSNE settings. Updates can only be made before running the viSNE
analysis. Learn more about viSNE settings.
CHANNEL_ID parameters are the normalizedShortNameId attribute of the channels on
which to run viSNE. This information can be retrieved from the Panels endpoints.
SAMPLING_METHOD parameter can have a value of either "proportional" or "equal".
Within the populationSelections nested object, the POPULATION.GATE_SET_ID
parameters are the gateSetId attribute value of the populations on which to run
viSNE. Note that this argument is the gateSetId attribute of a population object
and not the ID of the object itself. This secondary ID is experiment-specific
and will be a smaller number. An argument of 0 corresponds to the ungated
population, i.e., the raw data with no filtering applied. Another term for a
population is a "gate set" because it's a set of gates (learn more). Multiple
populations can be selected for a single viSNE run and FCS files can appear
redundantly among different population selections.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"visne":
{
"name": "visne_api_run_test",
"channels": [27,28,87,268,269,270,271,272],
"compensationId": -2,
"samplingTotalCount": 10000,
"samplingTargetType": "proportional",
"populationSelections": [
{
"id": 1,
Example Request
Update viSNE Details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"visne":
{
"name": "viSNE analysis - Updated",
"channels": [{{CHANNEL_ID_1}}, {{CHANNEL_ID_2}}, {{CHANNEL_ID_3}}],
"compensationId": {{COMP_ID}},
"samplingTotalCount": {{TOTAL_EVENTS_IN_RUN}},
"samplingTargetType": "{{SAMPLING_METHOD}}",
Example Response
200 OK
Body
Header(0)
View More
{
"visne": {
"id": 112,
"name": "viSNE analysis - Updated",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"settings": {
"samplingTotalCount": 85000,
"samplingTargetType": "proportional",
"compensationId": -2,
DEL
Delete viSNE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}
Delete a viSNE analysis permanently.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Delete viSNE
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Copy viSNE Settings
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/copy_settings
Copy an existing viSNE analysis to create a new viSNE analysis with the same
settings.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Copy viSNE Settings
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/copy_settings' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"visne": {
"id": 114,
"name": "Copy of viSNE analysis - Updated",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"createdAt": "2017-04-13T06:54:55Z",
"updatedAt": "2017-04-13T06:54:55Z"
}
}
PUT
Rename viSNE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/rename
Rename a viSNE analysis. This is useful for post-run modifications of viSNE
analysis name, since the update command is not allowed after the run is started.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"visne":
{
"name": "foooname"
}
}
Example Request
Rename viSNE
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/rename' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"visne":
{
"name": "API viSNE - Renamed"
}
}'
Example Response
200 OK
Body
Header(0)
View More
{
"visne": {
"id": 112,
"name": "API viSNE - Renamed",
"status": "New",
"sourceExperiment": 418,
"createdExperiment": null,
"createdAt": "2017-04-13T06:11:03Z",
"updatedAt": "2017-04-13T06:55:54Z"
}
}
POST
Run viSNE
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/run
Run a viSNE analysis.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Run viSNE
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/run' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"visneStatus": {
"id": 112,
"name": "API viSNE - Renamed",
"status": "Pending",
"progress": 0,
"startTime": 0,
"endTime": 0,
"runtime": 0,
"progressMessage": "Pending",
"createdExperiment": null
GET
Show viSNE Status
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/status
Show viSNE analysis execution status.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show viSNE Status
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/advanced_analyses/visne/{{VISNE_ID}}/status' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"visneStatus": {
"id": 112,
"name": "API viSNE - Renamed",
"status": "Running",
"progress": 23,
"startTime": "2017-04-13T07:03:25Z",
"endTime": 0,
"runtime": 0,
"progressMessage": "Iteration 1: KL divergence is 118.202986",
"createdExperiment": null
Attachments
Only FCS files can be analyzed in Cytobank, but any file can be uploaded as an
attachment. Exported PDFs, statistics, and files also automatically attach
themselves to the Experiment they are exported from. Interact with attachments
using these endpoints. Learn more about attachments in Cytobank
GET
List Attachments for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments
List the attachments in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List Attachments for Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"attachments": [
{
"id": 3014,
"filename": "CyTOF_PBMC_27_v1.acs",
"size": 12241855,
"description": "Original ACS File that this experiment was created from.",
"type": "UserAttachment",
"experimentId": 1412,
"uploadedById": 5,
"mimeType": null,
GET
Show Attachment Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}
Show details for an attachment in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show Attachment Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"attachment": {
"id": 3265,
"filename": "Statistics_export.zip",
"size": 781634,
"description": "Exported statistics from experiment '2012-12 Healthy Human PBMC w/ 26 Surface Markers from DVS (Clone)'.",
"type": "ExportAttachment",
"experimentId": 1412,
"uploadedById": 5,
"mimeType": null,
"md5sum": "81a9174c3ab04cc534b7e2993a2314c5",
POST
Upload Attachment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/upload
Upload an attachment to an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
file
@{{FILE_NAME}}
Example Request
Upload Attachment
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/upload' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
GET
Download Attachment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}/download
Download an attachment from an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Download Attachment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}/download' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Download All Attachments from Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/download_zip
Download a ZIP file of all attachments from an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Download All Attachments from Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/download_zip' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
PUT
Update Attachment Description
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}
Update an attachment description.
HEADERS
Authorization
Bearer {{JWT_TOKEN}}
Content-Type
application/json
BODYraw
{
"attachments":
{
"description": "Description goes here..."
}
}
Example Request
Update Attachment Description
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}' \
--header 'Authorization: Bearer {{JWT_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"attachments":
{
"description": "Description goes here..."
}
}'
DEL
Delete Attachment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}
Delete an attachment from an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Delete Attachment
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/attachments/{{ATTACHMENT_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Authentication
Every call to the Cytobank API must be accompanied by an authentication token.
Tokens are generated from the Authenticate API endpoint with a username and
password, or on a user profile page within Cytobank. Tokens should be kept
secure as they confer access to the data and analyses of an account.
Tokens expire after 8 hours by default but this figure my change depending on
custom configurations of an Enterprise Cytobank. Use the Logout / Revoke API
endpoints to invalidate one or all tokens for a user account. All issued tokens
can be invalidated from the user profile page within Cytobank as well.
POST
Authenticate
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/authenticate
Post username and password to receive an authentication token. The token comes
embedded in an object that describes the user that requested it.
HEADERS
Accept
application/json
charset
UTF-8
Content-Type
application/json
BODYraw
{
"username": "{{USERNAME}}",
"password": "{{PASSWORD}}"
}
Example Request
Authenticate
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/authenticate' \
--header 'Accept: application/json' \
--header 'charset: UTF-8' \
--header 'Content-Type: application/json' \
--data-raw ''
Example Response
200 OK
Body
Header(10)
View More
{
"user": {
"id": 22,
"username": "CytobankSupport",
"location": "Mountain View",
"organization": "Cytobank",
"twitter": "",
"bio": "Cytobanker",
"firstName": "Cytobank",
"lastName": "Support",
"email": "support@cytobank.org",
POST
Logout
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/logout
Invalidate the token used in the call to this endpoint.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Logout
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/logout' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Revoke All Tokens
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/revoke_tokens
Invalidate all existing tokens for the user making this call.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Revoke All Tokens
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/revoke_tokens' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Revoke all Tokens for any User (Admin only)
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/revoke_user_tokens
Revoke all tokens for a given user. This endpoint only works for admins of the
Cytobank being accessed.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{"user_id": {{USER_ID}}}
Example Request
Revoke all Tokens for any User (Admin only)
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/revoke_user_tokens' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{"user_id": {{USER_ID}}}'
Compensations
Get information about compensations stored in Cytobank with these endpoints. For
information about file-internal compensation for an individual FCS file, consult
the FCS Files endpoints. Learn more about compensation in Cytobank.
GET
List Compensations for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/compensations
List compensations in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Compensations for Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/compensations' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"compensations": [
{
"id": 151,
"name": "Example Comp",
"sources": [
{
"name": "Ax488-A",
"id": 36,
"shortName": "Ax488-A"
},
GET
Show Compensation Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/compensations/{{COMP_ID}}
Show details for a compensation.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Compensation Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/compensations/151' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"compensation": {
"id": 151,
"name": "Example Comp",
"sources": [
{
"name": "Ax488-A",
"id": 36,
"shortName": "Ax488-A"
},
{
POST
Upload Compensation CSV
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_compensation_matrix
Upload a compensation CSV to an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Upload Compensation CSV
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_compensation_matrix' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
Example Response
200 OK
Body
Header(0)
{
"message": "Successfully imported compensation from uploaded file test_comp.csv"
}
DROP
DROP allows any numeric matrix data to be uploaded to Cytobank for analysis.
Learn more about DROP.
POST
Upload FCS File (CSV to FCS)
https://{{CYTOBANK}}/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload
Upload spreadsheet file for conversion. The uploaded file will be converted to
FCS and be found within the Experiment to which it's uploaded.
HEADERS
Authorization
Bearer {{user_jwt}}
Bodyformdata
file
Can upload CSV/TSV/TXT/FCS
convertDelimitedFiles
true
This can be true/false
dataMatrixStartRow
2
dataMatrixStartColumn
1
skippedColumns[]
2
Example Request
Upload FCS File (CSV to FCS)
curl --location -g --request POST 'https://{{CYTOBANK}}/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload' \
--header 'Authorization: Bearer {{user_jwt}}' \
--form 'file=@"/path/to/file"' \
--form 'convertDelimitedFiles="true"' \
--form 'dataMatrixStartRow="2"' \
--form 'dataMatrixStartColumn="1"' \
--form 'skippedColumns[]="2"'
POST
Upload ZIP FCS File (CSV to FCS)
https://{{CYTOBANK}}/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload_zip
Upload zip file of spreadsheets to convert. Each file within the zip should have
the same properties for dataMatrixStartRow and dataMatrixStartColumn.
HEADERS
Authorization
Bearer {{user_jwt}}
Bodyformdata
file
Can upload CSV/TSV/TXT/FCS
convertDelimitedFiles
true
This can be true/false
dataMatrixStartRow
2
dataMatrixStartColumn
1
skippedChannels
2
[ , , ... ]
Example Request
Upload ZIP FCS File (CSV to FCS)
curl --location -g --request POST 'https://{{CYTOBANK}}/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload_zip' \
--header 'Authorization: Bearer {{user_jwt}}' \
--form 'file=@"/path/to/file"' \
--form 'convertDelimitedFiles="true"' \
--form 'dataMatrixStartRow="2"' \
--form 'dataMatrixStartColumn="1"' \
--form 'skippedChannels="2"'
Experiments
An Experiment is a container for data and analyses in Cytobank. If data are on
Cytobank, they must be within an Experiment. Configurations such as gates,
compensations, scales, Sample Tags, and illustrations are also linked to an
individual Experiment. Within the Cytobank interface, the Experiment Summary
Page is a useful integration point for information about an Experiment.
GET
List Experiments
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments
List all accessible Experiments.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Experiments
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Show Experiment Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}
Show details for an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Experiment Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"experiment": {
"id": 10559,
"version": 23,
"purpose": "Stimulate PBMC with IL6, IL10, and LPS. Measure phosphorylation of Stat3 and p38 after 15 minutes of stimulation. Stain for CD4+ T cells, CD4- T cells, monocytes, and B cells.",
"comments": null,
"public": false,
"deleted": false,
"sources": "",
"experimentName": "PBMC Experiment (fluorescence) (Clone)",
"gateVersion": 1,
POST
Create Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments
Create a new Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"experiment":
{
"experimentName": "My API Experiment",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"projectId": {{PROJECT_ID}},
"purpose": "Trying out the Cytobank API",
"comments": "These become the comments in the Experiment"
}
}
Example Request
CreateExperiment
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"experiment":
{
"experimentName": "API Experiment",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"projectId": {{PROJECT_ID}},
"purpose": "Trying out the Cytobank API",
Example Response
200 OK
Body
Header(9)
View More
{
"experiment": {
"id": 7598,
"version": 0,
"purpose": "API testing",
"comments": "Testing API",
"public": false,
"deleted": false,
"sources": "",
"experimentName": "New API experiment",
"gateVersion": 0,
PUT
Update Experiment Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}
Update details for an Experiment. To update only certain attributes for an
Experiment, pass only those attributes in the update request.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"experiment":
{
"experimentName": "My API Experiment - updated",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"projectId": {{PROJECT_ID}},
"purpose": "Trying out the Cytobank API",
"comments": "This becomes the comments in the Experiment"
}
}
Example Request
Update Experiment Details
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"experiment":
{
"experimentName": "My API Experiment - updated",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"projectId": {{PROJECT_ID}},
"purpose": "Trying out the Cytobank API",
POST
Clone Experiment (Full Clone)
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/clone
Fully clone an Experiment. Learn more about the full clone functionality.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Clone Experiment (Full Clone)
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/clone' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Clone Experiment (Selective Clone)
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/selective_clone
Selectively clone an Experiment. Learn more about the selective clone
functionality.
To include all files in the selective clone without passing all the IDs, simply
but -1 as the only element in the fcsFileIds array. I.e.: "fcsFileIds": [-1]
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
View More
{
"experiment":
{
"experimentName": "selectively cloned Experiment",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"cloneGates": true,
"cloneAnnotations": true,
"cloneAttachments": true,
"fcsFileIds": [{{FCS_FILE_ID_1}}, {{FCS_FILE_ID_2}}, {{FCS_FILE_ID_3}}],
"cloneCompensations": true,
Example Request
Clone Experiment (Selective Clone)
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/selective_clone' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"experiment":
{
"experimentName": "selectively cloned Experiment",
"primaryResearcherId": {{USER_ID}},
"principalInvestigatorId": {{PI_ID}},
"cloneGates": true,
"cloneAnnotations": true,
PUT
Trash Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}
Set the deleted attribute of this Experiment to true, which moves it to the
trash. This is reversible and not to be confused with permanent deletion.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"experiment":
{
"deleted": {{TRUEFALSE}}
}
}
Example Request
Trash Experiment
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/10559' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw ''
Example Response
200 OK
Body
Header(10)
View More
{
"experiment": {
"id": 10559,
"version": 23,
"purpose": "Stimulate PBMC with IL6, IL10, and LPS. Measure phosphorylation of Stat3 and p38 after 15 minutes of stimulation. Stain for CD4+ T cells, CD4- T cells, monocytes, and B cells.",
"comments": null,
"public": false,
"deleted": true,
"sources": "",
"experimentName": "PBMC Experiment (fluorescence) (Clone)",
"gateVersion": 1,
DEL
Delete Experiment Permanently
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}
Delete the Experiment and all analyses (including SPADE, viSNE, etc.)
permanently. This is not reversible.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Delete Experiment Permanently
curl --location -g --request DELETE 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
FCS Files
GET
List FCS Files for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files
List all FCS files in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List FCS Files in Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"fcsFiles": [
{
"id": 209114,
"filename": "pbmc_lrs005_il10.fcs",
"cytometer": "LSRII",
"mode": "L",
"md5sum": "0a6ce75257e4c2694643136852e5e877",
"clustered": false,
"guid": "823de422-6867-46f1-90b8-4de6298451a4",
"threshold": "FSC,18000",
GET
Show FCS File Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}
Show details for an FCS file in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show FCS File Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"fcs_file": {
"id": 209114,
"filename": "pbmc_lrs005_il10.fcs",
"cytometer": "LSRII",
"mode": "L",
"md5sum": "0a6ce75257e4c2694643136852e5e877",
"clustered": false,
"guid": "823de422-6867-46f1-90b8-4de6298451a4",
"threshold": "FSC,18000",
"severity": 0,
GET
Show File-Internal Compensation Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}/compensation
Show File-Internal Compensation (aka spillover matrix, spill matrix, spill
string) details for an FCS file in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show File-Internal Compensation Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}/compensation' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"FcsFileInternalCompensation": {
"id": null,
"name": "pbmc_lrs005_il10_pbmc_lrs005_il10.fcs_-_IL10_Ungated.fcs - spill string",
"sources": [
{
"name": "pStat3",
"id": 36,
"shortName": "Ax488-A"
},
{
GET
Download Single FCS File
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}/download
Download a specific FCS file from an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Download Single FCS File
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/{{FCS_FILE_ID_1}}/download' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Zip & Download Specific FCS Files
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/download_zip?fcs_file_ids={{FCS_FILE_ID_1}},{{FCS_FILE_ID_2}},{{FCS_FILE_ID_3}}
Download a group of FCS files from an Experiment as a ZIP file. The files to be
downloaded are specified by ID in the URL.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
fcs_file_ids
{{FCS_FILE_ID_1}},{{FCS_FILE_ID_2}},{{FCS_FILE_ID_3}}
BODYraw
{
"fcsFiles":
{
"fcsFileIds": [4845, 4846]
}
}
Example Request
Zip & Download Specific FCS Files
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/download_zip?fcs_file_ids={{FCS_FILE_ID_1}},{{FCS_FILE_ID_2}},{{FCS_FILE_ID_3}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--data-raw '{
"fcsFiles":
{
"fcsFileIds": [4845, 4846]
}
}'
GET
Zip & Download All FCS Files
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/download_zip
Zip & Download all FCS Files from an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
BODYraw
{
"fcsFiles":
{
"fcsFileIds": [4845, 4846]
}
}
Example Request
Zip & Download All FCS Files
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/download_zip' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--data-raw '{
"fcsFiles":
{
"fcsFileIds": [4845, 4846]
}
}'
POST
Upload FCS File to Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload
Upload an FCS file to an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
file
@{{FILE_NAME}}
Example Request
Upload FCS File to Experiment
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
POST
Upload Zip of FCS Files to Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload_zip
Upload one or more FCS files to an Experiment as a ZIP file.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
file
@{{FILE_NAME}}
Example Request
Upload Zip of FCS Files to Experiment
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/fcs_files/upload_zip' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
Gates and Populations
In Cytobank there is a distinction between gates and populations. A gate is
simply a shape drawn on a plot. A population is a set of gates and can have
parents and children. Learn more about gates and populations.
Currently gate and population information can only be read and not written to
Cytobank via the JSON API. To write gates and populations to Cytobank via the
API, the Upload Gating-ML endpoint should be used.
GET
List Gates for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/gates
List gates for an Experiment. Currently only the Scratch Gates from the gating
interface are returned. These have a version of -1. This is to be contrasted
with Experiment Gates, which will have a version number that is a positive
integer equal to the number of times the version has been incremented in the
gating interface. Learn more about gate versioning in Cytobank.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Gates for Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/gates' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"gates": [
{
"id": 1428108,
"name": "intact cells",
"type": "PolygonGate",
"tailored": false,
"tailoredPerPopulationGateSetId": null,
"tailoredPerPopulation": false,
"version": -1,
"experimentId": 10559,
GET
Show Gate Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/gates/{{GATE_ID}}
Show details for a gate in an Experiment. The gate ID passed in the request is
the value of the id attribute of the gate and not the gate_id attribute.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Gate Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/gates/{{GATE_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"gate": {
"id": 1428108,
"name": "intact cells",
"type": "PolygonGate",
"tailored": false,
"version": -1,
"experimentId": 10559,
"xNormalizedShortNameId": 1,
"yNormalizedShortNameId": 4,
"compensationId": 151,
GET
List Populations for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/populations
List populations (aka gate sets) for an Experiment. Currently only the Scratch
Populations from the gating interface are returned. These have a version of -1.
This is to be contrasted with Experiment Populations, which will have a version
number that is a positive integer equal to the number of times the version has
been incremented in the gating interface. Learn more about gate versioning in
Cytobank. The same principle applies to populations.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Populations
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/populations' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"populations": [
{
"id": 45547,
"name": "intact cells",
"version": -1,
"experimentId": 10559,
"gateSetId": 1,
"createdAt": "2016-07-26T22:02:10Z",
"updatedAt": "2016-07-26T22:02:10Z",
"definition": {
GET
Show Population Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/populations/{{POPULATION_ID}}
Show details for a population (aka gate set) in an Experiment. Pass the value
for the id attribute of the population and not the gateSetId attribute.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Population Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/10559/populations/{{POPULATION_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"population": {
"id": 45549,
"name": "CD33+ monocytes",
"version": -1,
"experimentId": 10559,
"gateSetId": 3,
"createdAt": "2016-07-26T22:02:10Z",
"updatedAt": "2016-07-26T22:02:10Z",
"definition": {
"gates": [
GET
Download Gating-ML
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/download_gatingml
Download gates via Gating-ML for an Experiment. Learn more about Gating-ML.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Download Gating-ML
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/download_gatingml' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Upload Gating-ML
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_gatingml
Upload gates to an Experiment via a Gating-ML file. Learn more about Gating-ML.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
file
@{{FILE_NAME}}
Example Request
Upload Gating-ML
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_gatingml' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
Panels
A collection of channels, the markers being studied on them, and the FCS files
this applies to form a panel. Learn more about panels in Cytobank.
GET
List Panels for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/panels
List panels in an Experiment and associated details.
The object returned is an array of panels. Each panel has an id, name, array of
channels, array of files that are in the panel, and a panelChannelMappings
object. Each file will only appear in one (or zero) panels. The
panelChannelMappings object gives information about the order that the channels
appear within files within panels, because groups of files within the same panel
could have channels in different orders. While potentially critical for
index-based operations on features within FCS files on a local computer, no
operations via the Cytobank API will rely on this ordering information and thus
this nested object can be ignored.
Various functions of the Cytobank API will require a mastery of using the list
of panels and nested arrays of channels and files. Many Cytobank API endpoints
take an argument of normalizedShortNameId (a numeric proxy for the shortName),
which is an attribute of a channel, and describes unambiguously which column of
data to operate on for a given file. The longName of the channel is not
guaranteed to be unique within a panel, although it usually is. Typically the
longName is the starting point for analysis. Consider fetching statistics, for
example. The objective might be to fetch median intensity of CD8+ T cells on the
pSTAT3 channel in a particular named file. The Statistics endpoint requires id
attributes for all these components to return statistics. The Gates and
Populations and FCS Files endpoints would be used to get the id and gateSetId
attribute for their respective components. Next, the normalizedShortNameId is
needed for pSTAT3. This is obtained by first fetching panel information from
this endpoint. Next, the arrays of file ids are searched to establish which
panel the file is in. When the panel is found, its list of channels is searched
by longName for pSTAT3. This gives a normalizedShortNameId and the key to
submitting the statistics request.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Panels
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/panels' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"panels": [
{
"id": 40558,
"name": "Panel 1",
"channels": [
{
"shortName": "Ax488-A",
"longName": "pStat3",
"normalizedShortNameId": 36,
"fcsFileChannelIndex": 3
GET
Show Panel Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/panels/{{PANEL_ID}}
Show details for a panel in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Panel Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/panels/{{PANEL_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"id": 40558,
"name": "Panel 1",
"channels": [
{
"shortName": "Ax488-A",
"longName": "pStat3",
"normalizedShortNameId": 36,
"fcsFileChannelIndex": 3
},
{
Sample Tags
GET
Download Sample Tags
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/download_sample_tags
Download sample tags from an Experiment as a TSV (tab separated values) table
file. Learn more about exporting and importing sample tags.
Currently there is no JSON support for Sample Tags and the information can only
be exchanged via file.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Download Sample Tags
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/download_sample_tags' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
POST
Upload sample tags to an Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_sample_tags
Upload sample tags to an Experiment. Sample tags should be in the form of a TSV
(tab separated values) table file, which can be sourced from the Download Sample
Tags endpoint. Learn more about importing and exporting sample tags.
Currently there is no JSON support for Sample Tags and the information can only
be exchanged via file.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
file
@{{FILE_NAME}}
Example Request
Upload sample tags to an Experiment
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/upload_sample_tags' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--form 'file="@{{FILE_NAME}}"'
Example Response
200 OK
Body
Header(0)
{
"message": "Successfully imported the sample tags annotated in the uploaded file 'test_annotations.tsv'!"
}
Scales
Data are rarely presented exactly as they were acquired on the instrument. Learn
more about data scaling.
A scale type of 1 is linear. 2 is log. 4 is arcsinh.
GET
List Scales for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/scales
List scale settings for an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Scales for Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/10559/scales' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"scales": [
{
"id": 89801,
"minimum": -200,
"maximum": 262144,
"cofactor": 150,
"experimentId": 10559,
"normalizedShortNameId": 36,
"scaleType": 4
},
GET
Show Scale Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/scales/{{SCALE_ID}}
Show details for a scale in an Experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
Show Scale Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/10559/scales/89801' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
{
"scale": {
"id": 89801,
"minimum": -200,
"maximum": 262144,
"cofactor": 150,
"experimentId": 10559,
"normalizedShortNameId": 36,
"scaleType": 4
}
}
PUT
Update Scale
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/scales/{{SCALE_ID}}
Update settings for a single scale in an Experiment. To update only certain
attributes for a scale, pass only those attributes in the update request.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"scale": {
"minimum": -200.5,
"maximum": 10000,
"cofactor": 10,
"scaleType": 4
}
}
Example Request
Update Scale
View More
curl --location -g --request PUT 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/scales/{{SCALE_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"scale": {
"minimum": -200.5,
"maximum": 10000,
"cofactor": 10,
"scaleType": 4
}
}'
Sharing
One should never analyze alone... Learn more about sharing and collaboration in
Cytobank.
GET
List Full Access Users for Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/full_access_users
List all full access users in an experiment.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyurlencoded
Example Request
List Full Access Users for Experiment
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/full_access_users' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(0)
View More
{
"experiment": {
"full_access_users": [
{
"id": 43,
"name": "Cytobank Support",
"email": "redacted@cytobank.org"
},
{
"id": 102,
"name": "Cyril Cytometry",
POST
Add Full Access User to Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/add_full_access_user
Add a full access user to an experiment.
Users can be added by using one of the following fields:
* userId
* userName
* userEmail
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"experiment":
{
"userId": {{FULL_ACCESS_USER_ID}}
}
}
Example Request
Add Full Access User to Experiment
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/add_full_access_user' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"experiment":
{
"userId": {{FULL_ACCESS_USER_ID}}
}
}'
Example Response
200 OK
Body
Header(0)
{
"message": "Cyril Cytometry has been given full access to this experiment."
}
POST
Remove Full Access User From Experiment
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/add_full_access_user
Remove a full access user from an experiment.
Users can be removed by using one of the following fields:
* userId
* userName
* userEmail
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Content-Type
application/json
BODYraw
{
"experiment":
{
"userName": {{FULL_ACCESS_USER_NAME}}
}
}
Example Request
Remove Full Access User From Experiment
View More
curl --location -g --request POST 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/experiments/{{EXPT_ID}}/add_full_access_user' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"experiment":
{
"userName": {{FULL_ACCESS_USER_NAME}}
}
}'
Example Response
200 OK
Body
Header(0)
{
"message": "Cyril Cytometry was successfully removed from the full access list."
}
Statistics
GET
Show General Statistics
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/statistics?experimentId={{EXPT_ID}}&gateVersion={{GATE_VERSION}}&experimentVersion={{EXPT_VERSION}}&compensationId={{COMP_ID}}&fcsFileIds={{FCS_FILE_ID_1}}&fcsFileIds={{FCS_FILE_ID_2}}&channelIds={{CHANNEL_ID_1}}&channelIds={{CHANNEL_ID_2}}&gateSetIds={{POPULATION_ID_1}}&gateSetIds={{POPULATION_ID_2}}
Retrieve a batch of common statistics for an Experiment.
Parameter Details:
* EXPT_VERSION must be set to the current version of the Experiment, which can
be seen as the version attribute returned from a call to the Show Experiment
Details endpoint.
* GATE_VERSION of -1 corresponds to the state of gates and populations in the
gating interface. Faster performance can be achieved by using the maximum
gate version from the experiment (learn more about gate versions). Maximum
gate version can be seen as the gateVersion attribute returned from a call to
the Show Experiment Details endpoint.
* COMP_ID is the ID of the compensation to apply to the statistics. Use -2 for
file-internal compensation. Use -1 for uncompensated.
* FCS_FILE_ID parameters are the IDs of FCS files to calculate statistics on.
Multiple are permitted.
* CHANNEL_ID parameters are the normalizedShortNameId attribute of the channels
to calculate statistics on. This information can be retrieved from the Panels
endpoints.
* POPULATION.GATE_SET_ID parameters are the gateSetId attribute values of the
populations to calculate statistics for. Multiple are permitted. Note that
this argument is the gateSetId attribute of a population object and not the
ID of the object itself. This secondary ID is experiment-specific and will be
a smaller number. An argument of 0 corresponds to the ungated population,
i.e., the raw data with no filtering applied. Another term for a population
is a "gate set" because it's a set of gates (learn more).
The minimum parameters to receive a response are EXPT_VERSION, GATE_VERSION,
COMP_ID, EXPT_ID, and FCS_FILE_ID. Without POPULATION.GATE_SET_ID then
statistics will be returned for all populations. Without CHANNEL_ID then only
event counts will be returned.
When submitting a single request with multiple files and channels, make sure
that all the channels appear within all the files. An error will result
otherwise.
Returned data:
Statistics returned include event count, minimum, maximum, mean, median,
variance, standard deviation, and 2nd/98th percentile.
Results objects will be returned for each file by each population in the
Experiment. Within each results object, results for multiple channels are keyed
on the normalizedShortNameId attribute within each statistic type. The short
name and long name that correspond to this ID can be deciphered using panel
information from the Panels API endoints.
Performance note:
While this endpoint accepts multiple parameters at once, for large datasets it
may be necessary to send multiple requests to avoid client timeouts. Also note
that if only event counts are being fetched then optimizations can be made for a
faster request (see Show Event Count Statistics endpoint below).
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
experimentId
{{EXPT_ID}}
gateVersion
{{GATE_VERSION}}
experimentVersion
{{EXPT_VERSION}}
compensationId
{{COMP_ID}}
fcsFileIds
{{FCS_FILE_ID_1}}
fcsFileIds
{{FCS_FILE_ID_2}}
channelIds
{{CHANNEL_ID_1}}
channelIds
{{CHANNEL_ID_2}}
gateSetIds
{{POPULATION_ID_1}}
gateSetIds
{{POPULATION_ID_2}}
Bodyurlencoded
Example Request
Show General Statistics
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/statistics?experimentId={{EXPT_ID}}&gateVersion={{GATE_VERSION}}&experimentVersion={{EXPT_VERSION}}&compensationId={{COMP_ID}}&fcsFileIds={{FCS_FILE_ID_1}}&fcsFileIds={{FCS_FILE_ID_2}}&channelIds={{CHANNEL_ID_1}}&channelIds={{CHANNEL_ID_2}}&gateSetIds={{POPULATION.GATE_SET_ID_1}}&gateSetIds={{POPULATION.GATE_SET_ID_2}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
[
{
"populationIdentifierKey": "209014,10559,32,[3],-1,-1,,30,popid",
"experimentId": 10559,
"gateVersion": -1,
"compensationId": -1,
"fcsFileId": 209014,
"gateSetId": 3,
"eventCount": 38420,
"minimums": {},
"maximums": {},
GET
Show Event Count Statistics
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/statistics?experimentId={{EXPT_ID}}&gateVersion={{GATE_VERSION}}&experimentVersion={{EXPT_VERSION}}&compensationId={{COMP_ID}}&fcsFileIds={{FCS_FILE_ID_1}}&fcsFileIds={{FCS_FILE_ID_2}}&gateSetIds={{POPULATION_ID_1}}&gateSetIds={{POPULATION_ID_2}}
This is just another take on the general statistics endpoint. It works the same
but excludes channel parameters. In the absence of channel information only
event count data are returned. If only event count data are needed, this
approach can be faster than retrieving all statistics by avoiding unnecessary
computation.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
PARAMS
experimentId
{{EXPT_ID}}
gateVersion
{{GATE_VERSION}}
experimentVersion
{{EXPT_VERSION}}
compensationId
{{COMP_ID}}
fcsFileIds
{{FCS_FILE_ID_1}}
fcsFileIds
{{FCS_FILE_ID_2}}
gateSetIds
{{POPULATION_ID_1}}
gateSetIds
{{POPULATION_ID_2}}
Bodyurlencoded
Example Request
Show Event Count Statistics
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/statistics?experimentId={{EXPT_ID}}&gateVersion={{GATE_VERSION}}&experimentVersion={{EXPT_VERSION}}&compensationId={{COMP_ID}}&fcsFileIds={{FCS_FILE_ID_1}}&fcsFileIds={{FCS_FILE_ID_2}}&gateSetIds={{POPULATION_ID_1}}&gateSetIds={{POPULATION_ID_2}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
Example Response
200 OK
Body
Header(10)
View More
[
{
"populationIdentifierKey": "209014,10559,32,[3],-1,-1,,30,popid",
"experimentId": 10559,
"gateVersion": -1,
"compensationId": -1,
"fcsFileId": 209014,
"gateSetId": 3,
"eventCount": 38420,
"minimums": {},
"maximums": {},
Users
One should never analyze alone...
GET
List Users
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/users
List all users on this Cytobank. This endpoint is for admins only and will
respond with an authorization error if accessed by a non-admin.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
List Users
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/users' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'
GET
Show User Details
https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/users/{{USER_ID}}
Show details for a user. This endpoint is for admins only and will respond with
an authorization error if accessed by a non-admin.
HEADERS
Authorization
Bearer {{AUTH_TOKEN}}
Bodyformdata
Example Request
Show User Details
curl --location -g --request GET 'https://{{CYTOBANK}}.cytobank.org/cytobank/api/v1/users/{{USER_ID}}' \
--header 'Authorization: Bearer {{AUTH_TOKEN}}'