Skip to content

API

CellEngine provides a first-class HTTP API that enables you to securely, reproducibly and easily perform any action from your language of choice.

General

Authentication

CellEngine uses tokens for authentication and authorization. Every request must be accompanied by a token in the Authorization header:

Authorization: Bearer <token>

To retrieve a token, go to your user profile page in CellEngine and click new in the API Tokens section. The following settings are available:

  • Description is a free-form name or description of the token.
  • Expiration date limits the lifetime of the token. This can be up to one year from today's date.
  • Allowed IP ranges optionally restricts the IP addresses from which requests using the token will be accepted, in CIDR format.
  • Permissions specifies a subset of permissions that the token can use. For example, if you have full read/write access to an experiment, but the token only has fcsfile.upload, the token will only be able upload FCS files. If you only have read-only access to an experiment, the token will not be able to upload FCS files; it does not gain the permission that you do not have.

If you need to modify, regenerate or revoke a token, you can do so from your user profile as well.

Versioning

The current stable API is version 1. All endpoints are nested under /v1/ (e.g. https://cellengine.com/api/v1/experiments/...).

Request volumes

CellEngine was built for speed and throughput. Use the bulk endpoints whenever possible (e.g. bulk statistics and download gated populations from multiple files).

If you have a requirement for large-volume requests that are not satisfied by our bulk endpoints, please contact us. Avoid making more than 100 requests per second. Your requests may be throttled.

API Toolkits

We provide API toolkits for R and Python, as well as an OpenAPI specification. Contact us about toolkits for Wolfram Mathematica and JavaScript (Node.js).

Standard query parameters for list routes

All list routes (e.g. GET /experiments/) support the following parameters unless otherwise noted:

Parameter Value Description
fields String Fields to return (exclusively) or omit (from default set), in the format -fieldName (omit) or +fieldName (include).
limit Number Maximum number of results to return.
query String Complex query comprised of query operators (see below).
skip Number Number of results to skip (e.g. an offset).

Allowed query operators are as follows:

Operator Description Example
eq equal to eq(eventCount, 5000) for FCS files with exactly 5000 events.
exists property exists exists(data.Population, true) for an experiment with a metadata key of "Population".
gt greater than gt(eventCount, 5000) for FCS files with more than 5000 events.
lt less than lt(eventCount, 5000) for FCS files with less than 5000 events.
gte greater than or equal to gte(eventCount, 5000) for FCS files with at least 5000 events.
lte less than or equal to lte(eventCount, 5000) for FCS files with up to 5000 events.
ne not equal to ne(name, "myfile.fcs") for FCS files not named "myfile.fcs".
size length of an array field size(annotations, 2) for FCS files with two annotations.
in member of an array field in(primaryResearcher._id, [<yourId>, <yourCoworkersId>]) for experiments where you or your coworker are primary researchers. (Note that these results would be limited to experiments to which you have access.)
nin not a member of an array field
all match all criteria all(tags, ["apoptosis", "cell cycle"]) for experiments with those tags.
and combine operators with and
or combine operators with or
elemMatch specifies that the same record must have multiple matching properties

If you are performing many queries or complex queries, we suggest that you contact us to ensure that your queries are efficient.

Standard HTTP verbs and headers

  • Concurrency control is offered via the If-Unmodified-Since header for any resource that has an updated property. Setting If-Unmodified-Since to the value of updated that appears in the version of the resource that you currently have allows you to avoid overwriting changes made by other users or applications. For more information, see the Mozilla Developer Network documentation page for that header.

  • The X-Experiment-Updated header contains the UTC timestamp at which the experiment or any of its descendant resources (such as gates and scales) were last modified. It is the same as the experiment.deepUpdated property returned by GET /experiments/:experimentId. This header is only guaranteed to be set when the experiment.deepUpdated property is changed.

Attachments

Attachments are non-data files that are stored in an experiment.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the attachment.
crc32c String, read-only The CRC32c sum for the file, hex-encoded, per RFC 4960 Appendix B.
experimentId ID, read-only ID of the experiment to which the attachment belongs.
filename String The name of the file.
md5 String, read-only The MD5 sum for the file, hex-encoded.
size Integer, read-only The number of bytes in the file.

Methods

upload

Uploads an attachment. The maximum file size is 5 TB.

Required Permissions

This API requires the following permissions:

  • "attachment.upload"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/attachments
Content-Type: multipart/form-data
---
<multipart form data including file>
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Body Parameters
* File The file contents. The name of the field does not matter.
Response
201 Created
Location: https://cellengine.com/api/v1/experiments/:experimentId/attachments/:attachmentId
---
{
    crc32c,
    experimentId,
    filename,
    md5,
    size
}

list

Lists attachments in the experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/attachments
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<attachment>}
]

delete

Deletes an attachment.

Required Permissions

This API requires the following permissions:

  • "attachment.delete"
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId/attachments/:attachmentId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
attachmentId String ID of the attachment.

Do not supply a request body with this method.

Response
204 No Content

update

Updates an attachment. The only writable property is the filename; thus this method is only suitable for renaming an attachment.

Required Permissions

This API requires the following permissions:

  • "attachment.update"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/attachments
Content-Type: application/json
---
{
    "filename": "new filename.ext"
}
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
attachmentId String ID of the attachment.
Body Parameters
filename String The name of the file.
Response
200 OK
---
{
    crc32c,
    experimentId,
    filename,
    md5,
    size
}

download

Downloads the file.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "attachment.download"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/attachments/:attachmentId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
attachmentId String ID of the attachment.

Do not supply a request body with this method.

Response
200 OK
Content-Disposition: attachment; filename="<filename>"
Content-Type: <mime-type>
---
<octet-stream>

Compensations

A compensation is a list of channel names and a corresponding square matrix. The matrix is technically a "spill"/"spillover" matrix, which is inverted to yield the compensation matrix; most applications refer to the spill matrix as a compensation matrix, however.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the compensation.
channels String[] The names of the channels to which this compensation matrix applies.
experimentId String, read-only The ID of the experiment to which this compensation belongs.
name String The name of the compensation.
spillMatrix Number[] The row-wise, square spillover matrix. The length of the array must be the number of channels squared.

Special Values

Wherever a compensation value can be supplied to the API, three special constants may be used:

Value Description
0 Uncompensated Do not apply a compensation.
-1 File-Internal Compensation Uses the file's internal compensation matrix, if available. If not available, an error will be returned.
-2 Per-File Compensation Use the compensation assigned to each individual FCS file. Not a valid value for FcsFile.compensation.

Methods

list

Lists compensations in the experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/compensations
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response

If successful, this method returns an array of Compensation resources in the response body.

create

Creates a compensation matrix.

Required Permissions

This API requires the following permissions:

  • "compensation.create"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/compensations/
Content-Type: application/json
---
{
    "name": string,
    "channels": string[],
    "spillMatrix": number[]
}
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the compensation belongs.
Body Parameters
channels String[] The names of the channels to which this compensation matrix applies.
spillMatrix Number[] The row-wise, square spillover matrix. The length of the array must be the number of channels squared.
Optional Body Parameters
name String The name of the compensation. Defaults to "Untitled Compensation".
Response

If successful, this method returns a Compensation resource in the response body.

update

Updates a compensation matrix.

Required Permissions

This API requires the following permissions:

  • "compensation.update"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/compensations/:compensationId
Content-Type: application/json
---
{
    "name": string,
    "channels": string[],
    "spillMatrix": number[]
}
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the compensation belongs.
compensationId String ID of the compensation matrix.
Optional Body Parameters
channels String[] The names of the channels to which this compensation matrix applies.
name String The name of the compensation.
spillMatrix Number[] The row-wise, square spillover matrix. The length of the array must be the number of channels squared.
Response

If successful, this method returns a Compensation resource in the response body.

delete

Deletes a compensation.

Required Permissions

This API requires the following permissions:

  • "compensation.delete"
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId/compensations/:compensationId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
compensationId String ID of the compensation.

Do not supply a request body with this method.

Response
204 No Content

Experiments

Resource Representation

Property Value Description
_id String, read-only The unique ID of the experiment.
absoluteCountParameters Object|null Information used to calculate absolute cell counts.
absoluteCountParameters.beadPopulation String The ID of the bead population.
absoluteCountParameters.concentrationAnnotation String The name of the annotation containing the bead concentration.
absoluteCountParameters.countAnnotation String The name of the annotation containing the bead count.
absoluteCountParameters.type String One of the following:
  • "concentration" - Specify concentrationAnnotation and beadPopulation
  • "countAndVolume" - Specify countAnnotation, beadPopulation and volumeAnnotation
  • "sampleVolume" - Specify volumeAnnotation and volumeUnit
absoluteCountParameters.volumeAnnotation String The name of the annotation containing the sample volume.
absoluteCountParameters.volumeUnit String The units of the sample volume, if not present in the sample volume annotation itself. One of "ml", "ul", "nl".
activeCompensation Compensation|null The most recently used compensation. Used to select the compensation in various parts of the Web interface. If this value is null, that means a compensation has not yet been explicitly selected in the UI and the "used" value is determined by the experiment state: If perFileCompensationsEnabled is true, then per-file compensation is used. If all files have a file-internal comp matrix, then file-internal is used. Otherwise, no compensation (uncompensated) is used.
analysisSourceExperiment ID, optional, read-only If this is a derived analysis, its source experiment.
analysisTask ID, optional, read-only If this is a derived analysis, the analysis task that created it.
annotationNameOrder String[] Order in which annotations appear in all tables in the Web interface.
annotationSources Record<String, Object> Sources of FCS file annotations, used to automatically annotate files on upload. Keys are the annotation names, values are as documented below.
annotationSources.$.index Number For "filename" sources the index of the value to extract from the split filename.
annotationSources.$.key String For "header" sources the keyword name.
annotationSources.$.source "filename"|"header" The source type: either part of the filename or a header keyword value.
annotationSources.$.tokens String For "filename" sources the tokens (characters) used to split the filename.
annotationTableColumnWidths Record<String, Number> The widths of the columns for all annotation tables in the Web UI.
annotationTableColumnWraps Record<String, Boolean> Whether or not each annotation uses text wrapping in the annotation table.
annotationTableSortColumns String|Number[] The current sorting state for the annotation table.
annotationValidators Record<String, Object> Validators that apply to FCS file annotations. Keys are the annotation name, values are as documented below.
annotationValidators.$.enum String[], optional String values allowed for the annotation.
annotationValidators.$.max Number, optional Maximum allowed value, when interpreted as a number.
annotationValidators.$.min Number, optional Minimum allowed value, when interpreted as a number.
annotationValidators.$.required Boolean, optional Whether or not a value is required for the annotation.
cloneSourceExperiment ID, optional, read-only Indicates the experiment from which this experiment was cloned, if applicable.
colorSpec ColorSpec Describes what colors are assigned to populations, files, channels and/or annotations. Must be of the form Array<[string, Array<[string | null, number]>]>.
comments TextOp[] Comments about the experiment. This property is an array of TextOps, each of which is in the form {insert: "some text", attributes: {bold: false, italic: false, underline: false}}.
created Datetime, read-only The creation time of the experiment.
data Object May contain auxiliary information about the experiment, such as where it was imported from.
dataOrder String[] Display order of the keys in data.
deepUpdated Datetime, read-only The last time that the experiment or any of its descendant resources (e.g. gates, scales) were modified. This property is eventually consistent; its value may not be updated instantaneously after a descendant resource is modified.
deleted Datetime The time when the experiment was moved to the trash. Experiments are permanently deleted approximately seven days after this time. Cannot be set on revision experiments, experiments that are locked or experiments with an active retention policy.
locked Boolean, read-only Whether or not the experiment is locked and cannot be modified. Locking an experiment locks all descendant resources as well, including gates and populations. Currently only true for revision experiments.
name String, max length 1024 The name of the experiment.
palettes Record<String, String[]> The color palettes for the experiment. Keys are palette IDs, values are arrays of hexadecimal colors.
path ID[] The experiment's path. Each entry is the ID of an ancestor folder, in hierarchical order. A root-level experiment has a path of [].
perFileCompensationsEnabled Boolean If per-file compensations are enabled for the experiment.
permissions[] Permission[], read-only List of permissions for the experiment. Only modifiable via the sharing API.
permissions[].grantDate Datetime When the permission was granted.
permissions[].grantee User User to whom the permission was granted.
permissions[].grantor User User who granted the permission.
permissions[].role String The role that the grantee has.
primaryResearcher User (partial representation) The user who is the primary researcher assigned to the experiment. Only modifiable by the primaryResearcher.
retentionPolicy.history[].retainUntil Datetime, read-only Date that the retention policy was set to.
retentionPolicy.history[].timestamp Datetime, read-only When Date when the retention policy was changed.
retentionPolicy.history[].user ID, read-only ID of user who set the retention policy.
retentionPolicy.history[] RetentionPolicy[], read-only History of all changes to the experiment's retention policy.
retentionPolicy.retainUntil Datetime A date until when this experiment cannot be deleted. (This date may be in the past if the retention policy has expired.) Note: retention policies may only be extended.
revisions[] Revision[], read-only List of revisions of the experiment.
revisions[]._id Experiment, read-only ID of the revision experiment.
revisions[].comments String, max length 1024 Comments about the revision, such as why it was saved.
revisions[].creator User, read-only User who created the revision.
revisions[].timestamp Datetime, read-only Timestamp when the revision was created.
revisionSourceExperiment ID, optional, read-only Indicates the experiment of which this experiment is a revision, if applicable.
sortingSpec Object Describes the way annotations, populations and channels are sorted. Properties of this object are the thing being sorted, and the values are the sort order.
tags String[] List of tags for the experiment.
updated Datetime, read-only The last time that the experiment was modified. This value is a shallow timestamp; it is not updated when descendant resources such as gates are modified. (See deepUpdated.)
uploader User (partial representation), read-only The user who created the experiment.

Methods

list

List experiments accessible to the requesting user (i.e. ones for which the user has the "experiment.read" permission).

Request
GET https://cellengine.com/api/v1/experiments
Parameter Value Description
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
----
[
    {<experiment>}
]

create

Create an experiment. Creating an experiment also creates a blank ScaleSet for the experiment.

Required Permissions

This API requires the following permissions:

  • If the new experiment would be in a folder, "folder.createExperiment" on a parent folder.
Request
POST https://cellengine.com/api/v1/experiments
Content-Type: application/json
Parameter Value Description
Path Parameters
None
Optional Body Parameters
name String Defaults to "Untitled Experiment".
comments TextOp[] Comments about the experiment. This property is an array of TextOps, each of which is in the form {insert: "some text", attributes: {bold: false, italic: false, underline: false}}. Defaults to [].
uploader User ID Defaults to user making request.
path String[] of ID Array of folder IDs comprising the path.
primaryResearcher User ID Defaults to user making request.
tags String[] Defaults to an empty array.
Response
201 Created
Location: <URI>
----
{<experiment>}

read

Gets an experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.

Do not supply a request body with this method.

Response
200 OK
----
{<experiment>}

update

Updates an experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "experiment.update"
  • If setting deleted, "experiment.delete", as well as "folder.removeExperiment" if the experiment is in a folder
  • If moving the experiment (changing path), "experiment.move", as well as "folder.removeExperiment" on the current parent folder and "folder.createExperiment" on the new parent folder, if any
  • If changing primaryResearcher, "experiment.changePrimaryResearcher"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String
Body Parameters
activeCompensation Compensation
annotationNameOrder String[]
annotationTableSortColumns String|Number[]
annotationTableColumnWidths Number[]
annotationSources Object
annotationValidators Object
comments TextOp[]
deleted Datetime
name String
perFileCompensationEnabled Boolean
primaryResearcher User ID
retentionPolicy.retainUntil Datetime
savedStatisticsExports Object[]
sortingSpec Object
tags String[]

See Experiment Resource Representation for a description of the parameters.

Response
200 OK
----
{<experiment>}

delete

Marks the experiment for deletion. It will be deleted permanently after approximately seven days.

Revision experiments, locked experiments and experiments with an active retentionPolicy cannot be deleted.

Required Permissions

This API requires the following permissions:

  • "experiment.delete"
  • "folder.removeExperiment" on an ancestor folder if the experiment is in a folder
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.

Do not supply a request body with this method.

Response
204 No Content

clone

Cloning an experiment saves a deep copy of the experiment and all of its resources, including attachments, FCS files, gates and populations.

Cloned experiments do not count toward your account's resource usage.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "experiment.clone"
  • "folder.createExperiment" if the experiment would be created in a folder
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/clone
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Body Parameters
name String
path String[] Array of folder IDs comprising the path.

See Experiment Resource Representation for a description of the parameters.

Response
201 Created
Location: <URI>
----
{<experiment>}

save revision

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "experiment.saveRevision"

change permissions

import from BD FACSDiva

Required Permissions

This API requires the following permissions:

  • "gate.create"
  • "population.create"
  • "scaleset.update"
  • "illustration.create"

import gates, populations, compensations and/or illustrations from another experiment

Required Permissions

This API requires the following permissions:

  • "experiment.read" on the source experiment
  • "population.create" if importing gates and populations
  • "gate.create" if importing gates and populations
  • "illustration.create" if importing illustrations
  • "compensation.create" if importing compensations
  • "experiment.update" if importing saved statistics exports
  • "experiment.update" if importing annotation columns

export populations to new experiment

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "experiment.clone"

export Gating-ML

Generates a Gating-ML 2.0 XML file containing the experiment's compensation matrices, gates, populations and scales.

Please see the documentation for exporting Gating-ML for a list of limitations of the Gating-ML specification and workarounds.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId.gatingml
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
fcsFileId String If provided, the Gating-ML file will contain this FCS file's tailored gates (in addition to any non-tailored gates). If omitted, the file will contain the global gates.
Response
200 OK
Content-Disposition: attachment; filename="<filename>"
Content-Type: application/vnd.isac.gating-ml+xml
----
<xml>

export JSON

Generates a JSON file containing all of the resources in the experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId.json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Response
200 OK
Content-Type: application/json
----
{
    experiment: <experiment>,
    attachments: [<attachment>],
    compensations: [<compensations],
    fcsFiles: [<fcsFiles>],
    scaleSets: [<scaleSets>],
    gates: [<gates>],
    populations: [<populations>],
    illustrations: [<illustrations>]
}

FCS Files

FCS files are the standard data representation for flow cytometry.

In CellEngine, an fcsfile resource represents the file itself, along with metadata such as the panel and annotations.

Each FCS file has its own panel. A channel is an array of objects containing the channel name ("channel"), channel reagent ("reagent") and index of the channel in the file. The Web UI will display all files with the same "panelName" in the same panel. Note that channels for different files may be in any order within the same panel (e.g. PacBlu can be channel 1 in file 1, and channel 3 in file 2). Consumers of the API are expected to keep the channel names and reagent names for all files with the same panelName consistent. Failure to do so is benign when making requests pertaining to single files, but may cause an error, warning message or undefined behavior when making requests pertaining to multiple files or when working from the Web UI.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the file.
annotations[] Annotation[] Metadata about the file.
annotations[].name String Name of the annotation (i.e. the key).
annotations[].value String Value of the annotation.
compensation Compensation, optional Used with per-file compensation to indicate the compensation to apply to this file.
crc32c String, read-only The CRC32c sum for the file, hex-encoded, per RFC 4960 Appendix B.
deleted Datetime If set, the file has been soft-deleted and may be permanently deleted later.
eventCount Integer, read-only The number of events (rows) in the file.
experimentId String, read-only ID of the experiment that this file belongs to.
filename String The filename.
gatesLocked Boolean If true, no gates that apply to this file can be changed.
hasFileInternalComp Boolean, read-only Whether or not this file has a valid file-internal compensation matrix.
header JSON String, read-only The file header stored as a JSON string.
isControl Boolean Whether or not this is a control file. Control files are hidden from most of the Web UI, and can be used to exclude compensation or calibration beads from analysis, for example.
md5 String, read-only The MD5 sum for the file, hex-encoded.
panel[] Channel[] The file's panel.
panel[].channel String The channel name.
panel[].reagent String, optional The reagent for the channel.
panel[].index Integer The 1-based index of the channel in the file.
panelName String The name of the file's panel. Files with the same panelName are grouped into a panel.
sampleName String, read-only The sample name extracted from the file header.
size Integer, read-only The number of bytes in the file.
spillString String, read-only, optional The file-internal compensation, if present.

Methods

list

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request

Gets the list of all FCS files for the experiment.

Control files are excluded by default; use ?includeControls=true in the query to include them.

Soft-deleted FCS files are included by default; use ?eq(deleted,null) in the query to exclude them.

The header field is not returned by default due to its size. To include it, specify fields=+header in the query.

GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Optional Query Parameters
Standard query parameters for list routes
includeControls Boolean Include control FCS files. Defaults to false.

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<fcsfile>}
]
Example: query FCS files by annotation

If you have annotated your files, you can perform lookups by those annotations. For example, to find files with "plate column" equal to "A":

GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles?query=elemMatch(annotations, eq(name, "plate column"), eq(value, "A"))

(Shown before URL encoding, which would convert spaces to %20 and quotation marks to %22.)

To find files that match on multiple criteria, combine multiple elemMatch operators with and. For more information on query operators, see standard query parameters for list routes.

upload

Uploads a file. The maximum file size is approximately 2.3 GB. Contact us if you need to work with larger files.

Automatically parses panels and annotations and updates ScaleSets to include all channels in the file.

Required Permissions

This API requires the following permissions:

  • "fcsfile.upload"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles
Content-Type: multipart/form-data
---
<multipart form data including file>
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Body Parameters
* File The file contents. The name of the field does not matter.
Response
201 Created
Location: https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId
---
{<fcsfile>}

create

Creates an FCS file by copying, concatenating and/or subsampling existing file(s) from this or other experiments, or by importing from an S3-compatible service. This endpoint can be used to import files from other experiments.

When concatenating and subsampling at the same time, subsampling is applied to each file before concatenating.

If addFileNumber is true, a file number column (channel) will be added to the output file indicating which file each event (cell) came from. The values in this column have a uniform random spread (±0.25 of the integer value) to ease visualization. While this column can be useful for analysis, it will cause the experiment to have FCS files with different panels unless all FCS files that have not been concatenated are deleted.

During concatenation, any FCS header parameters that do not match between files will be removed, with some exceptions:

  • $BTIM (clock time at beginning of acquisition) and $DATE will be set to the earliest value among the input files.
  • $ETIM (clock time at end of acquisition) will be set to the latest value among the input files.
  • $PnR (range for parameter n) will be set to the highest value among the input files.

All channels present in the first FCS file in the fcsFiles parameter must also be present in the other FCS files.

When importing from an S3-compatible service, be aware of the following:

  • Only a single file can be imported at a time.
  • The host property must include the bucket and region as applicable. For example, for AWS, this would look like mybucket.s3.us-east-2.amazonaws.com.
  • The path property must specify the full path to the object, e.g. /Study001/Specimen01.fcs.
  • Importing private S3 objects requires an accessKey, a secretKey and optionally a sessionToken for a user with appropriate permissions. For AWS, GetObject is required.
  • Importing objects may incur fees from the S3 service provider.
Required Permissions

This API requires the following permissions:

  • "fcsfile.upload"
  • If importing files from another experiment, "experiment.read" and "experiment.clone" on the source experiment(s).
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Required Body Parameters
fcsFiles String[]|{_id: String, experimentId: String}[]|{host: String, path: String, accessKey?: String, secretKey?: String, sessionToken?: string}[] List of file IDs or objects to process. If more than one file is provided, they will be concatenated in order. To import files from other experiments, provide an array of objects with _id and experimentId properties. To import a file from an S3-compatible service, provide a length-1 array of objects with host and path; if the S3 object is private, additionally provide accessKey, secretKey and, if required, sessionToken.
Optional Body Parameters
addFileNumber Boolean If concatenating files, adds a file number channel to the resulting file.
addEventNumber Boolean Add an event number column to the exported file. This number corresponds to the index of the event in the original file; when concatenating files, the same event number will appear more than once.
filename String Filename to use for the created file. Required if concatenating or subsampling.
preSubsampleN Integer Randomly subsample the file to contain this many events.
preSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1).
seed Number Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used.
Response
201 Created
Location: https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId
---
{<fcsfile>}

download file or population or send to S3 (FCS or TSV)

Retrieves the FCS file in either FCS or TSV format. Optionally gates a specified population and/or subsamples. The file can either be downloaded or sent to an S3-compatible service.

Set the original query parameter to true to retrieve the original FCS file verbatim. When exporting as FCS format with the original parameter set to false or left unspecified, the following apply:

  • The current value of the file's panel property will be used to set the $PnS (reagent) header keywords.
  • The compensatedQ and compensationId parameters will be used to set the $SPILLOVER header keyword.
  • Other synonymous changes may be present. For example, the DATA segment will always be little-endian.

When exporting as TSV format, the file's panel property will be used to set the column headers.

When sending the file to an S3-compatible service, use the POST HTTP method and supply a dest object in the body, as documented below.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "fcsfile.download"
Request

The request may be either GET or POST. Use GET when downloading the file; use POST when sending the file to an S3-compatible service.

GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId.fcs
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId.fcs
GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId.tsv
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId.tsv
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
fcsFileId String ID of the file.
Optional Query Parameters
compensatedQ Boolean If true, applies the compensation specified in compensationId to the exported events. For TSV format, the numerical values will be the compensated values. For FCS format, the numerical values will be unchanged, but the file header will contain the compensation as the spill string (file-internal compensation).
compensationId Compensation Required if populationId or compensatedQ is specified. Compensation to use for gating.
headers Boolean For TSV format only. If true, a header row containing the channel names will be included.
original Boolean If true, the returned file will be byte-for-byte identical to the originally uploaded file. If false or unspecified (and compensatedQ is false, populationId is unspecified and all subsampling parameters are unspecified), the returned file will contain essentially the same data as the originally uploaded file, but may not be byte-for-byte identical. For example, the byte ordering of the DATA segment will always be little-endian and any extraneous information appended to the end of the original file will be stripped. This parameter takes precedence over compensatedQ, populationId and the subsampling parameters.
populationId String If provided, only events from this population will be included in the output file.
postSubsampleN Integer Randomly subsample the file to contain this many events after gating.
postSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) after gating.
preSubsampleN Integer Randomly subsample the file to contain this many events before gating.
preSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) before gating.
seed Number Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used.
addEventNumber Boolean Add an event number column to the exported file. When a populationId is specified (when gating), this number corresponds to the index of the event in the original file.
Optional Body Parameters
dest Object If copying to an S3-compatible service, information about that service.
dest.host String Required for S3 transfers. The full S3 host, including the bucket and region as applicable. For example, for AWS, this would look like mybucket.s3.us-east-2.amazonaws.com.
dest.path String The path prefix for the object. This is concatenated directly with the file name. Use a trailing "/" to specify a "directory" in S3. For example, if the path is /Study001/ and the file is called Specimen01.fcs, the object key will be /Study001/Specimen01.fcs. Use no trailing slash to specify a file prefix. For example, if the path is /transfer1_, the object key will be /transfer1_Specimen01.fcs. Note that S3 object keys must start with "/"; a path of "" will result in an Invalid URI response. Defaults to "/".
dest.accessKey String Required for private buckets. The S3 access key. Must be associated with an account with appropriate S3 permissions (e.g. PutObject).
dest.secretKey String Required for private buckets. The S3 secret key.
dest.sessionToken String Required for private buckets when using temporary credentials (e.g. AWS STS). The S3 session token.
dest.headers Object Custom headers to include in the S3 request. Common examples are x-amz-storage-class/x-goog-storage-class and x-amz-server-side-encryption. Some headers, such as Content-Length, Content-MD5 and Content-Type, cannot be modified. Refer to https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html for AWS header documentation and https://cloud.google.com/storage/docs/migrating#custommeta regarding compatibility with Google Cloud Platform.
Response

If downloading the file as FCS:

200 OK
Content-Disposition: attachment; filename="<filename>"
Content-Type: application/vnd.isac.fcs
----
<octet-stream>

If downloading the file as TSV:

200 OK
Content-Disposition: attachment; filename="<filename>"
Content-Type: text/tab-separated-values; charset=utf-8
----
<text>

If sending the file to an S3-compatible service:

200 OK
Content-Type: application/json
---
{
    "s3Status": 200,
    "s3StatusMessage": "OK",
    "s3Headers": {
        "x-amz-id-2": "5Z4FF2oZq7z/EaUkT+dg8pOX+i6lym3FRrIcxycB+4UEgo04Xqy/rWjAU935PcUBzUwb6dyT00A=",
        "x-amz-request-id": "P0TFRCZ7SMW2JTGE",
        "date": "Sat, 11 Sep 2021 01:55:40 GMT",
        "etag": "\"3613a1e91e28bb78da20105654dd779c\"",
        "server": "AmazonS3",
        "content-length": "0",
        "connection": "close"
    }
    "s3Response": ""
}

download multiple files or populations (FCS or TSV)

Downloads multiple files bundled into a ZIP archive. Files can either be gated or ungated.

There are two ways to make this request: GET or POST. The GET request can be easier to make, but when requesting many files or populations the maximum URL length could be exceeded. (The combination of the request URL and headers together must be less than about 15 KB.) The POST route instead allows the parameters to be passed in the request body, for which there is no practical maximum size.

Every combination of fcsFileIds and populationIds will be exported (i.e. every population for every FCS file specified).

Unless the original, unmodified FCS files are being exported, the current values of the files' panel properties will be used to set the $PnS (reagent) header keywords.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "fcsfile.download"
GET Request
GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/zip
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
addEventNumber Boolean Add an event number column to the exported file. When populationIds is specified (when gating), this number corresponds to the index of the event in the original file.
compensatedQ Boolean Optional. If true, applies the compensation specified in compensationId to the exported events. For TSV format, the numerical values will be the compensated values. For FCS format, the numerical values will be unchanged, but the file header will contain the compensation as the spill string (file-internal compensation).
compensationId Compensation Required if populationIds or compensatedQ is specified. Compensation to use for gating.
fcsFileIds String[] Optional. Defaults to returning all non-control files in the experiment.
filenameTemplate String Tokenized template to dynamically name each file in the resulting archive.
populationIds String[] Optional. If provided, only events from these populations will be included in the output files. Defaults to ungated.
postSubsampleN Integer Randomly subsample the file to contain this many events after gating.
postSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) after gating.
preSubsampleN Integer Randomly subsample the file to contain this many events before gating.
preSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) before gating.
seed Number Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used.
Required Query Parameters
format fcs, tsv (with header) or tsv (without header), case-insensitive Specifies the format.

Do not supply a request body with this method.

POST Request
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/zip
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Body Parameters
addEventNumber Boolean Add an event number column to the exported file. When populationIds is specified (when gating), this number corresponds to the index of the event in the original file.
compensatedQ Boolean Optional. If true, applies the compensation specified in compensationId to the exported events. For TSV format, the numerical values will be the compensated values. For FCS format, the numerical values will be unchanged, but the file header will contain the compensation as the spill string (file-internal compensation).
compensationId Compensation Required if populationIds or compensatedQ is specified. Compensation to use for gating.
fcsFileIds String[] Optional. Defaults to returning all files in the experiment.
filenameTemplate String Tokenized template to dynamically name each file in the resulting archive.
populationIds String[] Optional. If provided, only events from these populations will be included in the output files. Defaults to ungated.
postSubsampleN Integer Randomly subsample the file to contain this many events after gating.
postSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) after gating.
preSubsampleN Integer Randomly subsample the file to contain this many events before gating.
preSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) before gating.
seed Number Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used.
Required Body Parameters
format fcs, tsv (with header) or tsv (without header), case-insensitive Specifies the format.
Response
Status: 303
Location: <redirect location>
---

Making a GET request to the redirected location yields the following response:

Status: 200
Content-Disposition: attachment; filename="<experiment name> - Gated Populations.zip"
Content-Type: application/zip
Content-Length: <length>
----
<octet-stream>

read

Gets metadata about the file.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET /experiments/:experimentId/fcsfiles/:fcsFileId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
fcsFileId String ID of the file.

Do not supply a request body with this method.

Response
Status: 200 OK
----
{<fcsfile>}

delete

Deletes the file immediately. To soft-delete a file, set its deleted property instead.

Required Permissions

This API requires the following permissions:

  • "fcsfile.delete"
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
fcsFileId String ID of the FCS file.

Do not supply a request body with this method.

Response
Status: 204 No Content

bulk delete

Deletes multiple files. To soft-delete files, set their deleted properties instead.

Required Permissions

This API requires the following permissions:

  • "fcsfile.delete"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/bulkdelete
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Required Body Parameters
(unnamed) String[] Array of IDs of the FCS files.

Do not supply a request body with this method.

Response
Status: 200
Content-Type: application/json
---
{
    nDeleted: <n>
}

update

Modifies an FCS file's metadata.

When modifying annotations, the characters \r and \n and leading and trailing whitespace will automatically be removed from annotation values by the server.

Note that if the experiment has annotationValidators and the request includes changes to annotations that would violate those validators, the change will still be applied. You must make an additional request to validate the FCS files using the validate endpoint.

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"
  • If setting deleted, "fcsfile.delete"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/:fcsFileId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
fcsFileId String ID of the FCS file.
Optional Body Parameters
filename String
panel[] Channel[]
panel[].channel String
panel[].reagent String Optional; only channel and index are required.
panel[].index Integer
panelName String
isControl Boolean
compensation Compensation
deleted Datetime
gatesLocked Boolean
annotations[] Annotation[]
annotations[].name String
annotations[].value String

See FCS File Resource Representation for a description of the parameters.

Response
Status: 200 OK
----
{<fcsFile>}

bulk update

Modifies multiple FCS files' metadata. Only a subset of FCS file properties may be modified from this API. If you have a need to modify additional properties in bulk, email support@cellengine.com.

When modifying annotations, the characters \r and \n and leading and trailing whitespace will automatically be removed from annotation values by the server.

Note that if the experiment has annotationValidators and the request includes changes to annotations that would violate those validators, the change will still be applied. You must make an additional request to validate the FCS files using the validate endpoint.

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"
  • If setting deleted, "fcsfile.delete"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/bulkupdate
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Optional Body Parameters
[].filename String
[].gatesLocked Boolean
[].isControl Boolean
[].compensation Compensation
[].annotations[] Annotation[]
[].annotations[].name String
[].annotations[].value String

See FCS File Resource Representation for a description of the parameters.

Response
Status: 204 No Content

validate annotations

Tests all or some files in the experiment for compliance with the experiment's annotationValidators.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/fcsfiles/validate
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Optional Query Parameters
fcsFileId String ID of a specific FCS file to test. Repeat the query parameter to test multiple files.
Response
Status: 200 OK
---
[{
    _id: string,
    valid: boolean,
    errors: string[]
}]
Parameter Value Description
[]._id String FCS file ID.
[].valid Boolean True if the file complies with all validators.
[].errors String[] List of violations.

rename reagent

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"

rename panel

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"

delete annotation

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"

rename annotation

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"

add annotations from header

Required Permissions

This API requires the following permissions:

  • "fcsfile.update"

Folders

Folders can be used to organize experiments. Permissions granted on folders cascade down the folder hierarchy, applying to descendant folders and experiments.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the folder.
name String The name of the folder.
created Datetime, read-only When the folder was created.
creator ID, read-only The user who created the folder.
deleted Datetime The time when the folder was moved to the trash. Folders are permanently deleted approximately seven days after this time.
path ID[] The folder's path. Each entry is the ID of an ancestor folder, in hierarchical order. A root-level folder has a path of [].
permissions[] Permission[], read-only List of permissions for the folder. Only modifiable via the sharing API.
permissions[].grantDate Datetime When the permission was granted.
permissions[].grantor User User who granted the permission.
permissions[].grantee User User to whom the permission was granted.
permissions[].role String The role that the grantee has.

Methods

list

Required Permissions

This API does not require any permissions, but will only return folders to which the requesting user has access (folder.read).

Request
GET /folders
Parameter Value Description
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<folder>}
]

create

Required Permissions
  • "folder.createFolder" on an ancestor folder, if creating a folder in another folder
Request
POST /folders
Parameter Value Description
Required Body Parameters
name String The name of the folder.
Optional Body Parameters
path ID[] The folder's path. Each entry is the ID of an ancestor folder, in hierarchical order. A root-level folder has a path of [].
Response
201 OK
Content-Type: application/json
---
{<folder>}

read

Required Permissions
  • "folder.read"
Request
GET /folders/:folderId
Parameter Value Description
Path Parameters
folderId String ID of the folder.

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
{<folder>}

update

Required Permissions
  • "folder.update"
  • "folder.move" if changing path
  • "folder.removeFolder" on a current ancestor folder if changing path
  • "folder.createFolder" on a destination ancestor folder if changing path
  • "experiment.move" on all experiments in the folder if changing path
Request
PATCH /folders/:folderId
Parameter Value Description
Path Parameters
folderId String ID of the folder.
Optional Body Parameters
name String The name of the folder.
path ID[] The folder's path. Each entry is the ID of an ancestor folder, in hierarchical order. A root-level folder has a path of [].

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
{<folder>}

Gates

Gates are geometric shapes within which events (cells) must be contained to be considered part of a population.

Gates may be any one of RectangleGate, PolygonGate, EllipseGate, RangeGate, QuadrantGate or SplitGate.

When tailoring a gate to a file, a new gate is created with the same GID as the original gate, but with an fcsFileId property set to the file to which the gate is tailored. The update and delete API endpoints accept requests by GID to make for efficient updates to families of tailored gates.

Compound gates (quadrant and split) are made up of "sectors." Quadrant gates have four sectors (upper-right, upper-left, lower-left, lower-right) and split gates have two sectors (left and right). In addition to the top-level GID (like simple gates), these gates have model.gids and names lists that specify the GID and name for each sector, in the order shown above. Populations using compound gates must reference these sector GIDs; referencing the top-level GID of a compound gate is meaningless.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the gate.
experimentId ID, read-only ID of the experiment to which the gate belongs.
name String Name of the gate. (Not used for compound gates.)
type RectangleGate, PolygonGate, EllipseGate, RangeGate, QuadrantGate, SplitGate The type of the gate.
gid String The gate "group ID." Families of tailored gates all use the same GID, but have unique _id and fcsFileId values.
xChannel String The name of the X channel.
yChannel String Required for 2D gates (i.e. not RangeGate or SplitGate). The name of the Y channel.
tailoredPerFile Boolean If true, indicates that gates with this GID are tailored per-file.
fcsFileId String If tailoredPerFile=true, the ID of the FCS file to which this gate is tailored. If blank, this is the default gate that will be used when there is no gate with the required GID and fcsFileId.
model Gate The geometric description of the gate. See tables below for type-specific information.
model.label Number[] X, Y coordinate of the gate label. (Not used for compound gates.)
model.locked Boolean If true, the gate cannot be moved in the Web UI.

RectangleGate

Property Value Description
model.rectangle.x1 Number
model.rectangle.y1 Number
model.rectangle.x2 Number
model.rectangle.y2 Number

PolygonGate

Property Value Description
model.polygon.vertices Number[][] Array of X, Y coordinates, e.g. [[x1, y1], [x2, y2], [x3, y3]]. May contain up to 300 vertices. If you require more than 300 vertices, please contact us.

EllipseGate

Property Value Description
model.ellipse.center Number[] X, Y coordinate of the ellipse center point.
model.ellipse.major Number Length of the semi-major axis.
model.ellipse.minor Number Length of the semi-minor axis. (Note that this may be larger than the major value.)
model.ellipse.angle Number Rotation of the ellipse.

RangeGate

Property Value Description
model.range.x1 Number Position of the first vertical line.
model.range.x2 Number Position of the second vertical line.
model.range.y Number Vertical position of the dashed line joining the vertical lines.

QuadrantGate

Property Value Description
model.quadrant.x Number Position of the center point.
model.quadrant.y Number Position of the center point.
model.quadrant.angles Number[] Angles at which the quadrant lines appear, in radians. Zero (0) points horizontally to the right; angles proceed counter-clockwise.
model.gids ID[] GIDs of the sectors.
names String[] Names of the sectors.
model.labels Number[][] X, Y coordinates of the gate labels.

Quadrant gate sectors are half-open: the bottom and left edges are inclusive, and the top and right edges are exclusive. This ensures that every event appears in exactly one sector. Angles are sorted when gate membership is calculated, meaning that no two sectors can overlap each other.

SplitGate

Property Value Description
model.split.x Number Position of the center point.
model.split.y Number Vertical position of the dashed line extending from the vertical line.
model.gids ID[] GIDs of the sectors.
names String[] Names of the sectors.
model.labels Number[][] X, Y coordinates of the gate labels.

Split gate sectors are half-open: the left edge is inclusive, and the right edge is exclusive. This ensures that every event appears in exactly one sector.

Methods

list

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET /experiments/:experimentId/gates/
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<gate>}
]

create

Create one or multiple gates.

Required Permissions

This API requires the following permissions:

  • "gate.create"
  • "population.create" if createPopulation is true
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/gates
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Optional Query Parameters
createPopulation Boolean Automatically create corresponding population(s). Defaults to false. Not available for bulk gate creation.
parentPopulationId String For use with createPopulation=true. Specifies the parent population.
Required Body Parameters
* Gate or Gate[] A single gate or array of gates to create.

The requests body must be less than 1 MB. As a typical gate is less than 1 kB, approximately 1,000 gates may be created at once.

If any gates fail validation, no gates will be created.

When creating tailored gates, the global gate (with fcsFileId set to null) must exist before creating the tailored gates.

Response

For single gates, without createPopulation query param, or with createPopulation=false:

201 Created
Location: path to new gate
----
<gate>

With createPopulation=true for simple gates:

201 Created
----
{
    gate: <gate>,
    population: <population>
}

With createPopulation=true for compound gates:

201 Created
----
{
    gate: <gate>,
    populations: [<population>, ...]
}

For multiple gates:

201 Created
----
[<gate>, <gate>, ...]

update

Required Permissions

This API requires the following permissions:

  • "gate.update"
  • "gate.lock" if setting locked=true
  • "gate.unlock" if setting locked=false
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/gates/:gateID
Response

Returns an object reflecting the updated gate.

update group

Updates all gates in a gate group (ones with the same GID).

Required Permissions

This API requires the following permissions:

  • "gate.update"
  • "gate.lock" if setting locked=true
  • "gate.unlock" if setting locked=false
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/gates?gid=:GID
Response

Returns an object indicating how many gates were modified: {nModified: <Integer>}.

delete

Deletes a gate or tailored gate group.

If deleting a global gate (with fcsFileId set to null), all tailored gates with the same gid must be deleted first. Otherwise, a 400 error will occur.

When deleting compound gates, the top-level gid must be used; specifying the gid of a sector (i.e. one listed in model.gids) will result in no gates being deleted.

If the operation results in no gates remaining with the same GID, then that GID will be removed from all populations in the experiment. The number of modified populations is reflected in the response.

Required Permissions

This API requires the following permissions:

  • "gate.delete"
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId/gates/:gateId
DELETE https://cellengine.com/api/v1/experiments/:experimentId/gates?gid=:GID[&exclude=:gateID]
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Optional Path Parameters
gateId String ID of the gate, if deleting a single gate.
Required Query Parameters
gid String GID of the gate family, if deleting a whole tailored gate family.
Optional Query Parameters
exclude String Deprecated ID of a single gate to keep, if deleting a whole tailored gate family.

Deprecated exclude parameter

The exclude query parameter is deprecated and will be removed in the future. While this parameter can be used in a two-step process to untailor gates (the first step deleting all but the to-be-global gate, and the second step making the to-be-global gate the global gate by setting its fcsFileId to null), that two-step process puts the CellEngine experiment in an error state between the first and second steps by having a tailored gate without a global gate.

To safely untailor gates, use the disable tailoring API instead.

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
{
    nRemoved: <Integer>,
    populations: {
        nModified: <Integer>
    }
}

apply tailoring

Sets the gate provided in the request body as the gate for the specified FCS files. If tailored gates already exist for any of the specified FCS files, those gates will be deleted (if the provided gate matches the global gate) or updated (if the provided gate does not match the global gate); otherwise, gates will be created.

Required Permissions

This API requires the following permissions:

  • "gate.update"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/gates/:gateId
DELETE https://cellengine.com/api/v1/experiments/:experimentId/gates?gid=:GID[&exclude=:gateID]
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Required Query Parameters
gid String GID of the gate family.
Required Body Parameters
fcsFileIds String[] IDs of files to which to apply tailoring.
gate Object The gate object to apply to the files. experimentId, gid, tailoredPerFile and _id are not required.

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
{
    updated: {_id: string, fcsFileId: string}[],
    updated: {_id: string, fcsFileId: string}[],
    deleted: {_id: string, fcsFileId: string}[]
}

disable tailoring

Disables tailoring for a gate family, making a gate into the global gate.

When specifying a compound gate, the top-level gid must be used; using the gid of a sector (i.e. one listed in model.gids) is an error.

Required Permissions

This API requires the following permissions:

  • "gate.delete"
  • "gate.update"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/gates/disabletailoring
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Required Body Parameters
gid String GID of the gate family for which to disable tailoring.
globalGateId String ID of the gate to make the new global gate.
Response
200 OK
Content-Type: application/json
---
{
    nRemoved: <Integer>
}

Plots

Methods

get

Renders a 1D or 2D flow plot.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/plot
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Required Query Parameters
fcsFileId String FCS file ID.
plotType contour, dot, density or histogram (case-insensitive) Plot type.
xChannel String X channel name.
Optional Query Parameters
axesQ Boolean Display axes lines. Defaults to true.
axisLabelsQ Boolean Display axis labels. Defaults to true.
axisLabelFontSize Number Font size for axis labels.
color String Case-insensitive string in the format #rgb, #rgba, #rrggbb or #rrggbbaa. The foreground color, i.e. color of curves in "histogram" and "contour" plots, dots in "dot" plots.
compensation Compensation Compensation to use for gating and display.
gateLabel String One of "eventCount", "eventCountPerUl", "mean", "median", "percent", "mad", "cv", "stddev", "geometricMean", "name", "none" (case-insensitive).
gateLabelFontSize Number Font size for gate labels.
height Integer Image height. Defaults to 228.
percentileStart Number For contour plots, the percentile of the first contour.
percentileStep Number For contour plots, the percentile step between each contour.
populationId Population Defaults to ungated.
postSubsampleN Integer Randomly subsample the file to contain this many events after gating.
postSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) after gating.
preSubsampleN Integer Randomly subsample the file to contain this many events before gating.
preSubsampleP Number Randomly subsample the file to contain this percent of events (0 to 1) before gating.
renderGates Boolean Render gates into the image.
seed Number Seed for random number generator used for subsampling. Use for deterministic (reproducible) subsampling. If omitted, a pseudo-random value is used.
smoothing Number For density and contour plots, adjusts the amount of smoothing. Defaults to 0 (no smoothing). Set to 1 for typical smoothing. Higher values (up to 10) increase smoothing.
strokeThickness Number The thickness of histogram and contour plot lines. Defaults to 1.
tickLabelsQ Boolean Display tick labels. Defaults to false.
ticksQ Boolean Display ticks. Defaults to true.
tickLabelFontSize Number Font size for tick labels.
width Integer Image width. Defaults to 228.
xAxisLabelQ Boolean Display x axis label. Overrides axisLabelsQ.
xAxisQ Boolean Display x axis line. Overrides axesQ.
xTickLabelsQ Boolean Display x tick labels. Overrides tickLabelsQ.
xTicksQ Boolean Display x ticks. Overrides ticksQ.
yAxisLabelQ Boolean Display y axis label. Overrides axisLabelsQ.
yAxisQ Boolean Display y axis line. Overrides axesQ.
yChannel String for 2D plots Y channel name.
yTickLabelsQ Boolean Display y tick labels. Overrides tickLabelsQ.
yTicksQ Boolean Display y ticks. Overrides ticksQ.
zChannel String for dot plots colored by a 3rd channel Color channel name.
Response
200 OK
Content-Type: image/png
---
<octet-stream>

Populations

On a biological basis, populations are groups of cells that are analyzed together. For example, you may have a "T cells" population or a "STAT3 positive" population. On an implementation basis, populations are combinations of gates.

(Preface: In all examples below, population names are used for ease of discussion. In reality, gate GIDs are used.)

Simple populations look like {"$and": [singlets, T cells, CD4+]}, which would mean that events must be in "singlets" AND "T cells" AND "CD4+". Populations will almost always use the "$and" operator.

More complex populations can be built with combinations of "$and", "$or", "$not" and "$xor":

{"$and": [
    singlets,
    CD3+,
    {"$or": [CD4+, CD8+]}
]}

This would require cells to be in "singlets" AND "CD3+" AND either "CD4+" OR "CD8+". (It would not select CD4+/CD8+ double-positive cells.)

{"$and": [
    singlets,
    {"$not": dead}
]}

This would return cells in "singlets" and not in "dead".

{"$and": [
    singlets,
    leukocytes,
    {"$not": [
        CD3+,
        CD20+
    ]}
]}

This would return singlet leukocytes that are neither CD3+ nor CD20+ (e.g. monocytes, dendritic cells and NK cells from a blood sample). Note that while boolean NOT is technically a unary operator, CellEngine implements the operator as both unary ({"$not": dead}) and n-ary ({"$not": [CD3+, CD20+]}), which could be thought of as neither x nor y or none of x, y or z.

Constructing barcoding populations becomes easy with logical populations. For example, if you have a six-choose-three barcoding scheme (e.g. cells must be positive for exactly three of six channels), one population would be:

{"$and": [
    BC1,
    BC2,
    BC3,
    {"$not": [BC4, BC5, BC6]}
]}

Warning

While it's possible to create any population imaginable via the API, CellEngine might not be able to be able to display the populations in a hierarchy. Plots and statistics will be correct despite this.

gates Syntax

The gates string must be an RFC8259-compliant JSON string. The formal syntax is:

GateQuery {
    ("$and"|"$or"|"$not"|"$xor" : Array<GID|GateQuery>) | ("$not" : GID)
}

Translated, that means a GateQuery is comprised of a JSON-formatted object with a single key (one of "$and", "$or", "$not" or "$xor"), whose value is an array of GID strings and more GateQueries. Additionally, "$not" is allowed to have a scalar GID string value.

Populations using sectors of compound gates (i.e., a half of a split gate or a quadrant of a quadrant gate) must reference the sector GID found at gate.model.gids[#]; referencing the top-level GID of a compound gate is is an error.

Special Values

Wherever a population ID can be supplied to the API, null can be supplied to indicate Ungated (all events).

Resource Representation

Property Value Description
_id String, read-only The unique ID of the population.
experimentId String, read-only The ID of the experiment to which this population belongs.
gates JSON String The gate expression that defines this population. See above information. This string must be RFC8259-compliant JSON.
name String The name of the population.
parentId String The population's parent population.
pathName String, read-only The full path name of the population, automatically generated by the server. This name includes prepended ancestor names.
terminalGateGid String The GID of the gate that differentiates this population from its parent. This is used in conjunction with parentId to determine if a gate should be displayed on a plot. For basic populations, it should be the GID of the gate that differentiates this population from the parent. For complex populations (e.g. combination populations) with more than one gate that is different from the parent, it should be null. Note: for compound gates, this property should correspond to the sector GID found at gate.model.gids[#], not the top-level GID.
uniqueName String, read-only The unique name of the population, automatically generated by the server. This name includes prepended ancestor names until the name is unique within the experiment.

Methods

list

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/populations
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<population>}
]

create

Required Permissions

This API requires the following permissions:

  • "population.create"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/populations
Response
201 Created
Content-Type: application/json
---
{population}

update

Required Permissions

This API requires the following permissions:

  • "population.update"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/populations/:populationId
Response
200 OK
Content-Type: application/json
---
{population}

delete

Deletes a population.

If this population is selected in any illustrations in the same experiment, those selections are cleared.

If the specified population is defined by a sector of a compound gate (e.g. a quadrant of a quadrant gate), all other sectors of the compound gate will be deleted as well.

Required Permissions

This API requires the following permissions:

  • "population.delete"
  • "gate.delete" if deleteBranch=true
Request
DELETE https://cellengine.com/api/v1/experiments/:experimentId/populations/:populationId
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
populationId String ID of the population.
Optional Query Parameters
deleteBranch Boolean Defaults to false. If true, deletes corresponding gate and all descendant populations/gates.
includeRoot Boolean Applies to deleteBranch=true usage only. Defaults to true. If false, only descendants of the specified population are deleted.

Do not supply a request body with this method.

Response

Without deleteBranch

204 No Content

With deleteBranch=true

200 OK
Content-Type: application/json
---
{
    nRemoved: <Integer>,
    _id: <String[]>,
    gates: {
        nRemoved: <Integer>,
        gid: <String[]>
    }
}

The response gates.gid excludes sector GIDs; it only contains top-level GIDs.

ScaleSets

A scale set is a set of scales (one scale per channel name for all channels in the experiment). Each experiment has exactly one scale set. Uploading a file updates the experiment's scale set to ensure that the new file's channels are included. If a new channel must be added to a ScaleSet, the default scale from the FCS file will be used.

Resource Representation

Property Value Description
_id String, read-only The unique ID of the scale set.
experimentId String, read-only The ID of the experiment to which this scale set belongs.
name String The name of the scale set.
scales[] Scale[] The scales comprising the scale set.
scales[].channelName String The name of the channel to which this scale applies.
scales[].scale Scale The scale for this channel.
scales[].scale.cofactor Number, optional For ArcSinhScales, the value by which the input is divided.
scales[].scale.minimum Number The minimum display value for the scale.
scales[].scale.maximum Number The maximum display value for the scale.
scales[].scale.type ArcSinhScale, LinearScale or LogScale The type of scale.

Methods

list

Gets the list of scale sets in the experiment. Currently there is exactly one scale set per experiment.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET https://cellengine.com/api/v1/experiments/:experimentId/scalesets
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Optional Query Parameters
Standard query parameters for list routes

Do not supply a request body with this method.

Response
200 OK
Content-Type: application/json
---
[
    {<scaleset>}
]

update

Modifies the scale set. Changing a scale will also adjust the coordinates of gates using the modified scale.

Required Permissions

This API requires the following permissions:

  • "scaleset.update"
Request
PATCH https://cellengine.com/api/v1/experiments/:experimentId/scalesets/:scaleSetId
Response

Statistics

Methods

get

Calculates statistics for combinations of FCS files, populations and channels.

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
POST https://cellengine.com/api/v1/experiments/:experimentId/bulkstatistics
Content-Type: application/json
Parameter Value Description
Path Parameters
experimentId String ID of the experiment to which the file belongs.
Required Body Parameters
statistics String[] Any of "mean", "median", "quantile", "mad" (median absolute deviation), "geometricMean", "eventCount", "eventCountPerUl", "cv", "stddev" or "percent" (case-insensitive).
q Number for "quantile" statistic
channels String[] for "mean", "median", "geometricmean", "cv", "stddev", "mad" or "quantile" statistics Names of channels to calculate statistics for.
compensationId Compensation Compensation to use for gating and statistic calculation. See special compensation values.
Optional Body Parameters
annotations Boolean Include file annotations in output (defaults to false).
digits Integer Number of digits to appear after the decimal point. May be a value between 0 and 20, inclusive. (TSV and CSV format only.)
fcsFileIds String[] FCS files to get statistics for. If omitted, statistics for all non-control FCS files will be returned.
format String One of "TSV (with[out] header)", "CSV (with[out] header)" or "json" (default), case-insensitive.
fullPaths Boolean Include full population paths in output (defaults to false).
ids Boolean Include population and file IDs in output (defaults to true).
layout String The file (TSV/CSV) or object (JSON) layout.
  • "tall-skinny" One row/object per combination of FCS file, population, statistic and channel.
  • "medium" One row/object per combination of FCS file, population and channel. Separate column/property for each statistic.
  • "short-wide" One row/object per FCS file. One column/property per combination of population, statistic and channel. This format is not readily machine-readable and does not include population IDs or the uniquePopulationName.
Case-insensitive.
percentOf String|String[] Population ID or array of population IDs. If omitted or the string "PARENT", will calculate percent of parent for each population. If a single ID, will calculate percent of that population for all populations specified by populationIds. If an array, will calculate percent of each of those populations.
populationIds String[] List of population IDs. Defaults to ungated. For ungated, omit or use null.
uniqueNames Boolean Include unique population names in output (defaults to true).
Response

For format="json", a JSON array with all combinations of provided parameters (FcsFiles x Populations x channels x statistics). For example:

POST https://cellengine.com/api/v1/experiments/:experimentId/bulkstatistics
{
    "statistics": ["mean", "median", "quantile"],
    "channels": ["PE-A", "FSC-A"],
    "q": 0.95,
    "compensationId": -1,
    "fcsFileIds": ["<fcsFileId1>", "<fcsFileId2>"],
    "format": "json",
    "layout": "medium",
    "populationIds": ["<populationId1>", "<populationId2>"]
}

200 OK
Content-Type: application/json
---
[
    {
        fcsFileId: "<fcsFileId1>",
        filename: "Specimen 01.fcs",
        populationId: "<populationId1>",
        population: "Singlets",
        uniquePopulationName: "Singlets",
        parentPopulationId: null,
        parentPopulation: "Ungated",
        channel: "PE-A",
        reagent: "CD3",
        mean: 52040.376758718616,
        median: 50881.291015625,
        quantile: 51616.5477815448
    },
    {
        fcsFileId: "<fcsFileId1>",
        filename: "Specimen 01.fcs",
        populationId: "<populationId1>",
        population: "Singlets",
        uniquePopulationName: "Singlets",
        parentPopulationId: null,
        parentPopulation: "Ungated",
        channel: "FSC-A",
        mean: 87881.26381655093,
        median: 86734.2890625,
        quantile: 87800.75920644606
    },
    ... continued for fcsFileId2, populationId2
]

For format="csv", "tsv", "csv (with header)" or "tsv (with header)", a text file in the specified format.

Tasks

Resource Representation

Task

This wrapping object shows the current state of the task, as well as including its definition. It is read only after creation.

Property Value Description
_id String, read-only The unique ID of the task.
name String, read-only The name of the analysis task
user String, read-only The ID of the user who ran the analysis.
status String, read-only one of "COMPLETE", "FAILED", "RUNNING", "TERMINATED", "NEW", "STAGING", or "COMPLETED"
data TaskDefinition, read-only The requested task.
output object, read-only The output and/or errors of an analysis.
output.results object, read-only, optional If present, the successful output of the algorithms run.
output.errors object, read-only, optional If present, errors encountered during the algorithms being run.
output.warnings object, read-only, optional If present, warnings generated during the algorithms being run.
statusMessage String, read-only, optional Only present in terminal states. Describes the status of the task.
progress Number, read-only, optional Present in "RUNNING" and terminal states. An estimated completion percentage of the task.
stagingTime String, read-only The time when the task was staged to run.
startTime String, read-only The time when the task began running.
updateTime String, read-only The time when the task status or output was last updated.
endTime String, read-only The time when the task completed.

TaskDefinition

Property Value Description
experimentId String, read-only The ID of the experiment to run algorithms against.
populationId String or null The ID of the population to run algorithms against, null for UNGATED
fcsFileIds String[] An array of FCS file IDs to apply the algorithm to
algorithms[] AlgorithmSpec[] The specificatins for the algorithms to run.
channels String[] The channels to which to apply the analysis.
subsampling TaskSubsampling, optional An object with subsampling specifications.
subsampling.postP number, optional, 0–1 Subsampling proportion
subsampling.postN number, optional Subsampling absolute number
subsampling.seed number, optional A random number seed, for replicability across runs
rescale boolean, optional If true, rescale the channel to have the range [0, 1]
compensation string, 0, -1, or -2 The id of the compensation to use, 0 for uncompensated, -1 file-internal compensation, and -2 for per-file compensation

AlgorithmSpec

See Analysis Algorithms for a descriptions of these algorithms.

PCA (Principal Component Analysis) dimension reduction

See PCA for more information.

Property Value Description
whiten boolean, optional Whiten
nComponents number, optional Number of components to keep. Defaults to 2.
t-SNE (t-distributed Stochastic Neighbor Embedding) dimension reduction

See t-SNE for more information.

Property Value Description
type "t-SNE" Request t-SNE analysis. Case sensitive.
perplexity Number, optional Must be between (0,nRow), but typically between [5,50]. Defaults to 30.
preLearningRate Number, optional Learning rate during exaggeration phase. Typically between (10,1000). Defaults to nRows / 12.
postLearningRate Number, optional Learning rate after exaggeration phase. Defaults to preLearningRate.
nNeighbors Number, optional Number of nearest neighbors in the range [0,min(1023,nRow)]. Defaults to 3 * perplexity.
exaggerationIter Number, optional Exaggeration iterations. Defaults to 250.
earlyExaggeration Number, optional Exaggeration during exaggeration phase.
lateExaggeration Number, optional Exaggeration after exaggeration phase.
pcaInitialization Number, optional If true, embeddings are initialized with principal components. Defaults to false.
maxIter Number, optional Total number of iterations. Defaults to 1000.
UMAP (Uniform Manifold Approximation and Projection) dimension reduction

See UMAP for more information.

Property Value Description
type "UMAP" Request UMAP analysis. Case sensitive.
nNeighbors Number, optional Number of nearest neighbors in the range [0,1023). Defaults to 15.
nEpochs Number, optional The number of training epochs. Larger values result in more accurate embeddings. If number of events is greater than 10,000, defaults to 30, otherwise, 100.
minDistance Number, optional, 0 < n < 1 Minimum distance. Defaults to 0.1.
randomSeed Number, optional Random seed, for repeatability.
SOM (Self-organizing Map) clustering

See SOM for more information.

Property Value Description
type "SOM" Request SOM analysis. Case sensitive.
xGridSize Number, optional, 1–10000 X grid size
yGridSize Number, optional, 1–10000 Y grid size
startRadius Number, optional, 0–1 Starting radius
somIters Number, optional, 100–1e9 Total number of times the map is updated. Defaults to 10,000,000.
consensusIters Number, optional, 0–200 Number of iterations to find consensus
consensusClustersK Number, optional Number of clusters to cut the tree at during consensus clustering. Defaults to 10.
randomSeed Number, optional Random seed, for repeatability.
Louvain clustering

See Louvain, Leiden and Ensemble Clustering of Graphs (PhenoGraph) for more information.

Property Value Description
type "Louvain" Request Louvain clustering. Case sensitive.
nNeighbors Number, optional, 1–1023 Number of nearest neighbors in the range [0,1023). Defaults to 30.
maxIter Number, optional, 10–1e6 Defaults to 1000.
resolution Number, optional, 0.001–1e4 Called gamma in the modularity formula. Higher values lead to more but smaller communities. Lower values lead to fewer but larger communities. Defaults to 1.0.
Leiden clustering

See Louvain, Leiden and Ensemble Clustering of Graphs (PhenoGraph) for more information.

Property Value Description
type "Leiden" Request Leiden clustering. Case sensitive.
nNeighbors Number, optional, 1–1023 Number of nearest neighbors in the range [0,1023). Defaults to 30.
maxIter Number, optional, 10–1e6 Defaults to 1000.
resolution Number, optional, 0.001–1e4 Called gamma in the modularity formula. Higher values lead to more but smaller communities. Lower values lead to fewer but larger communities. Defaults to 1.0.
ECG clustering

See Louvain, Leiden and Ensemble Clustering of Graphs (PhenoGraph) for more information.

Property Value Description
type "ECG" Request ECG clustering
nNeighbors Number, optional, 1–1023 Number of nearest neighbors in the range [0,1023). Defaults to 30.
ensembleSize Number, optional The number of graph permutations to use for the ensemble. Defaults to 16.
minEdgeWeight Number, optional, 0 < n < 1 The minimum value to assign as an edgeweight in the ECG algorithm. Defaults to 0.05.

Methods

cancel

Cancel a running task, discarding any progress or result.

Required Permissions
Request

POST /api/v1/tasks/<taskId>/cancel

This request has no body.

Response
204 OK

The response body is empty.

list

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET /api/v1/tasks
Response
200 OK
Content-Type: application/json
----
[
    {<task>},
    ...
]

run (create)

Required Permissions

This API requires the following permissions:

  • "experiment.read"
  • "experiment.clone"
Request
Parameter Value Description
Path Parameters
experimentId String ID of the experiment.
Required Body Parameters
algorithms AlgorithmSpec[] An array of algorithm specifications to run on the experiment, population, and fcs files
populationId String or null The population that is the parent of the populations to analyze.
fcsFileIds String[] An array of FCS file IDs to apply the algorithm to
Optional Body Parameters
subsampling String[] for "mean", "median", "geometricmean", "cv", "stddev", "mad" or "quantile" statistics Names of channels to calculate statistics for.
compensationId Compensation Compensation to use for gating and statistic calculation. Seespecial compensation values.
Optional Body Parameters
annotations Boolean Include file annotations in output (defaults to false). 
POST /api/v1/experiments/<experimentId>/runtask
{
    "name": "<task name>";
    "algorithms": [
        <algorithm spec>,
        ...
    ],
    "populationId": "<populationId>" or null,
    "fcsFileIds": ["<fcsFileId>"]
    "subsampling": {
        "postN"
    }
                        fcsFileIds: string[];
            subsampling?: Pick<Subsampling, "postN" | "postP" | "seed">;
            /**
             * Rescale each channel to have range [0, 1].*/
            rescale: boolean;
            channels: string[];
            /**
             * Unlike the rest of CellEngine,
             * string forms of the numbers (e.g. "-1") are not accepted.
             */
            compensation: string | 0 | -1 | -2;
}
Response
200 OK
Content-Type: application/json
----
<task>

read

Required Permissions

This API requires the following permissions:

  • "experiment.read"
Request
GET /api/v1/tasks/<taskId>
Parameter Value Description
Path Parameters
taskId String ID of the task.
Optional Query Parameters
wait_for_change String When "true", waits for a change to be made to the task before returning
Response
200 OK

Content-Type: application/json
----
<task>